metadata-agregator/proto/metadata/v1/metadata.proto

syntax = "proto3";

package metadata.v1;

option go_package = "github.com/metadata-agregator/pkg/gen/metadata/v1;metadatav1";

// Provider identifies the upstream metadata source a request is resolved
// against. It also selects which ID namespace bare `id` fields refer to.
enum Provider {
  // Unset. Requests default to the server's configured default provider.
  PROVIDER_UNSPECIFIED = 0;
  // MusicBrainz (https://musicbrainz.org). Native IDs are MBIDs (UUIDs).
  PROVIDER_MUSICBRAINZ = 1;
}

service MetadataService {
  rpc GetArtist(GetArtistRequest) returns (GetArtistResponse);
  rpc SearchArtists(SearchArtistsRequest) returns (SearchArtistsResponse);
  rpc GetAlbum(GetAlbumRequest) returns (GetAlbumResponse);
  rpc GetArtistAlbums(GetArtistAlbumsRequest) returns (GetArtistAlbumsResponse);
  rpc GetTrack(GetTrackRequest) returns (GetTrackResponse);
  rpc GetAlbumTracks(GetAlbumTracksRequest) returns (GetAlbumTracksResponse);
  rpc SearchAlbums(SearchAlbumsRequest) returns (SearchAlbumsResponse);
  rpc SyncArtist(SyncArtistRequest) returns (SyncArtistResponse);
}

// Requests

// GetArtistRequest looks up a single artist by one of its identifiers.
message GetArtistRequest {
  // How to locate the artist. Exactly one field must be set.
  oneof identifier {
    // Provider-native identifier for the artist, in the ID namespace of
    // `provider`. For PROVIDER_MUSICBRAINZ this is the artist MBID.
    // Example: "5b11f4ce-a62d-471e-81fc-a69a8278c7da" (Radiohead).
    string id = 1;
    // Identifier from a specific external source, when the source differs
    // from `provider` or must be named explicitly.
    // Example: {source: "musicbrainz", source_id: "5b11f4ce-..."}.
    ExternalID external = 2;
  }
  // Source to resolve against and the ID namespace of `id`.
  // Example: PROVIDER_MUSICBRAINZ.
  Provider provider = 3;
}

// SearchArtistsRequest performs a fuzzy, paginated artist search.
message SearchArtistsRequest {
  // Free-text search terms, typically the artist name. Example: "radiohead".
  string query = 1;
  // Maximum number of results to return. Example: 25 (0 uses the default).
  int32 limit = 2;
  // Number of leading results to skip, for pagination. Example: 25.
  int32 offset = 3;
  // Source to search. Example: PROVIDER_MUSICBRAINZ.
  Provider provider = 4;
}

// GetAlbumRequest looks up a single album (release group) by identifier.
message GetAlbumRequest {
  // How to locate the album. Exactly one field must be set.
  oneof identifier {
    // Provider-native album identifier, in the ID namespace of `provider`.
    // For PROVIDER_MUSICBRAINZ this is the release-group MBID.
    // Example: "b1392450-e666-3926-a536-22c65f834433" (OK Computer).
    string id = 1;
    // Identifier from a specific external source.
    // Example: {source: "musicbrainz", source_id: "b1392450-..."}.
    ExternalID external = 2;
  }
  // Source to resolve against. Example: PROVIDER_MUSICBRAINZ.
  Provider provider = 3;
}

// GetArtistAlbumsRequest lists an artist's albums, paginated and optionally
// filtered by release type.
message GetArtistAlbumsRequest {
  // Provider-native artist identifier (same namespace as GetArtistRequest.id).
  // Example: "5b11f4ce-a62d-471e-81fc-a69a8278c7da".
  string artist_id = 1;
  // Maximum number of albums to return. Example: 50.
  int32 limit = 2;
  // Number of leading albums to skip, for pagination. Example: 0.
  int32 offset = 3;
  // Source to query. Example: PROVIDER_MUSICBRAINZ.
  Provider provider = 4;
  // Optional release-type filter; empty means all types.
  // Example: ["album", "ep"].
  repeated string album_types = 5;
}

