Tizonia Documentation

Tizonia is a command-line streaming music client and server designed for Linux. It provides an interface to various streaming services and media servers, including:

• Streaming Services: YouTube, SoundCloud, TuneIn, iHeart Internet Radio, and Spotify.
• Media Servers: Plex.
• Output Devices: Chromecast.

It is notable for being the first open-source implementation of OpenMAX IL 1.2.

Note on Current Development: Tizonia is currently undergoing a revival for a v1 release targeting Ubuntu 24.04 amd64. Users should be aware that legacy installation instructions and some streaming-service documentation may be outdated. Check the v1 roadmap issues for the latest status.

Tizonia is designed for an efficient, unobtrusive music search and listening experience based on the following principles:

• Simple CLI UI: Optimized for keyboard usage to minimize time between command and playback.
• Fuzzy Search: Uses fuzzy string matching to maximize search results from streaming services. If no direct match is found, Tizonia may attempt an 'I'm Feeling Lucky' guess.
• Continuous Playback: The play queue runs in looped mode by default. Currently, there is no way to configure non-looped playback.
• Minimal Distractions: The interface is limited to track information and a simple visual progress bar. It does not support fast-forward or rewind (only skip to next/previous track).
• Single-command workflow: The goal is to find and play music using a single command-line option.

Skema is a bespoke test execution framework used to build and test arbitrary OpenMAX IL graphs and pipelines (both tunneled and non-tunneled). It uses a custom, easy-to-write XML syntax to define these pipelines.

• GitHub Repository: https://github.com/tizonia/skema
• Documentation: Available in the Tizonia wiki at https://github.com/tizonia/tizonia-openmax-il/wiki/Skema.

The parser supports HTTP upgrades (like WebSockets). When an upgrade request is detected, the parser will issue on_headers_complete and on_message_complete callbacks as if it were a normal HTTP message without a body, but http_parser_execute() will stop parsing immediately after the headers.

To handle an upgrade:

1. Check if parser->upgrade is set to 1 after http_parser_execute() returns.
2. The non-HTTP data (the new protocol data) begins at the buffer offset returned by http_parser_execute().

Tizonia supports three different bit-depth options for specifying color codes, depending on your terminal's capabilities. You can mix bit-depths within a single theme (e.g., using 3/4-bit for some colors and 24-bit for others), but a single Cxy definition must stick to one bit-depth for both foreground and background.

Option 1: 3/4-bit color codes

Uses standard ANSI escape codes:

• Normal FG colors: 30-37
• Bright FG colors: 90-97
• Normal BG colors: 40-47
• Bright BG colors: 100-107

Option 2: 8-bit color codes

Uses the 38,5,⟨n⟩ and 48,5,⟨n⟩ syntax:

• 38,5,⟨n⟩ -> Foreground color
• 48,5,⟨n⟩ -> Background color

Option 3: 24-bit color codes

Uses RGB values:

• 38,2,⟨r⟩,⟨g⟩,⟨b⟩ -> RGB foreground color
• 48,2,⟨r⟩,⟨g⟩,⟨b⟩ -> RGB background color

Tizonia uses a fork of dbus-cplusplus where the API has been moved into the Tiz::DBus namespace. This namespace change was implemented to prevent symbol collisions and allow safe distribution alongside other Tizonia programs and libraries. When writing code that uses this library, ensure you use the Tiz prefix for all DBus-related types and functions.

namespace Tiz
{
namespace DBus
{

// ... API members ...

} /* namespace DBus */
} /* namespace Tiz */

As of Tizonia v1, the legacy libspotify-based Spotify streaming backend has been completely removed. This means:

• No Spotify CLI options: Options starting with --spotify-* are no longer supported and will be rejected as unknown.
• No Spotify configuration: Keys starting with spotify.* in tizonia.conf are ignored.
• No Spotify OpenMAX components: The component OMX.Aratelia.audio_source.spotify.pcm is no longer available in the resource manager.
• No Spotify plugins: The spotify_source plugin is absent from the build and package set.

Local playback and other supported service backends remain unchanged. If you have existing configuration files with spotify.* keys, they can be manually deleted, though they will simply be ignored by the software.

Tizonia can function as a simplified Icecast/SHOUTcast LAN streaming server. In this mode, it streams local media files (such as .mp3) to a single client over the network. This is useful for streaming a local music collection to other machines or mobile devices on your local network.

To enable this mode, use the --server flag.

tizonia --server --recurse --shuffle $HOME/Music

Tizonia uses a tizonia.conf file for configuration. When upgrading Tizonia, a new template is installed in the system location, but your existing local configuration file in the user's local configuration directory will remain unmodified. Old configuration files are backward-compatible with newer versions of the software.

To access new features after an upgrade, you must manually update your local configuration file. The file uses an INI-style format.

# -*-Mode: conf; -*
# tizonia-config v0.22.0 configuration file

[ilcore]
# ... configuration sections ...