Media Session API
Audience: End users and non-technical stakeholders Last Updated: 2026-04-05 Version: 2.0.0
Overview
Llamafin integrates deeply with your device's native media controls, allowing you to manage your music playback from outside the app. Whether you are driving and using Android Auto or Apple CarPlay, wearing Bluetooth headphones with media buttons, or using your phone's lock screen, Llamafin responds to your commands and keeps your OS informed about what is playing.
This integration goes beyond simple play and pause -- it provides rich metadata (song title, artist, album artwork), queue previews, and even voice search support, creating a seamless experience across the app and your operating system.
Key Concepts
1. Lock Screen Controls
When music is playing in Llamafin, your device's lock screen displays:
| Control | Description |
|---|---|
| Album Artwork | The current song's album art (or generated artwork if unavailable) |
| Song Title | The name of the currently playing track |
| Artist Name | The performing artist |
| Album Name | The album the track belongs to |
| Play/Pause | Tap to toggle playback |
| Next/Previous | Skip to the next or previous track |
| Seek Controls | Rewind or fast-forward by a fixed interval |
| Progress Bar | Shows how far through the track you are (on supported devices) |
These controls work even when the app is in the background, allowing you to manage playback without unlocking your phone.
2. Car UI Integration
When you connect your phone to your car's infotainment system, Llamafin provides a rich browsing experience through Android Auto and Apple CarPlay:
| Feature | Description |
|---|---|
| Home Screen | Quick access to latest, recently played, and frequently played music |
| Library Browsing | Browse albums, artists, songs, playlists, genres, and folders |
| Album Detail | View and play all songs from an album |
| Artist Detail | View and play all albums from an artist |
| Playlist Detail | View and play songs from a playlist |
| Genre Detail | View and play songs from a genre |
| Downloads | Browse and play your downloaded content |
| Search Suggestions | Quick access to popular music suggestions |
| Play All | Play all tracks in a list from the start |
| Shuffle | Shuffle all tracks in a list |
3. Headset and Bluetooth Remote Controls
Physical media buttons on your headphones, steering wheel controls, or Bluetooth speaker buttons are all recognised:
| Button | Action |
|---|---|
| Play/Pause | Toggles playback |
| Next Track | Skips to the next song |
| Previous Track | Returns to the start of the current song, or goes to the previous song |
| Seek Forward | Skips ahead by a short interval |
| Seek Backward | Rewinds by a short interval |
4. Voice Search
Your device's voice assistant (Google Assistant on Android, Siri on iOS) can search and play music from Llamafin:
- Say "Play [song name] on Llamafin" to start playback
- Say "Play [artist name] on Llamafin" to play music from that artist
- Say "Search Llamafin for [query]" to browse results
5. Queue synchronisation (Car UI)
When connected to a car system, the upcoming tracks in your Llamafin queue are shown in the car's native "Now Playing" interface. The next 15 tracks are sent to the car UI, showing you what is coming up and allowing you to select any queued track directly.
6. Favorite Toggle (Native Controls)
On supported platforms, you can mark a song as a favorite directly from the native notification or lock screen controls. The favorite status is synced with your Jellyfin server.
7. Repeat Mode Cycling (Native Controls)
On supported platforms, you can cycle through repeat modes (Off → Repeat All → Repeat One) from the native notification area.
8. Keep-Alive Service (Android)
On Android, Llamafin can run a background service that prevents the operating system from stopping the app while music is playing. This is especially important when:
- Your phone is locked and in your pocket
- You are using Android Auto
- Other apps are consuming resources
The keep-alive service can be:
- Always on: Enabled in Settings > Advanced
- Auto-enabled: Forced on when Android Auto or CarPlay is connected
- User controlled: Toggled on or off based on your preference
9. 30-Minute Timeout
If you pause or stop playback and do not resume for 30 continuous minutes (and no car system is connected), Llamafin clears the lock screen notification to avoid showing stale information. Your queue and playback position are preserved -- you can resume instantly by reopening the app.
10. Notification Icon
The notification icon shown in your device's status bar is configured in the app settings. This icon appears alongside playback controls when music is playing in the background.
Configuration
Media Session Settings
| Setting | Location | Description |
|---|---|---|
| Keep App Alive | Settings > Advanced | Enable the Android background service to prevent the app from being killed while playing music |
What Affects Media Session
| Setting | Impact on Media Session |
|---|---|
| Appearance (Background) | Affects the fallback artwork generated when no album art is available |
| Player Name | Identifies your device to the Jellyfin server (visible in active sessions) |
| Shuffle Mode | Synchronised with car UI "Shuffle" header button |
| Repeat Mode | Synchronised with native notification repeat icon |
How It Works
Lock Screen Control Flow
1. You start playing music in Llamafin
↓
2. App sends metadata to native OS layer:
- Song title, artist, album
- Album artwork (with multi-level fallback)
- Track duration
↓
3. OS displays lock screen media controls
↓
4. You interact with lock screen (tap play, skip, seek)
↓
5. Native OS sends event back to Llamafin
↓
6. Llamafin translates the event into app action:
- "Play" → Resume playback
- "Next" → Advance to next track
- "Seek to 2:30" → Jump to that position
↓
7. App updates playback state
↓
8. App sends updated metadata and status back to OS
↓
9. Lock screen display updates
Car UI Browsing Flow
1. You connect your phone to your car (Android Auto or CarPlay)
↓
2. Car UI displays Llamafin as a music source
↓
3. You tap to browse your library
↓
4. Car requests a page of content (e.g., "Show me Albums")
↓
5. Llamafin checks if data is already loaded:
- If yes: sends it immediately
- If no: fetches from Jellyfin server, then sends
↓
6. Content transformed for car display:
- Album covers resized
- Titles formatted appropriately
- "Play All" and "Shuffle" headers added
↓
7. Car UI displays the browse page
↓
8. You tap an album
↓
9. Car requests album detail
↓
10. Llamafin sends the album's song list
↓
11. You tap "Play All" or an individual song
↓
12. Llamafin begins playback, queue appears in car's "Now Playing"
Artwork Resolution
Llamafin uses a multi-level fallback strategy to ensure artwork is always displayed:
1. Local downloaded artwork (if available)
↓ If not found
2. Album's primary image from Jellyfin server
↓ If not found
3. Artist's primary image
↓ If not found
4. Album backdrop image
↓ If not found
5. Generated artwork from first letters of song/artist name (SVG, 512×512)
↓ If not found
6. Llamafin app logo
This means you always see something meaningful on your lock screen, even if the original artwork is unavailable.
Voice Search Flow
1. You activate Google Assistant or Siri
↓
2. You say "Play [something] on Llamafin"
↓
3. Voice assistant sends query to Llamafin
↓
4. App performs search with the query
↓
5. Search results returned
↓
6. Playback begins with best match
Keep-Alive Behaviour
App starts
↓
Check "Keep App Alive" setting
↓
If enabled:
- Native background service activated
- OS prevented from killing app
- Music continues in background
↓
If Android Auto/CarPlay connects:
- Keep-alive forced ON (regardless of setting)
↓
If Android Auto/CarPlay disconnects:
- Keep-alive reverts to user setting
↓
If setting disabled while car disconnected:
- Background service stopped
- OS may kill app when resources are low
Integration with Other Features
| Feature | Media Session Integration | Description |
|---|---|---|
| Player & Queue | Metadata source, queue sync | Current track info, playback state, and upcoming tracks sent to native OS |
| Audio Engine | Playback status sync | Play/pause/buffering state, seek position, playback rate |
| Downloads | Offline car browsing | Download containers available in car UI even when offline |
| Library | Car UI browsing | Albums, artists, songs, playlists, genres, folders browsable from car |
| Search | Voice search, suggestions | Voice queries trigger search; suggestions sent to car UI |
| Settings | Keep-alive toggle | User controls background service behaviour |
| Device | Platform detection | Artwork handling differs between web, mobile, and desktop platforms |
| System | Server URL, auth | Artwork fetched from authenticated Jellyfin server |
Error Handling & Reliability
Artwork Failures
| Scenario | Fallback Behaviour |
|---|---|
| Local artwork file corrupted | Fetches from Jellyfin server |
| Server unreachable | Generates artwork from text (initials) |
| Text generation fails | Uses bundled Llamafin logo |
Plugin initialisation Failure
| Scenario | User Experience |
|---|---|
| Native plugin fails to load | Error toast displayed; app continues to function without native controls |
| Listener attachment fails | Lock screen and car UI controls unavailable until app restart |
Malformed Commands
| Scenario | Behaviour |
|---|---|
| Unrecognized media ID from car UI | Logged as warning; no action taken |
| Missing context (user ID, library ID) | Logged; request ignored until context available |
30-Minute Timeout
| Scenario | Behaviour |
|---|---|
| Playback paused for 30 minutes (no car connected) | Lock screen notification cleared; queue preserved for instant resume |
| Playback paused for 30 minutes (car connected) | Timeout bypassed; notification remains active for car UI |
Technical Specifications
| Specification | Value | Description |
|---|---|---|
| Native Plugin | llamafin-media-session (custom Capacitor plugin) | Not the standard Web Media Session API |
| Supported Platforms | Android, iOS, Web, Electron | Full features on mobile, limited on web/desktop |
| Car UI Systems | Android Auto, Apple CarPlay | Full library browsing |
| Lock Screen Controls | Play, Pause, Next, Previous, Seek | Platform-dependent |
| Queue Sync | 15 upcoming tracks | Shown in car UI "Now Playing" |
| Artwork Fallback Levels | 7 | From local file to generated SVG to app logo |
| Generated Artwork Size | 512 × 512 pixels | SVG-to-PNG conversion |
| Pause Timeout | 30 minutes | Before lock screen notification cleared |
| Seek Debounce | 50 milliseconds | Before syncing seek position to OS |
| Queue Sync Debounce | 250 milliseconds | Before syncing queue to OS |
| Max Car Browse Items | 100 per page | Items beyond this show "Continue on Phone" |
| Keep-Alive Service | Android only | Background service to prevent app termination |
| Voice Assistants | Google Assistant, Siri | Via native plugin integration |
| Notification Icon | ic_stat_notification | Configured in Capacitor config |
Known Limitations
Platform Coverage
- Web and Desktop: The custom Capacitor plugin may have limited or no-op functionality on web and Electron platforms. Lock screen controls may not be available.
- iOS CarPlay: Keep-alive behaviour may differ from Android due to platform restrictions.
Media Session Configuration
- No in-app controls: All media session configuration is managed through native OS interfaces. There are no settings within Llamafin to customise lock screen behaviour.
- Hardcoded icons: Some car UI icons use hardcoded Android resource URIs and are not platform-abstracted.
Queue and Timeout
- Queue only syncs to car: The upcoming queue is only sent to the car UI when Android Auto or CarPlay is connected. It is not visible on the standard lock screen.
- No smart timeout on car: The 30-minute pause timeout is skipped when a car is connected. If you park and walk away, the lock screen notification may remain indefinitely.
Related Documentation
- Player & Queue -- Playback controls, queue management
- Audio Engine -- Playback status, seek behaviour
- Offline Support -- Offline playback, downloaded content
- Downloads System -- Download container browsing in car UI