Metadata-Version: 2.5
Name: mmng-ui
Version: 1.4.2
Summary: A Textual TUI for multimon-ng — decode POCSAG and FLEX pager messages from SDR applications in your terminal or web browser.
Project-URL: Homepage, https://github.com/lingfish/mmng-ui
Project-URL: Issues, https://github.com/lingfish/mmng-ui/issues
Project-URL: Changelog, https://github.com/lingfish/mmng-ui/blob/main/CHANGELOG.md
Project-URL: CI, https://gitlab.lucid.net.au/lucid/mmng-ui
Author-email: Jason Lingohr <jason@lucid.net.au>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: decoder,flex,ham-radio,multimon-ng,pager,pocsag,sdr,textual,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console :: Curses
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Ham Radio
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click==8.3.0
Requires-Dist: moment==0.12.1
Requires-Dist: rich==14.2.0
Requires-Dist: textual==6.3.0
Provides-Extra: web
Requires-Dist: textual-serve==1.1.2; extra == 'web'
Description-Content-Type: text/markdown

# mmng-ui

A TUI (text user interface) frontend for [multimon-ng](https://github.com/EliasOenal/multimon-ng).

`mmng-ui` will listen on a chosen UDP port for raw streams from software like SDR++, use `multimon-ng` to decode it,
and show you POCSAG/FLEX messages in a wonderful text interface.

You can also use it within a web browser!

<a href="https://www.buymeacoffee.com/lingfish" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-red.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>


## Table of contents

<!-- TOC -->
* [mmng-ui](#mmng-ui)
  * [Table of contents](#table-of-contents)
  * [Purpose](#purpose)
  * [Installation](#installation)
    * [Normal TUI (text console) mode](#normal-tui-text-console-mode)
    * [Web mode](#web-mode)
  * [How to use it](#how-to-use-it)
    * [JSON detection](#json-detection)
    * [sox conversion mode](#sox-conversion-mode)
    * [Multiple ports and tabs](#multiple-ports-and-tabs)
    * [Capcode database](#capcode-database)
    * [Save tab to file](#save-tab-to-file)
  * [Example screenshot](#example-screenshot)
  * [Supported Python versions](#supported-python-versions)
<!-- TOC -->


## Purpose

Why not?  I know there are other frontends out there, but I haven't seen any for use in a text console.

I also wanted to learn both [Rich](https://github.com/Textualize/rich) and [Textual](https://github.com/Textualize/textual).

See `CHANGELOG.md` for all the latest updates. The links may not be clickable.

## Installation

### Normal TUI (text console) mode

The recommended way to install `mmng-ui` is to use [pipx](https://pipx.pypa.io/stable/).

After getting `pipx` installed, simply run:

```shell
username@host:~$ pipx install mmng-ui
```

Please [don't use pip system-wide](https://docs.python.org/3.11/installing/index.html#installing-into-the-system-python-on-linux).

You can of course also install it using [classic virtualenvs](https://docs.python.org/3/library/venv.html).

### Web mode

Thanks to Textual's [web serving support](https://github.com/Textualize/textual-serve), you can also run `mmng-ui` in a
web browser!

First, install `mmng-ui` with the `web` feature/extra:

```shell
username@host:~$ pipx install 'mmng-ui[web]'
```

Then run `mmng-ui` with the `--serve` option.  Your console will show you the URL to connect to!

By default, it will bind to all interfaces (and both IPv4 and IPv6 if enabled).  See the help screen for other choices.

If you supply either `--serve-host` or `--serve-port`, there's no need to specify `--serve` as well -- it is implied.

## How to use it

See `mmng-ui --help` for CLI options.

Run `mmng-ui`, and you'll be greeted with this screen:

![screenshot](/docs/initial%20screen.png)

Notice in the status pane, it says "Receiver: idle" -- it is now listening for UDP packets sent to the default port
of 8888.

Now go to your favourite SDR application, and send to where `mmng-ui` is running. If possible, make sure you encode and
send in the right sample rate that `multimon-ng` likes, 22050 Hz. It probably helps to send mono too.

If you can't send at 22050 Hz, [click here](#sox-conversion-mode) to read about using `sox` mode.

Alpha POCSAG messages will soon display in the top pane.  The bottom pane will show the raw output from `multimon-ng`,
as well as any errors or issues with decoding.

The status panel shows any incoming connections.  Receiver will transition between the following states:

| Receiver state | Description                                     |
|----------------|-------------------------------------------------|
| idle           | No UDP traffic yet seen, or seen in 5 seconds   |
| receiving      | Actively receiving a decode from `multimon-ng`  |
| waiting        | Traffic is coming in, but nothing to be decoded |

Just below the status panel is a sparkline -- this updates on each decode, and reflects character length of said
decode.

Underneath the log window in another sparkline, and this shows messages per second, for the last minute.

The footer shows available keyboard choices to quit the app, show a help screen, and clear all logging panes.

The mouse will also work!

### JSON detection

`mmng-ui` will attempt to auto-detect the output format from `multimon-ng`, and if it looks like JSON, it'll use it.

JSON output was merged into `multimon-ng` [version 1.4.0](https://github.com/EliasOenal/multimon-ng/releases/tag/1.4.0).  Support for older versions will eventually be dropped.

### sox conversion mode

With release 1.3.0, you can use the `--sox-rate` (optionally with `--sox-binary`) CLI arguments and `mmng-ui` will put
an instance of `sox` in the decoding pipeline, before `multimon-ng`. You can use the same format as `sox` accepts,
for example, `48k`, or `32000`.

### Multiple ports and tabs

You can listen on multiple UDP ports simultaneously by passing `--port` (or `-p`) more than once:

```shell
mmng-ui --port 8888 --port 8889 --port 8890
```

Each port gets its own tab with an independent status pane, sparkline, and message log.  At launch you can name a tab
using `--port <port>=<name>` or `--port <port>:<name>`:

```shell
mmng-ui --port 8888=Primary --port 8889=Secondary
```

You can also rename the active tab at any time by pressing `r`.

### Capcode database

Pass a JSON or CSV file of known capcodes with `--capcodes` (or `-k`):

```shell
mmng-ui --capcodes /path/to/capcodes.json
```

The file format is an array of objects with `address`, `label`, and optional `icon` and `colour` fields:

```json
[
  { "address": "1234567", "label": "Fire Dept",     "icon": "fire",     "colour": "red" },
  { "address": "7654321", "label": "Ambulance",      "icon": "ambulance" },
  { "address": "1111111", "label": "Local Council" }
]
```

When a message's capcode matches a known entry, its alias is shown in the configured colour with an optional emoji
prefix.  Unmatched capcodes display the raw address as before.

CSV format is also supported:

```csv
address,label,icon,colour
1234567,Fire Dept,fire,red
7654321,Ambulance,ambulance,
```

### Save tab to file

Press `s` while the app is running to open the save dialog.  You can choose a filename and export format -- CSV,
Markdown, or JSON -- to save all messages from the active tab.

## Example screenshot

Here's what a screen full of decodes might look like:

![screenshot](/docs/working%20screen.png)

## Supported Python versions

`mmng-ui` supports Python 3.10 and newer.

## Star history

[![Star History Chart](https://api.star-history.com/chart?repos=lingfish/mmng-ui&type=date&legend=top-left)](https://www.star-history.com/?type=date&repos=lingfish%2Fmmng-ui)
