Initial commit

src/provider.rs

@@ -0,0 +1,69 @@
+use serde::{Deserialize, Serialize};
+
+use crate::error::TagResult;
+
+/// A reference to a release (album) that a recording appears on.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReleaseRef {
+    pub mbid: String,
+    pub title: String,
+    pub date: Option<String>,
+    pub track_number: Option<i32>,
+}
+
+/// A recording match from a search query.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RecordingMatch {
+    pub mbid: String,
+    pub title: String,
+    pub artist: String,
+    pub artist_mbid: Option<String>,
+    pub releases: Vec<ReleaseRef>,
+    /// MusicBrainz API score (0-100).
+    pub score: u8,
+}
+
+/// A release (album) match from a search query.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReleaseMatch {
+    pub mbid: String,
+    pub title: String,
+    pub artist: String,
+    pub artist_mbid: Option<String>,
+    pub date: Option<String>,
+    pub track_count: Option<i32>,
+    pub score: u8,
+}
+
+/// Full details for a recording, retrieved by MBID.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RecordingDetails {
+    pub mbid: String,
+    pub title: String,
+    pub artist: String,
+    pub artist_mbid: Option<String>,
+    pub releases: Vec<ReleaseRef>,
+    pub duration_ms: Option<u64>,
+    pub genres: Vec<String>,
+}
+
+/// Trait for metadata lookup backends. MusicBrainz is the default implementation;
+/// others (Last.fm, Discogs, etc.) can be added later.
+pub trait MetadataProvider: Send + Sync {
+    fn search_recording(
+        &self,
+        artist: &str,
+        title: &str,
+    ) -> impl std::future::Future<Output = TagResult<Vec<RecordingMatch>>> + Send;
+
+    fn search_release(
+        &self,
+        artist: &str,
+        album: &str,
+    ) -> impl std::future::Future<Output = TagResult<Vec<ReleaseMatch>>> + Send;
+
+    fn get_recording(
+        &self,
+        mbid: &str,
+    ) -> impl std::future::Future<Output = TagResult<RecordingDetails>> + Send;
+}