Tuners

Tuner endpoints provide access to channel status, signal quality, streaming control, hardware settings, and scheduling. Each tuner corresponds to one FM receiver channel.

---

GET /tuners/all

Returns an array of all tuner objects.

Roles: user, admin

Response: Array of Tuner objects.

[
  {
    "tuner_id": 0,
    "name": "Radio 1",
    "frequency": 104300,
    "tuned": true,
    "state": 1,
    "signal_ok": true,
    "muted": false,
    "stream_enabled": true,
    "quality": {
      "rssi": 62,
      "snr": 38,
      "multipath": 4,
      "stereo": true,
      "stereo_blend": 100,
      "rds": true,
      "level": true,
      "alarms": ""
    },
    "rds": {
      "pi": "1234",
      "ps": "RADIO 1 ",
      "prog_type": "Pop Music",
      "radiotext": "Now playing: Artist - Track Title"
    },
    "stream": {
      "url": "udp://239.1.1.1:1234",
      "codec": "mp3",
      "requested_bitrate": 128,
      "measured_bitrate": 128
    },
    "thresholds": { "...": "..." },
    "schedule": { "active": false, "events": {} },
    "hw_settings": { "...": "..." }
  }
]

---

GET /tuner/{tuner_id}

Returns the full state object for a single tuner.

Roles: user, admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index (zero-based)

Response: Single Tuner object.

---

POST /tuner/{tuner_id}/settings

Configures the frequency, name, and hardware parameters for a tuner.

Roles: user, admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Request body:

{
  "name": "Radio 1",
  "frequency": 104300,
  "hw_settings": {
    "agc_state": 1,
    "channel_filter": 1,
    "deemphasis": 2,
    "lna_gain": 0,
    "rssi_threshold": 20
  }
}

Field	Type	Description
name	string	Display label for this channel slot
frequency	integer (kHz)	Tuning frequency, e.g. 104300 for 104.3 MHz
hw_settings	object	See Hardware Settings

---

POST /tuners/all/settings

Applies the same hardware settings to all tuners simultaneously. Useful for bulk configuration changes such as setting de-emphasis for an entire region.

Roles: user, admin

Request body:

{
  "hw_settings": {
    "agc_state": 1,
    "channel_filter": 1,
    "deemphasis": 1,
    "lna_gain": 0,
    "rssi_threshold": 20
  }
}

---

POST /tuner/{tuner_id}/state

Sets the operational state of a tuner.

Roles: admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Request body:

{ "state": 1 }

Value	State	Description
0	Disabled	Tuner is off, no measurements
1	Enabled	Tuner is actively monitoring
2	Sleep	Tuner is paused but retains configuration

---

POST /tuner/{tuner_id}/station

Tunes a tuner to a previously discovered station by its station_id. Equivalent to setting the frequency directly, but uses a station from the scan results list.

Roles: admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Request body:

{ "station_id": 3 }

Note

Returns 503 if the tuner is busy (e.g. mid-scan). Retry after a short delay.

---

POST /tuner/{tuner_id}/scan

Performs a full FM band scan on the specified tuner and returns a list of discovered stations. Discovered stations are automatically added to the global station list.

Roles: user, admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Query parameters:

Parameter	Type	Default	Description
async	0 or 1	0	Set to 1 to use chunked transfer encoding for asynchronous streaming of results

Response: Array of Station objects.

Warning

Due to hardware design, a full band scan can take up to 10 seconds. During this time the tuner is unavailable — other requests to the same tuner will return 503.

---

POST /tuner/{tuner_id}/stream

Enables or disables IP streaming for a tuner and sets stream parameters.

Roles: user, admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Request body:

{
  "enabled": true,
  "stream": {
    "url": "udp://239.1.1.1:5004",
    "codec": "mp3",
    "bitrate": 128
  }
}

