Parent directory

README.md

3783 bytes

Muse Guessr

A simple CLI music guessing game built with Go and bubbletea.

It scans a directory of music files, plays a short 2-second segment from a random position in each song, and you guess the title, album, and artist.

How it works

  1. Catalog — walks the given directory recursively, keeps common music file types, skips files under any blacklisted directory, and reads each file's title/album/artist tags (via dhowden/tag). Files without readable tags fall back to the filename as the title.
  2. Clip — picks a random 30-second window in the song (using ffprobe for the duration), decodes it to mono PCM with ffmpeg, finds the first point where the RMS volume meets the window's average volume (so silent stretches are skipped), and plays the following 2 seconds via aplay.
  3. Guess — the TUI shows three input fields (title, album, artist). You type your answer and submit. Matching ignores casing, punctuation, and extra whitespace, allows typos, and accepts omitted parenthesized extras such as (Live). The similarity threshold is matchThreshold = 0.7 in matching.go.
  4. Score — earn 4 points for the title, 4 for the album, and 2 for the artist, independently. Each round is worth up to 10 points. Blank answers earn no points. Using the extended hint (Ctrl+L) halves the score for that round.

Songs are played in a shuffled order.

Requirements

  • Go (to build)
  • ffmpeg on PATH (decoding)
  • ffprobe on PATH (duration lookup)
  • aplay on PATH (playback, from ALSA)

Build

go build -o museguessr .

Usage

museguessr -dir /path/to/music [-blacklist blacklist.txt] [-rounds 10]

| Flag | Default | Description | | ------------ | ------------------ | ------------------------------------------------------------------ | | -dir | /mnt/media/music | Directory to scan for music files (searched recursively). | | -blacklist | blacklist | File with one directory per line; every file under it is excluded. | | -rounds | 10 | Number of songs to play. 0 means one per song in the catalog. |

Web UI

Run the game as a web app instead of the TUI with -web:

museguessr -dir /path/to/music -web [-port 8080]

This starts an HTTP server (default port 8080) that serves a single-page interface built with Go templates and htmx. Audio clips are generated on the fly with ffmpeg and streamed to the browser as WAV, so no local audio playback is required — just ffmpeg and ffprobe on PATH. Open http://localhost:8080 in a browser. Type your guess in the three fields and submit; use Next song to advance and Play again to restart.

| Flag | Default | Description | | ------- | ------- | ---------------------------------- | | -web | false | Serve a web UI instead of the TUI. | | -port | 8080 | Port for the web server. |

Blacklist file

One directory per line — every file under that directory is excluded. Entries may be absolute, or relative to -dir. # starts a comment.

# skip these folders entirely
Remixes
./Old Demos
/home/pavle/music/Karaoke

Controls (in the TUI)

  • Tab / Shift+Tab — move between input fields
  • Ctrl+R — replay the music segment
  • Ctrl+L — play a longer 4-second hint (halves the score for that round)
  • Enter (or Space) — submit your guess / advance to the next song
  • Esc — skip ahead while a clip is playing, or quit on the final screen