276 lines
8.6 KiB
Rust
276 lines
8.6 KiB
Rust
//! # pmoparadise - Radio Paradise Client for Rust
|
|
//!
|
|
//! `pmoparadise` is an idiomatic Rust client library for accessing Radio Paradise's
|
|
//! streaming API. It provides metadata retrieval, block streaming, and optional
|
|
//! per-track extraction from FLAC blocks.
|
|
//!
|
|
//! ## Features
|
|
//!
|
|
//! - **Metadata Access**: Get current and historical block metadata with song information
|
|
//! - **Block Streaming**: Stream continuous FLAC blocks with automatic prefetching
|
|
//! - **FLAC Quality**: Lossless CD quality or better
|
|
//! - **Per-Track Extraction** (optional): Extract individual tracks from FLAC blocks
|
|
//! - **Async/Await**: Built on tokio for efficient async I/O
|
|
//! - **Type-Safe**: Strongly typed API with comprehensive error handling
|
|
//!
|
|
//! ## Quick Start
|
|
//!
|
|
//! ```no_run
|
|
//! use pmoparadise::RadioParadiseClient;
|
|
//!
|
|
//! #[tokio::main]
|
|
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! // Create a client
|
|
//! let client = RadioParadiseClient::new().await?;
|
|
//!
|
|
//! // Get what's currently playing
|
|
//! let now_playing = client.now_playing().await?;
|
|
//!
|
|
//! if let Some(song) = &now_playing.current_song {
|
|
//! println!("Now Playing: {} - {}", song.artist, song.title);
|
|
//! if let Some(album) = &song.album {
|
|
//! println!("Album: {}", album);
|
|
//! }
|
|
//! }
|
|
//!
|
|
//! // Get all songs in the current block
|
|
//! for (index, song) in now_playing.block.songs_ordered() {
|
|
//! println!(" {}. {} - {} ({}s)",
|
|
//! index,
|
|
//! song.artist,
|
|
//! song.title,
|
|
//! song.duration / 1000);
|
|
//! }
|
|
//!
|
|
//! Ok(())
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! ## Streaming Blocks
|
|
//!
|
|
//! Radio Paradise broadcasts music in continuous "blocks" - each block is a single
|
|
//! FLAC file containing multiple songs with metadata indicating timing offsets.
|
|
//!
|
|
//! ```no_run
|
|
//! use pmoparadise::RadioParadiseClient;
|
|
//! use futures::StreamExt;
|
|
//!
|
|
//! #[tokio::main]
|
|
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! let client = RadioParadiseClient::new().await?;
|
|
//! let block = client.get_block(None).await?;
|
|
//!
|
|
//! // Stream the block
|
|
//! let mut stream = client.stream_block_from_metadata(&block).await?;
|
|
//!
|
|
//! while let Some(chunk) = stream.next().await {
|
|
//! let bytes = chunk?;
|
|
//! // Feed to audio player, write to file, etc.
|
|
//! }
|
|
//!
|
|
//! Ok(())
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! ## Per-Track Extraction (Feature: `per-track`)
|
|
//!
|
|
//! **Important**: This is an advanced feature with significant tradeoffs.
|
|
//! See the [`track`] module documentation for details.
|
|
//!
|
|
//! Most applications should stream blocks and use player-based seeking instead.
|
|
//!
|
|
//! ```no_run
|
|
//! # #[cfg(feature = "per-track")]
|
|
//! # {
|
|
//! use pmoparadise::RadioParadiseClient;
|
|
//! use std::path::Path;
|
|
//!
|
|
//! #[tokio::main]
|
|
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! let client = RadioParadiseClient::new().await?;
|
|
//! let block = client.get_block(None).await?;
|
|
//!
|
|
//! // Extract first track to WAV
|
|
//! let mut track = client.open_track_stream(&block, 0).await?;
|
|
//! track.export_wav(Path::new("track.wav"))?;
|
|
//!
|
|
//! // Or get position for player-based seeking (recommended)
|
|
//! let (start, duration) = client.track_position_seconds(&block, 0)?;
|
|
//! println!("Play with: mpv --start={} --length={} {}", start, duration, block.url);
|
|
//!
|
|
//! Ok(())
|
|
//! }
|
|
//! # }
|
|
//! ```
|
|
//!
|
|
//! ## Architecture
|
|
//!
|
|
//! The API is organized into several modules:
|
|
//!
|
|
//! - [`client`]: Main HTTP client for API access
|
|
//! - [`models`]: Data structures for blocks, songs, and metadata
|
|
//! - [`stream`]: Block streaming functionality
|
|
//! - [`track`]: Per-track extraction (feature-gated)
|
|
//! - [`error`]: Error types and result aliases
|
|
//!
|
|
//! ## Radio Paradise Block Format
|
|
//!
|
|
//! Radio Paradise streams use a block-based format:
|
|
//!
|
|
//! - Each block is a single FLAC audio file
|
|
//! - Blocks contain multiple songs (typically 10-15 minutes total)
|
|
//! - Metadata includes timing offsets (`song[i].elapsed` in ms) for each song
|
|
//! - Block URLs follow the pattern: `https://apps.radioparadise.com/blocks/chan/0/4/<start>-<end>.flac`
|
|
//! - The `end_event` of one block is the `event` of the next, enabling seamless transitions
|
|
//!
|
|
//! ## Best Practices
|
|
//!
|
|
//! ### For Continuous Playback
|
|
//!
|
|
//! 1. Get current block with `get_block(None)`
|
|
//! 2. Stream block with `stream_block_from_metadata()`
|
|
//! 3. Use `prefetch_next()` to prepare the next block
|
|
//! 4. When current block ends, stream the next block seamlessly
|
|
//!
|
|
//! ### For Per-Song Seeking
|
|
//!
|
|
//! **Recommended approach** (efficient):
|
|
//! ```bash
|
|
//! # Use your audio player's seek capability
|
|
//! mpv --start=123.5 --length=234.0 <block_url>
|
|
//! ```
|
|
//!
|
|
//! **Alternative** (resource-intensive, requires `per-track` feature):
|
|
//! - Download and decode block
|
|
//! - Extract specific track to PCM/WAV
|
|
//!
|
|
//! ## Error Handling
|
|
//!
|
|
//! All operations return `Result<T, Error>` with detailed error types:
|
|
//!
|
|
//! ```no_run
|
|
//! use pmoparadise::{RadioParadiseClient, Error};
|
|
//!
|
|
//! #[tokio::main]
|
|
//! async fn main() {
|
|
//! let client = RadioParadiseClient::new().await.unwrap();
|
|
//!
|
|
//! match client.get_block(Some(99999999)).await {
|
|
//! Ok(block) => println!("Got block: {}", block.event),
|
|
//! Err(Error::Http(e)) => eprintln!("Network error: {}", e),
|
|
//! Err(Error::Json(e)) => eprintln!("Parse error: {}", e),
|
|
//! Err(e) => eprintln!("Other error: {}", e),
|
|
//! }
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! ## Audio Streaming (Feature: `pmoaudio`)
|
|
//!
|
|
//! For direct audio streaming and integration with pmoaudio pipelines,
|
|
//! use `RadioParadiseStreamSource`:
|
|
//!
|
|
//! ```no_run
|
|
//! # #[cfg(feature = "pmoaudio")]
|
|
//! # {
|
|
//! use pmoparadise::{RadioParadiseClient, RadioParadiseStreamSource};
|
|
//! use pmoaudio::pipeline::Node;
|
|
//!
|
|
//! #[tokio::main]
|
|
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! let client = RadioParadiseClient::new().await?;
|
|
//! let stream_source = RadioParadiseStreamSource::new(client, None).await?;
|
|
//!
|
|
//! // Create audio node from stream source
|
|
//! let node = Node::from_logic(stream_source);
|
|
//!
|
|
//! // Use in pmoaudio pipeline...
|
|
//!
|
|
//! Ok(())
|
|
//! }
|
|
//! # }
|
|
//! ```
|
|
//!
|
|
//! **RadioParadiseStreamSource**:
|
|
//! - Downloads and decodes FLAC blocks in real-time
|
|
//! - Automatically detects bit depth (16/24/32-bit)
|
|
//! - Inserts track boundaries with metadata
|
|
//! - Integrates seamlessly with pmoaudio pipelines
|
|
//!
|
|
//! ## Cargo Features
|
|
//!
|
|
//! - `default`: Standard metadata and streaming (no FLAC decoding)
|
|
//! - `per-track`: Enable FLAC decoding and per-track extraction (adds `claxon`, `hound`, `tempfile`)
|
|
//! - `pmoserver`: Enable REST API extension for pmoserver integration (adds `utoipa`, `axum`)
|
|
//! - `pmoaudio`: Enable RadioParadiseStreamSource for pmoaudio integration
|
|
//! - `pmoconfig`: Enable configuration integration with pmoconfig
|
|
//! - `server`: Enable RadioParadiseSource for UPnP ContentDirectory integration
|
|
//!
|
|
//! ## See Also
|
|
//!
|
|
//! - [Radio Paradise](https://radioparadise.com) - Official website
|
|
//! - [Radio Paradise API](https://api.radioparadise.com) - API documentation
|
|
|
|
pub mod channels;
|
|
pub mod client;
|
|
pub mod error;
|
|
pub mod models;
|
|
pub mod source;
|
|
|
|
#[cfg(feature = "pmoaudio")]
|
|
pub mod node_stats;
|
|
|
|
#[cfg(feature = "pmoserver")]
|
|
pub mod pmoserver_ext;
|
|
|
|
#[cfg(feature = "pmoconfig")]
|
|
pub mod config_ext;
|
|
|
|
#[cfg(feature = "pmoaudio")]
|
|
pub mod radio_paradise_stream_source;
|
|
|
|
#[cfg(feature = "pmoaudio")]
|
|
pub mod stream_channel;
|
|
|
|
#[cfg(feature = "pmoaudio")]
|
|
pub mod playlist_feeder;
|
|
|
|
// Re-exports for convenience
|
|
pub use client::{ClientBuilder, RadioParadiseClient};
|
|
pub use error::{Error, Result};
|
|
pub use models::{Block, DurationMs, EventId, NowPlaying, Song};
|
|
pub use source::RadioParadiseSource;
|
|
|
|
#[cfg(feature = "pmoaudio")]
|
|
pub use radio_paradise_stream_source::RadioParadiseStreamSource;
|
|
|
|
#[cfg(feature = "pmoaudio")]
|
|
pub use playlist_feeder::{RadioParadisePlaylistFeeder, END_OF_BLOCKS_SIGNAL};
|
|
|
|
#[cfg(feature = "pmoaudio")]
|
|
pub use stream_channel::{
|
|
HistoryFlacStream, HistoryOggStream, HistoryStreamError, ParadiseChannelManager,
|
|
ParadiseHistoryBuilder, ParadiseHistoryOptions, ParadiseStreamChannel,
|
|
ParadiseStreamChannelConfig,
|
|
};
|
|
|
|
#[cfg(feature = "pmoserver")]
|
|
pub use pmoserver_ext::{
|
|
create_api_router, RadioParadiseApiDoc, RadioParadiseExt, RadioParadiseState,
|
|
};
|
|
|
|
#[cfg(feature = "pmoconfig")]
|
|
pub use config_ext::RadioParadiseConfigExt;
|
|
|
|
// Version information
|
|
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn test_version() {
|
|
assert!(!VERSION.is_empty());
|
|
}
|
|
}
|