qobuz_api_rust/
metadata.rs

1/// Metadata handling utilities for Qobuz audio content.
2///
3/// This module provides comprehensive functionality for working with metadata from
4/// Qobuz music content, including extraction from API responses and embedding into
5/// audio files. The module is designed to handle various audio formats (FLAC, MP3, etc.)
6/// with format-specific tagging approaches that ensure compatibility with the original
7/// C# Qobuz implementation.
8///
9/// # Overview
10///
11/// The metadata module consists of three main components:
12///
13/// - **Configuration** ([`MetadataConfig`](config/struct.MetadataConfig.html)): Controls which metadata fields are embedded in audio files
14/// - **Embedding** ([`embed_metadata_in_file`](embedder/fn.embed_metadata_in_file.html)): Embeds comprehensive metadata into audio files
15/// - **Extraction** ([`extract_comprehensive_metadata`](extractor/fn.extract_comprehensive_metadata.html)): Extracts metadata from Qobuz API responses into a standardized format
16///
17/// # Usage Examples
18///
19/// ## Basic metadata embedding
20///
21/// ```rust,no_run
22/// use qobuz_api_rust::{models::{Track, Album, Artist}, metadata::{embed_metadata_in_file, MetadataConfig}};
23///
24/// // Assuming you have track, album, and artist data from the Qobuz API
25/// // let track: Track = /* ... */;
26/// // let album: Album = /* ... */;
27/// // let artist: Artist = /* ... */;
28///
29/// // Use default configuration (most fields enabled, comment disabled)
30/// let config = MetadataConfig::default();
31///
32/// // Embed metadata into an audio file
33/// tokio_test::block_on(async {
34///     embed_metadata_in_file("path/to/audio.flac", &track, &album, &artist, &config).await.unwrap();
35/// });
36/// ```
37///
38/// ## Custom metadata configuration
39///
40/// ```rust
41/// use qobuz_api_rust::metadata::MetadataConfig;
42///
43/// // Create a minimal configuration
44/// let minimal_config = MetadataConfig {
45///     album_artist: true,
46///     artist: true,
47///     track_title: true,
48///     album: true,
49///     track_number: true,
50///     disc_number: true,
51///     cover_art: true,
52///     ..Default::default()
53/// };
54///
55/// // Or disable all metadata embedding
56/// let no_metadata_config = MetadataConfig {
57///     album_artist: false,
58///     artist: false,
59///     track_title: false,
60///     track_number: false,
61///     track_total: false,
62///     disc_number: false,
63///     disc_total: false,
64///     album: false,
65///     explicit: false,
66///     upc: false,
67///     isrc: false,
68///     copyright: false,
69///     composer: false,
70///     genre: false,
71///     release_year: false,
72///     release_date: false,
73///     comment: false,
74///     cover_art: false,
75///     label: false,
76///     producer: false,
77///     involved_people: false,
78///     url: false,
79///     media_type: false,
80/// };
81/// ```
82///
83/// ## Metadata extraction for processing
84///
85/// ```rust
86/// use qobuz_api_rust::{models::{Track, Album, Artist}, metadata::extract_comprehensive_metadata};
87///
88/// // Assuming you have track, album, and artist data
89/// // let track: Track = /* ... */;
90/// // let album: Album = /* ... */;
91/// // let artist: Artist = /* ... */;
92///
93/// let metadata = extract_comprehensive_metadata(&track, &album, &artist);
94/// if let Some(title) = metadata.get("TITLE") {
95///     println!("Track title: {}", title);
96/// }
97/// ```
98///
99/// # Format Considerations
100///
101/// The library handles different audio formats with appropriate tagging standards:
102///
103/// - **FLAC**: Uses Vorbis Comments format with specific field mappings
104/// - **MP3**: Uses ID3v2 format with standard frame mappings
105/// - **Other formats**: Defaults to ID3v2-compatible tagging
106///
107/// Some metadata fields have format-specific behavior to match the original C#
108/// implementation, particularly around artist naming conventions and composer handling.
109///
110/// # Features
111///
112/// - **Comprehensive metadata support**: Handles all major Qobuz metadata fields
113/// - **Format-specific tagging**: Proper tag mapping for different audio formats
114/// - **Cover art embedding**: Downloads and embeds highest quality available artwork
115/// - **Duplicate prevention**: Intelligent deduplication of artists and composers
116/// - **Classical music support**: Special handling for conductor and orchestra roles
117/// - **Configurable embedding**: Fine-grained control over which fields to embed
118///
119/// # Re-exports
120///
121/// The most commonly used items are re-exported at the crate root for convenience:
122/// - [`MetadataConfig`](config/struct.MetadataConfig.html)
123/// - [`embed_metadata_in_file`](embedder/fn.embed_metadata_in_file.html)
124/// - [`extract_comprehensive_metadata`](extractor/fn.extract_comprehensive_metadata.html)
125pub mod config;
126/// Audio file metadata embedding functionality.
127///
128/// Provides the [`embed_metadata_in_file`] function for embedding comprehensive
129/// metadata from Qobuz API responses into audio files with format-specific handling.
130pub mod embedder;
131/// Metadata extraction from Qobuz API responses.
132///
133/// Provides the [`extract_comprehensive_metadata`] function for extracting
134/// metadata from Qobuz API response objects into a standardized key-value format.
135pub mod extractor;
136
137pub use {
138    config::MetadataConfig, embedder::embed_metadata_in_file,
139    extractor::extract_comprehensive_metadata,
140};
qobuz_api_rust/metadata.rs

qobuz_api_rust/
metadata.rs
