// Code generated by ndpgen. DO NOT EDIT.
//
// Package types holds the stable, shared data types exchanged between
// Navidrome and its plugins. These types are referenced by host services and
// capability wrappers via the types package.

package types

// ArtistRef is the minimal information a plugin returns for Navidrome to match an
// artist against the library. It is a reference, not a full artist entity: it
// carries only matching keys (name and optional internal/MusicBrainz IDs) plus a
// few projection fields used when describing a track's participants, never
// descriptive data such as biographies or images.
type ArtistRef struct {
	// ID is the internal Navidrome artist ID (if known).
	ID string `json:"id,omitempty"`
	// Name is the artist name.
	Name string `json:"name"`
	// MBID is the MusicBrainz ID for the artist.
	MBID string `json:"mbid,omitempty"`
	// SortName is the artist name used for sorting (if known).
	SortName string `json:"sortName,omitempty"`
	// Role is the participation category (e.g. "artist", "composer", "performer").
	Role string `json:"role,omitempty"`
	// SubRole is a specialization within Role (e.g. the instrument for a performer).
	SubRole string `json:"subRole,omitempty"`
}

// SongRef is the minimal information exchanged between a plugin and Navidrome to
// match a song. It is used both as input (a song Navidrome already has) and as
// output (a song a plugin suggests, which may not be in the library yet). Unlike
// Track, it is an abstract recording reference carrying only matching keys (IDs,
// ISRC, and title/artist/album/duration) that Navidrome resolves to a library track.
type SongRef struct {
	// ID is the internal Navidrome mediafile ID (if known).
	ID string `json:"id,omitempty"`
	// Name is the song name.
	Name string `json:"name"`
	// MBID is the MusicBrainz ID for the song.
	MBID string `json:"mbid,omitempty"`
	// ISRC is the International Standard Recording Code for the song.
	ISRC string `json:"isrc,omitempty"`
	// Artist is the artist name.
	//
	// Deprecated: use Artists.
	Artist string `json:"artist,omitempty"`
	// ArtistMBID is the MusicBrainz artist ID.
	//
	// Deprecated: use Artists.
	ArtistMBID string `json:"artistMbid,omitempty"`
	// Artists is the full artist list; when set, takes precedence over Artist/ArtistMBID for matching.
	Artists []ArtistRef `json:"artists,omitempty"`
	// Album is the album name.
	Album string `json:"album,omitempty"`
	// AlbumMBID is the MusicBrainz release ID.
	AlbumMBID string `json:"albumMbid,omitempty"`
	// Duration is the song duration in seconds.
	//
	// Deprecated: use DurationMs, which carries millisecond precision. When
	// DurationMs is non-zero it takes precedence; Duration is kept only for
	// backwards compatibility with plugins that still send seconds.
	Duration float32 `json:"duration,omitempty"`
	// DurationMs is the song duration in milliseconds. It supersedes Duration
	// when non-zero.
	DurationMs uint32 `json:"durationMs,omitempty"`
}

// Track is a stable, public projection of a library media file for plugin consumption.
// It is a sane subset of the internal model.MediaFile, intended for reuse across host
// services and capabilities. Timestamps are Unix epoch seconds.
//
// Unlike SongRef, which is an abstract recording reference carrying only matching keys,
// Track is a concrete library entity: it identifies a specific media file that exists
// (or once existed) in the library and exposes its full descriptive metadata.
type Track struct {
	// Identity & location
	ID          string `json:"id"`
	LibraryID   int32  `json:"libraryId"`
	LibraryName string `json:"libraryName,omitempty"`
	Path        string `json:"path,omitempty"`
	Missing     bool   `json:"missing"`
	// Core metadata
	Title          string `json:"title"`
	Album          string `json:"album"`
	Artist         string `json:"artist"`
	AlbumArtist    string `json:"albumArtist,omitempty"`
	AlbumID        string `json:"albumId,omitempty"`
	SortTitle      string `json:"sortTitle,omitempty"`
	SortAlbumName  string `json:"sortAlbumName,omitempty"`
	SortArtistName string `json:"sortArtistName,omitempty"`
	// Track / disc / dates
	TrackNumber  int32  `json:"trackNumber"`
	DiscNumber   int32  `json:"discNumber"`
	DiscSubtitle string `json:"discSubtitle,omitempty"`
	Year         int32  `json:"year"`
	Date         string `json:"date,omitempty"`
	OriginalYear int32  `json:"originalYear"`
	OriginalDate string `json:"originalDate,omitempty"`
	ReleaseYear  int32  `json:"releaseYear"`
	ReleaseDate  string `json:"releaseDate,omitempty"`
	// Audio / file
	Size       int64   `json:"size"`
	Suffix     string  `json:"suffix,omitempty"`
	Duration   float64 `json:"duration"`
	BitRate    int32   `json:"bitRate"`
	SampleRate int32   `json:"sampleRate"`
	BitDepth   *int32  `json:"bitDepth,omitempty"`
	Channels   int32   `json:"channels"`
	Codec      string  `json:"codec,omitempty"`
	// Descriptive
	Genres         []string `json:"genres,omitempty"`
	Comment        string   `json:"comment,omitempty"`
	BPM            *int32   `json:"bpm,omitempty"`
	ExplicitStatus string   `json:"explicitStatus,omitempty"`
	CatalogNum     string   `json:"catalogNum,omitempty"`
	Compilation    bool     `json:"compilation"`
	HasCoverArt    bool     `json:"hasCoverArt"`
	// MusicBrainz
	MbzRecordingID    string `json:"mbzRecordingId,omitempty"`
	MbzReleaseTrackID string `json:"mbzReleaseTrackId,omitempty"`
	MbzAlbumID        string `json:"mbzAlbumId,omitempty"`
	MbzReleaseGroupID string `json:"mbzReleaseGroupId,omitempty"`
	MbzAlbumType      string `json:"mbzAlbumType,omitempty"`
	MbzAlbumComment   string `json:"mbzAlbumComment,omitempty"`
	// ReplayGain — nil means no data; 0 is a valid measured value, so these
	// must stay pointers to distinguish "absent" from "0".
	RGAlbumGain *float64 `json:"rgAlbumGain,omitempty"`
	RGAlbumPeak *float64 `json:"rgAlbumPeak,omitempty"`
	RGTrackGain *float64 `json:"rgTrackGain,omitempty"`
	RGTrackPeak *float64 `json:"rgTrackPeak,omitempty"`
	// Timestamps (Unix epoch seconds)
	BirthTime int64 `json:"birthTime"`
	CreatedAt int64 `json:"createdAt"`
	UpdatedAt int64 `json:"updatedAt"`
	// AverageRating is the track's mean rating across all users (always set; 0 when unrated).
	AverageRating float64 `json:"averageRating"`
	// Per-user annotations, set only for a user-scoped match. Timestamps are Unix
	// seconds; a nil pointer means "no value".
	Starred   bool   `json:"starred,omitempty"`
	StarredAt *int64 `json:"starredAt,omitempty"`
	Rating    int32  `json:"rating,omitempty"`
	PlayCount int64  `json:"playCount,omitempty"`
	PlayDate  *int64 `json:"playDate,omitempty"`
	// Composite
	Tags map[string][]string `json:"tags,omitempty"`
	// Participants lists the track's artists across all roles, each tagged with its Role.
	Participants []ArtistRef `json:"participants,omitempty"`
}
