HLS Meta GPIO

Overview

The HLS Meta GPIO app plays an HLS audio stream on a Barix LX400 and automatically operates a relay output (GPO) in response to ad‑break markers carried inside that stream. It is designed for broadcast and ad‑insertion workflows where a downstream device — a mixer, a local ad player, a "now playing" sign, or a station‑automation input — needs to know, in real time, when the main programme has entered an advertisement break and when it has returned to normal programming.

The app continuously reads the stream's own signalling. Two kinds of in‑stream markers are understood: SCTE‑35 cue markers carried in the stream's playlist, and ID3 metadata embedded in the audio itself. When either marker indicates that an ad break has started, the app closes the configured relay; when the marker indicates the break has ended, it opens the relay again.

The distinguishing feature of the app is that relay switching is aligned with the audio you actually hear. The stream is buffered before it reaches the loudspeaker output, so a naïve trigger would fire several seconds before the corresponding audio was audible. Instead, the app measures its own playout delay and holds each relay change until the exact moment the marked audio reaches the output. The result is a relay transition that coincides with the audible start and end of the break, not with its arrival over the network.

Front‑panel status LEDs indicate the play state and whether a break is currently active, so an operator can confirm at a glance that the app is running and tracking correctly.

Compatible Hardware

The HLS Meta GPIO app runs on:

• Barix LX400 — full support. The LX400 provides the relay outputs (GPOs) that the app controls, the analog audio output used for monitoring, and the status LEDs used for indication.

The app requires the relay outputs of the LX400 to signal ad breaks. Devices without relay outputs are not suitable for this app.

The stream source can be any standard HLS stream that delivers AAC audio segments and carries ad‑break signalling as SCTE‑35 playlist cues, embedded ID3 metadata, or both. Both HTTP and HTTPS streams are supported.

Installation Process

Before you begin: make sure your LX400 is running a compatible Flexa firmware (version 2.3.3 or later). If the app package requires a newer firmware than the one installed, the device will offer to update during installation.

NOTE 1: If your LX400 is already running an application you must RESET TO DEFAULTS before proceeding and installing a new one.

NOTE 2: If your LX400 is registered in a management portal or has the Flexa Agent enabled on the HOME page, ensure it has no assigned application. If you can access the portal, assign this app there; otherwise, the portal’s assigned app will override the local configuration.

Step 1 — Open the device web interface

• Point a web browser at the IP address of your LX400.

• Log in with your device credentials.

  

Step 2 — Upload the app package

• Open the Flexa app HOME page of the web interface.

• Choose Upload and select the hls-meta-gpio.zip package file.

• Wait for the upload to complete. The device installs the app and adds a new configuration tab named HLS Meta GPIO.

Step 3 — Verify and configure

• Confirm that the HLS Meta GPIO tab now appears in the interface.

• Open the tab and enter your configuration (see Configuration Overview below).

• Save the form. The app starts automatically and restarts whenever you save new settings.

  

Configuration Overview

All settings are entered from the HLS Meta GPIO tab. The tab is divided into the sections described below. After changing any value, save the form to apply it — the app reloads its configuration and restarts each time you save.

Stream Source

Defines what the app plays and how loud the decoded stream is.

• HLS Stream URL — the address of the HLS playlist (.m3u8) to play. This may be a master playlist or a media playlist, over HTTP or HTTPS. This is the only mandatory field; until it is set, the app waits and the status LED shows a red slow blink.

• Stream Volume — a software gain applied to the decoded programme, on a scale of 0 to 100. Use this to trim the level of the stream itself.

Audio Output

• Output Volume — the main output volume of the device, on a scale of 0 to 100. This sets the final loudness of the analog monitoring output, independently of the Stream Volume above. Set it to 100 for full output.

Ad‑Break Trigger

This section controls what the app treats as an ad break, which is the heart of the app's behaviour.

• Trigger Source — selects which in‑stream signal is allowed to start and end a break:

  • Manifest cues + ID3 (both) (default) — either signal can activate the break. This is the most tolerant setting and is recommended unless you have a specific reason to restrict it.

  • Manifest SCTE‑35 cues only — only the playlist's cue markers are honoured; embedded ID3 markers are ignored.

  • ID3 Insert frames only — only the embedded ID3 markers are honoured; playlist cue markers are ignored.

  See Operational Behavior → What triggers the relay below for exactly how each signal is interpreted.

• Alignment Trim (ms) — a fine adjustment, in milliseconds, of the moment the relay switches relative to the audible audio. Leave it at 0 for automatic alignment. Enter a positive value to make the relay switch later (further into the break), or a negative value to make it switch earlier. This is intended only for small corrections to match a specific downstream device; the app already aligns to the audible audio on its own.

GPO Output

Defines which relay is operated and its resting logic.

• Relay Output Number — which relay output (1 to 8) the app operates when a break starts and ends.

