This crate provides the foundational abstractions for different music sources in the PMOMusic ecosystem, such as Radio Paradise, Qobuz, local playlists, etc.

Features

FIFO Support: Dynamic audio sources using pmoplaylist for streaming
Container/Item Navigation: Browse and search using DIDL-Lite format (pmodidl)
Cache Integration: Automatic URI resolution with pmoaudiocache and pmocovers
Change Tracking: update_id and last_change for UPnP notifications
Send + Sync: Ready for async servers

Architecture

The MusicSource trait provides a unified interface for all music sources:

┌─────────────────────────────────────┐
│       MusicSource Trait             │
├─────────────────────────────────────┤
│ • Basic Info (name, id, image)      │
│ • ContentDirectory (browse, search) │
│ • URI Resolution (with caching)     │
│ • FIFO Management                   │
│ • Change Tracking                   │
└─────────────────────────────────────┘
         ▲         ▲         ▲
         │         │         │
    ┌────┴───┐ ┌──┴────┐ ┌──┴─────┐
    │ Radio  │ │ Qobuz │ │ Local  │
    │Paradise│ │       │ │Playlist│
    └────────┘ └───────┘ └────────┘

Quick Start

Implementing a Music Source

use pmosource::{async_trait, MusicSource, BrowseResult, Result};
use pmodidl::{Container, Item};
use pmoplaylist::FifoPlaylist;
use std::time::SystemTime;

#[derive(Debug)]
pub struct MyRadioSource {
    playlist: FifoPlaylist,
    // ... other fields
}

#[async_trait]
impl MusicSource for MyRadioSource {
    fn name(&self) -> &str {
        "My Radio"
    }

    fn id(&self) -> &str {
        "my-radio"
    }

    fn default_image(&self) -> &[u8] {
        include_bytes!("../assets/my-radio.webp")
    }

    async fn root_container(&self) -> Result<Container> {
        Ok(self.playlist.as_container().await)
    }

    async fn browse(&self, object_id: &str) -> Result<BrowseResult> {
        // Return items from FIFO
        let tracks = self.playlist.get_items(0, 100).await;
        // Convert tracks to Items...
        Ok(BrowseResult::Items(items))
    }

    async fn resolve_uri(&self, object_id: &str) -> Result<String> {
        // Return cached URI if available, or original URI
        Ok(format!("http://cache-server/audio/{}", object_id))
    }

    fn supports_fifo(&self) -> bool {
        true
    }

    async fn append_track(&self, track: Item) -> Result<()> {
        // Convert Item to Track and add to playlist
        self.playlist.append_track(pmo_track).await;
        Ok(())
    }

    async fn remove_oldest(&self) -> Result<Option<Item>> {
        if let Some(track) = self.playlist.remove_oldest().await {
            // Convert Track to Item and return
            Ok(Some(item))
        } else {
            Ok(None)
        }
    }

    async fn update_id(&self) -> u32 {
        self.playlist.update_id().await
    }

    async fn last_change(&self) -> Option<SystemTime> {
        Some(self.playlist.last_change().await)
    }

    async fn get_items(&self, offset: usize, count: usize) -> Result<Vec<Item>> {
        let tracks = self.playlist.get_items(offset, count).await;
        // Convert tracks to Items...
        Ok(items)
    }
}

Using a Music Source

use pmosource::MusicSource;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let source = MyRadioSource::new("http://localhost:8080");

    // Get source info
    println!("Source: {}", source.name());
    println!("ID: {}", source.id());

    // Get root container for ContentDirectory
    let root = source.root_container().await?;
    println!("Root: {} ({})", root.title, root.id);

    // Browse items
    let result = source.browse(&root.id).await?;
    for item in result.items() {
        println!("Track: {}", item.title);
    }

    // Resolve audio URI
    let uri = source.resolve_uri("track-123").await?;
    println!("Stream from: {}", uri);

    // Track changes
    println!("Update ID: {}", source.update_id().await);

    Ok(())
}

Trait Methods

Basic Information

name() -> &str: Human-readable name
id() -> &str: Unique identifier (e.g., "radio-paradise")
default_image() -> &[u8]: Embedded WebP logo (300x300px)
default_image_mime_type() -> &str: MIME type (default: "image/webp")

root_container() -> Container: Root container for UPnP ContentDirectory
browse(object_id: &str) -> BrowseResult: Browse containers/items
resolve_uri(object_id: &str) -> String: Get audio URI (cached or original)

FIFO Support (Dynamic Sources)

supports_fifo() -> bool: Whether this source uses a FIFO
append_track(track: Item): Add track to FIFO (auto-removes oldest if full)
remove_oldest() -> Option<Item>: Remove oldest track from FIFO

Change Tracking

update_id() -> u32: Increments on each change (for UPnP notifications)
last_change() -> Option<SystemTime>: Timestamp of last modification

Pagination & Search

get_items(offset: usize, count: usize) -> Vec<Item>: Paginated browsing
search(query: &str) -> BrowseResult: Search (optional, default: not supported)

Integration with PMOMusic Ecosystem

With pmoplaylist

Sources that support FIFO (radios, streaming services) use pmoplaylist::FifoPlaylist to manage dynamic track lists:

use pmoplaylist::{FifoPlaylist, Track};

let playlist = FifoPlaylist::new(
    "my-radio".to_string(),
    "My Radio".to_string(),
    50, // capacity
    DEFAULT_IMAGE,
);

// Add tracks
playlist.append_track(Track::new("id", "title", "uri")).await;

// Tracks automatically removed when capacity reached

With pmoaudiocache

When the cache feature is enabled, sources can integrate with pmoaudiocache to:

Cache audio files locally (with FLAC conversion)
Serve from local cache instead of re-streaming
Extract and merge metadata

// Resolve URI checks cache first
async fn resolve_uri(&self, object_id: &str) -> Result<String> {
    if let Some(cached_pk) = self.get_cached_pk(object_id).await {
        Ok(format!("{}/audio/cache/{}", self.cache_base_url, cached_pk))
    } else {
        Ok(self.get_original_uri(object_id))
    }
}

With pmocovers

When the cache feature is enabled, sources can integrate with pmocovers to:

Cache album art locally (with WebP conversion)
Generate multiple size variants
Serve optimized images

With pmodidl

All sources use pmodidl for DIDL-Lite generation compatible with UPnP/DLNA.

Examples

Radio Paradise

See examples/radio_paradise.rs for a complete implementation of a streaming radio source with:

FIFO management using pmoplaylist
Simulated cache integration
Full DIDL-Lite export
Change tracking

Run the example:

cargo run --example radio_paradise

Design Patterns

Static Sources (Albums, Local Playlists)

impl MusicSource for LocalAlbum {
    fn supports_fifo(&self) -> bool {
        false  // Static content
    }

    async fn append_track(&self, _: Item) -> Result<()> {
        Err(MusicSourceError::FifoNotSupported)
    }

    async fn update_id(&self) -> u32 {
        0  // Never changes
    }
}

Dynamic Sources (Radios, Streaming Services)

impl MusicSource for RadioSource {
    fn supports_fifo(&self) -> bool {
        true  // Dynamic content
    }

    async fn append_track(&self, track: Item) -> Result<()> {
        // Add to pmoplaylist::FifoPlaylist
        self.playlist.append_track(converted_track).await;
        Ok(())
    }

    async fn update_id(&self) -> u32 {
        self.playlist.update_id().await
    }
}

Thread Safety

All MusicSource implementations must be Send + Sync for use in async servers.

License

MIT OR Apache-2.0

README.md

pmosource - Music Source Abstraction for PMOMusic