diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..8478f66 --- /dev/null +++ b/README.en.md @@ -0,0 +1,204 @@ +A retro terminal music player inspired by Winamp. Play local files, streams, podcasts, YouTube, YouTube Music, SoundCloud, Bilibili, Spotify, NetEase Cloud Music, Xiaoyuzhou (小宇宙), Navidrome, Plex, and Jellyfin with a spectrum visualizer, parametric EQ, and playlist management. + +**[cliamp.stream](https://cliamp.stream)** + +Built with [Bubbletea](https://github.com/charmbracelet/bubbletea), [Lip Gloss](https://github.com/charmbracelet/lipgloss), [Beep](https://github.com/gopxl/beep), and [go-librespot](https://github.com/devgianlu/go-librespot). + + +https://github.com/user-attachments/assets/fbc33d20-e3ac-4a62-a991-8a2f0243c8ea + + +## Install + +```sh +curl -fsSL https://raw.githubusercontent.com/bjarneo/cliamp/HEAD/install.sh | sh +``` + +**Homebrew** + +```sh +brew install bjarneo/cliamp/cliamp +``` + +The formula pulls in all required runtime libraries automatically. + +**Arch Linux (AUR)** + +```sh +yay -S cliamp +``` + +**Go** + +```sh +go install github.com/bjarneo/cliamp@latest +``` + +Linux builds need ALSA development headers installed first. See [Building from source](#building-from-source). + +**Pre-built binaries** + +Download from [GitHub Releases](https://github.com/bjarneo/cliamp/releases/latest). + +> **macOS:** the pre-built binaries dynamically link against FLAC, Vorbis, and Ogg +> from Homebrew. If you download directly from Releases (or use the `install.sh` +> script) you must install them first, otherwise you will see errors like +> `Library not loaded: /opt/homebrew/opt/libvorbis/lib/libvorbisenc.2.dylib`: +> +> ```sh +> brew install flac libvorbis libogg +> ``` +> +> Installing via `brew install bjarneo/cliamp/cliamp` does this for you. +> +> **Linux:** the pre-built binaries statically link FLAC, Vorbis, and Ogg, so no +> extra codec packages are required. You may still need an ALSA bridge for your +> sound server — see [Troubleshooting](#troubleshooting). +> +> **Windows:** download `cliamp-windows-amd64.exe` from Releases. If `HOME` is not +> set, cliamp stores its config under `%APPDATA%\cliamp`. The Spotify provider is +> currently unavailable on Windows builds. + +**Optional runtime dependencies** (all platforms, all install methods): + +- [ffmpeg](https://ffmpeg.org/) — for AAC, ALAC, Opus, and WMA playback +- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — for YouTube, YouTube Music, SoundCloud, Bandcamp, Bilibili, and NetEase Cloud Music + +On macOS: `brew install ffmpeg yt-dlp`. On Linux, use your distribution's package manager. + +On Windows, install `ffmpeg` and `yt-dlp` with your preferred package manager and keep both on `PATH`. + +**Build from source** + +```sh +git clone https://github.com/bjarneo/cliamp.git && cd cliamp && go build -o cliamp . +``` + +## Quick Start + +```sh +cliamp ~/Music # play a directory +cliamp *.mp3 *.flac # play files +cliamp https://example.com/stream # play a URL +``` + +Press `Ctrl+K` to see all keybindings. + +**Configure remote providers** (Navidrome, Plex, Jellyfin, Spotify, YouTube Music, NetEase Cloud Music) with the interactive wizard: + +```sh +cliamp setup +``` + +It walks you through each provider, validates the connection, and writes the right block to your config file (`~/.config/cliamp/config.toml`, or `%APPDATA%\cliamp\config.toml` on Windows when `HOME` is unset). See [docs/cli.md](docs/cli.md#setup-wizard) for details. + +## Radio + +Press `R` in the player to browse and search 30,000+ online radio stations from the [Radio Browser](https://www.radio-browser.info/) directory. + +Add your own stations to `~/.config/cliamp/radios.toml` (or `%APPDATA%\cliamp\radios.toml` on Windows when `HOME` is unset). See [docs/configuration.md](docs/configuration.md#custom-radio-stations). + +Want to host your own radio? Check out [cliamp-server](https://github.com/bjarneo/cliamp-server). + +## Building from source + +**Prerequisites:** + +- [Go](https://go.dev/dl/) 1.25.5 or later +- ALSA development headers (Linux only — required by the audio backend) + +**Linux (Debian/Ubuntu):** + +```sh +sudo apt install libasound2-dev +``` + +**Linux (Fedora):** + +```sh +sudo dnf install alsa-lib-devel libvorbis-devel flac-devel +``` + +**Linux (Arch):** + +```sh +sudo pacman -S alsa-lib +``` + +**macOS:** No extra dependencies — CoreAudio is used. + +**Windows:** No extra SDKs required for the core player. `ffmpeg.exe` and `yt-dlp.exe` remain optional runtime dependencies for the same formats/providers as on other platforms. Spotify is not available on Windows builds. + +**Clone and build:** + +```sh +git clone https://github.com/bjarneo/cliamp.git +cd cliamp +make && make install +``` + +Or without Make: `go build -o cliamp .` + +`make install` places the binary in `~/.local/bin/`. + +**Optional runtime dependencies:** + +- [ffmpeg](https://ffmpeg.org/) — for AAC, ALAC, Opus, and WMA playback +- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — for YouTube, SoundCloud, Bandcamp, Bilibili, and NetEase Cloud Music + +## Docs + +- [Configuration](docs/configuration.md) +- [Keybindings](docs/keybindings.md) +- [CLI Flags](docs/cli.md) +- [Streaming](docs/streaming.md) +- [Playlists](docs/playlists.md) +- [YouTube, SoundCloud, Bandcamp and Bilibili](docs/yt-dlp.md) +- [YouTube Music](docs/youtube-music.md) +- [NetEase Cloud Music](docs/netease.md) +- [SoundCloud](docs/soundcloud.md) +- [Lyrics](docs/lyrics.md) +- [Spotify](docs/spotify.md) +- [Navidrome](docs/navidrome.md) +- [Plex](docs/plex.md) +- [Jellyfin](docs/jellyfin.md) +- [Themes](docs/themes.md) +- [SSH Streaming](docs/ssh-streaming.md) +- [Remote Control (IPC)](docs/remote-control.md) +- [Headless Daemon Mode](docs/headless.md) +- [Audio Quality](docs/audio-quality.md) +- [Media Controls](docs/mediactl.md) +- [Quickshell Now-Playing Widget (Omarchy)](docs/quickshell.md) +- [Lua Plugins](docs/plugins.md) + - [Community Plugins](docs/community-plugins.md) + - [Soap Bubbles Visualizer](https://github.com/bjarneo/cliamp-plugin-soap-bubbles) + +## Troubleshooting + +**No audio output (silence with no errors)** + +On Linux systems using PipeWire or PulseAudio, cliamp's ALSA backend needs a bridge package to route audio through your sound server: + +- **PipeWire:** `pipewire-alsa` +- **PulseAudio:** `pulseaudio-alsa` + +Install the appropriate package for your system: + +```sh +# PipeWire (Arch) +sudo pacman -S pipewire-alsa + +# PulseAudio (Arch) +sudo pacman -S pulseaudio-alsa + +# Debian/Ubuntu (PipeWire) +sudo apt install pipewire-alsa +``` + +## Author + +[x.com/iamdothash](https://x.com/iamdothash) + +## Disclaimer + +Use this software at your own risk. We are not responsible for any damages or issues that may arise from using this software.