Track Details & Metadata
Relevant source files
The following files were used as context for generating this wiki page:
Track Details & Metadata refers to the system within Spotty that fetches, caches, and maps music information from Spotify's private interfaces. This system manages core attributes like titles, artists, and artwork, as well as enriched metadata such as popularity, BPM, and musical keys.
The metadata pipeline consumes data from three primary sources: the Pathfinder GraphQL API for general catalog browsing, the Spotify Connect (spclient) metadata endpoint for detailed track information, and a specialized extended-metadata endpoint for technical audio attributes. This data enables native macOS features like sortable track tables and artwork-led media headers.
Metadata Architecture & Data Flow
Metadata flows from Spotify's remote services into the CatalogMetadataRepository, which serves as a session-scoped cache. The repository differentiates between high-value catalog sources and provisional metadata from the playback queue.
The application uses specific mapping logic to convert raw transport models into domain models.
Sources: Sources/Spotty/Spotify/CatalogMetadataRepository.swift, Sources/Spotty/Spotify/CatalogMapping.swift, Sources/Spotty/Spotify/TrackAttributes.swift
Track Attributes Enrichment
The system enriches standard track data with technical attributes (BPM, Key, Popularity) using a batched Protobuf-based API. This process is triggered when tracks are loaded into a view, such as a playlist or album.
Data Acquisition Flow
CatalogMetadataRepositoryidentifies tracks requiring enrichment.- The repository batches requests (up to 100 tracks per batch).
TrackAttributesAPIencodes the request intoBatchedEntityRequestProtobuf format.- Spotify returns
BatchedExtensionResponse, which includes full track messages and audio attributes.
Audio Attribute Definitions
| Attribute | Field Type | Description |
|---|---|---|
| Popularity | Int | 0–100 value derived from the TRACK_V4 extension via zigzag decoding. |
| BPM | Int | Tempo rounded to the nearest whole beat per minute from AUDIO_ATTRIBUTES_V2. |
| Key | String | Musical key label, preferring Camelot values (e.g., "8B") or Major/Minor names. |
Sources: Sources/Spotty/Spotify/TrackAttributes.swift:18-24, Sources/Spotty/Spotify/TrackAttributes.swift:175-200
Catalog Repository & Caching
The CatalogMetadataRepository manages the lifecycle of metadata during an authenticated session. It uses an accountEpoch to ensure data remains valid across session reconnects.
- Source Precedence: Higher-value catalog sources (Search, Playlist, Album) overwrite provisional metadata from the Now Playing state or Queue.
- Cache Limits: The attribute cache is capped at 20,000 entries to manage memory.
- Revision Tracking:
trackAttributesRevisionandcontentRevisionnotify UI components of metadata updates.
Sources: Sources/Spotty/Spotify/CatalogMetadataRepository.swift:85-115, Sources/Spotty/Spotify/CatalogMetadataRepository.swift:232-242
Data Mapping & Transformation
The CatalogMapping utility performs pure conversion from Spotify's JSON/Pathfinder models to internal CatalogTrack and CatalogItem models.
Date Handling
Spotify uses a specific ISO8601 format. The mapper includes a sentinel check for the Unix epoch (1970-01-01). If a date matches the epoch, the system treats it as missing (nil) to avoid misleading "Date Added" displays.
Sources: Sources/Spotty/Spotify/CatalogMapping.swift:182-192
Track Duration Calculation
Duration is converted from milliseconds (API standard) to TimeInterval (seconds) for local playback and UI formatting.
duration: TimeInterval(track.durationMs ?? 0) / 1_000
Sources: Sources/Spotty/Spotify/CatalogMapping.swift:21
Summary
The Track Details & Metadata module provides a robust pipeline for fetching music data through multi-layered API interactions. By combining Pathfinder for discovery, Connect APIs for metadata, and Protobuf extensions for technical attributes, Spotty maintains a detailed local catalog that supports advanced sorting and rich visual presentations.