Music Playback
Authored by Claude · Last updated AI generated documentation written by reading the source codeCardinal Music plays audio directly in the browser. Audio streams are served by Cardinal Media Server and played back using the Web Audio API via Howler.js. The server manages the playback queue; the client manages the player state and UI.
Starting playback
Click the play button on any track, release, or artist to begin playback. Cardinal creates a playback queue on the server, then begins streaming the first track to your browser.
If the track is already loaded and paused, clicking play resumes it from where it was paused rather than starting a new queue.
Playback controls
The audio player appears while a track is active. It displays the track title, artist names, and release artwork.
| Control | Description |
|---|---|
| Previous | Go to the previous track in the queue, or restart the current track (see below) |
| Play / Pause | Resume or pause the current track |
| Next | Skip to the next track in the queue |
| Stop | Stop playback and unload the player |
| Scrubber | Click or drag to seek to any position in the track |
The scrubber displays elapsed time and total duration in MM:SS format, updated every 250 ms.
Previous track behavior
The previous control behaves differently depending on how far into the current track you are:
- Less than 8 seconds played — skips to the previous track in the queue
- 8 or more seconds played — restarts the current track from the beginning
- First track in the queue — restarts the current track regardless of position
Playback queue
Every playback session is backed by a queue created on Cardinal Media Server. The queue is server-side and persists independently of the browser tab. There are two queue types: static and dynamic.
Static queues
A static queue contains an explicit, ordered list of tracks. When you play a single track, a release, or a manual selection, Cardinal creates a static queue with those tracks in the order you initiated playback. The order does not change during the session.
Dynamic queues
A dynamic queue is generated automatically from your library. If you have multiple libraries configured, the library switcher controls which library the queue draws from.
| Name | Description |
|---|---|
| True Shuffle | Selects 200 tracks at random from your active library. Every session produces a different sequence with no repeating pattern. The pool is fixed when the queue is created and does not refill mid-session. |
Transcoding
All audio is transcoded to MP3 at 320 kbps before being sent to the browser. Transcoding happens in real time on Cardinal Media Server; no pre-converted files are stored.
This means playback format compatibility is determined by your server's ffmpeg installation, not by the browser. The following source formats are supported:
| Format | Notes |
|---|---|
| MP3 | Fully supported |
| FLAC | Fully supported |
| Opus | Fully supported |
| M4A | Supported on most systems |
| WAV | Supported on most systems |
| AAC | Supported on most systems |
See Music indexing for the full list of indexed file types.
Playback history
Cardinal Media Server records a history entry each time you play a track. History is used to calculate play counts and to track how far through a track you listened.
Progress is stored as a normalized value from 0 to 1, where 1 represents the track played to completion. A progress value above 0.991 (99.1%) is rounded up to 1.0 and counted as a full play.
History is saved at three points during playback:
| Event | When it fires |
|---|---|
| Load | When the audio stream finishes loading and playback begins |
| End | When the track plays through to the end naturally |
| Stop | When you stop the player manually |
Play count on the Tracks page reflects the total number of history entries for a track.
Concurrent streams
Cardinal Music supports multiple simultaneous audio streams. Two settings on Cardinal Media Server control this behavior:
| Setting | Default | Description |
|---|---|---|
max_concurrent_audio_streams | 1 | Maximum number of loaded players at one time |
max_concurrent_playing_audio_streams | 1 | Maximum number of players actively playing at one time |
When starting a new track would exceed max_concurrent_audio_streams, the oldest existing player is stopped and removed. When starting a new track would exceed max_concurrent_playing_audio_streams, the oldest playing player is paused rather than removed — it remains loaded and can be resumed.
Fig. 1 — Concurrent stream enforcement (default limits, max = 1 each)
Before After starting track B
───────────────────── ─────────────────────────────────────────
Player A: playing Player A: paused (auto-paused, oldest)
Player B: playing (new)
Both settings are configured in Cardinal Media Server's settings panel.
Multiple queues
When max_concurrent_audio_streams is set above 1, multiple players can be loaded simultaneously — each with its own independent queue. This allows you to, for example, have a True Shuffle session running alongside a specific album queue.
The player bar
Only one player is visible in the player bar at a time. When multiple players exist, pagination arrows appear showing the current position (e.g. 1 of 2). Use the arrows to cycle through loaded players without affecting playback.
Automatic player switching
The visible player switches automatically in two situations:
- A new player is created — the bar switches to the newest player immediately.
- A paused player resumes playing — the bar switches to the most recently active playing player.
This means starting a new track always brings that track's player into view, and resuming a paused player surfaces it without manual navigation.
Queue isolation
Each player owns exactly one queue. Controls in the player bar (previous, next, scrubber) act only on the player currently shown — they have no effect on other loaded players. Stopping a player removes it and its queue entirely; the bar reverts to the next available player.
Fig. 2 — Multi-queue state with max_concurrent_audio_streams = 2
Player A (True Shuffle): paused ← loaded, not visible
Player B (Album queue): playing ← visible in player bar (newest active)
User clicks ← arrow in player bar
→ Player A now visible; Player B still playing in background
Playback timeout
If a stream does not finish loading within the timeout window, Cardinal automatically skips to the next track in the queue and displays an error notification.
| Setting | Default | Description |
|---|---|---|
audio_playback_timeout | 8000 ms | Time to wait for a stream to load before skipping |
This setting is configured in Cardinal Media Server's settings panel. Increase it on slow connections or when streaming large uncompressed files.
Required capabilities
Playing music requires the following capabilities assigned to the user's role:
| Capability | Required for |
|---|---|
MusicApp.Login | Accessing Cardinal Music |
MusicTracks.Read | Reading track metadata |
MusicTracks.Play | Streaming audio |
MusicHistory.Create | Recording playback history |
See Role-Based Access Control for information on assigning capabilities to roles and roles to users.
Was this article helpful?