Go on Man-You

Full-text search and lyrics in a Go music server

Wed, 18 Feb 2026 18:00:00 +0200

The Tunes server started as a way to stream my music library from a Raspberry Pi. It’s accumulated features since then. Two recent additions changed how I interact with it day-to-day: accent-insensitive full-text search across the entire library, and lyrics, both embedded from audio files and fetched from LRClib.

The search problem

Searching a music library is harder than it sounds. You want “bjork” to match “Björk”. You want “cafe” to match “Café”. You want “creme” to match “Crème Brûlée” in an album title. And you want it fast enough that results appear as you type.

The previous search was a LIKE query with wildcards. It worked, but it couldn’t handle diacritics and got slow on a 15,000-track library with multi-column matches.

FTS5 with unicode61

SQLite’s FTS5 extension does exactly what we need. The unicode61 tokenizer with remove_diacritics 2 strips all Unicode diacritical marks during indexing and querying:

tunes/search_fts.go: FTS5 table creation

func (s *SearchFTS) InitializeFTS() error {
 createSQL := `
 CREATE VIRTUAL TABLE IF NOT EXISTS tracks_fts USING fts5(
 track_id UNINDEXED,
 name,
 artist,
 album_artist,
 album,
 composer,
 genre,
 tokenize='unicode61 remove_diacritics 2'
 )`
 if err := s.db.Exec(createSQL).Error; err != nil {
 if strings.Contains(err.Error(), "no such module: fts5") {
 Sugar.Warn("FTS5 module not available - search will be disabled.")
 s.fts5Available = false
 return nil
 }
 return fmt.Errorf("failed to create FTS5 table: %w", err)
 }
 s.fts5Available = true
 return nil
}

track_id UNINDEXED stores the ID in the FTS table for joins but doesn’t tokenize it. If FTS5 isn’t compiled into the SQLite build, search degrades gracefully instead of crashing.

The index rebuilds atomically in a transaction: delete all FTS data, repopulate from the tracks table using COALESCE for NULL safety:

tunes/search_fts.go: index rebuild

func (s *SearchFTS) RebuildIndex(ctx context.Context) error {
 return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 if err := tx.Exec("DELETE FROM tracks_fts").Error; err != nil {
 return fmt.Errorf("failed to clear FTS table: %w", err)
 }
 populateSQL := `
 INSERT INTO tracks_fts (track_id, name, artist, album_artist,
 album, composer, genre)
 SELECT track_id, COALESCE(name, ''), COALESCE(artist, ''),
 COALESCE(album_artist, ''), COALESCE(album, ''),
 COALESCE(composer, ''), COALESCE(genre, '')
 FROM i_tunes_tracks WHERE deleted_at IS NULL`
 return tx.Exec(populateSQL).Error
 })
}

Query building

User queries are split into words, each gets a * suffix for prefix matching, and they’re joined with implicit AND. FTS5 special characters are stripped to prevent injection:

tunes/search_fts.go: query sanitization

func buildFTSQuery(query string) string {
 words := strings.Fields(strings.TrimSpace(query))
 var parts []string
 for _, word := range words {
 escaped := escapeFTSToken(word)
 if escaped != "" {
 parts = append(parts, escaped+"*")
 }
 }
 return strings.Join(parts, " ")
}

func escapeFTSToken(token string) string {
 var result strings.Builder
 for _, r := range token {
 switch r {
 case '"', '*', '^', '(', ')', '{', '}', '[', ']', ':', '-':
 continue
 default:
 result.WriteRune(r)
 }
 }
 return result.String()
}

Typing “aphex win” becomes aphex* win*, which matches “Aphex Twin” via prefix expansion. Typing “cafe del” matches “Café Del Mar” because the tokenizer already stripped the accent at index time.

Unified search endpoint

The /search?q= endpoint returns artists, albums, and tracks in a single response, each ranked independently by BM25:

tunes/search_handler.go

type UnifiedSearchResponse struct {
 Artists []ArtistInfo `json:"artists"`
 Albums []AlbumInfo `json:"albums"`
 Tracks []ITunesTrack `json:"tracks"`
}