// GetTrackRequest looks up a single track (recording) by identifier.
message GetTrackRequest {
  // How to locate the track. Exactly one field must be set.
  oneof identifier {
    // Provider-native track identifier, in the ID namespace of `provider`.
    // For PROVIDER_MUSICBRAINZ this is the recording MBID.
    // Example: "b9d99e0e-1472-4a37-8b2a-2f6b0a1234ab".
    string id = 1;
    // Identifier from a specific external source.
    // Example: {source: "musicbrainz", source_id: "b9d99e0e-..."}.
    ExternalID external = 2;
    // International Standard Recording Code. Example: "GBAYE9600477".
    string isrc = 3;
  }
  // Source to resolve against. Example: PROVIDER_MUSICBRAINZ.
  Provider provider = 4;
}

// GetAlbumTracksRequest lists the tracks belonging to an album.
message GetAlbumTracksRequest {
  // Provider-native album identifier (same namespace as GetAlbumRequest.id).
  // Example: "b1392450-e666-3926-a536-22c65f834433".
  string album_id = 1;
  // Source to query. Example: PROVIDER_MUSICBRAINZ.
  Provider provider = 2;
}

// SearchAlbumsRequest performs a fuzzy, paginated album search.
message SearchAlbumsRequest {
  // Free-text search terms, typically the album title. Example: "ok computer".
  string query = 1;
  // Optional artist name to narrow the search. Example: "radiohead".
  string artist = 2;
  // Maximum number of results to return. Example: 25.
  int32 limit = 3;
  // Number of leading results to skip, for pagination. Example: 0.
  int32 offset = 4;
  // Source to search. Example: PROVIDER_MUSICBRAINZ.
  Provider provider = 5;
  // Optional release-type filter; empty means all types.
  // Example: ["album"].
  repeated string album_types = 6;
}

// SyncArtistRequest fetches an artist and their catalog from a provider and
// persists it to the local store.
message SyncArtistRequest {
  // How to identify the artist to sync. Exactly one field must be set.
  oneof target {
    // Artist name to resolve via search before syncing. Example: "Radiohead".
    string name = 1;
    // Exact external identifier of the artist to sync.
    // Example: {source: "musicbrainz", source_id: "5b11f4ce-..."}.
    ExternalID external = 2;
  }
  // Source to sync from. Example: PROVIDER_MUSICBRAINZ.
  Provider provider = 3;
}

// Responses

message GetArtistResponse {
  // The resolved artist.
  Artist artist = 1;
}

message SearchArtistsResponse {
  // Matching artists, ordered by relevance.
  repeated Artist artists = 1;
  // Total number of matches available across all pages. Example: 137.
  int32 total = 2;
}

message GetAlbumResponse {
  // The resolved album.
  Album album = 1;
}

message GetArtistAlbumsResponse {
  // The artist's albums for the requested page.
  repeated Album albums = 1;
  // Total number of albums available across all pages. Example: 42.
  int32 total = 2;
}

message GetTrackResponse {
  // The resolved track.
  Track track = 1;
}

message GetAlbumTracksResponse {
  // The album's tracks, ordered by disc then track number.
  repeated Track tracks = 1;
}

message SearchAlbumsResponse {
  // Matching albums, ordered by relevance.
  repeated Album albums = 1;
  // Total number of matches available across all pages. Example: 58.
  int32 total = 2;
}

message SyncArtistResponse {
  // The synced artist as persisted locally.
  Artist artist = 1;
  // Number of albums fetched and stored during the sync. Example: 12.
  int32 albums_synced = 2;
  // Number of tracks fetched and stored during the sync. Example: 148.
  int32 tracks_synced = 3;
}

// Core Entities

// Artist is a performer or group.
message Artist {
  // Provider-native identifier (MBID for MusicBrainz).
  // Example: "5b11f4ce-a62d-471e-81fc-a69a8278c7da".
  string id = 1;
  // Display name. Example: "Radiohead".
  string name = 2;
  // Name normalized for alphabetical sorting. Example: "Radiohead"; for a
  // person, "Beatles, The" or "Hendrix, Jimi".
  string sort_name = 3;
  // Kind of artist. Example: "Group", "Person".
  string artist_type = 4;
  // ISO 3166-1 alpha-2 country code. Example: "GB".
  string country = 5;
  // Date the artist formed or was born, ISO 8601. Partial dates allowed.
  // Example: "1985" or "1985-05-01".
  string formed_date = 6;
  // Date the artist disbanded or died, ISO 8601; empty if still active.
  // Example: "2011-04-30".
  string disbanded_date = 7;
  // Free-text biography or annotation.
  string description = 8;
  // URL of a representative image. Example: "https://example.org/radiohead.jpg".
  string image_url = 9;
  // Genres associated with the artist.
  repeated Genre genres = 10;
  // Identifiers for this artist in external sources.
  repeated ExternalID external_ids = 11;
}

