{"id":17383098,"url":"https://github.com/shinokada/tera","last_synced_at":"2026-04-02T13:58:00.065Z","repository":{"id":138588692,"uuid":"382483255","full_name":"shinokada/tera","owner":"shinokada","description":"Interactive terminal music radio player. Play your favorite radio station, CRUD your favorite lists, and explore new radio stations from your terminal.  https://tera.codewithshin.com/","archived":false,"fork":false,"pushed_at":"2026-03-26T05:12:18.000Z","size":503773,"stargazers_count":139,"open_issues_count":15,"forks_count":7,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-03-27T01:32:47.323Z","etag":null,"topics":["binary","cli","debian","fedora","golang","linux","macos","music","music-player","radio","windows"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/shinokada/tera/v3","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/shinokada.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["shinokada"],"patreon":null,"open_collective":null,"ko_fi":"codewithshin","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2021-07-02T23:11:48.000Z","updated_at":"2026-03-26T05:09:41.000Z","dependencies_parsed_at":"2023-04-15T12:01:30.287Z","dependency_job_id":"3a6cf2b5-6e84-4897-994b-b3c2ec722c22","html_url":"https://github.com/shinokada/tera","commit_stats":null,"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"purl":"pkg:github/shinokada/tera","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinokada%2Ftera","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinokada%2Ftera/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinokada%2Ftera/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinokada%2Ftera/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shinokada","download_url":"https://codeload.github.com/shinokada/tera/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shinokada%2Ftera/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307414,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["binary","cli","debian","fedora","golang","linux","macos","music","music-player","radio","windows"],"created_at":"2024-10-16T07:40:35.737Z","updated_at":"2026-04-02T13:58:00.057Z","avatar_url":"https://github.com/shinokada.png","language":"Go","readme":"# Tera: Terminal Radio\n[REPO](https://github.com/shinokada/tera)\n\nA terminal-based internet radio player powered by [Radio Browser](https://www.radio-browser.info/).\n\n## Features\n\n- 🔍 **Search** - Find stations by name, tag, language, country, or state\n- 🎲 **I Feel Lucky** - Random station discovery by keyword\n- 💾 **Favorites** - Organize stations into custom lists with duplicate detection\n- ⭐ **Star Ratings** - Rate stations 1-5 stars and browse your top-rated collection\n- 🏷️ **Custom Tags** - Tag stations with personal labels and build dynamic playlists\n- ⚡ **Quick Play** - Direct playback from main menu (shortcuts 10-99+)\n- 🕐 **Recently Played** - Last N stations shown below Quick Play Favorites in the main menu\n- 🔊 **Playback Control** - Play/pause with persistent status, adjust volume, and mute during playback\n- 🚫 **Block List** - Block unwanted stations from appearing in searches and auto-play\n- ☁️ **Sync \u0026 Backup** - Export/restore local zip backups and sync all data via GitHub Gists\n- 🗳️ **Voting** - Support your favorite stations on Radio Browser\n- 🎨 **Themes** - Choose from predefined themes or customize via YAML config\n- 💤 **Sleep Timer** - Set a timer to stop playback automatically\n- 📊 **Most Played** - View your listening history sorted by play count, last played, or first played\n- 🔄 **Update Checker** - Get notified when a new version is available\n- 🎵 **Continue on Navigate** - Keep listening while browsing: station keeps playing as you explore other screens, with a Now Playing bar showing on every non-player screen\n- ⌨️ **Keyboard-driven** - Full navigation without a mouse\n- ❓ **Context Help** - Press `?` anytime to see available keyboard shortcuts\n- 🖥️ **Command-Line Play** - Play stations directly from the terminal without opening the TUI\n\n## Requirements\n\n- [mpv](https://mpv.io/) - Media player for audio playback\n\n## Installation\n\n### Homebrew (macOS/Linux)\n```sh\n# update and upgrade\nbrew update \u0026\u0026 brew upgrade\nbrew install shinokada/tera/tera\n# Upgrade existing installation\nbrew upgrade shinokada/tera/tera\n```\n\n### Golang\n```sh\ngo install github.com/shinokada/tera/v3/cmd/tera@latest\n```\n\n### Debian/Ubuntu\n```sh\nsudo dpkg -i tera_3.x.x_linux_amd64.deb\nsudo apt-get install -f  # Install mpv dependency if needed\n```\n\n### Fedora/RHEL\n```sh\nsudo rpm -i tera_3.x.x_linux_amd64.rpm\n```\n\n### Windows Scoop\n```sh\nscoop bucket add shinokada https://github.com/shinokada/scoop-bucket\nscoop install tera\n```\n\n### Windows Winget\n```sh\nwinget install Shinokada.Tera\n# Upgrade existing installation\nwinget upgrade Shinokada.Tera\n```\n\n### Manual Download\n\nDownload the latest binary for your platform from the [releases page](https://github.com/shinokada/tera/releases):\n\n| Platform | Architecture  | File                             |\n| -------- | ------------- | -------------------------------- |\n| macOS    | Intel         | `tera_3.x.x_darwin_amd64.tar.gz` |\n| macOS    | Apple Silicon | `tera_3.x.x_darwin_arm64.tar.gz` |\n| Linux    | x86_64        | `tera_3.x.x_linux_amd64.tar.gz`  |\n| Linux    | ARM64         | `tera_3.x.x_linux_arm64.tar.gz`  |\n| Windows  | x86_64        | `tera_3.x.x_windows_amd64.zip`   |\n| Windows  | ARM64         | `tera_3.x.x_windows_arm64.zip`   |\n\n#### macOS/Linux\n\n```sh\n# Download and extract (example for macOS Apple Silicon)\ntar -xzf tera_3.x.x_darwin_arm64.tar.gz\n\n# Move to a directory in your PATH\nsudo mv tera /usr/local/bin/\n```\n\n#### Windows\n\n1. Download the `.zip` file for your architecture\n2. Extract the archive\n3. Add the extracted directory to your PATH or move `tera.exe` to a directory already in your PATH\n\n## Quick Start\n\n```sh\n# Start TERA\ntera\n\n# Main Menu Options:\n# 1) Play from Favorites - Browse your saved lists\n# 2) Search Stations     - Find new stations\n# 3) Most Played         - Your listening statistics\n# 4) Top Rated           - Browse your highest-rated stations\n# 5) Browse by Tag       - Browse stations by your custom tags\n# 6) Tag Playlists       - Dynamic playlists from tag combinations\n# 7) Manage Lists        - Create/edit/delete favorite lists\n# 8) Block List          - Manage blocked stations\n# 9) I Feel Lucky        - Random station by keyword\n# 0) Sync \u0026 Backup       - Backup/restore data locally or via GitHub\n# -) Settings            - Configure TERA\n\n# Quick Play (from main menu):\n# Type 10-99+ to instantly play stations from \"My-favorites\"\n\n# Need help? Press ? anytime to see keyboard shortcuts!\n```\n\n## Command-Line Play\n\nPlay stations directly from the terminal without opening the TUI — useful for shell scripts, startup routines, or timed listening sessions.\n\n```sh\ntera play \u003csource\u003e [args] [--duration \u003cduration\u003e]\n```\n\n### Sources\n\n| Full form     | Short alias | Args              | Description                               |\n| ------------- | ----------- | ----------------- | ----------------------------------------- |\n| `favorites`   | `fav`       | `[list-name] [n]` | Play nth station from a favorites list    |\n| `recent`      | `rec`       | `[n]`             | Play the nth most recently played station |\n| `top-rated`   | `top`       | `[n]`             | Play the nth highest-rated station        |\n| `most-played` | `most`      | `[n]`             | Play the nth most-played station          |\n| `lucky`       | —           | `\u003ckeyword ...\u003e`   | Play a random station matching keyword(s) |\n\n`[list-name]` defaults to `My-favorites`. `[n]` defaults to `1` (first item, 1-based).\n\n### Examples\n\n```sh\n# Play the first station from My-favorites\ntera play fav\n\n# Play the 3rd station from the jazz list\ntera play fav jazz 3\n\n# Play the most recently played station\ntera play rec\n\n# Play the highest-rated station\ntera play top\n\n# Play the most-played station\ntera play most\n\n# Play a random station matching a keyword\ntera play lucky ambient\n\n# Multi-word keywords work too\ntera play lucky smooth jazz\n\n# Stop automatically after 30 minutes\ntera play fav --duration 30m\n\n# Play for 1 hour then stop\ntera play lucky ambient --duration 1h\n```\n\n### Duration\n\nThe optional `--duration` flag accepts Go duration format: `30s`, `10m`, `1h`, `1h30m`. Without it, playback continues until `Ctrl+C`.\n\n### Status Line\n\nA single line is printed when playback starts:\n\n```text\n▶ Playing: Jazz FM  [jazz · item 1 of 12]  (Ctrl+C to stop)\n▶ Playing: Jazz FM  [jazz · item 1 of 12]  (stops in 30m · Ctrl+C to stop early)\n```\n\n### Notes\n\n- Requires `mpv` to be installed (same as the TUI)\n- CLI play sessions update Recently Played and Most Played history in the TUI\n- `lucky` requires network access to query Radio Browser; all other sources are local\n- Run `tera play --help` for full usage\n\n---\n\n## Main Features\n\n### Play from Favorites\n\nBrowse and play stations from your organized lists. Navigate with `↑↓` or `jk`, press `Enter` to play. Press `/` to filter stations by name.\n\n### Search Stations\n\nSix search methods to find stations:\n- **By Tag** - Genre/style (jazz, rock, classical)\n- **By Name** - Station name (BBC, NPR, KEXP)\n- **By Language** - Broadcasting language\n- **By Country** - Country code (US, UK, JP)\n- **By State** - Region/state name\n- **Advanced** - Search both name and tags\n\nSee [Search Guide](#search-guide) below for details.\n\n### Manage Lists\n\nCreate, rename, and delete your favorite lists. Stations can be:\n- Saved to multiple lists\n- Moved between lists\n- Deleted from lists\n\n**Duplicate Detection**: TERA automatically prevents adding the same station twice to any list.\n\n### Block List\n\nBlock unwanted stations to prevent them from appearing in shuffle mode and, by default, in search results.\n\n**How to Block:**\n- While playing any station, press `b` to block it instantly\n- Press `u` within 5 seconds to undo (in case of accidental block)\n- Works in Search, I Feel Lucky, and Play from Favorites\n\n**Block List Management:**\nFrom main menu, select \"8. Block List\" to:\n- **1. View Blocked Stations** — List all blocked stations; press `u` to unblock, `c` to clear all\n- **2. Manage Block Rules** — Block entire countries, languages, or tags at once\n- **3. Import/Export Blocklist** — Backup and restore your blocklist\n- **4. Search Visibility** — Control whether blocked stations appear in search results\n\n**Search Visibility (default: hidden):**\nBy default, blocked stations are completely hidden from search results. To change this:\n1. Go to **Block List → 4. Search Visibility**\n2. Press `y` to show blocked stations in search (marked with 🚫)\n3. Press `n` to hide them again (default)\n\n**Keyboard Shortcuts:**\n\n| Screen     | Key | Action                    |\n| ---------- | --- | ------------------------- |\n| Playing    | `b` | Block current station     |\n| Playing    | `u` | Undo block (5 sec window) |\n| Block List | `u` | Unblock selected station  |\n| Block List | `c` | Clear all blocks          |\n\n**Storage Location:**\n- Linux: `~/.config/tera/data/blocklist.json`\n- macOS: `~/Library/Application Support/tera/data/blocklist.json`\n- Windows: `%APPDATA%\\tera\\data\\blocklist.json`\n\n### Star Ratings\n\nRate your favorite stations from 1-5 stars to build your personal collection of top stations.\n\n**How to Rate:**\n- While playing any station, press `r` then `1-5` to rate\n- Press `r` then `0` to remove a rating\n- Press `r` then any other key (or `Esc`) to cancel without changing the rating\n- Stars appear in search results, favorites, and the playing screen\n\n**Top-Rated View:**\nFrom main menu, select \"4. Top Rated\" to:\n- Browse all your rated stations sorted by rating\n- Filter by minimum star rating (press `f`)\n- Sort by rating high/low or recently rated (press `s`)\n- Play stations directly from the list\n\n**Keyboard Shortcuts:**\n\n| Screen    | Key            | Action           |\n| --------- | -------------- | ---------------- |\n| Playing   | `r` then `1-5` | Rate station     |\n| Playing   | `r` then `0`   | Remove rating    |\n| Top Rated | `f`            | Cycle filter     |\n| Top Rated | `s`            | Cycle sort order |\n\n**Storage Location:**\n- Linux: `~/.config/tera/data/station_ratings.json`\n- macOS: `~/Library/Application Support/tera/data/station_ratings.json`\n- Windows: `%APPDATA%\\tera\\data\\station_ratings.json`\n\n### Custom Tags\n\nOrganize stations with your own personal labels. Tags are stored locally and never transmitted.\n\n**How to Tag:**\n- While playing any station, press `t` to add a single tag\n- Press `T` (shift+t) to open the **Manage Tags** dialog and toggle multiple tags at once\n- The tag input has autocomplete — start typing and press Tab to complete from existing tags\n\n**Browse by Tag (menu option 5):**\n- See all your tags and how many stations each one covers\n- Select a tag to browse and play the matching stations\n- Press `d` on a tag to remove it from every station at once\n\n**Tag Playlists (menu option 6):**\n- Create named playlists that dynamically pull in stations matching a tag combination\n- Choose **any** (OR) or **all** (AND) matching\n- Edit or delete playlists at any time; the station list updates automatically\n\n**Tag pills in lists:**\nTagged stations show `[tag]` pills inline in every list view — Favorites, Search, Most Played, and Top Rated — so you can see your labels at a glance.\n\n**Keyboard Shortcuts:**\n\n| Screen        | Key | Action                       |\n| ------------- | --- | ---------------------------- |\n| Playing       | `t` | Add a tag (quick input)      |\n| Playing       | `T` | Open Manage Tags dialog      |\n| Browse by Tag | `d` | Delete tag from all stations |\n\n**Tag rules:**\n- Lowercase only (normalized automatically)\n- Up to 50 characters; alphanumeric, spaces, hyphens, underscores\n- Up to 20 tags per station\n\n**Storage Location:**\n- Linux: `~/.config/tera/data/station_tags.json`\n- macOS: `~/Library/Application Support/tera/data/station_tags.json`\n- Windows: `%APPDATA%\\tera\\data\\station_tags.json`\n\n### Sleep Timer\n\nSet a timer to automatically stop playback — useful for falling asleep to radio.\n\n**How to Use:**\n- While playing any station, press `Z` to open the sleep timer dialog\n- Choose a preset duration (15, 30, 45, 60, or 90 minutes) or enter a custom value\n- Press `+` while the timer is running to extend it by 15 minutes\n- When the timer expires, playback stops and a session summary is shown\n\n**Session Summary:**\n- Lists every station played during the timer session\n- Shows total listening duration vs. the duration you set\n- Press `0` to return to the main menu, or any other key to exit TERA\n\n**Keyboard Shortcuts:**\n\n| Screen  | Key | Action                         |\n| ------- | --- | ------------------------------ |\n| Playing | `Z` | Open sleep timer dialog        |\n| Playing | `+` | Extend running timer by 15 min |\n\n### I Feel Lucky\n\nEnter a keyword (genre, mood, style) and TERA finds a random matching station. Perfect for music discovery!\n\n**Input Focus**: The page has two focusable areas — `Genre/keyword` (default) and `Choose an option` (history navigation). Use `Tab` to toggle between them:\n- `▶ Genre/keyword:` is highlighted when active — type freely, including keywords starting with digits (e.g. `80s`, `2pac`)\n- `▶ Choose an option:` is highlighted when active — use `↑↓`/`jk` to navigate history, or `1-N` shortcuts to pick a recent search\n\n**Shuffle Mode**: Enable shuffle mode to automatically cycle through multiple stations matching your keyword:\n- Press `Ctrl+T` to toggle shuffle on/off\n- Stations play in random order without repeats\n- Optional auto-advance timer (configurable)\n- Navigate backward through recently played stations\n- Configure shuffle behavior in Settings → Shuffle Settings\n\nSee [Shuffle Mode](#shuffle-mode) for detailed features.\n\n### Settings\n\nAccess app configuration from the main menu (Settings: `-`):\n\n- **Theme / Colors** - Switch between predefined themes or customize colors\n- **Appearance** - Customize header display (text, ASCII art, alignment, colors, padding)\n- **Play Options** - Control playback behaviour while navigating (see below)\n- **Connection Settings** - Auto-reconnect and buffering for unstable networks (4G/GPRS)\n- **Shuffle Settings** - Configure shuffle mode behavior (auto-advance, history size)\n- **History** - Search history and Recently Played display settings (size, display rows, reset)\n- **Check for Updates** - View current version and check for new releases\n- **About TERA** - See version, installation method, and update command\n\nThe Settings menu automatically detects how you installed TERA (Homebrew, Go, Scoop, Winget, etc.) and shows the appropriate update command.\n\n### Play Options (Continue on Navigate)\n\nWhen **Continue on Navigate** is enabled, a playing station keeps streaming as you move to other screens:\n\n- A **♫ Now Playing** bar appears above the footer on every non-player screen, showing the station name, star rating, context, and a reminder to press `x` to stop.\n- Press `x` from **any screen** to stop playback immediately.\n- Selecting a new Quick Play or Recently Played station automatically stops the previous one first — no double playback.\n\n**Enable / Disable:**\n1. Press `-` from the main menu → Settings\n2. Select **5. Play Options**\n3. Toggle **Continue on Navigate** on or off\n\n### Appearance Settings\n\nCustomize how the TERA header appears at the top of the application:\n\n**Header Modes:**\n- **Default** - Show \"TERA\" text (default)\n- **Text** - Display custom text\n- **ASCII** - Show custom ASCII art (max 15 lines)\n- **None** - Hide header completely\n\n**Customization Options:**\n- **Alignment** - Left, center, or right\n- **Width** - Header width (10-120 characters)\n- **Color** - Auto, hex code (#FF0000), or ANSI code (0-255)\n- **Bold** - Enable/disable bold text\n- **Padding** - Top and bottom spacing (0-5 lines)\n\n**Tips:**\n- Preview changes before saving\n- Use [TAAG](https://patorjk.com/software/taag/) or `figlet` to generate ASCII art\n- Settings stored in the config directory (see [File Locations](#file-locations))\n\n### Connection Settings\n\nFor users on unstable networks (mobile data, GPRS, 4G), configure automatic reconnection:\n\n- **Auto-reconnect** - Automatically retry when stream drops (default: enabled)\n- **Reconnect delay** - Wait time between attempts: 1-30 seconds (default: 5s)\n- **Stream buffer** - Cache size to handle brief signal drops: 10-200 MB (default: 50MB)\n\nSettings stored in the config directory (see [File Locations](#file-locations)).\n\n### Quick Play \u0026 Recently Played\n\nThe main menu shows two instant-access sections below the regular menu:\n\n```text\nMain Menu \u0026 Quick Play\n\nChoose an option:\n\n  1. Play from Favorites\n  ...\n  -. Settings\n\n─── Quick Play Favorites ───\n  10. Jazz FM • UK • MP3 192kbps\n  11. BBC Radio 6 Music • UK • AAC 128kbps\n\n─── Recently Played ───\n  12. WBGO Jazz 88.3 • United States • 3 minutes ago\n  13. FIP • France • 1 hour ago\n  14. Radio Swiss Jazz • Switzerland • Yesterday\n\nType 10-14 to play instantly!\n```\n\n**Quick Play Favorites:** Stations from \"My-favorites.json\" with shortcuts starting at 10.\n\n**Recently Played:** Your last N stations (default 5), shown in most-recently-played order. Shortcuts continue from where Quick Play Favorites end.\n\n**How it works:**\n- Type the shortcut number and press Enter, or navigate with `↑↓` and press Enter\n- Station plays immediately via the shared player\n- Press `Esc` to stop playback\n- The `▶` indicator marks the currently playing station in both sections\n\n**Configure Recently Played:**\n1. Press `-` from the main menu → Settings\n2. Select **5. History → 2. Play History**\n3. Available options:\n   - **Toggle Show** — enable or disable the section entirely\n   - **History Size** — how many stations to track (1–20, default 5)\n   - **Display Rows** — cap the number of rows shown at once (1–10; `0` = fill available space)\n   - **Reset All Play Stats** — clears play counts, Most Played, and Recently Played\n\n## Theme Configuration\n\n### In-App Theme Selection\n\nThe easiest way to change themes is through the Settings menu:\n\n1. Press `-` from the main menu to open Settings\n2. Select \"Theme / Colors\"\n3. Choose from predefined themes:\n   - **Default** - Cyan and blue tones\n   - **Ocean** - Deep blue theme\n   - **Forest** - Green nature theme\n   - **Sunset** - Warm orange and red\n   - **Purple Haze** - Purple and magenta\n   - **Monochrome** - Classic black and white\n   - **Dracula** - Popular dark theme\n   - **Nord** - Arctic, north-bluish\n\n### Manual Configuration\n\nYou can also customize colors and padding by editing the theme config file:\n\n```sh\ntera theme path   # Show config file location\ntera theme reset  # Reset to defaults\n```\n\nThe config file includes an ANSI color reference (0-15 standard colors, 16-255 extended colors). Example:\n\n```yaml\ncolors:\n  primary: \"6\"      # Cyan\n  highlight: \"3\"    # Yellow\n  error: \"9\"        # Bright Red\n  \npadding:\n  list_item_left: 2\n```\n\n## Update Checker\n\nTERA automatically checks for new versions on startup. When an update is available:\n\n- A yellow **⬆ Update** indicator appears in the main menu footer\n- Go to **Settings → Check for Updates** for details and update instructions\n\n### Checking for Updates\n\n1. Press `-` from the main menu to open Settings\n2. Select \"Check for Updates\" (option 2)\n3. View:\n   - Your current version\n   - Latest available version\n   - Link to release notes\n   - Installation method (automatically detected)\n   - Specific update command for your installation\n\nTERA detects how you installed it and provides the correct update command. For example:\n- If installed via Homebrew: Shows `brew upgrade shinokada/tera/tera`\n- If installed via Go: Shows `go install github.com/shinokada/tera/v3/cmd/tera@latest`\n- If installed via Scoop: Shows `scoop update tera`\n- If installed via Winget: Shows `winget upgrade tera`\n\n### Update Commands\n\n| Installation Method | Update Command                                                            |\n| ------------------- | ------------------------------------------------------------------------- |\n| Homebrew            | `brew upgrade shinokada/tera/tera`                                        |\n| Go install          | `go install github.com/shinokada/tera/v3/cmd/tera@latest`                 |\n| Scoop               | `scoop update tera`                                                       |\n| Winget              | `winget upgrade tera`                                                     |\n| APT/DEB             | `sudo apt update \u0026\u0026 sudo apt install --only-upgrade tera`                 |\n| RPM/DNF             | `sudo dnf upgrade tera`                                                   |\n| Manual              | Download from [releases page](https://github.com/shinokada/tera/releases) |\n\n## Shuffle Mode\n\nShuffle mode is an enhanced version of \"I Feel Lucky\" that lets you explore multiple stations matching your search keyword without manually searching each time.\n\n### How It Works\n\n1. Navigate to **I Feel Lucky** from the main menu (option 9)\n2. Press `Ctrl+T` to toggle shuffle mode on\n3. Enter your keyword (e.g., \"jazz\", \"rock\", \"meditation\")\n4. Press Enter to start shuffle mode\n\n### Features\n\n**Automatic Station Discovery**\n- TERA finds all stations matching your keyword\n- Plays them in random order without repeats\n- No duplicates until all stations have been played\n\n**Auto-Advance Timer** (Optional)\n- Automatically skip to the next station after a set interval\n- Configurable intervals: 1, 3, 5, 10, or 15 minutes\n- Pause/resume timer with `p` key\n- Disable for manual control\n\n**Station History**\n- Keep track of recently played stations\n- Navigate backward with `b` key\n- Configurable history size: 3, 5, 7, or 10 stations\n- See last few stations in the shuffle history display\n\n**Seamless Playback**\n- All standard playback controls work (volume, mute, favorites, voting)\n- Save any station to your favorites while shuffling\n- Stop shuffle but keep playing current station with `h`\n\n### Shuffle Keyboard Shortcuts\n\n| Key      | Action                                         |\n| -------- | ---------------------------------------------- |\n| `Ctrl+T` | Toggle shuffle mode (in input screen)          |\n| `Tab`    | Switch focus: Genre/keyword ↔ Choose an option |\n| `n`      | Next shuffle station (manual skip)             |\n| `[`      | Previous station (from history)                |\n| `b`      | Block current station                          |\n| `u`      | Undo block (5 sec window)                      |\n| `p`      | Pause/resume auto-advance timer                |\n| `h`      | Stop shuffle, keep playing current             |\n| `f`      | Save to My-favorites                           |\n| `s`      | Save to another list                           |\n| `v`      | Vote for station                               |\n| `r`      | Rate station (then 1-5 / 0)                    |\n| `Esc`    | Stop shuffle and return to input               |\n\n### Shuffle Settings\n\nConfigure shuffle behavior in **Settings → Shuffle Settings**:\n\n**Auto-advance**\n- Enable/disable automatic station switching\n- When disabled, you manually control station changes with `n`/`[`\n\n**Auto-advance Interval**\n- Set how long each station plays before auto-advancing\n- Options: 1, 3, 5, 10, or 15 minutes\n- Default: 5 minutes\n\n**Remember History**\n- Enable/disable station history tracking\n- When disabled, you cannot go back to previous stations\n\n**History Size**\n- Number of previous stations to remember\n- Options: 3, 5, 7, or 10 stations\n- Default: 5 stations\n\n### Example Shuffle Session\n\n```text\n🎵 Now Playing (🔀 Shuffle: jazz)\n\nStation: Smooth Jazz 24/7\nCountry: United States\nCodec: AAC • Bitrate: 128 kbps\n\n▶ Playing...\n\n🔀 Shuffle Active • Next in: 4:23\n   Station 3 of session\n   \n─── Shuffle History ───\n  ← Jazz FM London\n  ← WBGO Jazz 88.3\n  → Smooth Jazz 24/7  ← Current\n\nSpace: Pause • n: Next • [: Prev • f: Fav • b: Block • p: Pause timer • h: Stop shuffle • 0: Main Menu • ?: Help\n```\n\n### Configuration File\n\nShuffle settings are stored in the config directory as `shuffle.yaml`:\n\n```yaml\nshuffle:\n  auto_advance: true           # Auto-advance enabled\n  interval_minutes: 5          # 5 minutes per station\n  remember_history: true       # Track history\n  max_history: 5               # Remember last 5 stations\n```\n\nFile location:\n- Linux: `~/.config/tera/shuffle.yaml`\n- macOS: `~/Library/Application Support/tera/shuffle.yaml`\n- Windows: `%APPDATA%\\tera\\shuffle.yaml`\n\nYou can edit this file directly or use the Settings menu.\n\n## Keyboard Shortcuts\n\n### Global Navigation\n\n| Key         | Action                                          |\n| ----------- | ----------------------------------------------- |\n| `↑↓` / `jk` | Navigate                                        |\n| `g` / `G`   | Top / End                                       |\n| `Enter`     | Select / Play                                   |\n| `Esc`       | Back / Stop                                     |\n| `0`         | Main Menu                                       |\n| `x`         | Stop Continue-on-Navigate playback (any screen) |\n| `?`         | Help                                            |\n| `Ctrl+C`    | Quit                                            |\n\n### Main Menu\n\n| Key      | Action                                         |\n| -------- | ---------------------------------------------- |\n| `0`      | Sync \u0026 Backup                                  |\n| `1-9`    | Quick select menu item                         |\n| `10-99+` | Quick play from My-favorites / Recently Played |\n| `-`      | Settings                                       |\n\n### Playback Controls\n\n| Key     | Action            |\n| ------- | ----------------- |\n| `Space` | Pause / Resume    |\n| `*`     | Volume up (+5%)   |\n| `/`     | Volume down (-5%) |\n| `m`     | Toggle mute       |\n| `r`     | Rate station      |\n| `b`     | Block station     |\n| `u`     | Undo block (5s)   |\n| `Z`     | Sleep timer       |\n| `+`     | Extend timer      |\n\n### Playing/Browsing Stations\n\n| Key | Action               |\n| --- | -------------------- |\n| `f` | Save to My-favorites |\n| `s` | Save to another list |\n| `v` | Vote for station     |\n| `t` | Add tag              |\n| `T` | Manage tags          |\n\n\u003e **Tip:** Press `?` while playing to see all available shortcuts for the current screen in a help overlay.\n\n### Favorites Station List\n\n| Key | Action                  |\n| --- | ----------------------- |\n| `/` | Filter stations by name |\n| `d` | Delete station          |\n\n### List Management\n\n| Key | Action                |\n| --- | --------------------- |\n| `n` | New list (in dialogs) |\n| `d` | Delete item           |\n\n## Search Guide\n\nThe **Search Stations** menu offers multiple ways to find stations:\n\n### Search Types\n\n| Option                     | Description                              | Example Query                       |\n| -------------------------- | ---------------------------------------- | ----------------------------------- |\n| **Search by Tag**          | Find stations by genre/style tags        | `jazz`, `rock`, `news`, `classical` |\n| **Search by Name**         | Find stations by their name              | `BBC`, `NPR`, `KEXP`                |\n| **Search by Language**     | Find stations broadcasting in a language | `english`, `spanish`, `japanese`    |\n| **Search by Country Code** | Find stations from a specific country    | `US`, `UK`, `FR`, `JP`              |\n| **Search by State**        | Find stations from a state/region        | `California`, `Texas`, `Bavaria`    |\n| **Advanced Search**        | Search both name AND tag fields          | `smooth jazz`, `classic rock`       |\n\n### Query Format\n\n- **Single words work**: `jazz`, `rock`, `news`\n- **Multi-word phrases work**: `classic rock`, `smooth jazz`, `talk radio`\n- **Partial matching**: Searching `BBC` finds \"BBC Radio 1\", \"BBC World Service\", etc.\n- **Case insensitive**: `Jazz`, `JAZZ`, and `jazz` all work the same\n\n### When to Use Advanced Search\n\nUse **Advanced Search** when:\n- You're not sure if your term is a station name or a genre tag\n- You want broader results across multiple fields\n- You're exploring and want maximum discovery\n\n**Features:**\n- **Country**: Enter a 2-letter code (e.g., \"US\") for Country Code search, or a full name (e.g., \"Japan\") for Country Name search.\n- **Bitrate**: Press 1, 2, or 3 to filter by quality. Press the same number again to unselect.\n- **Language**: Case-insensitive (e.g., \"English\" becomes \"english\").\n\nFor example, searching `jazz` in Advanced Search finds:\n- Stations with \"jazz\" in their name (e.g., \"Jazz FM\")\n- Stations tagged with \"jazz\" as a genre\n\n### Search Results\n\nResults are sorted by **votes** (most popular first) and limited to 100 stations. Broken/offline stations are automatically filtered out.\n\n**In the results:**\n- Navigate with `↑↓` or `jk`\n- Press `Enter` to view station details and play\n- Press `f` to add to My-favorites\n- Press `s` to add to another list\n- Press `v` to vote for the station\n\n## Sync \u0026 Backup\n\nBack up and sync your data locally or across devices using zip archives and GitHub Gists.\n\n### Export Backup (zip)\n\nSave a local copy of your data with no GitHub account required.\n\n1. From the main menu press `0` → **Sync \u0026 Backup**\n2. Select **7. Export backup (zip)**\n3. Choose which categories to include (favorites, ratings, tags, etc.)\n4. Confirm the save path (default: `~/tera-backup-YYYY-MM-DD.zip`)\n\n### Restore from Backup (zip)\n\n1. Select **8. Restore from backup (zip)**\n2. Enter the path to your zip file\n3. Choose which categories to restore\n4. Confirm — you will be warned before any existing files are overwritten\n\n### Sync to Gist\n\nPush all selected data to a dedicated secret GitHub Gist (`tera-data-backup`).\n\n**Quick Setup:**\n1. Go to **0) Sync \u0026 Backup → Token Management**\n2. Create a GitHub Personal Access Token with `gist` scope\n3. Paste the token in TERA\n4. Select **9. Sync all data to Gist** and choose categories\n\n### Restore from Gist\n\n1. Select **10. Restore all data from Gist**\n2. TERA fetches the `tera-data-backup` Gist and shows available categories\n3. Choose what to restore — you will be warned before overwriting\n\n### Sync Categories\n\n| Category                | Default |\n| ----------------------- | ------- |\n| Favorites (playlists)   | ✅ on    |\n| Settings (config.yaml)  | ✅ on    |\n| Ratings \u0026 votes         | ✅ on    |\n| Blocklist               | ✅ on    |\n| Station metadata \u0026 tags | ✅ on    |\n| Search history          | ❌ off   |\n\nCategory selections are saved in `sync_prefs.json` and reused on the next run.\n\n**Documentation:**\n- [Gist Setup Guide](docs/GIST_SETUP.md) - Token setup and security\n- [Gist Management Guide](docs/GIST_CRUD_GUIDE.md) - Complete feature guide\n\n## File Locations\n\nTERA stores its configuration files in the OS-standard config directory:\n\n| Operating System | Location                              |\n| ---------------- | ------------------------------------- |\n| **Linux**        | `~/.config/tera/`                     |\n| **macOS**        | `~/Library/Application Support/tera/` |\n| **Windows**      | `%APPDATA%\\tera\\`                     |\n\n### Configuration Files\n\n```text\ntera/\n├── config.yaml             # Unified configuration (all settings)\n├── data/\n│   ├── blocklist.json          # Blocked radio stations\n│   ├── voted_stations.json     # Voting history\n│   ├── station_metadata.json   # Play count \u0026 listening history\n│   ├── station_ratings.json    # Star ratings\n│   ├── station_tags.json       # Custom tags and tag playlists\n│   ├── favorites/\n│   │   ├── My-favorites.json   # Quick play list (main menu 10+)\n│   │   ├── Rock.json\n│   │   └── Jazz.json\n│   └── cache/\n│       ├── gist_metadata.json\n│       └── search-history.json\n└── .v2-backup-YYYYMMDD-HHMMSS/ # Automatic v2 config backup\n```\n\n**Environment Variable Override:**\nYou can set a custom favorites directory:\n```sh\nexport TERA_FAVORITE_PATH=\"/path/to/your/favorites\"\n```\n\n## Troubleshooting\n\n### No sound?\n- Ensure `mpv` is installed: `mpv --version`\n- Check your system audio settings\n- Try playing a test stream: `mpv https://stream.example.com`\n\n### Station won't play?\n- Some streams may be temporarily offline\n- Try another station\n- Check if the station works in a web browser\n\n### Stop stuck playback\n```sh\npkill mpv\n```\n\n### Multiple stations playing at once\nTERA should prevent this, but if it happens:\n- Press `x` from any screen to stop Continue-on-Navigate playback\n- Or kill all mpv processes:\n```sh\nkillall mpv\n# or on Linux\npkill -9 mpv\n```\n\n### Can't find My-favorites.json\nTERA creates it automatically at first launch. Check the favorites directory in your OS-specific config location (see [File Locations](#file-locations)).\n\nIf missing, restart TERA and it will be created.\n\n## Development\n\n### Requirements\n- Go 1.21+\n- mpv\n\n### Run from source\n```sh\ngit clone https://github.com/shinokada/tera.git\ncd tera\ngo run ./cmd/tera/\n```\n\n### Test\n```sh\ngo test ./... -v\n```\n\n### Build\n```sh\ngo build -o tera ./cmd/tera/\n```\n\n## Contributing\n\nContributions are welcome! Please:\n1. Open an issue to discuss proposed changes\n2. Fork the repository\n3. Create a feature branch\n4. Submit a pull request\n\n## License\n\n[MIT](LICENSE) © Shinichi Okada\n\n## Links\n\n- [GitHub Repository](https://github.com/shinokada/tera)\n- [Issue Tracker](https://github.com/shinokada/tera/issues)\n- [Radio Browser](https://www.radio-browser.info/) - Station database\n","funding_links":["https://github.com/sponsors/shinokada","https://ko-fi.com/codewithshin"],"categories":["\u003ca name=\"music\"\u003e\u003c/a\u003eSound and music"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinokada%2Ftera","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshinokada%2Ftera","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshinokada%2Ftera/lists"}