func (ls *LibraryService) HandleSearch(w http.ResponseWriter, r *http.Request) {
 query := strings.TrimSpace(r.URL.Query().Get("q"))
 artists := ls.searchArtistsFTS(ctx, repo, query, 5)
 albums := ls.searchAlbumsFTS(ctx, repo, query, 10)
 tracks := ls.searchTracksFTS(ctx, repo, query, 30)
 // ...
}

Each section queries specific FTS5 columns. Artist search hits both artist and album_artist, then merges and aggregates. The BM25 scoring comes from FTS5’s built-in function:

SELECT track_id, bm25(tracks_fts) as rank
FROM tracks_fts
WHERE tracks_fts MATCH ?
ORDER BY rank
LIMIT ?

BM25 order is preserved through joins by building a track map and reordering after the GORM query:

tunes/search_handler.go: preserving BM25 order

trackMap := make(map[int]ITunesTrack, len(tracks))
for _, t := range tracks {
 if t.TrackID != nil {
 trackMap[*t.TrackID] = t
 }
}
ordered := make([]ITunesTrack, 0, len(trackIDs))
for _, id := range trackIDs {
 if t, ok := trackMap[id]; ok {
 ordered = append(ordered, t)
 }
}

Album search uses a two-stage approach: FTS returns track IDs, those map to album_key, then the album_cache table provides pre-aggregated album metadata. This avoids re-aggregating album info on every search.

Lyrics from audio files

The music scanner already walks the filesystem to index tracks using github.com/dhowden/tag. Adding lyrics extraction was a matter of probing the right metadata keys:

tunes/music_scanner.go: lyrics extraction

func (ms *MusicScanner) extractLyricsFromMetadata(rawMetadata any) *ExtractedLyrics {
 var lyrics ExtractedLyrics
 switch raw := rawMetadata.(type) {
 case map[string]any:
 for _, key := range []string{
 "lyrics", "USLT", "unsynchronised_lyrics",
 "unsynced_lyrics", "LYRICS", "\xa9lyr",
 } {
 if val, ok := raw[key]; ok {
 switch v := val.(type) {
 case string:
 if v != "" { lyrics.PlainLyrics = v }
 case []byte:
 if len(v) > 0 { lyrics.PlainLyrics = string(v) }
 }
 }
 }
 // Also check SYLT for synchronized lyrics
 for _, key := range []string{"SYLT", "synchronised_lyrics", "synced_lyrics"} {
 // ... same pattern
 }
 }
 return &lyrics
}

USLT is the ID3v2 unsynchronized lyrics frame, "\xa9lyr" is the M4A/AAC lyrics atom, SYLT is synchronized (timestamped) lyrics. The scanner handles both plain text and timestamped LRC format.

LRClib integration

For tracks without embedded lyrics, the server fetches from LRClib, a free, open lyrics database with synced timestamps.

The lyrics service uses golang.org/x/time/rate to respect API limits:

tunes/lyrics_service.go

const (
 lrcLibBaseURL = "https://lrclib.net/api"
 lrcLibUserAgent = "Tunes/1.0 (https://github.com/manz/tunes-server)"
 lrcLibRateLimit = 2
)

func NewLyricsService(db *gorm.DB) *LyricsService {
 return &LyricsService{
 repo: NewLyricsRepository(db),
 httpClient: &http.Client{Timeout: 15 * time.Second},
 rateLimiter: rate.NewLimiter(rate.Limit(lrcLibRateLimit), 1),
 }
}

When fetching, the service validates that the returned lyrics match the track’s duration within 5 seconds. This prevents mismatches: same song title by different artists, live vs studio versions:

tunes/lyrics_service.go: duration tolerance

if duration > 0 && lrcResponse.Duration > 0 {
 if math.Abs(float64(duration)-lrcResponse.Duration) > durationTolerance {
 return nil, ErrLyricsNotFound
 }
}

The handler implements fetch-through caching: check the database first, if miss then fetch from LRClib, save, and return. No external call on subsequent requests for the same track.