// Album is a release group / collection of tracks.
message Album {
  // Provider-native identifier (release-group MBID for MusicBrainz).
  // Example: "b1392450-e666-3926-a536-22c65f834433".
  string id = 1;
  // Album title. Example: "OK Computer".
  string title = 2;
  // Release type. Example: "album", "ep", "single", "compilation".
  string album_type = 3;
  // Release date, ISO 8601. Partial dates allowed. Example: "1997-05-21".
  string release_date = 4;
  // Universal Product Code (barcode). Example: "724385522925".
  string upc = 5;
  // Number of tracks across all discs. Example: 12.
  int32 total_tracks = 6;
  // Number of discs in the release. Example: 1.
  int32 total_discs = 7;
  // URL of the cover art. Example: "https://coverartarchive.org/release/.../front".
  string cover_url = 8;
  // Credited artists, in credit order.
  repeated ArtistCredit artists = 9;
  // Releasing label, if known.
  Label label = 10;
  // Genres associated with the album.
  repeated Genre genres = 11;
  // Identifiers for this album in external sources.
  repeated ExternalID external_ids = 12;
}

// Track is a recording as it appears on an album.
message Track {
  // Provider-native identifier (recording MBID for MusicBrainz).
  // Example: "b9d99e0e-1472-4a37-8b2a-2f6b0a1234ab".
  string id = 1;
  // Track title. Example: "Paranoid Android".
  string title = 2;
  // Playing time in milliseconds. Example: 383000 (6:23).
  int32 duration_ms = 3;
  // International Standard Recording Code. Example: "GBAYE9600477".
  string isrc = 4;
  // Whether the track is flagged as explicit.
  bool explicit = 5;
  // 1-based disc number the track appears on. Example: 1.
  int32 disc_number = 6;
  // 1-based position of the track within its disc. Example: 2.
  int32 track_number = 7;
  // Credited performers, in credit order.
  repeated ArtistCredit artists = 8;
  // Underlying composition, if linked.
  Work work = 9;
  // Identifiers for this track in external sources.
  repeated ExternalID external_ids = 10;
}

// Work is the underlying composition a track recording is based on.
message Work {
  // Provider-native identifier (work MBID for MusicBrainz).
  string id = 1;
  // Work title. Example: "Paranoid Android".
  string title = 2;
  // Kind of work. Example: "Song".
  string work_type = 3;
  // ISO 639-3 language code of the lyrics. Example: "eng".
  string language = 4;
  // Credited composers and lyricists.
  repeated ArtistCredit composers = 5;
}

// Label is a record label.
message Label {
  // Provider-native identifier (label MBID for MusicBrainz).
  string id = 1;
  // Label name. Example: "Parlophone".
  string name = 2;
  // ISO 3166-1 alpha-2 country code. Example: "GB".
  string country = 3;
}

// Genre is a musical genre tag.
message Genre {
  // Provider-native identifier (genre MBID for MusicBrainz).
  string id = 1;
  // Genre name. Example: "alternative rock".
  string name = 2;
}

// ArtistCredit links an artist to a release or track, preserving how the
// artist is credited (role, order, and connecting text).
message ArtistCredit {
  // The credited artist.
  Artist artist = 1;
  // Role in this credit. Example: "main", "featured", "composer".
  string role = 2;
  // 0-based position within the credit list. Example: 0.
  int32 position = 3;
  // Text joining this credit to the next. Example: " feat. " or " & ".
  string join_phrase = 4;
}

// ExternalID identifies an entity within a third-party source.
message ExternalID {
  // Source name. Example: "musicbrainz", "spotify", "discogs".
  string source = 1;
  // The entity's identifier within that source.
  // Example: "5b11f4ce-a62d-471e-81fc-a69a8278c7da".
  string source_id = 2;
  // Canonical URL of the entity at the source, if available.
  // Example: "https://musicbrainz.org/artist/5b11f4ce-...".
  string url = 3;
}