Field	Type	Description
enabled	boolean	true to start streaming, false to stop
stream.url	string	Destination URL — UDP multicast or unicast (e.g. udp://239.1.1.1:5004)
stream.codec	string	Audio codec — see GET /valid_bitrates for supported values
stream.bitrate	integer	Requested audio bitrate in kbps

---

POST /tuner/{tuner_id}/muted

Mutes or unmutes a tuner's contribution to the front-panel monitor output.

Roles: user, admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Request body:

{ "muted": true }

---

POST /tuner/{tuner_id}/thresholds

Sets alert thresholds for a single tuner.

Roles: user, admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Request body:

{
  "rssi_threshold": 20,
  "rssi_interval": 5,
  "thresholds": {
    "tuner_id": 0,
    "rssi":        { "min": 20, "max": 0,   "margin": 2 },
    "snr":         { "min": 15, "max": 0,   "margin": 2 },
    "multipath":   { "min": 0,  "max": 60,  "margin": 5 },
    "stereoblend": { "min": 10, "max": 0,   "margin": 2 },
    "audiol":      { "min": 5,  "max": 0,   "margin": 1 },
    "audior":      { "min": 5,  "max": 0,   "margin": 1 },
    "rds": {
      "blocka": false,
      "blockb": false,
      "blockc": false,
      "blockd": false,
      "group_lost": true,
      "sync_lost": true,
      "margin": 3
    }
  }
}

Threshold ranges:

Metric	Min	Max	Disable
rssi	0	127	Set to 0
snr	0	127	Set to 0
multipath	0	100	Set to 100
stereoblend	0	127	Set to 0
audiol / audior	0	127	Set to 0

---

POST /tuners/all/thresholds

Applies the same threshold configuration to all tuners.

Roles: user, admin

Request body: Same structure as POST /tuner/{tuner_id}/thresholds.

---

POST /tuner/{tuner_id}/schedule

Configures a time-based schedule for a tuner — enabling and disabling it automatically at specified times.

Roles: user, admin

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Request body:

{
  "active": true,
  "events": {
    "monday": [
      { "minute": 480, "state": 1 },
      { "minute": 1200, "state": 0 }
    ],
    "saturday": [
      { "minute": 0, "state": 2 }
    ]
  }
}

minute is the number of minutes since midnight (0–1439). state values are the same as in POST /tuner/{tuner_id}/state: 0 = Disabled, 1 = Enabled, 2 = Sleep.

---

POST /tuners/all/schedule

Applies the same schedule to all tuners.

Roles: user, admin

Request body: Same structure as POST /tuner/{tuner_id}/schedule.

---

GET /tuner/{tuner_id}/live.m3u8

Returns an HLS live stream playlist (.m3u8) for the specified tuner. The playlist can be opened directly in any HLS-compatible player.

Authentication: Not required.

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Response: application/vnd.apple.mpegurl — M3U8 playlist

Example URL:

http://192.168.112.1/api/tuner/0/live.m3u8

---

GET /tuner/{tuner_id}/live.mp4

Returns a continuous MP4 live stream using chunked transfer encoding. The stream has no defined end — it continues until the connection is closed by the client.

Authentication: Not required.

Path parameters:

Parameter	Type	Description
tuner_id	integer ≥ 0	Tuner index

Response: video/mp4 — binary stream

---

Tuner Object

Full schema returned by /tuner/{id} and /tuners/all:

Field	Type	Description
tuner_id	integer	Tuner index
name	string	Configured display name
frequency	integer (kHz)	Tuned frequency
tuned	boolean	Whether the tuner has locked onto the frequency
state	0 / 1 / 2	Disabled / Enabled / Sleep
signal_ok	boolean	Whether signal is above the RSSI threshold
muted	boolean	Whether the tuner is muted on the monitor output
stream_enabled	boolean	Whether IP streaming is active
quality	object	Real-time signal measurements — see below
rds	object	RDS data — PI, PS, RadioText, PTY, country, language
stream	object	Active stream URL, codec, requested and measured bitrate
thresholds	object	Currently configured alert thresholds
schedule	object	Scheduling configuration
hw_settings	object	Hardware receiver settings

Signal Quality Fields

Field	Type	Description
rssi	integer	Received signal strength
snr	integer	Signal-to-noise ratio in dB
multipath	integer	Multipath interference level, 0–100%
stereo	boolean	Stereo pilot signal present
stereo_blend	integer	Stereo blend level, 0–100
rds	boolean	RDS data present
level	boolean	Audio level within configured bounds
alarms	string	Space-separated list of active alarm types

Hardware Settings

Field	Type	Values	Description
agc_state	integer	0 = off, 1 = on	Automatic Gain Control
channel_filter	integer	0–4	IF channel filter bandwidth
deemphasis	integer	1 = 75 µs, 2 = 50 µs	De-emphasis time constant
lna_gain	integer	≥ 0	LNA gain level
rssi_threshold	integer	≥ 0	Minimum RSSI for signal lock