Lyrics are stored with GORM’s FirstOrCreate + Assign for clean upserts:

tunes/lyrics_repository.go

func (r *LyricsRepository) SaveLyrics(ctx context.Context, lyrics *TrackLyrics) error {
 return r.db.WithContext(ctx).
 Where(TrackLyrics{TrackID: lyrics.TrackID}).
 Assign(TrackLyrics{
 LRCLibID: lyrics.LRCLibID,
 Instrumental: lyrics.Instrumental,
 PlainLyrics: lyrics.PlainLyrics,
 SyncedLyrics: lyrics.SyncedLyrics,
 Source: lyrics.Source,
 }).
 FirstOrCreate(lyrics).Error
}

Background enrichment

A POST /lyrics/enrich endpoint triggers a goroutine that processes tracks without lyrics in batches of 50. It finds un-enriched tracks with a LEFT JOIN:

tunes/lyrics_repository.go: finding tracks without lyrics

err := r.db.Joins(
 "LEFT JOIN track_lyrics ON i_tunes_tracks.track_id = track_lyrics.track_id",
).Where("track_lyrics.id IS NULL").
 Where("i_tunes_tracks.deleted_at IS NULL").
 Limit(limit).
 Find(&tracks).Error

Rate-limited at 2 requests per second, a 15,000-track library takes a few hours to fully enrich. The mutex prevents concurrent enrichment runs:

tunes/lyrics_service.go: single-flight enrichment

func (s *LyricsService) StartBackgroundEnrichment(ctx context.Context, ...) {
 s.mu.Lock()
 if s.isEnriching {
 s.mu.Unlock()
 return
 }
 s.isEnriching = true
 s.mu.Unlock()

 go func() {
 defer func() { s.mu.Lock(); s.isEnriching = false; s.mu.Unlock() }()
 tracks, _ := s.repo.GetTracksWithoutLyrics(ctx, 50)
 // ... process batch, respect rate limiter
 }()
}

Admin via sudoers

The authorization model is Unix-inspired. Instead of a boolean is_admin on the User model, there’s a dedicated sudoers table with audit trail:

tunes/models.go

type Sudoer struct {
 ID int `gorm:"primaryKey;autoIncrement"`
 UserID int `gorm:"column:user_id;uniqueIndex;not null"`
 GrantedBy int `gorm:"column:granted_by;not null"`
 GrantedAt time.Time `gorm:"autoCreateTime"`
 ExpiresAt *time.Time `gorm:"column:expires_at"`
 Active bool `gorm:"column:active;default:true"`
}

Destructive operations (deleting tracks, managing users) additionally require a sudo token, obtained by re-authenticating via WebAuthn passkey. Two-step elevation: request a challenge, prove you’re you, get a time-limited token. This prevents a stolen session from doing real damage.

Routes use higher-order functions for auth gating:

cmd/tunes-server/main.go

func sudoerRoute(authMiddleware func(http.Handler) http.Handler,
 authService *AuthService) func(http.HandlerFunc) http.Handler {
 return func(handler http.HandlerFunc) http.Handler {
 return authMiddleware(requireSudoerMiddleware(authService)(handler))
 }
}

The first user must be created via CLI before the server starts: tunes-server users add <username> --sudoer. No web-based registration for the initial admin. You need shell access.

What changed

The server went from “stream my library” to “actually find what I want to play.” FTS5 with accent stripping makes search work the way you’d expect: type a rough approximation of the artist name, get the right results. Lyrics with synced timestamps let the iOS app show karaoke-style scrolling text. Background enrichment means I didn’t have to manually tag anything. It just filled in over a couple of evenings.

Still no replacement for Apple Music’s catalog. But for my 15,000 tracks, it works better than iTunes Match ever did.

Tunes

Tue, 01 Jul 2025 10:31:38 +0200

iTunes Match worked great for years: you uploaded your library, Apple matched what it could, and you had access to everything from any device. But Apple is clearly moving everyone toward Apple Music, and iTunes Match has been slowly rotting. The writing was on the wall.

