Metadata-Version: 2.1
Name: pysdrweb
Version: 0.4.0
Summary: Server to host FM Radio via RTL-SDR utilities.
Home-page: https://github.com/eulersIDcrisis/pysdrweb
License: MIT
Author: Aaron Gibson
Author-email: eulersidcrisis@yahoo.com
Requires-Python: >=3.8,<4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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 :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Dist: PyYAML (>=6.0,<7.0)
Requires-Dist: click (>=8.0,<8.1)
Requires-Dist: lameenc (>=1.3.1)
Requires-Dist: soundfile (>=0.10,<1.0)
Requires-Dist: tornado (>=6.1,<7.0)
Project-URL: Bug Tracker, https://github.com/eulersIDcrisis/pysdrweb/issues
Project-URL: Repository, https://github.com/eulersIDcrisis/pysdrweb
Description-Content-Type: text/markdown

# pysdrweb

Project to create a web interface to RTL-SDR tooling.

## FM Radio Receiver

The first focus of the project is to make a simple, web-based
FM Radio receiver that can be controlled entirely through a
web browser. By visiting the main page, the user can listen in
on an (FM) radio station using any compatible RTL-SDR dongle
and change the frequency, as desired.

This receiver is backed by some _driver_, which implements the
set of calls necessary to run the radio, i.e. calls to generate
a raw PCM data stream that is then encoded on the fly. Usually,
this driver is simply the RTL-SDR program: `rtl_fm`, which the
server searches for by default.
(Other driver types are planned for the future, but are not yet
implemented.)

By default, python supports some (usually uncompressed) formats
out of the box:
 - WAV: Raw format used in CDs and other media.

If `soundfile` is also present (and installed correctly), then
this can also encode into more formats:
 - FLAC: Free Lossless Audio Codec, supported by most browsers
       with some possible compression.
 - OGG: Container format, supported by browsers. This format
       usually compresses fairly well, especially compared to
       more raw formats.
(The list isn't exhaustive, but the goal is to support more
browsers, not as many formats. The code should be easy enough
to add more formats, however, if that is ever really needed.)

If `lameenc` is also present, then this can also encode into
still more formats like:
 - MP3: Enough said.

Currently, this server appears to work on Firefox and Chrome.
With HLS, Safari should also be supported, though this will
require the app to stall for a bit to build up the appropriate
HLS buffering.

### Goal

The goal of this server is to support multiple formats and
multiple clients simultaneously, without straining _too_ many
system resources; the hope is that this server is low-key
enough to run on weaker hardware (yes, even with python).

### Running the Server

Currently, the server requires `rtl_fm` to be installed and
a valid RTL-SDR device to be plugged in.

The simplest way to run the server is:
```sh
pysdrweb_server -p 8080 -f 107.3M
```
This runs the server on port 8080 and listens (initially) on
107.3 FM.

If `rtl_fm` is not on the path, that can be passed in with:
```sh
pysdrweb_server -p 8080 -f 107.3M -m ${RTL_FM_PATH}
```

For the full set of options, it is easier to configure the
server with a configuration file. A sample configuration file
is shown below:
```yaml
#
# Sample 'native' driver configuration file.
# 
---
port: 9000
# Uncomment to require auth to change the frequency.
# auth:
#   type: basic
#   # This indicates whether 'readonly' (GET) requests require auth or not.
#   ignore_on_read: true
#   # Each user is denoted by: <user>: <password>
#   users:
#     admin: admin

# Starting (FM) channel/frequency to listen on startup.
default_frequency: 107.3M
# Driver settings.
driver:
  # Path to rtl_fm, if not on the path of the server.
  rtl_fm: /usr/local/bin/rtl_fm
  # Optional.
  kb_buffer_size: 128

# HLS Streaming Options
#
# Uncomment below to enable HLS with various options. HLS is a protocol
# that handles streams of media by splitting it into 'chunks', and serving
# those chunks as static files. The client will piece these chunks together
# into a continuous stream; the chunks are advertised to the client as an
# "HLS Playlist", a special file (with .m3u8 extension) that points to each
# chunk.
#
# NOTE: HLS is currently needed to support Safari/iOS browsers.
#
# Uncomment to enable HLS:
hls:
  enabled: true
  # Number of chunks (distinct audio files) to store.
  chunk_count: 6
  # The length of each individual chunk.
  seconds_per_chunk: 10
  # The format of the chunk. If unspecified, this will be a sensible default.
  # format: flac
```
Then, to run the server:
```sh
sdrfm_server -c config.yml
```
This permits adding authentication as well.

