Tizonia Documentation Release 0.1.0 Juan A. Rubio Jan 30, 2017 Contents 1 Introduction 3 1.1 Introduction...............................................3 1.2 Installation................................................4 2 Tutorial 7 2.1 Tutorial..................................................7 3 Development 15 3.1 Development............................................... 15 4 Indices and tables 47 i ii Tizonia Documentation, Release 0.1.0 The Tizonia Project - Copyright 2017 Juan A. Rubio Contents 1 Tizonia Documentation, Release 0.1.0 2 Contents CHAPTER 1 Introduction 1.1 Introduction 1.1.1 500-foot view Tizonia is a free and open-source multimedia software project based on OpenMAX IL. OpenMAX IL is an open standard maintained by the The Khronos Group that enables the creation and integration of software and hardware accelerated media streaming components like audio and video encoders and decoders, camera components, and media processing algorithms. Tizonia provides a number of libraries that implement the various features and components of the OpenMAX IL API, including the OpenMAX IL Core, the OpenMAX IL plugin infrastructure, Resource Management and a number of plugin implementations (primarily audio and video software decoders, and media sources and renderers). From a user-side perspective, the Tizonia project also features a command-line music player and audio streaming client/server for Linux with support for Spotify, Google Play Music and SoundCloud on-demand audio streaming services. Tizonia development is hosted on GitHub and software binary releases are available for Debian-based Linux distribu- tions from Bintray. 1.1.2 Current features • Simple, no-fuss command-line music player utility. • Cloud audio streaming services: – Spotify Premium, Google Play Unlimited, and SoundCloud. • Support for most common high-quality audio formats from local media: – Formats currently supported: mp3, mp2, mpa, m2a, aac, vorbis, opus, wav, aiff, and flac. • Playback of Icecast/SHOUTcast radio streams: 3 Tizonia Documentation, Release 0.1.0 – mp3, aac, and opus stations (ogg to be added soon). • LAN audio streaming server (Icecast/SHOUTcast): – Currently: mp3 stations can be created from local media (flac and opus to be added in the near future). • MPRIS v2 remote control interface. • Based on Tizonia’s own internal multimedia framework. – A full implementation of the OpenMAX IL 1.2 provisional specification. – No ffmpeg, libav, gstreamer or libvlc dependencies. 1.1.3 Roadmap • LAN streaming (Icecast/SHOUTcast) of any audio stream (including cloud services). • Integration of additional audio streaming services (e.g. Dirble, YouTube, etc.). • Multi-room synchronised playback. • Zeroconf/AVAHI networking. • Music Player Daemon protocol support. • Hardware-acceleration and Video support. 1.2 Installation Debian packages are available from Bintray for the following distro/arch combinations: • Ubuntu Trusty (14.04) – amd64, i386, armhf • Ubuntu Vivid (15.04) – amd64, i386, armhf • Debian Jessie (8) – amd64, i386, armhf, armel • Raspbian Jessie (8) – armhf 1.2.1 Install the latest release To install the latest release, use the following shortcut to the install.sh script: $ curl -L -O https://goo.gl/Vu8qGR&& chmod +x Vu8qGR&& ./Vu8qGR Note: The install.sh script is hosted on GitHub. 4 Chapter 1. Introduction Tizonia Documentation, Release 0.1.0 1 #!/bin/bash 2 # 3 # Copyright (C) 2011-2017 Aratelia Limited - Juan A. Rubio 4 # 5 # This program is free software: you can redistribute it and/or modify 6 # it under the terms of the GNU General Public License as published by 7 # the Free Software Foundation, either version 3 of the License, or 8 # (at your option) any later version. 9 # 10 # This program is distributed in the hope that it will be useful, 11 # but WITHOUT ANY WARRANTY; without even the implied warranty of 12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 # GNU General Public License for more details. 14 # 15 # You should have received a copy of the GNU General Public License 16 # along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 # 19 # Script that installs Tizonia's debian packages and their dependencies. 20 # 21 22 # Run the install actions in a subshell 23 ( 24 25 if cat /etc/*-release | grep raspbian; then 26 DISTRO="raspbian"; RELEASE="jessie" 27 elif cat /etc/*-release | grep jessie; then 28 DISTRO="debian"; RELEASE="jessie" 29 elif cat /etc/*-release | grep trusty; then 30 DISTRO="ubuntu"; RELEASE="trusty" 31 elif cat /etc/*-release | grep vivid; then 32 DISTRO="ubuntu"; RELEASE="vivid" 33 elif cat /etc/*-release | grep xenial; then 34 DISTRO="ubuntu"; RELEASE="xenial" 35 else 36 echo "Can't find a supported debian-based distribution." 37 exit1 38 fi 39 40 # Make sure some required packages are already installed 41 sudo apt-get -y --force-yes install python-dev curl apt-transport-https libffi-dev ,!libssl-dev 42 43 # To install libspotify deb packages, add Mopidy's archive to APT's 44 # sources.list 45 grep -q "apt.mopidy.com" /etc/apt/sources.list 46 if [["$?" -eq1]]; then 47 curl 'http://apt.mopidy.com/mopidy.gpg' | sudo apt-key add - 48 echo "deb http://apt.mopidy.com/ stable main contrib non-free" | sudo tee -a /etc/ ,!apt/sources.list 49 fi 50 51 # Add Tizonia's archive to APT's sources.list 52 grep -q "dl.bintray.com/tizonia" /etc/apt/sources.list 53 if [["$?" -eq1]]; then 54 curl -k 'https://bintray.com/user/downloadSubjectPublicKey?username=tizonia'| ,!sudo apt-key add - 55 echo"deb https://dl.bintray.com/tizonia/$DISTRO $RELEASE main" | sudo tee -a / ,!etc/apt/sources.list 1.2. Installation 5 Tizonia Documentation, Release 0.1.0 56 fi 57 58 # Resynchronize APT's package index files 59 sudo apt-get update 60 61 # Using pip, install Simon Weber's gmusicapi and soundcloud's API wrapper 62 sudo apt-get -y install python-pip \ 63 &&( sudo -H pip install --upgrade gmusicapi || sudo -H pip install --upgrade ,!gmusicapi) \ 64 && sudo -H pip install --upgrade soundcloud \ 65 && sudo -H pip install --upgrade youtube-dl \ 66 && sudo -H pip install --upgrade pafy 67 68 # Install libspotify 69 sudo apt-get -y install libspotify12 70 71 # Install Tizonia 72 sudo apt-get -y install tizonia-all 73 74 # Copy Tizonia's config file to the user's config directory 75 if [["$?" -eq0]]; then 76 TIZ_CONFIG_DIR="$HOME/.config/tizonia" 77 TIZ_CONFIG_FILE="$TIZ_CONFIG_DIR/tizonia.conf" 78 if [[ ! -e"$TIZ_CONFIG_FILE"]]; then 79 mkdir"$TIZ_CONFIG_DIR" 80 cp /etc/tizonia/tizonia.conf/tizonia.conf"$TIZ_CONFIG_FILE" 81 fi 82 fi 83 84 # Simple test to verify that everything went well 85 which tizonia > /dev/null 86 if [["$?" -eq0]]; then 87 echo ; tizonia 88 printf "\nTizonia is now installed.\n" 89 printf"Please add Spotify, Google Music, Soundcloud, and Dirble credentials in : ,!$TIZ_CONFIG_FILE\n" 90 else 91 echo "Oops. Something went wrong!" 92 exit1 93 fi 94 95 exit0 96 97 ) # end running in a subshell 6 Chapter 1. Introduction CHAPTER 2 Tutorial 2.1 Tutorial 2.1.1 Help Topics 7 Tizonia Documentation, Release 0.1.0 2.1.2 Global Options 2.1.3 OpenMAX IL Options 8 Chapter 2. Tutorial Tizonia Documentation, Release 0.1.0 2.1.4 Shoutcast Server 2.1.5 Shoutcast Client 2.1. Tutorial 9 Tizonia Documentation, Release 0.1.0 2.1.6 Spotify 10 Chapter 2. Tutorial Tizonia Documentation, Release 0.1.0 2.1.7 Google Play Music 2.1. Tutorial 11 Tizonia Documentation, Release 0.1.0 2.1.8 SoundCloud 12 Chapter 2. Tutorial Tizonia Documentation, Release 0.1.0 2.1.9 Local Media Playback 2.1. Tutorial 13 Tizonia Documentation, Release 0.1.0 14 Chapter 2. Tutorial CHAPTER 3 Development 3.1 Development 3.1.1 Architecture TODO 3.1.2 Requirements A relatively recent version of Debian or Ubuntu Linux (14.04+) should suffice. The most up-to-date list of libraries required to build and run Tizonia are listed in project’s main repo at GitHub. 3.1.3 OpenMAX IL Framework libtizplatform group libtizplatform tizatomic group tizatomic Atomic operations. This module is work-in-progress. Typedefs typedef tiz_atomic_var_t Atomic variable opaque handle. 15 Tizonia Documentation, Release 0.1.0 Functions OMX_ERRORTYPE tiz_atomic_var_init(tiz_atomic_var_ptr_t * app_atomic_var) Create a new atomic binary variable. Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise. Parameters • app_atomic_var: An atomic variable opaque handle to be initialised. OMX_ERRORTYPE tiz_atomic_var_test_and_set(tiz_atomic_var_t * ap_atomic_var) Atomic test and set. Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise. Parameters • app_atomic_var: An atomic variable opaque handle. void tiz_atomic_var_destroy(tiz_atomic_var_t * ap_atomic_var) Destroy the atomic binary variable. Parameters • app_atomic_var: An atomic variable opaque handle. tizbuffer group tizbuffer Dynamically re-sizeable buffer of contiguous binary data. Typedefs typedef tiz_buffer_t Dynamic buffer object opaque handle. Functions OMX_ERRORTYPE tiz_buffer_init(tiz_buffer_ptr_t * app_buf, const size_t a_nbytes) Create a new dynamic buffer object. Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise. Parameters • app_buf: A dynamic buffer handle to be initialised. • a_nbytes: Initial size of the data store. void tiz_buffer_destroy(tiz_buffer_t * ap_buf ) Destroy a dynamic buffer object. Parameters • ap_buf: A dynamic buffer handle to be destroyed. 16 Chapter 3. Development Tizonia Documentation, Release 0.1.0 int tiz_buffer_seek_mode(tiz_buffer_t * ap_buf, const int a_seek_mode) Set a new overwrite mode. Return The old seek mode, or -1 on error. Parameters • ap_buf: The dynamic