User Manual RetailPlayer

Portal version 4.9.0 · Device firmware 8.0.12 · Edition October 2026

This manual covers the RetailPlayer devices, their local web interface, the RetailPlayer Portal and the Portal's REST API (Broad API).

1. Introduction

1.1 What is RetailPlayer?

RetailPlayer is a multi-site, multi-channel audio platform for background music and scheduled messages. It has two parts:

• RetailPlayer devices. Compact Barix audio players (S400, SP400, M400, TPA400) installed at each site. They play internet radio streams, music synchronised from your own server (Store & Play), locally stored tracks and scheduled announcements.

• The RetailPlayer Portal. A web application that manages all devices from one place: registration, channels, schedules, volume, announcements, remote control, monitoring and firmware.

Out of the box a device finds its Portal automatically, opens a secure, permanent connection to it and receives its whole configuration. Audio never passes through the Portal: each device connects directly to the streaming servers and file servers you configure. Changes made in the Portal reach online devices within seconds.

1.2 Applications

• Background music for retail stores, restaurants, bars, gyms and hotels

• Central distribution of a radio or music service to many sites

• Scheduled messages, advertisements, announcements and bells (Retail Hero / Premium)

• Sonic branding and on-demand audio cues triggered by staff

• Corporate audio streaming and music on hold

• A background-music source for larger IP audio systems (RTP forwarding)

1.3 Who this manual is for

• Installers, who connect and set up devices on site.

• Operators and administrators, who manage devices, music, schedules and users in the Portal.

• End users, such as store staff using the remote control or QR codes.

• Integrators, who automate the Portal through the Broad REST API (chapter 17).

You need basic networking knowledge: IP addresses, DHCP, DNS and firewalls.

1.4 Versions covered

• Portal: 4.9.0.

• Device firmware: 8.0.12.

Older firmware versions may lack some functions, or behave differently. Always run the latest firmware on the devices: see chapter 16 and the release documentation.

1.5 Conventions

• Bold words are names of buttons, menus and fields as they appear on screen.

• <placeholder> marks a value you supply, for example <portal-domain>.

• Notes marked Important describe behaviour that can interrupt audio or delete content.

2. Getting a Portal: self-hosting or managed hosting