I didn’t want to subscribe to Apple Music. I wanted to keep my library, my ratings, my play counts, my playlists, all the metadata accumulated over 20 years. So I built my own streaming setup: a Go backend that serves the library over HTTP, and SwiftUI apps that play it on iOS, macOS, and tvOS.

Exporting the library

Apple Music (formerly iTunes) can export the library as an XML plist file. It’s a flat dictionary of tracks keyed by ID, with every field you’d expect: name, artist, album, play count, rating, date added, file location, and about 60 more.

A track entry in the exported XML

<key>1234</key>
<dict>
 <key>Track ID</key><integer>1234</integer>
 <key>Name</key><string>Windowlicker</string>
 <key>Artist</key><string>Aphex Twin</string>
 <key>Album</key><string>Windowlicker</string>
 <key>Total Time</key><integer>381573</integer>
 <key>Location</key><string>file:///Music/Aphex%20Twin/Windowlicker/01%20Windowlicker.m4a</string>
</dict>

The Go struct that maps to this uses plist tags for XML parsing and gorm tags for database storage, with every optional field as a pointer for proper nil handling:

Track model (abbreviated)

type ITunesTrack struct {
 TrackID *int `plist:"Track ID" json:"track_id" gorm:"primaryKey"`
 Name *string `plist:"Name" json:"name" gorm:"index"`
 Artist *string `plist:"Artist" json:"artist" gorm:"index"`
 Album *string `plist:"Album" json:"album" gorm:"index"`
 TotalTime *int `plist:"Total Time" json:"total_time"`
 Location *string `plist:"Location" json:"location"`
 Rating *int `plist:"Rating" json:"rating" gorm:"index"`
 PlayCount *int `plist:"Play Count" json:"play_count"`
 DateAdded *time.Time `plist:"Date Added" json:"date_added" gorm:"index"`
 // ... 60+ more fields
}

The initial version parsed the XML on every startup using howett.net/plist. That worked fine for a 15,000-track library (about 2 seconds of parsing). But it eventually moved to SQLite with GORM for persistence, which also enabled FTS5 full-text search and pre-aggregated album caches.

The Go backend

The server is straightforward. A LibraryService holds the database, artwork cache, rate limiter, and various sub-services. Routes are plain net/http handlers with a JWT auth middleware:

Route setup (abbreviated)

// Auth routes (no middleware)
http.HandleFunc("/auth/login", authHandlers.HandleLogin)
http.HandleFunc("/auth/register", authHandlers.HandleRegister)

// Library routes (auth required)
http.Handle("/tracks", authMiddleware(http.HandlerFunc(service.HandleTracks)))
http.Handle("/artists", authMiddleware(http.HandlerFunc(service.HandleArtists)))
http.Handle("/albums", authMiddleware(http.HandlerFunc(service.HandleAlbums)))
http.Handle("/stream/", authMiddleware(http.HandlerFunc(service.HandleStream)))
http.Handle("/artwork/track/", authMiddleware(http.HandlerFunc(service.HandleTrackArtwork)))

The /stream/{id} endpoint serves audio files directly with http.ServeFile, which handles range requests and conditional caching automatically. No need to build a custom streaming protocol. HTTP does the job.

Authentication uses Argon2 for password hashing and session tokens stored in the database. It later grew WebAuthn support for passkey login, and a QR code flow for tvOS (where typing passwords with a remote is painful).

Album artwork

This was the most annoying part. The exported XML doesn’t include artwork. The actual cover images are either embedded in the audio files or live somewhere in Apple’s ecosystem that isn’t accessible after export.

The solution is a three-tier artwork system:

Embedded extraction: read the audio file metadata with github.com/dhowden/tag, pull out the cover image if present, cache it locally
iTunes Store lookup: search Apple’s public API for the album, download the highest resolution artwork available
Manual upload: for albums that don’t match either source

The iTunes Store lookup uses a scoring system to match results. Exact album + artist name match scores highest, partial matches score lower, and anything below a minimum threshold is rejected:

iTunes Store artwork search

