qobuz_api_rust/metadata/config.rs
1use serde::{Deserialize, Serialize};
2
3/// Configuration for metadata embedding in audio files.
4///
5/// This struct controls which metadata tags are written to audio files during the
6/// metadata embedding process. It provides fine-grained control over the embedding
7/// of various metadata fields, allowing users to customize which information is
8/// included in their audio files.
9///
10/// The configuration mirrors the options available in the original C# Qobuz
11/// application, ensuring compatibility and consistent behavior across implementations.
12/// Each field corresponds to a specific metadata tag that can be embedded in
13/// supported audio formats (FLAC, MP3, etc.).
14///
15/// # Usage
16///
17/// The [`MetadataConfig`] is used with the [`embed_metadata_in_file`] function
18/// to control which metadata fields are embedded:
19///
20/// ```rust
21/// use qobuz_api_rust::metadata::{MetadataConfig, embed_metadata_in_file};
22///
23/// // Create a custom configuration
24/// let mut config = MetadataConfig::default();
25/// config.comment = true; // Enable comment embedding
26/// config.explicit = false; // Disable explicit content flag
27///
28/// // Use the configuration when embedding metadata
29/// // embed_metadata_in_file("path/to/file.flac", &track, &album, &artist, &config).await?;
30/// ```
31///
32/// # Format Considerations
33///
34/// The actual metadata tags written depend on the audio file format:
35/// - **FLAC**: Uses Vorbis Comments format
36/// - **MP3**: Uses ID3v2 format
37/// - **Other formats**: Default to ID3v2-compatible tagging
38///
39/// Some fields may have format-specific behavior (e.g., album artist handling
40/// differs between FLAC and MP3 to match the original C# implementation).
41///
42/// # Examples
43///
44/// Create a minimal configuration that only embeds essential metadata:
45///
46/// ```rust
47/// use qobuz_api_rust::metadata::MetadataConfig;
48///
49/// let minimal_config = MetadataConfig {
50/// album_artist: true,
51/// artist: true,
52/// track_title: true,
53/// album: true,
54/// track_number: true,
55/// disc_number: true,
56/// cover_art: true,
57/// ..Default::default()
58/// };
59/// ```
60///
61/// Disable all metadata embedding (useful for privacy or minimal file size):
62///
63/// ```rust
64/// use qobuz_api_rust::metadata::MetadataConfig;
65///
66/// let no_metadata_config = MetadataConfig {
67/// album_artist: false,
68/// artist: false,
69/// track_title: false,
70/// track_number: false,
71/// track_total: false,
72/// disc_number: false,
73/// disc_total: false,
74/// album: false,
75/// explicit: false,
76/// upc: false,
77/// isrc: false,
78/// copyright: false,
79/// composer: false,
80/// genre: false,
81/// release_year: false,
82/// release_date: false,
83/// comment: false,
84/// cover_art: false,
85/// label: false,
86/// producer: false,
87/// involved_people: false,
88/// url: false,
89/// media_type: false,
90/// };
91/// ```
92#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
93pub struct MetadataConfig {
94 /// Whether to embed the album artist name.
95 ///
96 /// For FLAC files, this uses a single album artist name with conductor priority
97 /// for classical music. For MP3 files, this combines all main artists with "/"
98 /// separator.
99 pub album_artist: bool,
100 /// Whether to embed the track artist(s) name(s).
101 ///
102 /// Combines artists from performers, main artist, and album artists while
103 /// avoiding duplicates. Uses ", " separator for FLAC and "/" for MP3.
104 pub artist: bool,
105 /// Whether to embed the track title.
106 ///
107 /// Includes the version information (e.g., "Remastered", "Live") if available,
108 /// formatted as "Title (Version)".
109 pub track_title: bool,
110 /// Whether to embed the track number within the album.
111 ///
112 /// Corresponds to the track's position in the album track listing.
113 pub track_number: bool,
114 /// Whether to embed the total number of tracks in the album.
115 ///
116 /// Indicates the complete track count for the album.
117 pub track_total: bool,
118 /// Whether to embed the disc number for multi-disc albums.
119 ///
120 /// Also known as "media number" in Qobuz API terminology.
121 pub disc_number: bool,
122 /// Whether to embed the total number of discs in the album.
123 ///
124 /// Indicates the complete disc count for multi-disc albums.
125 pub disc_total: bool,
126 /// Whether to embed the album title.
127 ///
128 /// Includes the version information if available, formatted as "Album Title (Version)".
129 pub album: bool,
130 /// Whether to embed explicit content information.
131 ///
132 /// Indicates if the track contains explicit content (parental warning).
133 pub explicit: bool,
134 /// Whether to embed the Universal Product Code (UPC).
135 ///
136 /// A barcode identifier for the album product.
137 pub upc: bool,
138 /// Whether to embed the International Standard Recording Code (ISRC).
139 ///
140 /// A unique identifier for the specific sound recording.
141 pub isrc: bool,
142 /// Whether to embed copyright information.
143 ///
144 /// Contains the copyright notice for the track.
145 pub copyright: bool,
146 /// Whether to embed composer information.
147 ///
148 /// Combines composers from performers, track composer, and album composer
149 /// while avoiding duplicates. Uses "/" separator for multiple composers.
150 pub composer: bool,
151 /// Whether to embed genre information.
152 ///
153 /// Contains the primary musical genre of the album/track.
154 pub genre: bool,
155 /// Whether to embed the release year.
156 ///
157 /// Extracted from the most relevant date field (album release dates preferred,
158 /// then track release dates, then timestamp).
159 pub release_year: bool,
160 /// Whether to embed the full release date.
161 ///
162 /// For FLAC files, this uses the RecordingDate field (DATE in Vorbis Comments).
163 /// For MP3 files, this uses the ReleaseDate field (TDRL in ID3v2).
164 pub release_date: bool,
165 /// Whether to embed comment information.
166 ///
167 /// **Note**: Disabled by default to match common user preferences and the
168 /// original C# application defaults.
169 pub comment: bool,
170 /// Whether to embed album cover artwork.
171 ///
172 /// Downloads and embeds the highest quality available album cover image,
173 /// preferring mega > extralarge > large > medium > small > thumbnail sizes.
174 pub cover_art: bool,
175 /// Whether to embed record label information.
176 ///
177 /// Contains the name of the record label that released the album.
178 pub label: bool,
179 /// Whether to embed producer information.
180 ///
181 /// **Note**: Only embedded in FLAC files (as PRODUCER Vorbis Comments field).
182 /// Extracted from performers with "Producer" role.
183 pub producer: bool,
184 /// Whether to embed involved people information.
185 ///
186 /// Contains the complete performers string with names and roles
187 /// (e.g., "Artist Name, MainArtist - Producer Name, Producer").
188 pub involved_people: bool,
189 /// Whether to embed the Qobuz product URL.
190 ///
191 /// Creates a commercial information URL pointing to the album's Qobuz page.
192 pub url: bool,
193 /// Whether to embed media type information.
194 ///
195 /// Uses the album's release_type if available, otherwise falls back to
196 /// product_type. Common values include "album", "single", "compilation", etc.
197 pub media_type: bool,
198}
199
200impl Default for MetadataConfig {
201 /// Returns the default metadata configuration.
202 ///
203 /// The default configuration enables most metadata fields to provide
204 /// comprehensive metadata embedding, matching the behavior of the original
205 /// C# Qobuz application. The only exception is the `comment` field, which
206 /// is disabled by default based on common user preferences.
207 ///
208 /// # Returns
209 ///
210 /// A [`MetadataConfig`] instance with all fields set to `true` except
211 /// `comment` which is set to `false`.
212 fn default() -> Self {
213 Self {
214 album_artist: true,
215 artist: true,
216 track_title: true,
217 track_number: true,
218 track_total: true,
219 disc_number: true,
220 disc_total: true,
221 album: true,
222 explicit: true,
223 upc: true,
224 isrc: true,
225 copyright: true,
226 composer: true,
227 genre: true,
228 release_year: true,
229 release_date: true,
230 comment: false, // Default to false as per C# app defaults or common preference
231 cover_art: true,
232 label: true,
233 producer: true,
234 involved_people: true,
235 url: true,
236 media_type: true,
237 }
238 }
239}