Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/An7ar35/ctune
nCurses internet radio player for Linux
https://github.com/An7ar35/ctune
c ffmpeg internet-radio-player linux music ncurses radiobrowser-api terminal-app
Last synced: about 2 months ago
JSON representation
nCurses internet radio player for Linux
- Host: GitHub
- URL: https://github.com/An7ar35/ctune
- Owner: An7ar35
- License: agpl-3.0
- Created: 2021-06-15T14:48:07.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-05-14T12:22:11.000Z (about 1 year ago)
- Last Synced: 2024-01-27T17:03:36.911Z (5 months ago)
- Topics: c, ffmpeg, internet-radio-player, linux, music, ncurses, radiobrowser-api, terminal-app
- Language: C
- Homepage:
- Size: 51.1 MB
- Stars: 14
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- cli-apps - cTune - A ncurses based internet radio player written in C for Linux. (<a name="music"></a>Sound and music)
- awesome-cli-apps - cTune - A ncurses based internet radio player written in C for Linux. (<a name="music"></a>Sound and music)
README
cTune is a ncurses based internet radio player written in C for Linux.
Aside from playing a radio stream you can search and browse stations as well as keep a list of favourites.
It uses the RadioBrowser API to search and get radio stream information.
## Showcase video
[*Click here to watch the video (~45MB)*](https://www.eadavison.com/source/2023/ctune/Release%201.2/video/showcase.mp4)
## Features
- Play/search/browse radio stations using the RadioBrowser API
- Favourite stations from search/browse results
- Add/Edit custom local-only stations to favourites
- Sort favourites based on name/country/bitrate/codec/source/etc...
- Context-based help for key bindings (F1 key).
- Plugin system for playback (demuxing/resampling) and sound output (PCM)
- UI Themes
- Mouse support
### CLI
Usage: ./ctune [OPTION]...
--debug prints out all debug messages to the log
-f --favourite add station to favourites when used in conjunction with "--play"
-h --help display this help and exits
-p --play "UUID" plays the radio stream matching the RadioBrowser UUID
-r --resume resumes station playback of the last session
--show-cursor always visible cursor
-v --version prints version information and exits
## Application files
| type | file name | path | description |
|---------------|---------------|-------------------------|------------------------------------------------------------------------------|
| executable | `ctune` | `/usr/bin/` | cTune application binary |
| man | `ctune.1.gz` | `/usr/share/man/man1/` | cTune man page |
| configuration | `ctune.cfg` | `~/.config/ctune/` | where the configuration is stored |
| configuration | `ctune.fav` | `~/.config/ctune/` | where the favourite stations are stored |
| logging | `ctune.log` | `~/.local/share/ctune/` | log file for last runtime (date/timestamps inside are UTC) |
| logging | `playlog.txt` | `~/.local/share/ctune/` | playback log containing the stations and songs streamed during last runtime* |
*In case you want to find the name of a song/station that you liked and forgot to write down or favourite.
Both the application log and playback log are overwritten when `ctune` is launched again.
## Configuration
The configuration is generated at first launch in `~/.config/ctune/ctune.cfg`. This is where some aspects of cTune can be customised.
### Editable values
| Configuration string | Value type | Default value | Description |
|---------------------------------------|--------------|-----------------|-----------------------------------------------------------------------------------------------------------|
| `IO::Plugin::Player` | string | `ffmpeg` | Player plugin to use (`ffmpeg`, `vlc` ) |
| `IO::Plugin::SoundServer` | string | `pulse` | Sound output plugin to use (`pulse`, `alsa`, `sdl`, `sndio`) |
| `IO::OverwritePlayLog` | bool | `true` | Flag to overwrite play-log instead of appending to it |
| `IO::StreamTimeout` | unsigned int | `5` | Timeout value for streaming in seconds* |
| `IO::NetworkTimeout` | unsigned int | `8` | Timeout value for the network calls in seconds |
| `UI::Mouse` | bool | `false` | Flag to enable mouse support |
| `UI::UnicodeIcons` | bool | `false` | Flag to enable unicode icons (terminal font should support that) |
| `UI::Favourites::ShowTheme` | bool | `true` | Flag to show source theming on the Favourites tab |
| `UI::Favourites::UseCustomTheme` | bool | `true` | Flag to use the 'custom' preset's station source colouring instead of the currently selected preset's | |
| `UI::Favourites::UseLargeRows` | bool | `true` | Flag to use large format row entries in the Favourites tab |
| `UI::Search::UseLargeRows` | bool | `true` | Flag to use large format row entries in the Search tab |
| `UI::Browser::UseLargeRows` | bool | `false` | Flag to use large format row entries in the Browser tab |
| `UI::Theme::preset` | string | `default` | Theme preset name |
| `UI::Theme` | colour pair | `{WHITE,BLACK}` | Base theme colours (foreground, background) |
| `UI::Theme::row` | colour pair | `{WHITE,BLACK}` | Base theme colours for row entries (foreground, background) |
| `UI::Theme::row::selected::focused` | colour pair | `{WHITE,BLUE}` | Theme colours for selected and in-focus row entries |
| `UI::Theme::row::selected::unfocused` | colour pair | `{BLACK,WHITE}` | Theme colours for selected and out-of-focus row entries |
| `UI::Theme::row::favourite::local` | colour | `MAGENTA` | Text colour for a local based station's name on the row entry |
| `UI::Theme::row::favourite::remote` | colour | `YELLOW` | Text colour for a remote based station's name on the row entry |
| `UI::Theme::icon::playback::on` | colour | `GREEN` | Text colour for the playback icon when playing state is true ( > ) |
| `UI::Theme::icon::playback::off` | colour | `RED` | Text colour for the playback icon when playing state is false ( . ) |
| `UI::Theme::icon::queued` | colour | `CYAN` | Text colour for the queued indicator on the corresponding row entry ( > ) |
| `UI::Theme::field::invalid` | colour | `RED` | Text colour for an invalid field |
| `UI::Theme::button` | colour pair | `{WHITE,BLACK}` | Theme colours for buttons |
| `UI::Theme::button::invalid` | colour | `RED` | Validation button colour when linked action fails |
| `UI::Theme::button::validated` | colour | `GREEN` | Validation button colour when linked action is successful |
Colour values available: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`, `MAGENTA`, `CYAN`, `WHITE`
Available theme preset values: "`default`", "`hackerman`", "`red-zone`", "`deep-blue`", "`custom`" (<- this will use the `UI::Theme::*` values in the configuration file)
(*) `StreamTimeout` fully works with the `ffmpeg` player currently and only stream testing with `vlc` (LibVLC doesn't have a call to set a custom value on the player).
**Note:** The VLC plugin is more of a fallback in the event that ffmpeg is an unviable option.
### Auto-generated values
| Configuration string | Value type | Description |
|--------------------------|--------------|-------------------------------------------------------------------------------------|
| `Resume::UUID` | UUID string | UUID of the last station playing during previous session |
| `Resume::SourceID` | unsigned int | Source of the last station playing during previous session (local/radiobrowser/etc) |
| `Resume::Volume` | unsigned int | Volume at last exit (`0`-`100`) |
| `UI::Favourites::SortBy` | unsigned int | In-application selected default sorting for the entries in the Favourites tab |
## Dependencies
| functionality | libraries |
|---------------|----------------------------------------|
| Network | OpenSSL, POSIX sockets, Curl |
| Playback | FFMpeg/VLC, SDL2/PulseAudio/ALSA/sndio |
| Parsing | json-c (static) |
## Installation
### Compile from source
Requires the following to be installed on the system first:
- `cmake` version **3.17** and the CMake extra-modules package
- `git` for fetching the repos
- `ffmpeg`, `vlc` player libraries*
- `curl` and `openssl` libraries
- `sdl2` or `pulsedaudio` or `alsa` or `sndio` sound library/servers*
- `pandoc` and `gzip` for the man page
(*) The relevant plugins will be compiled for whatever libraries can be found on the system.
From there:
1. Clone the repository `git clone https://github.com/An7ar35/ctune.git`
2. Get in the directory with `cd ctune`
3. run `cmake . -DCMAKE_BUILD_TYPE=Release` (append ` -DCMAKE_INSTALL_PREFIX=` if you want to specify a custom directory for the installation)
4. run `cmake --build .`
5. run `sudo cmake --install .`
6. Done.
#### To uninstall
Just run `sudo xargs rm < install_manifest.txt` from within the cloned directory.
Or, alternatively:
- `cmake . -DCMAKE_BUILD_TYPE=uninstall`
- `sudo cmake --build . --target uninstall`
Finally, for both approaches, run `sudo mandb` after to purge the `ctune` entry for the man database
### Install from repository
#### Arch AUR (x64)
The package is available in the AUR repository under `ctune-git`. Install using your favourite AUR package browser/installer.
> Alternatively just download the `PKGBUILD` file into an empty staging folder and run `makepkg -si` from inside.
The rest should take care of itself.
#### Ubuntu 22.10 'Kinetic' (tested with _pulseaudio_ as the default server)
The version of ffmpeg libs packaged with ubuntu 22.04.1 LTS are too old. Since the API changed I've updated the calls in ctune which breaks compilation for older ffmpeg libs.
No PPA but here are copy/paste commands to install all the required programs and development libraries you would need before compiling `ctune`:
```shell
sudo apt-get install gcc libncurses5 git cmake cmake-extras make man pandoc gzip
```
```shell
sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libswresample-dev libavdevice-dev libavfilter-dev libssl-dev libcurl4-openssl-dev libncurses5-dev libbsd-dev libpulse-dev
```
Once all these are on the system compiling from source should work without hiccups.
## Docker
Docker is only there for testing purposes and only works on linux with either `pulseaudio` or `pipewire-pulse` installed and running.
It uses the Arch docker image as base. The `docker-compose.sh` script creates the container and runs it (final size = ~1GB).
## Platform
Linux x64 with a UTF-8 locale.
As a baseline v1.1.5 works on ArchLinux with:
- FFMpeg (libavformat 59.27.100, libavcodec 59.37.100, libswresample 4.7.100)
- VLC (3.0.15)
- PulseAudio (14.2.0)
- SDL (2.0.14)
- ALSA (1.2.5)
- sndio (1.7.0)
- OpenSSL (1.1.1k)
- Curl (7.77.0)
- nCurses (6.4.20221231)
- libbsd
## F.A.Q.
Q. **What are the key bindings?**
A. Press `F1` to get a contextual list of key bindings in the UI.
Q. **How do I use the mouse?**
A. Check out this [guide](docs/guide/mouse_navigation.md).
Q. **I'm getting weird symbols where the icons are supposed to be. What's going on?**
A. Your terminal font does not support the unicode characters used. Either change the font or switch back to ASCII icons from the Options menu.
Q. **Can I change the look?**
A. Yes. There are internal preset themes available in the Options menu and, if these don't strike your fancy, a custom theme can be specified inside ctune's configuration file.
## Bug reporting & Support
**Disclaimer: I've writen this software primarily for myself so temper your support-level expectations accordingly.**
That being said, if you find a bug you are welcome to open a ticket.
I'll try to deal with it time allowing. Same for bug PRs.
For tickets, please include the following to help diagnose the source of the problem:
1. Basic information:
1. **(UI bugs)** Terminal/Shell used if it's a UI bug (e.g.: Konsole 21.04 using BASH 5.1.8)
2. Version of cTune used and what sound output/libraries it was compiled/run against (run `ctune --version` to get a print out of all that info)
2. Bug description
1. What seems to break and where
2. What triggers the bug - how did the bug manifest itself + steps to reproduce it
3. **(UI bugs)** A screenshot of the issue
3. Logs and Configuration
1. Configuration used (see inside `ctune.cfg`)
2. The cTune error log (run `ctune --debug` to generate more granular and useful info during execution)
3. Copy of the system log's (`syslog`) cTune runtime specific entries where the bug occurred (output of `journalctl --utc -b -0 | grep ctune` if you're using `systemd`)
Thank you.
## License
Copyright @ 2020-23 E.A.Davison.
Licensed under [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html)