func (ls *LibraryService) searchITunesStore(artist, album string, tracks []ITunesTrack) *ITunesSearchItem {
 searchTerm := fmt.Sprintf("%s %s", strings.TrimSpace(artist), strings.TrimSpace(album))

 params := url.Values{}
 params.Set("term", searchTerm)
 params.Set("entity", "album")
 params.Set("media", "music")
 params.Set("limit", "10")

 searchURL := fmt.Sprintf("https://itunes.apple.com/search?%s", params.Encode())
 // ... fetch, decode, find best match by score
}

Apple’s API returns 100x100 thumbnails by default. The URL pattern is predictable (replace 100x100 with 600x600), but not all resolutions exist for all albums. The server tries 600, 512, and 300 with HEAD requests before falling back to the original.

The real constraint is rate limiting. Apple’s Search API starts returning 403s if you hit it too hard. The server uses a channel-based rate limiter that caps requests to 2 per second by default, configurable via TOML config.

The gapless playback problem

This one took a while to figure out. Live albums, DJ mixes, classical recordings: any music that’s supposed to flow continuously between tracks gets a gap when played back on iOS.

The root cause: iOS AVFoundation ignores the iTunSMPB gapless metadata in MP3 files. This is the atom that tells the player how many encoder delay and padding samples to skip. Apple’s own Music app reads it. AVFoundation does not.

The fix is converting MP3s to AAC. The AAC container stores gapless information in a way that AVFoundation actually respects. The server has a built-in transcoder:

Startup conversion

transcoder := tunes.NewTranscoderService(service, tunes.TranscodeOptions{
 Concurrency: 4,
 DeleteSource: false, // Keep original MP3s
})
results, err := transcoder.ConvertAllMP3s(context.Background())

It uses ffmpeg under the hood, runs 4 workers in parallel, keeps the originals, and updates the database paths. A 15,000-track library takes a couple of hours. After that, gapless playback works perfectly.

SwiftUI clients

The app targets iOS, macOS, and tvOS from a single codebase, with platform-specific extensions for navigation and layout. iOS uses tab navigation with a mini-player overlay, macOS uses a split view with sidebar, and tvOS uses focus-based navigation for the remote.

The audio player is built on AVQueuePlayer for seamless track transitions. It pre-buffers the next track 10 seconds before the current one ends, maintaining up to 3 items in the queue at any time.

One hard-won lesson: @Published property updates in background cause iOS to terminate the app for excessive main-thread UI work. The fix is gating all published writes behind a foreground check:

Background-safe state management

struct PlaybackState: Equatable {
 var currentTime: TimeInterval = 0
 var duration: TimeInterval = 0
 var isPlaying = false
 var isLoading = false

 static func == (lhs: PlaybackState, rhs: PlaybackState) -> Bool {
 return Int(lhs.currentTime) == Int(rhs.currentTime) &&
 Int(lhs.duration) == Int(rhs.duration) &&
 lhs.isPlaying == rhs.isPlaying &&
 lhs.isLoading == rhs.isLoading
 }
}

Grouping related properties into structs (instead of individual @Published vars) and implementing coarse equality comparison reduced SwiftUI re-renders significantly. The player only triggers a view update when the second changes, not on every time observer tick.

The API layer uses Combine publishers with automatic 401 retry: if a request fails with an expired token, the service transparently refreshes it and replays the original request. Network monitoring via NWPathMonitor lets the app degrade gracefully when offline, falling back to Core Data for cached data.

What grew out of it

What started as “stream my library from a Raspberry Pi” has accumulated features over time:

Full-text search with SQLite FTS5 across all track metadata
Play history tracking: every play gets logged with duration and completion status, which feeds a yearly replay feature (like Spotify Wrapped)
Lyrics: embedded USLT frames from audio files, plus LRClib API integration for synced timestamps
Offline mode: Core Data persistence with background sync, download management for keeping albums locally
Discogs integration: artist biographies and metadata from a separate database
Vector similarity search: track embeddings for “genius playlists” based on audio features and metadata

It’s not a replacement for Apple Music. It doesn’t have a catalog of 100 million songs. But it plays my music, with my metadata, on all my devices, without a subscription. That was the goal.