### Server REST API

Currently, the server supports a REST API that the main page
invokes to render. The main calls are described below:

| Method | Route | Description |
---------|-------|-------------|
| GET | `/api/frequency` | Returns the current frequency the server is listening on. |
| POST | `/api/frequency` | Change the frequency the server is listening on. |
| GET | `/api/procinfo` | Returns any (stderr) logging for the current driver. |
| GET | `/api/radio/audio.<ext>` | Fetch the audio streamed from the radio. |

### Audio Route (More Detail)

Much of this server relies on `/api/radio/audio.<ext>` to function since this
is the route that actually serves the audio file. This route uses the given
`<ext>` extension to determine the format to stream in. The route also accepts
an optional `timeout` parameter, telling the server how long to listen for (in
seconds). If not passed, the server will continue streaming indefinitely.

To download 10 seconds of the audio in WAV format (assuming the server is
running locally on port 8080) call:
```sh
curl http://localhost:8080/api/radio/audio.wav?timeout=10 > audio.wav
```

If a format is not supported, the response will indicate as such.

### Authentication

By default, the requests are not authenticated. If configured, however,
the requests can all require authentication using "HTTP Basic"-style
authentication. When making a request, the browser will prompt for the
username/password combination.

Other authentication may be added later.

## How It Works

For simplicity, the RTL-SDR tooling includes `rtl_fm`, which
streams FM audio data as raw, mono, 16-bit (2 byte) PCM data
at some configurable frequency. For example, the following
shell pipeline streams the frequency `107.3M` to an MP3 file:
```sh
# Listen on 107.3 FM, sampling at 48kHz
rtl_fm -f 107.3M -M fm -s 48000 | \
sox -traw -r48000 -es -b16 -c1 -V1 - -tmp3 - > output.mp3
```
The `sox` command is used to convert raw PCM data into framed
MP3 data. (It is possible to use `ffmpeg` in a similar vain as
well). The quality is quite bad; we need to sample more quickly
then resample down to a lower frequency:
```sh
# Sample at 200k, then resample down to 48k.
# Passing '-A fast' denotes the way to perform the resample.
rtl_fm -f 107.3M -M fm -s 200k -r 48k -A fast | \
sox -traw -r48k -es -b16 -c1 -V1 - -tmp3 - > output.mp3
```
This command can be run remotely and played (once) in the
browser using:
```sh
# Like above, but pipes the output to port 8080.
rtl_fm -f 107.3M -M fm -s 200k -r 48k -A fast | \
sox -traw -r48k -es -b16 -c1 -V1 - -tmp3 - | \
socat -u - TCP-LISTEN:8080
```
This pipeline is cool, but has some obvious problems. In
particular, the pipeline ends as soon as the browser stops
listening for any more input. Also, only one browser/client
can listen at a time. (Also, some browsers might not support
this for some formats...) Once finished, the command must be
executed again.
Changing the frequency also requires rerunning or otherwise
changing the command.

To address these issues, pysdrweb will buffer the PCM output
from whatever source (currently `rtl_fm`) and encode it on
the fly, which permits _multiple clients and formats_. This
also permits changing the frequency more easily.

## Future

A few low-hanging fruit features to consider adding:
 - Scan for available channels.
 - More sophisticated UI (Theming and Features)