The RetailPlayer Portal is available only as a self-hosted instance, installed and run on your own server. The former Barix-hosted cloud portal (https://manage.barix.com) is discontinued.

If you do not want to host the Portal yourself, Barix's partner StreamGuys offers a managed RetailPlayer Portal. See 2.2.

2.1 Self-hosted Portal

You install the Portal on your own Linux server with the Barix installer. You then own the instance and its data, and you control its domain, certificates and updates.

Everything about installing and running a self-hosted Portal is in the RPP Self Hosted – Deployment Instructions:

• host and network requirements;

• domains and certificates;

• product key and licensing;

• installation, updates and customization;

• enabling the Broad REST API;

• migration from the former Barix cloud Portal.

Device requirement: devices need firmware 7.0.4 or later to connect to a self-hosted Portal. Firmware 8.x (8.0.12 at the time of writing) is recommended.

2.2 Self-hosted subscription tiers and part numbers

Self-hosted Portal subscriptions are sold by device count, in two editions:

• BASIC covers device, channel and channel-list management, failover tracks, opening hours, channel and volume scheduling, QR-code remote control, firmware management, and user and organization management.

• PREMIUM adds the Retail Hero functions: asset manager, bundles, asset scheduling (messages and advertisements), audio cues and proof of play. It also adds the Broad REST API (chapter 17).

To change tier, renew the subscription or move to Premium, Barix issues a new product key. The deployment instructions describe how to install it.

Subscriptions must be purchased through our Distributor network.

2.3 Managed hosting by StreamGuys

Customers who do not want to run a server can use the RetailPlayer Portal hosted by Barix's partner StreamGuys and subscribe to one of the following tiers:

• a Basic package;

• a Premium Retail Hero package with asset management, scheduled messages, audio cues and proof of play.

StreamGuys also provides specialized support for its hosted Portal. To request the service, use the contact form on the StreamGuys RetailPlayer page.

3. Key concepts

3.1 How a device decides what to play

From the highest priority to the lowest:

Outside the opening hours the device plays nothing. A cue does not override the Priority URL, nor USB tracks when Play from USB is active.

3.2 How changes reach a device

1. You save a change in the Portal.

2. The Portal immediately pushes it to the online device over the device's secure WebSocket connection.

3. Files (failover tracks, assets, Store & Play tracks, firmware) are not pushed. The device receives a reference and downloads the file itself over HTTPS.

A device that is offline receives its complete configuration again the next time it connects. Devices keep playing, including schedules and stored tracks, while the Portal is unreachable.

4. RetailPlayer devices

4.1 Models

All models run the same RetailPlayer firmware and offer the same functions. Hardware details, connectors and pin-outs are on the hardware pages:

• S400 / SP400

• M400

• TPA400

Other hardware features:

• Ethernet: 10/100 Mbit/s.

• USB ports: for a USB stick (local tracks) or a supported Wi-Fi dongle.

• Reset button.

• Status LED(s).

• Label: the MAC address and the unique default web password are printed on the device label.

4.2 LEDs

The S400 and SP400 have one status LED. The M400 and TPA400 have two LEDs: the left one shows the system state, the right one the application state.

A blinking green LED is normal for a few minutes after start-up, while the device looks up and connects to its Portal.

4.3 The reset button

After a factory reset or rescue, the device reconnects to its Portal by itself (via the Flexa Registry) within about 7 minutes, as long as it is still registered there.

4.4 Audio formats

The device plays:

• MP3;

• AAC (.aac, .m4a; LC, HE-AAC, HE-AACv2);

• Ogg Vorbis, Opus;

• FLAC;

• WAV (linear PCM).

Streams can be:

• HTTP or HTTPS (Icecast, Shoutcast and similar servers, including .m3u and .pls playlists);

• RTP (Priority URL only).

Use MP3 or AAC for the widest compatibility. Files with an unsupported codec are skipped.

4.5 Local storage

The device stores failover tracks, assets and Store & Play tracks in its internal storage. The free and used space is shown in the device status in the Portal. Large Store & Play libraries are limited only by this space.
Barix ships RetailPlayer units with 32GB sd cards, of which 25.5GB are dedicated to audio file storage. The device reports its storage condition to the portal.

5. First installation

5.1 Before you start

1. Network. The site's network must allow the outbound connections listed in chapter 18. These are mainly HTTPS 443 to the Portal and to the Flexa Registry, NTP (UDP 123) and DNS. A DHCP server is required for the first start.

2. Portal. You need an account on a self-hosted or StreamGuys Portal, with permission to add devices.

3. Firmware. The device needs firmware 7.0.4 or later. Devices shipped recently already meet this. For older units, see chapter 16.

5.2 Step by step

1. Register the device in the Portal (section 8.2). Enter its MAC address (printed on the label), a name, the organization and, ideally, a channel list. You can also register the device after connecting it.

2. Connect the audio:

   • S400/SP400: 3.5 mm jack to your amplifier, using a 3.5 mm-to-2×RCA (Y) cable;

   • M400: RCA;

   • TPA400: a speaker on the terminal block.
     Turn the amplifier up enough to hear the Sonic IP announcement.

3. Connect the network. Use an Ethernet cable to a switch with DHCP. The SP400 and TPA400 power up from PoE.

4. Connect power (S400, M400). The device boots, the LED turns green, and the device announces its IP address over the audio output (Sonic IP).

5. Wait. The device asks the Flexa Registry which Portal it belongs to, stores that Portal's address, may reboot once, and connects. Allow up to 7 minutes.

6. Check:

   • in the Portal, the device shows Online;

   • the application LED is steady green;

   • playback starts as soon as a channel list is assigned.

Important: A device asks the Flexa Registry for its Portal at start-up.

• Firmware 8.0.7 and later asks immediately, then retries every 5 minutes if there is any network issue connecting with the registry.

• Firmware 7.0.4 to 8.0.6 asks only once, about 5 minutes after boot.

If you registered a device after it was already running, reboot or power-cycle it.

5.3 Finding the device's IP address

• Sonic IP: power-cycle the device and listen to the audio output.

• Portal: once connected, the IP is shown in the device status (section 8.6).

• mDNS name: <http://barix-<last> 6 hex digits of the MAC>.local, for example barix-0820a3.local.

• The DHCP server's lease table: RetailPlayer MAC addresses start with 00:08:E1.

• Barix Discovery Tool: see Find the IP address with the Discovery Tool. It finds devices on the same subnet and wired Ethernet only.

5.4 Wireless (optional)

A RetailPlayer can use Wi-Fi through a supported USB dongle. Chipsets known to work:

• Realtek RTL8188EU, for example TP-Link TL-WN722N or TL-WN725N;

• Realtek RTL8812BU, for example TP-Link Archer T3U, T3U Nano or T3U Plus, or Asus AC53 Nano.

Configure Wi-Fi in the device's web interface (section 6.5). Then:

1. Remove the Ethernet cable.

2. Power-cycle the device.

3. Check that Sonic IP announces the wireless address.

Wi-Fi limitations:

• Wi-Fi uses DHCP only.

• Hidden networks are not supported.

• WPA/WPA2-Personal (PSK) is the only security mode.

• The device does not roam between access points: disable roaming for it on the Wi-Fi system.

• For reliable 24/7 playback, wired Ethernet is recommended.

6. The device's local web interface

Each RetailPlayer has a small web interface for the settings that only make sense locally:

• network, Wi-Fi and proxy;

• the Priority URL and RTP forwarding;

• time servers;

• local firmware update, logs, reboot and factory reset.

Everything else (channels, volume, schedules, time zone) is managed from the Portal.

6.1 Opening the web interface

1. Find the device's IP address (section 5.3).

2. Open it in a browser: <http://<device-ip>>, or <https://<device-ip>> if the device is set to HTTPS. You can also use <http://barix-<last> 6 hex digits of the MAC>.local.

3. Log in with the username admin and the device's default password, printed on the device label. Each device has its own password.

The web interface must be enabled from the Portal. The Portal setting Web interface (device Settings, section 8.5) switches the device's web server on or off. It is off by default for devices added in the Portal.

• Web interface off: the browser cannot connect ("connection refused" or a timeout). Switch it on in the Portal, then wait for the device to apply it.

• After a factory reset or rescue: the web server is on again until the device reconnects to its Portal.

First login and password rules. The device may ask you to replace the default password. Choose Submit, or Skip this time. A new password must:

• be 12 to 32 characters long;

• contain at least one upper-case letter, one lower-case letter, one digit and one special character.

After a password change, log in again. A forgotten password can be cleared only with a factory reset (section 4.3), which also restores the default password.

The top bar shows:

• the device's local time;

• an information menu with the MAC address and firmware version;

• a light/dark mode switch;

• a link to Barix help;

• the account menu, with Change Password and Logout.

Menu:

Actions that interrupt the device (reboot, factory reset, firmware update) ask you to type a 6-digit code shown in the dialog, to prevent accidental clicks.

6.2 Dashboard

The Dashboard shows the device information: MAC address, device type and IPAM (audio module) type.

6.3 System Status

An empty Portal URL means the device has not yet received its Portal from the Flexa Registry (see 19.3).

6.4 System Settings: Application and Device

The settings page is divided into collapsible sections. Each field has a help icon (?). Buttons at the bottom:

• Submit saves. It is enabled only when something changed and all fields are valid.

• Cancel discards your changes.

If you leave the page with unsaved changes, the device warns you.

Application

Priority URL format:

• RTP with a static payload type: rtp://<ip>:<port>, for example rtp://239.0.1.39:5004. Multicast, unicast and broadcast are supported; multicast joins via IGMPv2.

• For non-standard payloads you can state the format: rtp://<ip>:<port>?format=[mulaw|alaw]&channels=[1|2]&rate=[8000|16000|24000|32000|48000].

• HTTP(S) stream URLs are also accepted.

Device

6.5 System Settings: Network

Notes:

• Wireless always uses DHCP. If the device runs on Wi-Fi only, keep the Ethernet protocol on DHCP as well.

• Proxies or firewalls that inspect TLS traffic can break the device's secure connection to the Portal. Let the Portal, Flexa Registry and update-server traffic pass through unchanged.

6.6 System Settings: Time and Security

Time Settings

The device must know the correct time to open its secure connection to the Portal. It sets its clock at start-up and keeps it synchronised.

The time zone is not set here. It is set per device in the Portal (section 8.5), and schedules follow it.

Security

6.7 What happens when you save

The message "System settings saved successfully." confirms the save.

6.8 Certificates Management

Certificates Management (button at the top of System Settings) installs additional CA certificates. You need one when your network or your streaming or file server uses certificates from a private (enterprise) certificate authority.

• Upload: drag a file onto the panel or choose Browse file, then Upload Certificate. Use a PEM-encoded .crt, .cer or .pem file. Invalid files are rejected with "is not a valid certificate".

• Installed Certificates lists the uploaded certificates. Each can be deleted.

Note: these are not the certificates used for the device’s web interface. That certificate is self-signed, stored at production, and cannot be changed. These are the certificates the device presents for outgoing connections.

6.9 Logs

• The log viewer: choose System, Application or Web Backend to see the latest lines. Refresh reloads them; Reverse logs order flips the order.

• Download all logs (⋮ menu) saves an archive named <product>_<MAC>_<date>_logs.tar.gz. It holds all logs plus diagnostic information. This is what Barix support needs: send the file as is, without unpacking it.

The archive contains the device configuration. Share it only with Barix support or your installer. Logs are kept in memory and are lost when the device reboots, so download them before rebooting a device that has a problem.

6.10 Update

Installs a firmware file from your computer. See chapter 16. The page shows the currently installed firmware, root file system and kernel versions.

1. Download the RetailPlayer firmware (.tar) from the firmware page.

2. Drag it onto the page or choose Browse file (TAR format, up to 256 MB).

3. Click Update and confirm with the 6-digit code.

4. Wait while the file uploads and installs. Do not remove power. The device reboots into the new firmware by itself.

6.11 Reboot

Reboot the device restarts the device after the 6-digit confirmation. The page reloads by itself once the device is back. If its IP address changed, enter the new address.

6.12 Defaults (factory reset from the web)

Reset Factory Defaults (with confirmation):

• restores all settings except the network settings;

• restores the default web password;

• deletes all content downloaded from the Portal (tracks, assets, Store & Play files);

• clears the stored Portal address.

The device then reboots and finds its Portal again through the Flexa Registry.

To reset everything, including the network settings, use the reset button (section 4.3).

7. The RetailPlayer Portal: basics

7.1 Logging in

1. Open your Portal's address (<https://<portal-domain>>) in a current browser: Chrome, Edge, Firefox or Safari.

2. Enter your username and password, then sign in. Your administrator creates your account (chapter 14).

3. If your administrator set "requires password change", you must choose a new password first.

Terms & Conditions. The Portal can show its owner's Terms & Conditions. At your first login they open in a dialog that you accept with I READ AND ACCEPT. Afterwards you can read them again at any time from the Terms & Conditions button in the top bar.

Session. After a long period of inactivity the Portal logs you out. Stay active, or log in again.

After a Portal update, a page that looks broken is usually an old copy in the browser cache. Reload it with a hard refresh (Ctrl+F5 on Windows, Cmd+Shift+R on Mac).

7.2 Screen layout

• Left menu: the functions you have privileges for. The full set:

  • Devices, Channels, Channel Lists;

  • Asset Organizer (Asset Manager, Bundles, Scheduling, Cues);

  • Organization (Settings, Tree, Proof of Play);

  • Users;

  • Portal Settings (Device's Firmware, RC API keys).

  • User Settings (your own access details)

• Organization selector (top bar): chooses the organization you work in. The lists (devices, channels, schedules, …) show this organization and its sub-organizations. New objects are created in the organization you choose in the create form.

• Top bar: Terms & Conditions and Logout.

The Asset Organizer menu appears only on a Premium / Retail Hero Portal. The Portal Settings menu appears only to administrators of the top (Root) organization.

7.3 User settings

In the user settings (gear icon) you can change:

• your first name and last name;

• your password: enter the current password, then the new one.

8. Devices in the Portal

8.1 The device list

Devices lists the devices of the selected organization and its sub-organizations. It refreshes by itself every minute.

• Counters and quick filters:

  • Online, Offline;

  • Playing fallback: online devices playing their channel's fallback URL;

  • Playing failover tracks: online devices playing their stored failover tracks.

• Search across name, MAC address, location and notes. Sort by column, and page through the list.

• Columns show the device's name, organization, channel list and current channel, whether it is online, whether it is within its opening hours, what it is playing (main URL, fallback, failover tracks, event, USB, priority) and its volume.

• Export All downloads all devices, including those of sub-organizations, as a CSV file. Administrators only.

• Delete (row action) removes a device. See 8.9.

• Add (the + button) registers devices. See 8.2 and 8.3.

Click a device to open its page, which has the remote control (8.4) and the tabs Settings, Automation, Assets, Status, QR codes and Utilities.

8.2 Registering a single device

1. Devices › + › single mode.

2. MAC address. Enter the device's MAC address from its label (for example 00:08:E1:AA:BB:11). The Portal checks that it is free. A device already registered on another Portal must first be removed there.

3. Fill in the details:

4. Finish. The Portal registers the device with the Flexa Registry and opens its Settings page.

The new device automatically receives the firmware entry with the highest version number configured in Portal Settings (15.1). It then downloads and installs that firmware. Make sure that entry is the firmware you want.

If the device is already running, it finds the Portal at its next registry check. Power-cycling the device forces a registry check to happen, do it if the device added was already powered before adding it to the portal. Firmware between 7.0.4 and 8.0.6 check the registry 5 min after boot, 8.0.7 and higher, check immediately at boot. The device restarts when the portal URL it gets from the registry differs from the one stored.

8.3 Registering devices in bulk (CSV)

1. Devices › + › bulk mode.

2. Prepare a CSV file (at most 1 MB) with one device per line, no header row, the MAC address and the name separated by a semicolon:

   "00:08:E1:AA:BB:01";"Store 12 – sales floor"
   "00:08:E1:AA:BB:02";"Store 12 – café"
   

3. Upload the file. The Portal checks it and reports invalid lines.

4. Choose the settings applied to all devices: organization, time zone, channel list, web interface, Sonic IP, USB, volume.

5. Confirm. The result lists each MAC address with its outcome: added, already registered, invalid MAC address, or not assigned in the registry.

Important: Bulk registration requires at least one firmware entry in Portal Settings › Device's Firmware (15.1). The new devices receive the entry with the highest version.

8.4 Device control (remote control)

At the top of the device page you can control an online device in real time:

The display updates when the device confirms the change.

8.5 Settings tab

Save to apply. Changes reach an online device immediately.

8.6 Status tab

The live state of the device, updated as the device reports it:

Different values are refreshed at different rates:

• immediately when they change: stream, active source, time zone, Sonic IP;

• every minute: buffer, opening-hours state, temperature, Wi-Fi;

• every 10 minutes: storage;

• every hour: system time and local time.

An offline device shows its last reported values.

Store & Play status. For a device playing one or more Store & Play channels, the status shows each Store & Play instance:

• playlist URL and refresh interval;

• downloaded files and total size;

• the last error reported by the device;

Press refresh to ask the device for its current state.

8.7 Automation tab

The Automation tab holds the device's schedules, in sub-tabs:

• Opening hours;

• Channel schedule;

• Volume schedule;

• Asset schedule (Premium);

• Cues (Premium).

One SAVE button saves all sub-tabs together.

All schedules run on the device itself, in the device's time zone (set in Settings). They keep working while the device is offline and as far as the unit has an NTP server reachable to resolve its clock.

Opening hours

• A weekly grid in 30-minute steps. Mark the periods when the device should play; the device is silent outside them.

• All and None set the whole week.

• Use it to stop music automatically when the shop is closed.

• Simple click-drag-release interface.

Channel schedule

• Weekly triggers that switch the device to a chosen channel at a given day and time.

• Pick a channel from the device's channel list, then click the grid to place a trigger (30-minute steps).

• Click on the same trigger to remove it.

• A trigger is an action to change channel stored on the device. At boot time, if any channel scheduler is configured, the device reads the last trigger set closest to its boot time and forces that channel to play. It is not necessary to fill in the channel scheduler with triggers for the same channel.

Volume schedule

• Weekly triggers that set the volume at given times.

• Choose the volume with the slider, then click a day and time to place it.

• The toolbar offers a list view, selection and deletion, and zoom.

• Each device has one volume schedule of its own.

• To remove all volume changes, delete the triggers and SAVE.

Asset schedule (Premium)

• Assigns one of the organization's asset schedules (11.4) to this device, or none.

• Only schedulers created in the same organization can be assigned to the device.

• The schedule itself is edited in Asset Organizer › Scheduling.

Cues (Premium)

• Assigns one of the organization's cue sets (11.5) to this device, or none.

• Only cues created in the same organization can be assigned to the device.

• The cue buttons then appear in the device control and on the QR-code remote.

COPY TO…

• Copies this device's opening hours, channel schedule or volume schedule to other devices.

• The dialog lists the devices of the organization selected in the top bar. Tick include sub-organizations to widen the list including devices part of sub organizations of the selected one.

• To copy across sub-organizations, select the parent organization first.

8.8 Assets tab (Premium)

The Assets tab lists the organization's assets, each with a checkbox-

• Untick an asset and save to disable it on this device only: the device will not play it when scheduled. It will still be able to play when assigned to an audio cue.

• Tick it again to re-enable it.

• Use case: an ad for chocolate bars is used in a shop’s scheduler but chocolate bars are out of stock at the moment. Disable the asset from playing until chocolate bars are available without touching the scheduler.

8.9 Utilities tab

Proof of Play (Premium)

This feature is only available to Premium subscribers. When enabled the portal stores the last 20 days of playback metadata reported by the device.

NOTE: only if metadata are available these are reported, files or streams without metadata don’t end up on the proof of play report.

For every reported item there is:

• Timestamp

• The resource it has been playing from (Stream - Store and Play - Fallback - Failover - USB)

• The channel name

• Filename (if playing from failover tracks or SnP channels)

• Title / Artist / Album: the stream title or the id3 tag info

• URL: streams only, the url of the stream playing

• Volume: the volume configured when the item played

EXPORT: Click on export to retrieve a csv file including the device’s playback history

Use the “from” “to” fields to filter only items played in a specific time frame.

Tools

The device uploads a diagnostics archive to the Portal. Check the list of device logs after about 5 minutes and download the archive for Barix support

8.10 Deleting a device

Delete in the device list removes the device from the Portal. The device:

• mutes;

• erases its configuration and downloaded content;

• resets to factory defaults and reboots.

The device is also released in the Flexa Registry, so its MAC address can be registered again, on this Portal or on another. Until it is registered again it stays offline.

Important: Deleting an organization (13.1) deletes all its devices in the same way.

9. Channels

Channels lists the channels of the selected organization and its sub-organizations. You can create, duplicate, edit and delete channels. There is no limit on the number of channels.

To create a channel: +, choose the organization, the name and the type, then fill in the fields below and save.

9.1 Stream channel

The device connects directly to the streaming server; the Portal is not in the audio path. The device identifies itself with the HTTP user agent retailplayer-<last 6 hex digits of the MAC>.

9.2 Store & Play channel

A Store & Play channel plays files from your own file server. The device downloads the tracks listed in a playlist, stores them, plays them locally and keeps them in sync.

How syncing works:

• The device starts playing as soon as the first track is downloaded.

• At each refresh, if any change are detected on the upstream m3u file, new tracks are downloaded, and tracks removed from the playlist are deleted from the device.

• A missing file is retried every 2 minutes forever and when the playlist finishes downloading it is reported to the portal as “File Not Found” in the Store and Play status.

Rules for the playlist and files:

• The playlist must be in the same directory as the audio files, and the names in the playlist must match the file names exactly. On Linux executing this command in the same directory of the mp3 tracks: ls > myplaylist.m3u creates a valid playlist file.

• Avoid accented and special characters in file names (# % ( ) = ? ^ ì è é ò ç).

• Each line of the playlist must name a file in that directory.

• Playlist file needs UTF-8 encoding.

• The URL must be a direct download. Google Drive, Dropbox or similar share links do not work.

• Storage is limited only by the device's free space.

See also What is Store & Play and how it works.

9.3 Editing and deleting channels

• Editing a channel updates every device whose channel list contains it, immediately:

  • a device currently playing it switches to the new URL;

  • a changed Store & Play channel is re-synchronised.

• Duplicate creates a copy named "Copy of …".

• Deleting a channel removes it from all channel lists. Devices playing it move to another channel of their list.

10. Channel lists and failover tracks

A channel list groups the channels a device may play, and holds the failover tracks. Each device has at most one channel list.

10.1 Creating a channel list

Channel Lists › +:

Save, then add failover tracks (10.2) and assign the list (10.3).

10.2 Failover tracks

Failover tracks are stored on every device that uses this channel list. They play when neither the main nor the fallback stream can be played, so the site never falls silent. They also play permanently when the list's channels are disabled ("play only tracks" mode).

Uploading Portal-hosted tracks (only for a saved list):

1. Open the list and drag audio files (MP3, AAC/M4A, Ogg, WAV) onto the upload area.

2. Wait for the uploads to finish, then CONFIRM.

3. Devices download the tracks immediately. A track can be played only once it is fully downloaded. Download progress is shown in the device status (8.6).

You can preview, delete one track, or delete all.

The number of failover tracks per list and their maximum file size are set by your Portal's licence.

Store & Play as failover. A Store & Play channel (9.2) can serve as the failover playlist instead. Its number of tracks and file sizes are limited only by the device's storage, and you manage the files on your own server.

10.3 Assigning a list to devices

• From the channel list window: Assign Devices, then tick or untick devices of the organization. (only devices part of the same organization are presented)

• Or from the device: Settings › Channel list (8.5).

When a list is assigned, the device receives:

• its channels and failover tracks, and downloads the tracks;

• its Store & Play setup.

It starts playing the first channel by name.

When a list is unassigned or deleted, the device's channels are removed. The device plays only local content (failover or USB tracks), if any.

10.4 Playing tracks only

To play a fixed set of music without any stream:

1. Create a list and upload the tracks.

2. Assign the list to the devices.

3. Wait until the devices have downloaded them (Status › failover tracks).

4. Switch PLAY ONLY TRACKS on, and save.

11. Asset Organizer: assets, bundles, scheduling and cues

The Asset Organizer is part of Premium / Retail Hero. It schedules messages, announcements, advertisements and jingles between the music, and lets staff play cues on demand. Assets belong to an organization, and every device of that organization receives them. Work in the same organization as the devices (organization selector).

11.1 How assets play

• When a scheduled asset or cue plays:

  1. the music (stream, Store & Play, USB files or failover) fades out;

  2. the asset plays;

  3. the music fades back in.

• Schedules run on the device, in its time zone, and keep working offline.

• Assets do not interrupt the Priority URL.

11.2 Asset Manager

• Upload. Drag audio files (MP3, WAV, Ogg, M4A/AAC, Opus) onto the upload area, up to 10 files at a time, then CONFIRM. The maximum file size is set by your Portal's licence.

• After confirming, every device of the organization downloads the new assets.

• Edit inline:

  • Name;

  • Notes;

  • Volume, 0–200 %: the playback level of this asset relative to normal; 100 % = unchanged.

• Preview plays an asset in your browser.

• Dependents shows where an asset is used (bundles, schedules, cue sets).

• Delete (tick, then delete). An asset that is still used by a bundle, schedule or cue set cannot be deleted until you remove it from there. Deleting is permanent and removes the asset from the devices.

NOTE: only assets with ID3 tags are reported in the proof of play report. A file with no tags is not reported.

11.3 Bundles

A bundle is an ordered list of assets that is scheduled as one item. Each time the bundle is due, the device plays one asset of the bundle, rotating through them. Use bundles to vary advertisements, for example "every 30 minutes, the next of 5 spots".

• Fields: name, notes, and the assets (add rows with +). The same asset may appear more than once.

• Changes reach the devices immediately, whether you create, edit or delete a bundle.

11.4 Scheduling (asset schedules)

An asset schedule is made of components. Each component plays one asset or one bundle on a time pattern. A schedule can hold up to 20 components and is shown on a timeline.

Component settings:

To use a schedule:

1. Scheduling › +, name the schedule, add components, then Save.

2. Assign to devices, or choose it on the device's Automation › Asset schedule (8.7)

Editing an assigned schedule updates the devices immediately. Deleting it removes it from the devices.

While an asset plays, the device status shows Active resource: Event.

11.5 Cues (cue sets)

A cue set is a set of up to 10 buttons. Each button plays an asset on demand. Example: a waiter plays a birthday song at the right time.

To create one:

1. Cues › +, name the cue set.

2. Add buttons with +. For each button set:

   • name (shown on the remote control);

   • asset: the file to be associated with the button;

   • volume (default 100);

   • background and text colours.
     Reorder buttons with the arrows.

3. Save, then Assign to devices, or choose the set on the device's Automation › Cues.

Pressing a button plays its asset immediately on the device, at the button's volume, over the music. Buttons are available:

• in the Portal's device control (8.4);

• on the QR-code remote (12.2) if cue play is allowed for that code.

12. Remote control and QR codes

12.1 Remote control in the Portal

Every user who can open a device can control it from its page: channel, volume, mute and cues (section 8.4).

12.2 QR codes for on-site staff

QR codes give staff a simple remote control on their phone, without a Portal account. The phone opens the Portal's remote-control site (the second domain of the Portal, for example remote-control.<portal-domain>). The page displays:

• the device status;

• the channel buttons;

• mute and the volume slider;

• the cue buttons.

What the page offers depends on the code's permissions.

Device › QR codes tab:

• + creates a code, named "QR Code nnnn" by default. New codes are enabled, with all actions allowed.

• Per code:

  • name;

  • enabled switch;

  • allow channel change;

  • allow volume change;

  • allow cue play;

  • usage count and last use.

• Show displays the QR code to scan or print.

• Delete a code to revoke access. Disabling it blocks access temporarily.

Here’s how a code with limited access (volume and cues disabled) appears on a mobile device:

To scan a code, point the phone camera at it and open the link.

Anyone who has the link can use the code until you disable or delete it. Print codes only where staff can reach them.

13. Organizations

Everything in the Portal belongs to an organization: devices, users, channels, channel lists, assets, bundles, schedules, cue sets and QR codes.

Organizations form a tree:

• Users of a parent organization see and manage everything in its sub-organizations.

• Users of a sub-organization see only their own branch.

A typical setup is one organization per customer or brand, with sub-organizations per region or store.

13.1 Tree

Organization › Tree shows the hierarchy:

• Icons mark organizations, channel lists, devices and users.

• Filters show or hide users, channel lists and devices.

From here you can:

• add a sub-organization: name and notes;

• remove a sub-organization: the Portal first lists everything it still contains (users, devices, QR codes, channel lists, channels, assets, failover tracks, bundles, schedules, cue sets), then asks for a 6-digit confirmation code.

Important: Removing an organization deletes everything in it. Its devices are reset to factory defaults and released from the Portal (as in 8.10). Move devices you want to keep to another organization first.

13.2 Settings

Organization › Settings:

• Name and notes of the organization.

• Maximum devices (from portal v4.9.0): the maximum number of devices in the organization. Only administrators of the Root organization can change it. When the limit is reached, no more devices can be added.

13.3 Proof of Play (Premium)

Organization › Proof of Play lists what the organization's devices played, for devices with proof of play enabled (8.9). For each entry:

• title, artist, album;

• source (stream, Store & Play, failover, USB, asset);

• device;

• time.

Filter and sort the list, and export it as CSV for reporting to advertisers or rights organizations.

14. Users and privileges

Users lists the users of the selected organization and its sub-organizations. The list shows the user name, first and last name, organization and last login.

14.1 Creating and editing a user

+ opens the user form:

To edit a user, open them from the list. You can change every field and set a new password. Delete removes the user. Users have no effect on devices.

14.2 Privileges

The Asset Organizer privileges also require a Premium / Retail Hero Portal subscription.

15. Portal Settings: firmware and RC API keys

Portal Settings is available to administrators of the Root organization on a self-hosted Portal. On StreamGuys Portal, StreamGuys manages it.

15.1 Device's Firmware

This page defines the firmware versions devices can be given.

Field	Description
Name	A unique name, for example "RetailPlayer 8.0.12"
Version	The version number, for example 8.0.12 - validation requires strict format: “1.2.3”
URL	The download address of the firmware image (http or https). Barix publishes it with each release: see the firmware page Customers can host firmware images on their file servers.
Auto update	This is a simple UI element appearing in the device’s firmware selector. It is used to inform end users that you as a portal owner may change without notice the link of this firmware to a different version. When you do so the device will update after a portal reconnection.

How the entries are used:

• Assigning firmware to a device: Device › Settings › Firmware (8.5), then save. The device downloads the image and installs it. See 16.2.

• New devices automatically receive the entry with the highest version number, even though the registration form has no firmware field. Make sure to select the expected firmware entry when adding a new device.

• Bulk registration requires at least one entry to exist

15.2 RC API keys

RC (Remote Control) API keys give external systems access to the device’s “QR Code” remote-control interface.

Each key has:

• a name;

• an organization;

• an Include Sub-Organizations option;

• an enabled switch;

• a usage count and last-use date.

The key itself is generated when you create it. You can disable a key, or delete it to revoke it.

These keys are not the key of the Broad REST API (17.2).

This pdf contains the REST API authentication and endpoint details: RetailPlayer Remote Control REST API.pdf

16. Firmware updates

Always run the latest RetailPlayer firmware. Firmware files and release notes:

• firmware page;

• release documentation.

Devices never update themselves: an update is always started by you, from the Portal or locally.

16.1 Minimum versions

16.2 Updating from the Portal

1. Make sure the version exists in Portal Settings › Device's Firmware (15.1). On StreamGuys Portals, ask StreamGuys.

2. Open the device's Settings, choose the version under Firmware, and save.

3. The device downloads the image in the background. It installs the update at 4:00 device local time, or at its next reboot, so music is not interrupted during the day. To install at once, reboot the device from Utilities.

The update server in the firmware entry's URL must be reachable from the site (chapter 18).

16.3 Updating locally

Use the device's web interface (section 6.10). This works without a Portal connection, and is the method for devices too old to connect.

If an update stops (for example at 80 %):

1. Do not reboot.

2. Download the logs (6.9).

3. Send them to Barix support.

16.4 Rescue

A rescue reinstalls the factory firmware image when a device no longer starts correctly.

Before you start:

• The device needs Ethernet with internet access: it downloads the image from release.barixupdate.com.

• The rescue erases everything.

Procedure:

1. Power the device off.

2. Hold the reset button while you apply power (S400 and M400: plug in the power supply; SP400 and TPA400: plug in the PoE cable). Keep holding for 8 seconds after power-up, then release.

3. The LED blinks orange while the image downloads and installs. Wait 20 minutes. Do not remove power.

4. Power-cycle the device, then log in to the web interface.

Afterwards, update to the latest firmware.

If the device stays unreachable, the device probably had no internet access during the rescue. Check the network and repeat.

17. The Broad REST API

The Broad API lets your own systems manage the Portal: register devices, manage channels, channel lists, assets and schedules, control devices, and export device data. It is part of the Premium self-hosted Portal only. This feature is not available on the StreamGuys portal.

The complete reference is the OpenAPI (Swagger) specification published with the self-hosting instructions. You can open it in http://editor.swagger.io

This chapter gives an overview and the points you must know.

17.1 Base URL and requests

• Base URL: <https://<portal-domain>>/broad/api/v1.

• Format:

  • Requests and responses are JSON.

  • Uploads (assets, failover tracks, bulk CSV) use multipart/form-data.

  • All IDs are UUIDs.

• MAC addresses: accepted with colons (00:08:E1:08:20:93), returned with dashes (00-08-E1-08-20-93).

• Organizations: {orgId} in a path is the organization that holds the object.

• Errors return a JSON body such as {"message": "Not found"}. Check the HTTP status code: success responses differ between endpoints (OK, {"message":"OK"}, {"id": …}).

17.2 Authentication and API key

Every request carries the key in the header:

x-retailplayer-apikey: <your-api-key>

On a self-hosted Premium Portal the administrator of the host sets the key, as described in the deployment instructions (section "Portal API"). Keep the key secret: it grants full access to the Portal.

Test the key with:

curl -s https://<portal-domain>/broad/api/v1/hello -H "x-retailplayer-apikey: <your-api-key>"

17.3 Paging, filtering and sorting

• List parameters: page, pageSize, filters (a JSON array of {field, operator, value}), orderBy, orderDirection (asc/desc), search, fields.

• Responses: {"data": […], "page": …, "total": …}.

• Page numbering differs:

  • 1-based (first page = 1): users, devices, channels, channel lists.

  • 0-based (first page = 0): assets, bundles, cues, asset schedules.

• Always send pageSize, and keep reading until you have total items.

18. Network requirements

All device connections are outbound. No inbound port from the internet is needed at the site. For the Portal server's own requirements, see the deployment instructions.

Allow these destinations by host name where possible, because IP addresses can change. Devices obtain their address by DHCP unless set to static (6.5). Firewalls and proxies that inspect or re-sign TLS traffic break the device's connection to the Portal.

More details: RetailPlayer Network Requirements.

19. Troubleshooting

The full guide is the Setup & Troubleshooting Guide. The most common cases are below.

19.1 No Sonic IP announcement

• Check the audio chain: cable, amplifier input and volume.

• Make sure Sonic IP is enabled. It is always on after a factory reset.

• No announcement usually means the device did not get an IP address. Check:

  • the cable and switch port;

  • that a DHCP server is present, and its lease table;

  • MAC filtering;

  • the VLAN.

• On Wi-Fi, check the SSID, the password and the signal.

19.2 Red LED

A red LED for more than 5 minutes after power-up indicates a hardware or storage-card fault.

1. Power-cycle the device.

2. If the LED stays red, contact Barix support with the device's MAC address.

19.3 The device has an IP address but stays offline in the Portal

1. Wait 7 minutes after power-up.

2. Check that the device is registered in the Portal with the correct MAC address. Then power-cycle it: firmware before 8.0.7 checks the registry only once per boot.

3. Check the firewall against chapter 18, in this order: DNS, NTP, Flexa Registry, Portal.

4. Open the device's web interface (enable it in the Portal if needed). In System Status, check the Portal URL:

   • empty: the device has not reached the Flexa Registry;

   • filled: the device knows its Portal but cannot connect.

5. Download the logs (6.9). Search retailplayer.log for:

   • "Portal URL": the address received from the registry.

   • "Flexa": the registry lookup.

   • "SSL Exception … certificate verify failed": usually a wrong device clock. Check NTP (UDP 123) and DNS.

   • "websocket": should change from CONNECTING to CONNECTED.

   • "portal is ALIVE": the connection is up.

6. Make sure the firmware is 7.0.4 or later, preferably the latest.

19.4 No audio, or the wrong audio

• Device status › Active resource shows what the device is trying to play.

• None:

  • check the opening hours: outside them the device is silent;

  • check that a channel list is assigned;

  • check that the volume is not 0 and the device is not muted.

• Fallback URL or failover tracks: the main stream is unreachable. Test the stream URL in a browser on the same network.

• Store & Play: check the status panel (8.6) for errors. Check the playlist rules (9.2) and the authentication.

• USB tracks play instead of the channel when Play USB tracks is on and a stick with audio files is inserted.

19.5 Scheduled audio does not play at the expected time

• Check the device's time zone (Settings). Schedules run in device local time.

• Check that the schedule is assigned to the device, and that the component is enabled and within its date range.

• Check that the asset is enabled on the device (Assets tab).

• Check that the device has downloaded the assets: device assets, storage.

19.6 Hum or noise on the output

Usually a ground loop between the device and the amplifier. To fix it:

• connect all equipment to the same power strip;

• fit a ground-loop isolator between the player and the amplifier;

• use shielded cables, kept away from mains cables.

See Why does my RetailPlayer audio output present static noise?.

19.7 Before contacting support

• [ ] Waited at least 7 minutes after power-up

• [ ] Firewall allows the destinations in chapter 18

• [ ] Firmware 7.0.4 or later (latest recommended)

• [ ] IP address, gateway and DNS correct

• [ ] Time synchronisation (NTP) working

• [ ] The device is registered in the Portal with the right MAC address

Send to support:

• the log archive (6.9 or 8.9), unchanged;

• screenshots of the device's System Status and of the Portal's device status;

• a description of the network and of the steps you took.

20. Security information

• Encrypted connection.

  • Devices connect to the Portal only over TLS (HTTPS / secure WebSocket).

  • Each device carries a Barix-issued client certificate, installed with the firmware.

  • Connections without a valid Barix certificate are rejected.

• Unique passwords. Every device made since 2019 has its own random default password, printed on the label. Change it, and use strong passwords for the device and the Portal.

• Local web interface off by default for devices added in the Portal. Enable it only when needed. HTTPS can be chosen for it (6.5).

• Closed firmware.

  • The firmware is Linux-based and accepts only Barix-signed updates.

  • Security updates come with firmware updates.

  • No third-party software can be installed.

  • SSH access is off and should be enabled only at Barix support's request.

• Outbound only. Devices need no inbound connections from the internet.

• Your data. On a self-hosted Portal, all configuration, audio and logs stay on your server.

More information: RetailPlayer device security.

21. Support and further documentation

Support

• Devices and self-hosted Portals: your local Barix distributor (barix.com/buy) or support@barix.com.

• StreamGuys-hosted Portals: StreamGuys support.

Documentation

• RetailPlayer Knowledge Base

• Quick Install Guide

• Release documentation and firmware

• Video tutorials

• Self-hosted deployment instructions

• Self-hosting technical requirements

• Setup & Troubleshooting Guide

• Network requirements

• Find the IP address with the Discovery Tool

• Store & Play explained

• Scheduling messages and assets

• Password issues

• Hard refresh your browser

• Advanced BGM / paging system with RTP forwarding

• Managed hosting: StreamGuys RetailPlayer

22. Appendix: reference tables

22.1 Device factory defaults (firmware 8.0.12)

22.2 Portal defaults for a new device

22.3 Timings