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
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 buffer handle. • a_seek_mode: TIZ_BUFFER_NON_SEEKABLE (default) or TIZ_BUFFER_SEEKABLE.
int tiz_buffer_push(tiz_buffer_t * ap_buf, const void * ap_data, const size_t a_nbytes) Copy data at the back the buffer.
Return The number of bytes actually stored. Parameters • ap_buf: The dynamic buffer handle. • ap_data: The data to be stored. • a_nbytes: The number of bytes to store.
void tiz_buffer_clear(tiz_buffer_t * ap_buf ) Reset the position marker. After this operation, tiz_buffer_available returns zero.
Parameters • ap_buf: The dynamic buffer handle.
int tiz_buffer_available(const tiz_buffer_t * ap_buf ) Retrieve the number of bytes available in the buffer.
Return The total number of bytes currently available. Parameters • ap_buf: The dynamic buffer handle.
int tiz_buffer_offset(const tiz_buffer_t * ap_buf ) Retrieve the current position marker.
Return The offset in bytes that marks the current position in the buffer. Parameters • ap_buf: The buffer handle.
void* tiz_buffer_get(const tiz_buffer_t * ap_buf ) Retrieve the current position in the buffer where data can be read from. If the buffer is empty, i.e. tiz_buffer_available returns zero, the pointer returned is the position of the start of the buffer.
Return The pointer to the current position in the buffer. Parameters • ap_buf: The dynamic buffer handle.
3.1. Development 17 Tizonia Documentation, Release 0.1.0
int tiz_buffer_advance(tiz_buffer_t * ap_buf, const int nbytes) Advance the current position in the buffer.
Return The number of bytes actually advanced. Parameters • ap_buf: The dynamic buffer handle. • nbytes: The number of bytes to increment the position marker by.
int tiz_buffer_seek(tiz_buffer_t * ap_buf, const long a_offset, const int a_whence) Re-position the position marker. The new position, measured in bytes, is obtained by adding offset bytes to the position speci- fied by whence. If whence is set to TIZ_BUFFER_SEEK_SET, TIZ_BUFFER_SEEK_CUR, or TIZ_BUFFER_SEEK_END, the offset is relative to the start of the buffer, the current position indicator, or end-of-data marker, respectively.
Return 0 on success, -1 on error (e.g. the whence argument was not TIZ_BUFFER_SEEK_SET, TIZ_BUFFER_SEEK_END, or TIZ_BUFFER_SEEK_CUR. Or the resulting buffer offset would be negative). Parameters • ap_buf: The dynamic buffer handle. • a_offset: The new position is obtained by adding a_offset bytes to the position specified by a_whence. • a_whence: TIZ_BUFFER_SEEK_SET, TIZ_BUFFER_SEEK_CUR, or TIZ_BUFFER_SEEK_END. tizevent group tizevent Global event loop, async io and timers.
Typedefs
typedef tiz_event_io_t Handle to an io event typedef tiz_event_timer_t Handle to a timer event typedef tiz_event_stat_t Handle to a file status change event typedef (* tiz_event_io_cb_f)(void *ap_arg0, tiz_event_io_t *ap_ev_io, void *ap_arg1, const uint32_t a_id, int a_fd, int a_events) Callback prototype for io events
Parameters • p_ev_io: The io event being notified • fd: The associated file descriptor
18 Chapter 3. Development Tizonia Documentation, Release 0.1.0
• events: The event types notified
Functions
OMX_ERRORTYPE tiz_event_loop_init(void) Explicit initialisation of the global event loop. The loop is hosted in its own thread which is spawned the first time this function or any other function in this module are called. Therefore it is not mandatory to call this function in order to instantiate the global event loop. This is only useful if for some reason the initialization cannot be done at the same time as the first use.
Return OMX_ErrorNone if success, OMX_ErrorInsufficientResources otherwise.
void tiz_event_loop_destroy(void) Explicit destruction of the global event loop. WARNING: After this function, the event loop cannot be recreated in the current process. Therefore, if this function is used, the caller should guarantee that the global event loop is no longer needed. tizpqueue group tizpqueue Non-synchronized priority queue. External synchronisation is required in case it needs to be accessed safely from multiple threads.
Typedefs
typedef tiz_pqueue_t Priority queue opaque structure.
Functions
OMX_ERRORTYPE tiz_pqueue_init(tiz_pqueue_t ** app_pq, OMX_S32 a_max_prio, tiz_pq_cmp_f apf_cmp, tiz_soa_t * ap_soa, const char * ap_name) Initialize a new empty priority queue with up to a_max_prio + 1 different priorities (i.e. priority groups [0..a_max_prio]). 0 is the highest priority. A string of up to TIZ_PQUEUE_MAX_NAME_LEN characters that can be used during debugging to identify this queue Parameters • app_pq: A handle to the priority queue object to be initialized • a_max_prio: Maximum number of priority groups that can be stored in the queue • apf_cmp: A comparison function (used by tiz_pqueue_remove and tiz_pqueue_removep func- tions) • ap_soa: The Tizonia’s small object allocator to allocate from. Or NULL if the Tizonia’s default allocation/deallocation routines should be used instead
Return OMX_ErrorNone if success, OMX_ErrorInsufficientResources otherwise
3.1. Development 19 Tizonia Documentation, Release 0.1.0
void tiz_pqueue_destroy(tiz_pqueue_t * ap_pq) Destroy a priority queue.
Pre The queue must be empty before calling this function Parameters • ap_pq: The priority queue to be destroyed. If NULL, or if the queue has already been detroyed, no operation is performed.
OMX_ERRORTYPE tiz_pqueue_send(tiz_pqueue_t * ap_pq, void * ap_data, OMX_S32 a_prio) Add an item to the end of the priority group a_prio.
Return OMX_ErrorNone if success, OMX_ErrorInsufficientResources otherwise
OMX_ERRORTYPE tiz_pqueue_receive(tiz_pqueue_t * ap_pq, void ** app_data) Receive the first item from the queue. The item received is no longer in the queue.
Return OMX_ErrorNone if success, OMX_ErrorNoMore if empty
OMX_ERRORTYPE tiz_pqueue_remove(tiz_pqueue_t * ap_pq, void * ap_data) Remove an item from the queue. The item is found using the comparison function provided at initialization time (see tiz_pqueue_init).
Return OMX_ErrorNone if success, OMX_ErrorNoMore if not found
OMX_ERRORTYPE tiz_pqueue_removep(tiz_pqueue_t * ap_pq, void * ap_data, OMX_S32 a_priority) Remove an item from the queue. The item is found using the comparison function provided at initialization time (see tiz_pqueue_init). The search is restricted to the priority group a_priority.
Return OMX_ErrorNone if success, OMX_ErrorNoMore if not found
OMX_S32 tiz_pqueue_remove_func(tiz_pqueue_t * ap_pq, tiz_pq_func_f apf_func, OMX_S32 a_data1, void * ap_data2) Remove from the queue all the items found using the comparison function apf_func.
Return The number of items removed from the queue.
OMX_ERRORTYPE tiz_pqueue_first(tiz_pqueue_t * ap_pq, void ** app_data) Return a reference to the first item in the queue.
Return OMX_ErrorNone if success, OMX_ErrorNoMore if none found
OMX_S32 tiz_pqueue_length(const tiz_pqueue_t * ap_pq) Return the number of items currently in the queue.
Return Number of items in the queue
OMX_S32 tiz_pqueue_dump(tiz_pqueue_t * ap_pq, tiz_pq_dump_item_f apf_dump) This function dumps the contents of all the nodes in the queue using the apf_dump callback function.
Return The number of nodes processed.
20 Chapter 3. Development Tizonia Documentation, Release 0.1.0
tizqueue
group tizqueue Thread-safe FIFO queue.
Typedefs
typedef tiz_queue_t Queue opaque structure.
Functions
OMX_ERRORTYPE tiz_queue_init(tiz_queue_ptr_t * app_q, OMX_S32 a_capacity) Initialize a new empty queue.
Return OMX_ErrorNone if success, OMX_ErrorInsufficientResources otherwise. Parameters • a_capacity: Maximum number of items that can be send into the queue.
void tiz_queue_destroy(tiz_queue_t * ap_q) Destroy a queue. If ap_q is NULL, or the queue has already been detroyed before, no operation is per- formed. OMX_ERRORTYPE tiz_queue_send(tiz_queue_t * ap_q, OMX_PTR ap_data) Add an item onto the end of the queue. If the queue is full, it blocks until a space becomes available. OMX_ERRORTYPE tiz_queue_receive(tiz_queue_t * ap_q, OMX_PTR * app_data) Retrieve an item from the head of the queue. If the queue is empty, it blocks until an item becomes available. OMX_S32 tiz_queue_capacity(tiz_queue_t * ap_q) Retrieve the maximum number of items that can be stored in the queue. OMX_S32 tiz_queue_length(tiz_queue_t * ap_q) Retrieve the number of items currently stored in the queue. tizrcfile group tizrcfile
Functions
const char* tiz_rcfile_get_value(const char * section, const char * key) Returns a value string from a give section using the value’s key
Return A newly allocated string or NULL if the specified key cannot be found. Parameters • section: String indicating the section where the key-value list pair is to be found. • key: A search key in the specified section.
3.1. Development 21 Tizonia Documentation, Release 0.1.0
char** tiz_rcfile_get_value_list(const char * section, const char * key, unsigned long * length) Returns a value string from a give section using the value’s key
Return An array of NULL-terminated strings or NULL if the specified key cannot be found. The array should be freed by the caller. Parameters • section: String indicating the section where the key-value list pair is to be found. • key: A search key in the specified section. • length: The length of the returned list.
int tiz_rcfile_compare_value(const char * section, const char * key, const char * value) Returns an integer less than, equal to, or greater than zero if the section-key-value triad provided is respec- tively, not found, found and matching, or found and no matching.
Return Returns an integer less than (key or section not found), equal to (section and key found, value matched), or greater than zero (section and key found, value unmatched). Parameters • section: String indicating the section where the key-value pair is to be found. • key: A search key in the specified section. • value: The value to be matched against.
int tiz_rcfile_status(void) Returns 0 if the status of the configuration file is such that a tizonia configuration file has been found at one of the expected locations and the file can be opened and read by the current user.
Return On success, zero is returned. On error, -1 is returned. tizshufflelst group tizshufflelst Simple implementation of the Knuth-Fisher-Yates shuffle algorithm.
Typedefs
typedef tiz_shuffle_lst_t Shuffle list opaque handle.
Functions
OMX_ERRORTYPE tiz_shuffle_lst_init(tiz_shuffle_lst_ptr_t * app_shuffle_lst, const size_t a_list_size) Create a new shuffled list of integers.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
22 Chapter 3. Development Tizonia Documentation, Release 0.1.0
OMX_S32 tiz_shuffle_lst_next(tiz_shuffle_lst_t * ap_shuffle_lst) Return the next integer in the list.
Return 0 if success, -1 otherwise.
OMX_S32 tiz_shuffle_lst_prev(tiz_shuffle_lst_t * ap_shuffle_lst) Return the prev integer in the list.
Return 0 if success, -1 otherwise.
OMX_S32 tiz_shuffle_lst_jump(tiz_shuffle_lst_t * ap_shuffle_lst, const OMX_S32 a_jump) Return the prev integer in the list.
Return 0 if success, -1 otherwise.
void tiz_shuffle_lst_destroy(tiz_shuffle_lst_t * p_shuffle_lst) Destroy the shuffled list object. tizsync group tizsync Semaphore, mutex, and condition variable wrappers.
Typedefs
typedef tiz_mutex_t Mutex opaque handle. typedef tiz_sem_t Semaphore opaque handle. typedef tiz_cond_t Conditional variable opaque handle. typedef tiz_rwmutex_t Read-write mutex opaque handle.
Functions
OMX_ERRORTYPE tiz_sem_init(tiz_sem_t * ap_sem, OMX_U32 a_value) Initialize a semaphore object using the given value.
Return OMX_ErrorNone if success, OMX_ErrorInsufficientResources or OMX_ErrorUndefined other- wise.
OMX_ERRORTYPE tiz_sem_destroy(tiz_sem_t * ap_sem) Free the resources associated with a semaphore object.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_sem_wait(tiz_sem_t * ap_sem) Wait for a semaphore being posted.
3.1. Development 23 Tizonia Documentation, Release 0.1.0
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_sem_post(tiz_sem_t * ap_sem) Post semaphore.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_sem_getvalue(tiz_sem_t * ap_sem, OMX_S32 * ap_sval) Get the current value of a semaphore object stored it in *ap_sval.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_mutex_init(tiz_mutex_t * ap_mutex) Initialize a mutex.
Return OMX_ErrorNone if success, OMX_ErrorInsufficientResources or OMX_ErrorUndefined other- wise.
OMX_ERRORTYPE tiz_mutex_destroy(tiz_mutex_t * ap_mutex) Destroy a mutex.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_mutex_lock(tiz_mutex_t * ap_mutex) Lock a mutex.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_mutex_unlock(tiz_mutex_t * ap_mutex) Unlock a mutex.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_rwmutex_init(tiz_rwmutex_t * ap_rwmutex) Initialize a read-write mutex.
Return OMX_ErrorNone if success, OMX_ErrorInsufficientResources or OMX_ErrorUndefined other- wise.
OMX_ERRORTYPE tiz_rwmutex_destroy(tiz_rwmutex_t * ap_rwmutex) Destroy a read-write mutex.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_rwmutex_rdlock(tiz_rwmutex_t * ap_rwmutex) Lock a read-write mutex for reading.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_rwmutex_rwlock(tiz_rwmutex_t * ap_rwmutex) Lock a read-write mutex for writing.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
24 Chapter 3. Development Tizonia Documentation, Release 0.1.0
OMX_ERRORTYPE tiz_rwmutex_unlock(tiz_rwmutex_t * ap_rwmutex) Unlock a read-write mutex.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_cond_init(tiz_cond_t * ap_cond) Initialize a condition variable.
Return OMX_ErrorNone if success, OMX_ErrorInsufficientResources or OMX_ErrorUndefined other- wise.
OMX_ERRORTYPE tiz_cond_destroy(tiz_cond_t * ap_cond) Destroy a condition variable.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_cond_signal(tiz_cond_t * ap_cond) Wake up one thread waiting for a condition variable.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_cond_wait(tiz_cond_t * ap_cond, tiz_mutex_t * ap_mutex) Wait for a condition variable to be signaled or broadcast. ap_mutex is assumed to be locked before.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_cond_timedwait(tiz_cond_t * ap_cond, tiz_mutex_t * ap_mutex, OMX_U32 a_millis) Wait for a condition variable to be signaled or broadcast until a_millis milliseconds. ap_mutex is assumed to be locked before.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_cond_broadcast(tiz_cond_t * ap_cond) Wake up all threads waiting for a condition variable.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise. tizthread group tizthread Simple thread/task management wrapper functions.
Typedefs
typedef tiz_thread_t Thread hdl
3.1. Development 25 Tizonia Documentation, Release 0.1.0
Functions
OMX_ERRORTYPE tiz_thread_create(tiz_thread_t * ap_thread, size_t a_stack_size, OMX_U32 a_priority, OMX_PTR(*a_pf_routine)(OMX_PTR), OMX_PTR ap_arg) Create a new thread, starting with execution of a_pf_routine getting passed ap_arg. The new hdl is stored in *ap_thread.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_thread_join(tiz_thread_t * ap_thread, void ** app_result) Make the calling thread wait for the termination of the thread ap_thread. The exit status of the thread is stored in *app_result.
Return OMX_ErrorNone if success, OMX_ErrorUndefined otherwise.
OMX_ERRORTYPE tiz_thread_setname(tiz_thread_t * ap_thread, const OMX_STRING a_name) Set the name of a thread.
Return 0 if success, -1 otherwise.
void tiz_thread_exit(OMX_PTR a_status) Terminate the calling thread. OMX_S32 tiz_thread_id(void) Get the thread id of the calling thread.
Return The thread id
OMX_S32 tiz_sleep(OMX_U32 a_usec) Sleep for the specified number of micro seconds.
Return 0 if success, -1 otherwise. libtizcore group libtizcore This library implements the base OpenMAX IL Core infrastructure, as specified in the standard. libtizonia group libtizonia This library implements the base OpenMAX IL component infrastructure, which includes support for the stan- dard OpenMAX IL state machine, port management, and buffer processing. tizscheduler group tizscheduler Component event loop, OpenMAX IL handler initialisation and servant scheduling.
26 Chapter 3. Development Tizonia Documentation, Release 0.1.0
Defines
TIZ_COMP_MAX_PORTS Maximum number of OpenMAX IL ports that may be registered with a Tizonia component. TIZ_COMP_MAX_ROLES Maximum number of roles that may be registered with a Tizonia component. TIZ_COMP_MAX_TYPES The maximum number of types that may be registered with a Tizonia component.
Typedefs
typedef (* tiz_role_config_port_init_f)(OMX_HANDLETYPE ap_hdl) ‘Configuration port’ factory function prototype. This function instantiates a ‘configuration port’ object for a specific component role. The ‘configura- tion’ port is a pseudo-port, it does not have an associated OpenMAX IL port index. It is used in lib- tizonia to encapsulate the logic for the component’s OpenMAX IL structures that are not associated to an actual OpenMAX IL port, i.e. OpenMAX IL parameter structures without an ‘nIndex’ member (e.g. OMX_PARAM_CONTENTURITYPE).
Note Tizonia components require exactly one ‘configuration port’ to be functional. Return A pointer to a newly instantiated ‘configuration port’ object. Parameters • ap_hdl: The component’s OpenMAX IL handle.
typedef (* tiz_role_port_init_f)(OMX_HANDLETYPE ap_hdl) ‘port’ factory function prototype. This function instantiates an OpenMAX IL ‘port’ object for a specific component role. Tizonia components require one or more ‘port’ objects to be functional.
Return A pointer to a newly instantiated ‘port’ object. Parameters • ap_hdl: The component’s OpenMAX IL handle.
typedef (* tiz_role_proc_init_f)(OMX_HANDLETYPE ap_hdl) ‘processor’ factory function prototype. This function instantiates an OpenMAX IL ‘processor’ object for a specific component role. Tizonia components require exactly one ‘processor’ object to be functional.
Return A pointer to a newly instantiated ‘processor’ object. Parameters • ap_hdl: The component’s OpenMAX IL handle.
typedef tiz_role_factory_t OpenMAX IL role registration factory structure (typedef). typedef tiz_event_pluggable_t ‘Pluggable’ event structure (typedef).
3.1. Development 27 Tizonia Documentation, Release 0.1.0
Functions
OMX_ERRORTYPE tiz_comp_init(const OMX_HANDLETYPE ap_hdl, const char * ap_cname) Instantiate the OpenMAX IL component infrastructure. When this function returns, the OpenMAX IL component handle is fully initialised. However, the component is still not functional until at least one role is registered (see tiz_comp_register_roles, and tiz_comp_register_types). This function is called by the IL plugin to initialize the base component infrastructure. When this function returns, the component has a ‘fsm’ and ‘kernel’ objects ready to function. It is typically called from the plugin’s entry point function, e.g. ‘OMX_ComponentInit’. Note This function must be called during the execution of the component’s entry point, usually OMX_ComponentInit. Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_cname: The component name.
Return An OpenMAX IL error Parameters • ap_hdl: The component handle received from the IL Core as a parameter to ‘OMX_ComponentInit’. The handle is passed to the base component so that it can initialize the IL API entry points. • ap_cname: The component’s name.
OMX_ERRORTYPE tiz_comp_register_roles(const OMX_HANDLETYPE ap_hdl, const tiz_role_factory_t * ap_role_list[], const OMX_U32 a_nroles) Registration of component roles. At least one factory must be registered for the component to be fully functional. At a minimum, this requires the specialisation of the ‘processor’ class (see tiz_comp_register_types).
Note This function must be called during the execution of the component’s entry point, usually OMX_ComponentInit. Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_role_list: A list of role factories. • a_nroles: The number of factories in the list.
OMX_ERRORTYPE tiz_comp_register_types(const OMX_HANDLETYPE ap_hdl, const tiz_type_factory_t * ap_type_list[], const OMX_U32 a_ntypes) Registration of component types (a.k.a. classes). Components need to register at least one additional class, a specialised ‘processor’ class. Ports may also need to be specialised.
28 Chapter 3. Development Tizonia Documentation, Release 0.1.0
Note This function must be called during the execution of the component’s entry point, usually OMX_ComponentInit. Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_type_list: A list of type/class factories. • a_ntypes: The number of factories in the list.
OMX_ERRORTYPE tiz_comp_register_alloc_hooks(const OMX_HANDLETYPE ap_hdl, const tiz_alloc_hooks_t * ap_new_hooks, tiz_alloc_hooks_t * ap_old_hooks) Registration of port buffer allocation hooks.
Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_new_hooks: The new port buffer allocation hooks. • ap_old_hooks: The old allocation hooks (the ones replaced).
OMX_ERRORTYPE tiz_comp_register_eglimage_hook(const OMX_HANDLETYPE ap_hdl, const tiz_eglimage_hook_t * ap_hook) Registration of the EGL image validation hook.
Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_hook: EGL image validation hook info.
OMX_ERRORTYPE tiz_comp_event_pluggable(const OMX_HANDLETYPE ap_hdl, tiz_event_pluggable_t * ap_event) Queueing of ‘pluggable’ events. A ‘pluggable’ event is submitted to the component’s event queue using this function. The component’s event loop will deliver the event to its handler for processing within the component’s thread context.
Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_event: The pluggable event.
void tiz_comp_event_io(const OMX_HANDLETYPE ap_hdl, tiz_event_io_t * ap_ev_io, void * ap_arg, const uint32_t a_id, const int a_fd, const int a_events) Queueing of ‘io’ events.
3.1. Development 29 Tizonia Documentation, Release 0.1.0
An ‘io’ event is submitted to the component’s event queue using this function. The component’s event loop will deliver the ‘io’ event to the ‘processor’ object for processing within the component’s thread context.
Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_ev_io: • ap_arg: • a_id: • a_fd: • a_events:
void tiz_comp_event_timer(const OMX_HANDLETYPE ap_hdl, tiz_event_timer_t * ap_ev_timer, void * ap_arg, const uint32_t a_id) Queueing of ‘timer’ events. An ‘timer’ event is submitted to the component’s event queue using this function. The component’s event loop will deliver the ‘timer’ event to the ‘processor’ object for processing within the component’s thread context.
Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_ev_timer: • ap_arg: • a_id:
void tiz_comp_event_stat(const OMX_HANDLETYPE ap_hdl, tiz_event_stat_t * ap_ev_stat, void * ap_arg, const uint32_t a_id, const int a_events) Queueing of ‘stat’ events. An ‘stat’ event is submitted to the component’s event queue using this function. The component’s event loop will deliver the ‘stat’ event to the ‘processor’ object for processing within the component’s thread context.
Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_hdl: The OpenMAX IL handle. • ap_ev_stat: • ap_arg: • a_id: • a_events:
size_t tiz_comp_event_queue_unused_spaces(const OMX_HANDLETYPE ap_hdl) Retrieve the current maximum number of items that could be insterted into the queue.
30 Chapter 3. Development Tizonia Documentation, Release 0.1.0
Return A registered type. Parameters • ap_hdl: The OpenMAX IL handle.
void* tiz_get_fsm(const OMX_HANDLETYPE ap_hdl) Retrieve the component’s ‘fsm’ servant object.
Return The fsm servant. Parameters • ap_hdl: The OpenMAX IL handle.
void* tiz_get_krn(const OMX_HANDLETYPE ap_hdl) Retrieve the component’s ‘kernel’ servant object.
Return The kernel servant. Parameters • ap_hdl: The OpenMAX IL handle.
void* tiz_get_prc(const OMX_HANDLETYPE ap_hdl) Retrieve the component’s ‘processor’ servant object.
Return The processor servant. Parameters • ap_hdl: The OpenMAX IL handle.
void* tiz_get_sched(const OMX_HANDLETYPE ap_hdl) Retrieve the component’s servant ‘scheduler’ object.
Return The scheduler object. Parameters • ap_hdl: The OpenMAX IL handle.
void* tiz_get_type(const OMX_HANDLETYPE ap_hdl, const char * ap_type_name) Retrieve a component’s registered type / class.
Return A registered type. Parameters • ap_hdl: The OpenMAX IL handle. struct #include
tiz_role_config_port_init_f pf_cport ‘configuration port’ factory function tiz_role_proc_init_f pf_proc ‘processor’ factory function
3.1. Development 31 Tizonia Documentation, Release 0.1.0
OMX_U32 nports number of ports in this role OMX_U8 tiz_role_factory::role[OMX_MAX_STRINGNAME_SIZE] the role name struct #include
OMX_PTR p_servant The servant object that will be processing the external event. tiz_event_pluggable_hdlr_f pf_hdlr The event handler
tizfsm
group tizfsm libtizonia’s OpenMAX IL FSM servant.
Functions
void* tiz_fsm_class_init(void * ap_tos, void * ap_hdl) ‘fsm’ metaclass initialisation.
Return The scheduler object. Parameters • ap_tos: Tizonia’s object system handle. • ap_hdl: The OpenMAX IL handle.
void* tiz_fsm_init(void * ap_tos, void * ap_hdl) ‘fsm’ class initialisation.
Return The scheduler object. Parameters • ap_tos: Tizonia’s object system handle. • ap_hdl: The OpenMAX IL handle. tizkernel group tizkernel The ‘kernel’ servant is responsible for all the OpenMAX IL port management functionality.
32 Chapter 3. Development Tizonia Documentation, Release 0.1.0
Functions
void* tiz_krn_class_init(void * ap_tos, void * ap_hdl) ‘kernel’ metaclass initialisation.
Return The scheduler object. Parameters • ap_tos: Tizonia’s object system handle. • ap_hdl: The OpenMAX IL handle.
void* tiz_krn_init(void * ap_tos, void * ap_hdl) ‘kernel’ class initialisation.
Return The scheduler object. Parameters • ap_tos: Tizonia’s object system handle. • ap_hdl: The OpenMAX IL handle.
OMX_ERRORTYPE tiz_krn_claim_eglimage(const void * ap_obj, const OMX_U32 a_pid, const OMX_BUFFERHEADERTYPE * p_hdr, OMX_PTR * app_eglimage) Retrieve the EGL image associated to a particular OpenMAX IL header.
Return OMX_ErrorNone on success, other OMX_ERRORTYPE on error. Parameters • ap_obj: The ‘kernel’ servant object. • a_pid: The index of the port that the EGL image is associated with. • ap_hdr: The OpenMAX IL header that the EGL image is associated with. • app_eglimage: The EGL image. libtizrmproxy group libtizrmproxy Manager client library This library implements a client to access Tizonia’s OpenMAX IL Resource Manager daemon. tizrmd group tizrmd daemon process. This module implements an OpenMAX IL Resource Manager D-Bus-based daemon.
3.1. Development 33 Tizonia Documentation, Release 0.1.0
3.1.4 OpenMAX IL Plugins libtizaacdec group libtizaacdec • Component name : “OMX.Aratelia.audio_decoder.aac” •Implements role: “audio_decoder.aac” libtizfr group libtizfr • Component name : “OMX.Aratelia.file_reader.binary” •Implements role: “audio_reader.binary” •Implements role: “video_reader.binary” •Implements role: “image_reader.binary” •Implements role: “other_reader.binary” libtizfw group libtizfw • Component name : “OMX.Aratelia.file_writer.binary” •Implements role: “audio_writer.binary” •Implements role: “video_writer.binary” •Implements role: “image_writer.binary” •Implements role: “other_writer.binary” libtizflacdec group libtizflacdec • Component name : “OMX.Aratelia.audio_decoder.flac” •Implements role: “audio_encoder.flac” libtizhttprnd group libtizhttprnd • Component name : “OMX.Aratelia.audio_renderer.http” •Implements role: “audio_renderer.http” libtizhttpsrc group libtizhttpsrc • Component name : “OMX.Aratelia.audio_source.http” •Implements role: “audio_source.http” •Implements role: “audio_source.http.gmusic”
34 Chapter 3. Development Tizonia Documentation, Release 0.1.0
•Implements role: “audio_source.http.scloud” •Implements role: “audio_source.http.dirble” •Implements role: “audio_source.http.youtube” libtizmp3dec group libtizmp3dec • Component name : “OMX.Aratelia.audio_decoder.mp3” •Implements role: “audio_decoder.mp3” libtizmp3enc group libtizmp3enc • Component name : “OMX.Aratelia.audio_encoder.mp3” •Implements role: “audio_encoder.mp3” libtizmp3meta group libtizmp3meta • Component name : “OMX.Aratelia.audio_metadata_eraser.mp3” •Implements role: “audio_metadata_eraser.mp3” libtizmpgdec group libtizmpgdec • Component name : “OMX.Aratelia.audio_decoder.mpeg” •Implements role: “audio_decoder.mp2” •Implements role: “audio_decoder.mp3” libtizoggdmux group libtizoggdmux • Component name : “OMX.Aratelia.container_demuxer.ogg” •Implements role: “source.container_demuxer.ogg” •Implements role: “filter.container_demuxer.ogg” libtizopusdec group libtizopusdec • Component name : “OMX.Aratelia.audio_decoder.opus” •Implements role: “audio_decoder.opus”
3.1. Development 35 Tizonia Documentation, Release 0.1.0 libtizopusfiledec group libtizopusfiledec • Component name : “OMX.Aratelia.audio_decoder.opusfile.opus” •Implements role: “audio_decoder.opus” libtizpcmdec group libtizpcmdec • Component name : “OMX.Aratelia.audio_decoder.pcm” •Implements role: “audio_decoder.pcm” libtizalsapcmrnd group libtizalsapcmrnd based on ALSA
•Component name : “OMX.Aratelia.audio_renderer.alsa.pcm” •Implements role: “audio_renderer.pcm” libtizpulsepcmrnd group libtizpulsepcmrnd based on pulseaudio
•Component name : “OMX.Aratelia.audio_renderer.pulseaudio.pcm” •Implements role: “audio_renderer.pcm” libtizspotifysrc group libtizspotifysrc • Component name : “OMX.Aratelia.audio_source.spotify.pcm” •Implements role: “audio_source.pcm.spotify” libtizvorbisdec group libtizvorbisdec • Component name : “OMX.Aratelia.audio_decoder.vorbis” •Implements role: “audio_decoder.vorbis” libtizvp8dec group libtizvp8dec • Component name : “OMX.Aratelia.video_decoder.vp8” •Implements role: “video_decoder.vp8”
36 Chapter 3. Development Tizonia Documentation, Release 0.1.0 libtizsdlivrnd group libtizsdlivrnd • Component name : “OMX.Aratelia.iv_renderer.yuv.overlay” •Implements role: “iv_renderer.yuv.overlay”
3.1.5 Streaming Clients libtizgmusic group libtizgmusic A C library to access the Google Play Music streaming service (using Simon Weber’s ‘gmusicapi’ python library).
Typedefs
typedef tiz_gmusic_t The gmusic opaque structure typedef tiz_gmusic_playback_mode_t Various playback modes that control the playback queue.
Enums
enum tiz_gmusic_playback_mode Various playback modes that control the playback queue. Values: ETIZGmusicPlaybackModeNormal ETIZGmusicPlaybackModeShuffle ETIZGmusicPlaybackModeMax
Functions
int tiz_gmusic_init(tiz_gmusic_ptr_t * app_gmusic, const char * ap_user, const char * ap_pass, const char * ap_device_id) Initialize the gmusic handle.
Return 0 on success. Parameters • app_gmusic: A pointer to the gmusic handle which will be initialised. • ap_user: A Google email account. • ap_pass: The password associated to the Google account. • ap_device_id: A 16-character string containing a device id associated to the Google Play Music account.
3.1. Development 37 Tizonia Documentation, Release 0.1.0
void tiz_gmusic_set_playback_mode(tiz_gmusic_t * ap_gmusic, const tiz_gmusic_playback_mode_t mode) Set the playback mode.
Parameters • ap_gmusic: The gmusic handle.
int tiz_gmusic_play_album(tiz_gmusic_t * ap_gmusic, const char * ap_album, const bool a_unlimited_search) Add the tracks of the specified album to the playback queue. After calling this method, the various tiz_gmusic_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_gmusic: The gmusic handle. • ap_album: The album name • a_unlimited_search: If true, Google Play Unlimited albums are included. Otherwise, only albums from the user’s library are considered.
int tiz_gmusic_play_artist(tiz_gmusic_t * ap_gmusic, const char * ap_artist, const bool a_unlimited_search) Add the tracks of the specified artist to the playback queue. After calling this method, the various tiz_gmusic_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_gmusic: The gmusic handle. • ap_artist: The artist name • a_unlimited_search: If true, Google Play Unlimited artists are included. Otherwise, only artists from the user’s library are considered.
int tiz_gmusic_play_playlist(tiz_gmusic_t * ap_gmusic, const char * ap_playlist, const bool a_unlimited_search) Add the tracks of the specified playlist to the playback queue. After calling this method, the various tiz_gmusic_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_gmusic: The gmusic handle. • ap_playlist: The playlist name • a_unlimited_search: If true, Google Play Unlimited playlists are included. Otherwise, only playlists from the user’s library are considered.
38 Chapter 3. Development Tizonia Documentation, Release 0.1.0
int tiz_gmusic_play_station(tiz_gmusic_t * ap_gmusic, const char * ap_station) Add the tracks of the specified station to the playback queue. After calling this method, the various tiz_gmusic_get* methods can be used to interact with the playback queue.
Note An Google Play Unlimited subscription is required. Return 0 on success Parameters • ap_gmusic: The gmusic handle. • ap_station: The station name
int tiz_gmusic_play_genre(tiz_gmusic_t * ap_gmusic, const char * ap_genre) Add the tracks of the specified genre to the playback queue. After calling this method, the various tiz_gmusic_get* methods can be used to interact with the playback queue.
Note An Google Play Unlimited subscription is required. Return 0 on success Parameters • ap_gmusic: The gmusic handle. • ap_genre: The genre
int tiz_gmusic_play_situation(tiz_gmusic_t * ap_gmusic, const char * ap_situation) Add the tracks of the specified situation to the playback queue. After calling this method, the various tiz_gmusic_get* methods can be used to interact with the playback queue.
Note An Google Play Unlimited subscription is required. Return 0 on success Parameters • ap_gmusic: The gmusic handle. • ap_situation: The situation
int tiz_gmusic_play_promoted_tracks(tiz_gmusic_t * ap_gmusic) Add Google Play Unlimited promoted tracks to the playback queue. After calling this method, the various tiz_gmusic_get* methods can be used to interact with the playback queue.
Note An Google Play Unlimited subscription is required. Return 0 on success Parameters • ap_gmusic: The gmusic handle.
3.1. Development 39 Tizonia Documentation, Release 0.1.0
void tiz_gmusic_clear_queue(tiz_gmusic_t * ap_gmusic) Clear the playback queue.
Parameters • ap_gmusic: The gmusic handle.
const char* tiz_gmusic_get_next_url(tiz_gmusic_t * ap_gmusic) Retrieve the next track url The the playback queue pointer moves one position forwards.
Parameters • ap_gmusic: The gmusic handle.
const char* tiz_gmusic_get_prev_url(tiz_gmusic_t * ap_gmusic) Retrieve the previous track url. The the playback queue pointer moves one position backwards.
Parameters • ap_gmusic: The gmusic handle.
const char* tiz_gmusic_get_current_song_artist(tiz_gmusic_t * ap_gmusic) Retrieve the current song’s artist.
Parameters • ap_gmusic: The gmusic handle.
const char* tiz_gmusic_get_current_song_title(tiz_gmusic_t * ap_gmusic) Retrieve the current song’s title.
Parameters • ap_gmusic: The gmusic handle.
const char* tiz_gmusic_get_current_song_album(tiz_gmusic_t * ap_gmusic) Retrieve the current song’s album.
Parameters • ap_gmusic: The gmusic handle.
const char* tiz_gmusic_get_current_song_duration(tiz_gmusic_t * ap_gmusic) Retrieve the current song’s duration.
Parameters • ap_gmusic: The gmusic handle.
const char* tiz_gmusic_get_current_song_track_number(tiz_gmusic_t * ap_gmusic) Retrieve the current song’s track number.
Parameters • ap_gmusic: The gmusic handle.
40 Chapter 3. Development Tizonia Documentation, Release 0.1.0
const char* tiz_gmusic_get_current_song_tracks_in_album(tiz_gmusic_t * ap_gmusic) Retrieve the number of tracks in the current song’s album.
Parameters • ap_gmusic: The gmusic handle.
const char* tiz_gmusic_get_current_song_year(tiz_gmusic_t * ap_gmusic) Retrieve the current song’s publication year.
Parameters • ap_gmusic: The gmusic handle.
void tiz_gmusic_destroy(tiz_gmusic_t * ap_gmusic) Destroy the gmusic handle.
Parameters • ap_gmusic: The gmusic handle. libtizsoundcloud group libtizsoundcloud library A C library to access the SoundCloud streaming service.
Typedefs
typedef tiz_scloud_t The soundcloud opaque structure typedef tiz_scloud_playback_mode_t Various playback modes that control the playback queue.
Enums
enum tiz_scloud_playback_mode Various playback modes that control the playback queue. Values: ETIZScloudPlaybackModeNormal ETIZScloudPlaybackModeShuffle ETIZScloudPlaybackModeMax
Functions
int tiz_scloud_init(tiz_scloud_ptr_t * app_scloud, const char * ap_oauth_token) Initialize the soundcloud handle.
Return 0 on success.
3.1. Development 41 Tizonia Documentation, Release 0.1.0
Parameters • app_scloud: A pointer to the soundcloud handle which will be initialised. • ap_oauth_token: A SoundCloud email account.
void tiz_scloud_set_playback_mode(tiz_scloud_t * ap_scloud, const tiz_scloud_playback_mode_t mode) Clear the playback queue.
Parameters • ap_scloud: The soundcloud handle.
int tiz_scloud_play_user_stream(tiz_scloud_t * ap_scloud) Add the tracks in the user’s stream to the playback queue. After calling this method, the various tiz_scloud_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_scloud: The soundcloud handle.
int tiz_scloud_play_user_likes(tiz_scloud_t * ap_scloud) Add the tracks in the user’s likes to the playback queue. After calling this method, the various tiz_scloud_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_scloud: The soundcloud handle.
int tiz_scloud_play_user_playlist(tiz_scloud_t * ap_scloud, const char * ap_playlist) Search the user’s collection for a playlist add its tracks to the playback queue. After calling this method, the various tiz_scloud_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_scloud: The soundcloud handle. • ap_playlist: The playlist name.
int tiz_scloud_play_creator(tiz_scloud_t * ap_scloud, const char * ap_creator) Add the last 50 tracks uploaded by a user/creator to the playback queue. After calling this method, the various tiz_scloud_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters
42 Chapter 3. Development Tizonia Documentation, Release 0.1.0
• ap_scloud: The soundcloud handle. • ap_creator: The creator/artist name.
int tiz_scloud_play_tracks(tiz_scloud_t * ap_scloud, const char * ap_tracks) Search SoundCloud for tracks and add them to the playback queue. After calling this method, the various tiz_scloud_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_scloud: The soundcloud handle. • ap_tracks: A search string.
int tiz_scloud_play_playlists(tiz_scloud_t * ap_scloud, const char * ap_playlists) Search SoundCloud for playlists and add them to the playback queue. After calling this method, the various tiz_scloud_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_scloud: The soundcloud handle. • ap_playlists: A search string.
int tiz_scloud_play_genres(tiz_scloud_t * ap_scloud, const char * ap_genres) Search SoundCloud for genres and tracks to the playback queue. After calling this method, the various tiz_scloud_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_scloud: The soundcloud handle. • ap_genres: The genres (a comma separated-list).
int tiz_scloud_play_tags(tiz_scloud_t * ap_scloud, const char * ap_tags) Search SoundCloud for tags and tracks to the playback queue. After calling this method, the various tiz_scloud_get* methods can be used to interact with the playback queue.
Return 0 on success Parameters • ap_scloud: The soundcloud handle. • ap_tags: The tags (a comma separated-list).
void tiz_scloud_clear_queue(tiz_scloud_t * ap_scloud) Clear the playback queue.
3.1. Development 43 Tizonia Documentation, Release 0.1.0
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_next_url(tiz_scloud_t * ap_scloud) Retrieve the next track url The the playback queue pointer moves one position forwards.
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_prev_url(tiz_scloud_t * ap_scloud) Retrieve the previous track url. The the playback queue pointer moves one position backwards.
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_current_track_user(tiz_scloud_t * ap_scloud) Retrieve the current track’s uploader/creator/artist.
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_current_track_title(tiz_scloud_t * ap_scloud) Retrieve the current track’s title.
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_current_track_duration(tiz_scloud_t * ap_scloud) Retrieve the current track’s duration.
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_current_track_year(tiz_scloud_t * ap_scloud) Retrieve the current track’s publication year.
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_current_track_permalink(tiz_scloud_t * ap_scloud) Retrieve the current track’s permalink.
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_current_track_license(tiz_scloud_t * ap_scloud) Retrieve the current track’s license.
44 Chapter 3. Development Tizonia Documentation, Release 0.1.0
Parameters • ap_scloud: The soundcloud handle.
const char* tiz_scloud_get_current_track_likes(tiz_scloud_t * ap_scloud) Retrieve the current track’s likes count.
Parameters • ap_scloud: The soundcloud handle.
void tiz_scloud_destroy(tiz_scloud_t * ap_scloud) Destroy the soundcloud handle.
Parameters • ap_scloud: The soundcloud handle.
3.1.6 Coding Style
General Philosophy
• GNU Style. • Line length is generally limited to 80 characters. • Each file starts with a header containing the short license text.
Formatting the Source Code
• clang-format is used and configuration files exist (.clang-format) in various sub-projects: – In general, C++ code follows a Google C++/Allman stylet (e.g. the tizonia command-line application, and the tizrmd daemon). – C-based libraries, like libtizonia, libtizcore, libtizplatform, etc, follow the GNU style.
Indentation
• Indentation is always done using spaces, tabs are never used. • One level of indentation is 2 characters long.
Naming Variables, Functions, and Files
TODO
3.1. Development 45 Tizonia Documentation, Release 0.1.0
46 Chapter 3. Development CHAPTER 4
Indices and tables
• genindex • modindex • search
47 Index
T tiz_get_type (C function), 31 tiz_atomic_var_destroy (C function), 16 tiz_gmusic_clear_queue (C function), 39 tiz_atomic_var_init (C function), 16 tiz_gmusic_destroy (C function), 41 tiz_atomic_var_test_and_set (C function), 16 tiz_gmusic_get_current_song_album (C function), 40 tiz_buffer_advance (C function), 18 tiz_gmusic_get_current_song_artist (C function), 40 tiz_buffer_available (C function), 17 tiz_gmusic_get_current_song_duration (C function), 40 tiz_buffer_clear (C function), 17 tiz_gmusic_get_current_song_title (C function), 40 tiz_buffer_destroy (C function), 16 tiz_gmusic_get_current_song_track_number (C func- tiz_buffer_get (C function), 17 tion), 40 tiz_buffer_init (C function), 16 tiz_gmusic_get_current_song_tracks_in_album (C func- tiz_buffer_offset (C function), 17 tion), 41 tiz_buffer_push (C function), 17 tiz_gmusic_get_current_song_year (C function), 41 tiz_buffer_seek (C function), 18 tiz_gmusic_get_next_url (C function), 40 tiz_buffer_seek_mode (C function), 17 tiz_gmusic_get_prev_url (C function), 40 tiz_comp_event_io (C function), 29 tiz_gmusic_init (C function), 37 tiz_comp_event_pluggable (C function), 29 tiz_gmusic_play_album (C function), 38 tiz_comp_event_queue_unused_spaces (C function), 30 tiz_gmusic_play_artist (C function), 38 tiz_comp_event_stat (C function), 30 tiz_gmusic_play_genre (C function), 39 tiz_comp_event_timer (C function), 30 tiz_gmusic_play_playlist (C function), 38 tiz_comp_init (C function), 28 tiz_gmusic_play_promoted_tracks (C function), 39 tiz_comp_register_alloc_hooks (C function), 29 tiz_gmusic_play_situation (C function), 39 tiz_comp_register_eglimage_hook (C function), 29 tiz_gmusic_play_station (C function), 38 tiz_comp_register_roles (C function), 28 tiz_gmusic_set_playback_mode (C function), 37 tiz_comp_register_types (C function), 28 tiz_krn_claim_eglimage (C function), 33 tiz_cond_broadcast (C function), 25 tiz_krn_class_init (C function), 33 tiz_cond_destroy (C function), 25 tiz_krn_init (C function), 33 tiz_cond_init (C function), 25 tiz_mutex_destroy (C function), 24 tiz_cond_signal (C function), 25 tiz_mutex_init (C function), 24 tiz_cond_timedwait (C function), 25 tiz_mutex_lock (C function), 24 tiz_cond_wait (C function), 25 tiz_mutex_unlock (C function), 24 tiz_event_loop_destroy (C function), 19 tiz_pqueue_destroy (C function), 19 tiz_event_loop_init (C function), 19 tiz_pqueue_dump (C function), 20 tiz_event_pluggable (C++ class), 32 tiz_pqueue_first (C function), 20 tiz_fsm_class_init (C function), 32 tiz_pqueue_init (C function), 19 tiz_fsm_init (C function), 32 tiz_pqueue_length (C function), 20 tiz_get_fsm (C function), 31 tiz_pqueue_receive (C function), 20 tiz_get_krn (C function), 31 tiz_pqueue_remove (C function), 20 tiz_get_prc (C function), 31 tiz_pqueue_remove_func (C function), 20 tiz_get_sched (C function), 31 tiz_pqueue_removep (C function), 20 tiz_pqueue_send (C function), 20
48 Tizonia Documentation, Release 0.1.0 tiz_queue_capacity (C function), 21 tiz_queue_destroy (C function), 21 tiz_queue_init (C function), 21 tiz_queue_length (C function), 21 tiz_queue_receive (C function), 21 tiz_queue_send (C function), 21 tiz_rcfile_compare_value (C function), 22 tiz_rcfile_get_value (C function), 21 tiz_rcfile_get_value_list (C function), 22 tiz_rcfile_status (C function), 22 tiz_role_factory (C++ class), 31 tiz_rwmutex_destroy (C function), 24 tiz_rwmutex_init (C function), 24 tiz_rwmutex_rdlock (C function), 24 tiz_rwmutex_rwlock (C function), 24 tiz_rwmutex_unlock (C function), 24 tiz_scloud_clear_queue (C function), 43 tiz_scloud_destroy (C function), 45 tiz_scloud_get_current_track_duration (C function), 44 tiz_scloud_get_current_track_license (C function), 44 tiz_scloud_get_current_track_likes (C function), 45 tiz_scloud_get_current_track_permalink (C function), 44 tiz_scloud_get_current_track_title (C function), 44 tiz_scloud_get_current_track_user (C function), 44 tiz_scloud_get_current_track_year (C function), 44 tiz_scloud_get_next_url (C function), 44 tiz_scloud_get_prev_url (C function), 44 tiz_scloud_init (C function), 41 tiz_scloud_play_creator (C function), 42 tiz_scloud_play_genres (C function), 43 tiz_scloud_play_playlists (C function), 43 tiz_scloud_play_tags (C function), 43 tiz_scloud_play_tracks (C function), 43 tiz_scloud_play_user_likes (C function), 42 tiz_scloud_play_user_playlist (C function), 42 tiz_scloud_play_user_stream (C function), 42 tiz_scloud_set_playback_mode (C function), 42 tiz_sem_destroy (C function), 23 tiz_sem_getvalue (C function), 24 tiz_sem_init (C function), 23 tiz_sem_post (C function), 24 tiz_sem_wait (C function), 23 tiz_shuffle_lst_destroy (C function), 23 tiz_shuffle_lst_init (C function), 22 tiz_shuffle_lst_jump (C function), 23 tiz_shuffle_lst_next (C function), 22 tiz_shuffle_lst_prev (C function), 23 tiz_sleep (C function), 26 tiz_thread_create (C function), 26 tiz_thread_exit (C function), 26 tiz_thread_id (C function), 26 tiz_thread_join (C function), 26 tiz_thread_setname (C function), 26
Index 49