{"id":38543430,"url":"https://github.com/sphildreth/tunez","last_synced_at":"2026-01-18T11:18:13.256Z","repository":{"id":331349247,"uuid":"1127055943","full_name":"sphildreth/tunez","owner":"sphildreth","description":"Terminal music player in full ANSI color.","archived":false,"fork":false,"pushed_at":"2026-01-04T05:14:25.000Z","size":25626,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-06T19:25:32.683Z","etag":null,"topics":["audio","cli","cross-platform","golang","melodee","music-player","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sphildreth.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY_PRIVACY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"sphildreth"}},"created_at":"2026-01-03T04:49:04.000Z","updated_at":"2026-01-04T05:14:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sphildreth/tunez","commit_stats":null,"previous_names":["sphildreth/tunez"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sphildreth/tunez","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphildreth%2Ftunez","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphildreth%2Ftunez/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphildreth%2Ftunez/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphildreth%2Ftunez/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sphildreth","download_url":"https://codeload.github.com/sphildreth/tunez/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphildreth%2Ftunez/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28503242,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","cli","cross-platform","golang","melodee","music-player","terminal","tui"],"created_at":"2026-01-17T07:13:49.728Z","updated_at":"2026-01-17T07:13:49.828Z","avatar_url":"https://github.com/sphildreth.png","language":"Go","funding_links":["https://ko-fi.com/sphildreth"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"graphics/tunez-logo.png\" alt=\"Tunez Logo\" width=\"120\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.22+-00ADD8?style=flat\u0026logo=go\" alt=\"Go Version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Platform-Linux%20%7C%20macOS-lightgrey?style=flat\" alt=\"Platform\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green?style=flat\" alt=\"License\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Status-Active%20Development-blue?style=flat\" alt=\"Status\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eTunez\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eA fast, beautiful terminal music player\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e •\n  \u003ca href=\"#quickstart\"\u003eQuickstart\u003c/a\u003e •\n  \u003ca href=\"#keybindings\"\u003eKeybindings\u003c/a\u003e •\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n---\n\nTunez is a **keyboard-driven terminal music player** written in Go. It features a responsive [Bubble Tea](https://github.com/charmbracelet/bubbletea) TUI, [mpv](https://mpv.io/) for high-quality audio playback, and support for multiple music sources through a flexible provider system.\n\n## Features\n\n- 🎵 **Beautiful TUI** — Rainbow-colored interface with smooth navigation\n- ⚡ **Responsive** — Non-blocking UI, all I/O happens in the background\n- 🎧 **High-quality playback** — Powered by mpv with gapless playback support\n- 🖼️ **Album artwork** — Auto-detects terminal graphics (Sixel/Kitty) for pixel-perfect images\n- 🔀 **Queue management** — Add, remove, reorder, shuffle, and repeat\n- 🔍 **Fast search** — Search across tracks, albums, and artists\n- 📚 **Multiple providers** — Local filesystem or Melodee API server\n- ⚙️ **Configurable** — Custom keybindings, themes, and profiles\n- ♿ **Accessible** — NO_COLOR support, works at 80×24\n\n## Installation\n\n### Prerequisites\n\n- **Go 1.22+**\n- **mpv** media player\n\n#### Install mpv\n\n```bash\n# Debian/Ubuntu\nsudo apt-get install -y mpv\n\n# macOS (Homebrew)\nbrew install mpv\n\n# Arch Linux\nsudo pacman -S mpv\n\n# Fedora\nsudo dnf install mpv\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/yourusername/tunez.git\ncd tunez/src\ngo build -o tunez ./cmd/tunez\n./tunez --version\n```\n\n## Quickstart\n\n### 1. Create a config file\n\n```bash\nmkdir -p ~/.config/tunez\ncp examples/config.example.toml ~/.config/tunez/config.toml\n```\n\n### 2. Edit the config\n\nPoint Tunez at your music library:\n\n```toml\nactive_profile = \"local\"\n\n[[profiles]]\nid = \"local\"\nname = \"My Music\"\nprovider = \"filesystem\"\nenabled = true\n\n[profiles.settings]\nroots = [\"/home/you/Music\"]\n```\n\n### 3. Run Tunez\n\n```bash\n./tunez\n```\n\nOr run the doctor to verify your setup:\n\n```bash\n./tunez -doctor\n```\n\n## Keybindings\n\n### Navigation\n\n| Key | Action |\n|-----|--------|\n| `↑` / `↓` | Navigate screens |\n| `j` / `k` | Move selection down / up |\n| `Enter` | Select / Play |\n| `Tab` | Next screen |\n| `Shift+Tab` | Previous screen |\n| `Backspace` / `Esc` | Go back |\n| `/` | Search |\n| `?` | Help |\n| `q` / `Ctrl+C` | Quit |\n\n### Playback\n\n| Key | Action |\n|-----|--------|\n| `Space` | Play / Pause |\n| `n` | Next track |\n| `p` | Previous track |\n| `h` / `l` | Seek -5s / +5s |\n| `H` / `L` | Seek -30s / +30s |\n| `-` / `+` | Volume down / up |\n| `m` | Mute |\n| `s` | Toggle shuffle |\n| `r` | Cycle repeat (off → all → one) |\n\n### Queue\n\n| Key | Action |\n|-----|--------|\n| `a` | Add to queue |\n| `A` / `P` | Play next |\n| `x` | Remove from queue |\n| `u` / `d` | Move up / down |\n| `C` | Clear queue |\n\n## Configuration\n\nTunez uses a TOML configuration file located at:\n- **Linux/macOS**: `~/.config/tunez/config.toml`\n- **Windows**: `%APPDATA%\\Tunez\\config.toml`\n\n### Example config\n\n```toml\nconfig_version = 1\nactive_profile = \"local\"\n\n[ui]\ntheme = \"rainbow\"\npage_size = 100\nno_emoji = false\n\n[player]\nmpv_path = \"mpv\"\ninitial_volume = 70\nseek_small_seconds = 5\nseek_large_seconds = 30\nvolume_step = 5\n\n[[profiles]]\nid = \"local\"\nname = \"Local Music\"\nprovider = \"filesystem\"\nenabled = true\n\n[profiles.settings]\nroots = [\"/home/you/Music\", \"/mnt/nas/music\"]\nscan_on_start = false\n\n[[profiles]]\nid = \"melodee\"\nname = \"Melodee Server\"\nprovider = \"melodee\"\nenabled = true\n\n[profiles.settings]\nbase_url = \"https://music.example.com\"\nusername = \"user\"\npassword_env = \"TUNEZ_MELODEE_PASSWORD\"\n```\n\nSee [docs/CONFIG.md](docs/CONFIG.md) for the full configuration reference.\n\n## Themes \u0026 Accessibility\n\nTunez ships with **19 beautiful themes** to match your terminal aesthetic:\n\n| Theme | Description |\n|-------|-------------|\n| `rainbow` | Default colorful theme |\n| `mono` | Elegant grayscale |\n| `green` | Classic terminal green |\n| `nocolor` | Accessible (respects NO_COLOR) |\n| `dracula` | Popular dark theme |\n| `nord` | Arctic, bluish tones |\n| `solarized` | Precision colors |\n| `gruvbox` | Retro, earthy tones |\n| `synthwave` | 80s neon vibes |\n| `matrix` | Digital rain green |\n| `neon` | Bright cyberpunk |\n| ... | and 8 more! |\n\n### Set a theme\n\n```toml\n[ui]\ntheme = \"dracula\"\n```\n\n### NO_COLOR support\n\nTunez respects the `NO_COLOR` environment variable for accessibility:\n\n```bash\nNO_COLOR=1 ./tunez\n```\n\nYou can also disable emoji in the config:\n\n```toml\n[ui]\nno_emoji = true\n```\n\n### Create your own theme\n\nWant to create a custom theme? See the [Theme Contributor Guide](src/internal/ui/themes/README.md) for step-by-step instructions.\n\n## Album Artwork\n\nTunez displays album artwork in the Now Playing screen. The quality depends on your terminal's graphics capabilities, which are **automatically detected** at startup.\n\n### Graphics Protocols\n\n| Protocol | Quality | Terminals |\n|----------|---------|-----------|\n| **Kitty** | Pixel-perfect | Kitty |\n| **Sixel** | High quality | iTerm2, WezTerm, foot, mlterm, Konsole, Windows Terminal, xterm (with sixel) |\n| **ANSI** | Good (half-blocks) | All terminals (fallback) |\n\nRun `tunez --doctor` to see which graphics protocol your terminal supports:\n\n```\n$ tunez --doctor\n┌─────────────────────────────────────────┐\n│           Tunez Doctor Report           │\n└─────────────────────────────────────────┘\n\n  ✓ Config file:    OK\n  ✓ mpv:            OK (mpv 0.37.0)\n  ✓ ffprobe:        OK (6.1.1)\n  ✓ cava:           OK (0.10.1)\n\n  ✓ Graphics:       sixel (Sixel graphics - high-quality images)\n```\n\n### Artwork Configuration\n\n```toml\n[artwork]\nenabled = true\nwidth = 40       # Width in terminal columns\nheight = 20      # Height in terminal rows\nquality = \"high\" # low, medium, high\nscale_mode = \"fit\" # fit, fill, stretch\n```\n\nThe artwork size automatically adjusts to fit your terminal window while preserving aspect ratio.\n\n### Supported Terminals for Best Quality\n\nFor **pixel-perfect album artwork**, use one of these terminals:\n\n- **[Kitty](https://sw.kovidgoyal.net/kitty/)** — Best quality, native graphics protocol\n- **[iTerm2](https://iterm2.com/)** (macOS) — Sixel support\n- **[WezTerm](https://wezfurlong.org/wezterm/)** — Cross-platform, Sixel support\n- **[foot](https://codeberg.org/dnkl/foot)** — Fast Wayland terminal, Sixel support\n- **[Windows Terminal](https://github.com/microsoft/terminal)** — Sixel support in recent versions\n\nOther terminals will use ANSI half-block characters, which still provide recognizable artwork.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [PHASE_PLAN.md](docs/PHASE_PLAN.md) | Development roadmap and phase breakdown |\n| [PRD.md](docs/PRD.md) | Product requirements |\n| [TUI_UX.md](docs/TUI_UX.md) | Screen specifications and interactions |\n| [CONFIG.md](docs/CONFIG.md) | Configuration reference |\n| [PROVIDERS.md](docs/PROVIDERS.md) | Provider interface contract |\n| [TECH_DESIGN.md](docs/TECH_DESIGN.md) | Architecture decisions |\n\n## Troubleshooting\n\n### Logs\n\nTunez writes logs to `~/.config/tunez/state/tunez-YYYYMMDD.log`\n\n### Common issues\n\n**\"mpv not found\"**\n```bash\n# Verify mpv is installed\nmpv --version\n\n# Or set an explicit path in config\n[player]\nmpv_path = \"/usr/local/bin/mpv\"\n```\n\n**Filesystem provider fails**\n- Ensure `roots` paths exist and are readable\n- Check log file for detailed errors\n\n**Melodee authentication fails**\n- Set the password environment variable:\n  ```bash\n  export TUNEZ_MELODEE_PASSWORD=\"your-password\"\n  ./tunez\n  ```\n\n## Contributing\n\nContributions are welcome! Please read the following before submitting:\n\n1. Keep the Bubble Tea `Update` loop free of blocking I/O\n2. Add tests for non-trivial logic\n3. Run `go test ./...` before submitting\n4. Follow existing code style (`go fmt`)\n\n### Development commands\n\n```bash\ncd src\ngo test ./...      # Run all tests\ngo test ./... -v   # Verbose output\ngo fmt ./...       # Format code\ngo vet ./...       # Check for issues\n```\n\n### TUI Testing with teatest\n\nTunez uses [teatest](https://github.com/charmbracelet/x/tree/main/exp/teatest) for TUI integration testing. Tests use mock providers with fixture data—no real config or music files needed.\n\n```bash\n# Run golden file tests (compares rendered UI to snapshots)\ngo test ./internal/app/... -run TestScreensGolden -v\n\n# Update golden files after intentional UI changes\ngo test ./internal/app/... -run TestScreensGolden -update\n\n# Test keybindings\ngo test ./internal/app/... -run TestKeyboardShortcuts -v\n```\n\nGolden files are stored in `src/internal/app/testdata/` and track expected screen output. See [docs/TEST_STRATEGY.md](docs/TEST_STRATEGY.md) for full details.\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with 🎵 and Go\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphildreth%2Ftunez","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsphildreth%2Ftunez","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphildreth%2Ftunez/lists"}