• Invert Output — chooses the relay's resting behaviour:

  • Unchecked (default) — the relay is closed during the ad break and open the rest of the time.

  • Checked — the relay is open during the ad break and closed the rest of the time. This "fail‑safe" wiring keeps the relay energised during normal programming, so a loss of power or a stopped app reads the same as an ad break at the downstream device.

Syslog

Optional remote logging for diagnostics and record‑keeping.

• Enable Syslog — turn remote logging on or off.

• Syslog Host — the address of your syslog server (shown only when logging is enabled).

• Syslog Port — the port of your syslog server (default 514).

When enabled, the app sends a log entry for every significant event, including each detected marker and each relay change, to your syslog server.

Operational Behavior

What triggers the relay

The app decides that an ad break is active from the stream's own signalling. Depending on the Trigger Source you selected, one or both of the following are considered:

SCTE‑35 cue markers (in the playlist)

• A cue‑out marker (the start‑of‑break signal, including its continuation form as the break progresses) puts the app into the break active state.

• A cue‑in marker (the return‑to‑programme signal) takes the app out of the break active state.

ID3 metadata (embedded in the audio)

• An embedded insert marker whose value indicates an ad break (an "ad‑break" identifier) puts the app into the break active state.

• Any other insert marker value — signalling a return to normal content — takes the app out of the break active state.

When the Trigger Source is set to both, the app is in the break active state whenever either source indicates a break, and returns to normal only when neither does. This makes the app robust to streams that carry one kind of marker more reliably than the other.

The relay follows the break active state directly: entering the state operates the relay for a break, leaving the state releases it — subject to the Invert Output setting, which decides whether "operated" means closed or open.

Alignment with audible audio

The app plays the stream with a short, fixed buffer between the network and the loudspeaker output — this buffer is what allows smooth, gap‑free playback. Because of it, a marker arrives from the network several seconds before the audio it belongs to is actually heard.

The app compensates for this automatically. It continuously measures how far behind the network the audible audio currently is, and when it encounters a marker it delays the relay change by exactly that amount. In practice this means:

• The relay closes (break start) at the instant the first advertisement becomes audible.

• The relay opens (break end) at the instant normal programming returns to air.

The Alignment Trim setting lets you nudge this timing if a particular downstream device needs the switch slightly earlier or later, but no trim is needed for normal use.

Start‑up and mid‑break join

If the app starts — or the stream is (re)connected — while an ad break is already in progress, the app detects the in‑progress break from the current signalling and sets the relay to the break active state immediately, so the relay always reflects the true state of the programme rather than waiting for the next transition.

Recovery

The app is self‑healing. If the stream is temporarily lost, it retries continuously and resumes playback and marker tracking on its own once the stream returns. It does not require a manual restart after a network interruption. When the app shuts down, it releases the relay to its normal (non‑break) position.

Status LED indications

The LX400's two front LEDs report status at a glance:

Configuration Example

Marking ad breaks for a downstream ad player

Goal: close relay 1 whenever the main stream is in an advertisement break, so a downstream local‑ad player can take over.

Settings on the LX400:

• HLS Stream URL: <https://provider.example.com/hls/playlist.m3u8>

• Stream Volume: 70

• Output Volume: 100

• Trigger Source: Manifest cues + ID3 (both)

• Alignment Trim (ms): 0

• Relay Output Number: 1

• Invert Output: unchecked

• Syslog: enabled, pointing at your logging server (optional)

Expected result: the app plays the stream on the LX400 output. The moment an advertisement becomes audible, relay 1 closes; the moment normal programming returns, relay 1 opens. LED 2 is lit red for the whole duration of each break. The relay transitions coincide with what you hear on the output, not with when the markers arrived over the network.

Software Disclaimer

IMPORTANT:

This software application ("Software") is provided "AS IS" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. In no event shall the author, developer, or distributor be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Software or the use or other dealings in the Software.

Use at Your Own Risk: The user assumes all responsibility and risk for the use of this Software. The author makes no representations or warranties regarding the accuracy, reliability, completeness, or timeliness of the Software or its suitability for any particular purpose.

No Support Obligation: The provision of this Software does not create any obligation to provide technical support, maintenance, updates, enhancements, or modifications. The Software is provided for educational and reference purposes only.

Third-Party Dependencies: This Software may utilize third-party libraries and components. The user is responsible for ensuring compliance with all applicable licenses and terms of use for such dependencies.

Network and Security: The user is solely responsible for implementing appropriate security measures and network configurations. The author is not responsible for any security vulnerabilities, data breaches, or network disruptions that may result from the use of this Software.

Compliance: Users are responsible for ensuring that their use of this Software complies with all applicable laws, regulations, and organizational policies in their jurisdiction.

Limitation of Liability: Under no circumstances shall the total liability of the author exceed zero dollars ($0.00) for any damages arising out of or related to the use of this Software.

By using this Software, you acknowledge that you have read, understood, and agree to be bound by the terms of this disclaimer.