iKlax Library (iKlaxLib)

1.5.1

Summary

A. What's iKlax ?
   What's an iKmix ?

B. What does iKlax Library contain ?
   1. The iKlax Tools Library (KToolLib)
   2. The iKlax Library (iKlaxLib or iKlaxReadLib)
      Available Audio Codecs

C. iKlax Read Library Architecture (Reading & Decoding)
   1. Import / Export
   2. Interactivity
   3. Player Controller
   4. iKlax File Explorer
   5. Element Explorer
   6. iKlax & iKmix Files Manager

D. iKlax Library Architecture (Encoding & Writing)
   1. Creating structure and modifying elements
   2. Constraints
      2-1. Selection Constraints
      2-2. Mixing Constraints
   3. Mix & Presets
   4. Encoding & Export

E. Compilation
   1. Windows
   2. Mac OS
   3. iPhone OS

F. How begin with the iKlax Read Library ?
   1. Play an iKlax File.
   2. Play an iKlax File with few interaction.
   3. Print an iKlax File Structure.
   4. A small iKlax Player in command line.

G. How begin with the iKlax Library ?
   5. Create a very simple iKlax File
   6. Create an iKlax File with groups
   7. Create an iKlax File with selection constraints
   8. Create an iKlax File with mixing constraints
   9. Create an iKlax File with author mix

H. Resources
   1. iKlax Files
   2. Applications

I. Licence

J. Authors & Partners

A. What's iKlax ?

iKlax's goal is to open up new creative fields and a new kind of artist/user relationship.

Hailing from the original idea of Owen Lagadec and Ivan Duchemin, the latest digital audio technology has been developed in collaboration with the Image & Sound" department of the LaBRI (Bordeaux IT Research Laboratory) and researchers Myriam Desainte-Catherine and Sylvain Marchand.

iKlax is a multitrack audio format.

This signifies that it can contain separate sound elements (like drums, guitar, vocals, etc.). This structure opens a new creative field for artists, allowing them to include various versions of a same song inside one file. The user also reaches a new plane of music listening and thus enters a closer relationship with the artist.

iKlax is also the first digital audio format that covers all levels of interactivity. Interactivity with music can be achieved on two levels:

• Track selection: the user can switch tracks on/off.
• Volume interaction: the user can modify the volume for each track or for the whole song.

File size varies according to 2 elements:

• The amount of tracks within the song: The amount is nearly unlimited. The limit is determined by the used playback system (PC, cell phones, portable audio players).
• The tracks type and compression used: wav, mp3, ogg vorbis, wma. A compressed iKlax file generally sizes between 25 & 40 MB.

More information on iklaxmedia.com

What's an iKmix ?

An iKmix is a 'mix' of an iKlax file. It contains presets on track's status and/or levels. An iKmix is associated with only one iKlax file. An iKlax file contains at least one iKmix.

An iKmix can be exported in an iKmix file. This file contains only presets but no audio data, so this file is really small and can be easyly shared with someone who owns the same iKlax file.

B. What does iKlax Library contain ?

1. The iKlax Tools Library (KToolLib)

The KToolLib is a great tools box for C development. All C standard libraries & functions had been rewritten in KToolLib, for multiplatform using. This library had been developed and tested on Windows XP & Vista, MacOS 10.4 & 10.5 (Intel & PowerPC), iPhone OS 3.x, Windows Mobile 6.5 and GNU/Linux (Ubuntu & Gentoo) for 32 & 64 bit processors. Actually the iKlax Team works on versions of KToolLib for Windows 7, MacOS 10.6, Android and Symbian.

If your prefered platform is not available, please contact us on iklaxmedia.com.

KToolLib Documentation

The KToolLib documentation is available here.

2. The iKlax Library (iKlaxLib or iKlaxReadLib)

The iKlaxLib is a tools box for interactive music and iKlax files decoding & encoding.
The iKlaxReadLib is a tools box for interactive music and iKlax files decoding only.
All the iKlax Read Library (iKlaxReadLib) is included in the iKlax Library (iKlaxLib).
Current versions of these libraries are only for Windows XP/Vista (32bit), MacOS 10.4 and later (Intel & PowerPC), and iPhone OS 3.x.

Other versions for iKlax files decoding/encoding and for other platforms will be available later, or can be provided on demand.

Available Audio Codecs

This table resumes which audio codecs are available by platforms.

Audio Format	Windows XP/Vista, Mac OS 10.4+	iPhone 3.x
Wave	PCM U8, PCM 16, PCM 24, PCM 32, PCM 64, float-32bit, double-64bit, A-law, U-law	PCM U8, PCM 16, PCM 32, A-law
Aiff	PCM S8, PCM 16, PCM 24, PCM 32, PCM 64, float-32bit, double-64bit, A-law, U-law	PCM S8, PCM 16, PCM 32, A-law
Au	PCM S8, PCM 16, PCM 24, PCM 32, PCM 64, float-32bit, double-64bit, A-law, U-law	PCM S8, PCM 16, PCM 32, A-law
Vorbis	Quality -1 to 10 (45 to 400 kbps)	Not available

C. iKlax Read Library Architecture (Reading & Decoding)

Some modules are available in this library :

• 1. Import / Export
• 2. Interactivity
• 3. Player Controller
• 4. iKlax File Explorer
• 5. Element Explorer
• 6. iKlax & iKmix Files Manager

1. Import / Export

With this module you can import iKlax or iKmix files and export iKmix files from an iKlax file. You can also export an iKmix from an iKlax file to an audio file. See the Import / Export API.

Some functionnalities:

• Load an iKlax file (See API)
• Import an iKmix file in a KFile structure (See API)
• Export an iKmix from KFile structure to a description file (See API)
• Export an iKmix from KFile structure to an audio file (See API)

2. Interactivity

All functions for interactive music. With these functions you can change the played tracks or its levels. See the Interactivity API.

Some functionnalities:

• Change the status (ON/OFF) of an element (See API)
• Change the level of an element (See API)
• Get all mix from a KFile structure (See API)
• Play a mix in a KFile structure (See API)
• Save a mix in a KFile structure (See API)
• Create a random mix in a KFile structure (See API)

3. Player Controller

All very usefull & easy functions to play and listen iKlax file. See the Player Controller API.

Some functionnalities:

• Play (See API)
• Pause (See API)
• Stop (See API)
• Initialize the sound card (See API)
• Close the sound card (See API)
• Go to a specific time (See API)
• Change the general level (See API)
• Change the general panning (See API)
• Play in 'repeat' mode (See API)
• Change sound system thread priority (See API)

4. iKlax File Explorer

Functions to manage iKlax File. See the iKlax File Explorer API.

Some functionnalities:

• Get the number of element of an iKlax file (See API)
• Get the number of tracks of an iKlax file (See API)
• Get the number of constraints of an iKlax file (See API)
• Get the length in second of an iKlax file (See API)
• Get tags keys of an iKlax file (See API)
• Get the value of a tag of an iKlax file (See API)
• Get the top elements names (See API)
• Get the childs names of an element (See API)
• Get the tracks names of an iKlax file (See API)

5. Element Explorer

Functions to manage elements from iKlax File. See the Element Explorer API.

Some functionnalities:

• Get the status of an element (On/Off) (See API)
• Get the level of an element (kelt_getCurrentLevel See API")
• Check is an element is a track (See API)
• Check is an element is a group (See API)

6. iKlax & iKmix Files Manager

Functions to manage iKlax & iKmix files.
The specifity of this object is an automatic loading of iKmix files. If you set a directory to this object, it will be able to:

• scan the directory and load all iKmix files corresponding to an iKlax file
• remember the files paths of all imported iKmix files which are in others directories

See the iKlax & iKmix Files Manager API.

Some functionnalities:

• Create a new manager (See API)
• Destroy a manager (See API)
• Load an iKlax file with the manager (See API)
• Close an iKlax file withe the manager (See API)
• Set the iKmix file directory (See API)
• Know if a iKmix is an Author Mix (See API)

D. iKlax Library Architecture (Encoding & Writing)

The iKlaxLib permits to create iKlax files with groups, constraints and predefined mix. With this library you can access and configure all the interactivity in a multitrack file.

1. Creating structure and modifying elements

1-1. Creating structure

Some functionnalities:

• Add a track from an audio file (See API)
• Add a group (See API)
• Add an element in a group (See API)
• Set the master level of the file (See API)
• Set the master pan of the file (See API)
• Add tags in the file (See API)

1-2. Modifying elements

Some functionnalities:

• Set a default level to an element (See API)
• Set a panoramisation to an element (See API)
• Hide an element (See API)
• Show an element (See API)
• Rename an element (See API)
• Remove an element (See API)

2. Constraints

The iKlax specificity is constraint. Constraints permits to reduce the level of interactivity in a multitrack files, and then gives a better exploration of a music to a listener.
iKlax proposes two types of contraints: selection constraints (on on/off status of tracks) and mixing constraints (on tracks levels).

2-1. Selection Constraints

Four selection constraints are available. A code example is available here.

• Not Mute (See API)
• Implication (See API)
• Exclusion (See API)
• Group Min/Max (See API)

2-2. Mixing Constraints

Two mixing constraints are available. A code example is available here.

• Level Limits (See API)
• Equivalence (See API)

3. Mix & Presets

This module regroups all functionnalities to create predefined mix in an iKlax file. (All the API)

• Create a mix (See API)
• Add tracks in a mix (See API)
• Set defined level on tracks (See API)
• Set the mix as default (See API)

4. Encoding & Export

It's very easy to export an iKlax file: There is only one function!
In this version of the library (1.5), the only available audio format on export is Vorbis (See more information about Vorbis).
On next versions, others audio formats will be available.

• See the API to export an iKlax file

E. Compilation

1. Windows

The only available binary for Windows OS is a dynamic library (a dll file).

• To compile a Windows project with iKlaxLib you must add directories ./include/KToolLib and ./include/iKlaxLib of the package as Include Directories, and define preprocessor macros KTL_DYNAMIC_IMPORT and KL_DYNAMIC_IMPORT.
  
• On linkage, you must link your binaries with files iKlaxLib1.5.lib or iKlaxReadLib1.5.lib, and KToolLib.lib of the package directory ./lib/win32.
• On execution, files iKlaxLib1.5.dll or iKlaxReadLib1.5.dll, KToolLib.dll (of package directory ./bin/win32) and SDL.dll, libogg.dll, libvorbis.dll, libvorbisfile.dll and libsndfile-1.dll (of package directory ./extern_libs/win32) must be in the same directory of the executable file or in a dll system directory.

2. Mac OS

The only available binary for Mac OS is a dynamic library (a dylib file).

• To compile a Mac OS project with iKlaxLib you must add directories ./include/KToolLib and ./include/iKlaxLib of the package as Include Directories.
  
• On linkage, you must link your binaries with files libiKlaxLib1.5.dylib or libiKlaxReadLib1.5.dylib, and libKToolLib.dylib of the package directory ./bin/macos.
• On execution, files libiKlaxLib1.5.dylib or libiKlaxReadLib1.5.dylib, libKToolLib.dylib (of package directory ./bin/macos) and libSDL-1.2.0.dylib, libogg.0.dylib, libvorbis.0.dylib, libvorbisfile.3.dylib, libvorbisenc.2.dylib and libsndfile.1.dylib (of package directory ./extern_libs/macos) must be in the same directory. You can also use the tool install_name_tool to change libraries identification names.

3. iPhone OS

The only available binary for iPhone OS is a static library (a .a file).

• To compile an iPhone OS project with iKlaxLib you must add directories ./include/KToolLib and ./include/iKlaxLib of the package as Include Directories.
  
• On linkage, you must link your binaries with :
  • files libiKlaxReadLib1.5.a and libKToolLib.a of the package directory ./lib/iphoneos
  • the file libogg-iphoneos3.0.a of the package directory ./extern_libs/iphoneos
  • the iPhone framework AudioToolBox
  • the c++ standard library with adding the linker flag -lstdc++.

F. How begin with the iKlax Read Library ?

1. Play an iKlax File.

You would like read and play an iKlax file ? See the source code example.

2. Play an iKlax File with few interaction.

You would like read and play an iKlax file with few interactions ? See the source code example.

3. Print an iKlax File Structure.

You would like print an iKlax file structure ? See the source code example.

4. A small iKlax Player in command line.

A complete example with a small player in command line. The user can choice status and levels tracks, save a mix or choice a existed mix. See the source code example.

G. How begin with the iKlax Library ?

This section contains examples only for writing & encoding iKlax file. To see example about reading & decoding iKlax file, go to the section F. How begin with the iKlax Read Library ?.

5. Create a very simple iKlax File

This is a very simple example to create and export an iKlax file: go to the source code example.

6. Create an iKlax File with groups

In this source code example you can learn how create groups in an iKlax file.

7. Create an iKlax File with selection constraints

You would like add selection constraints in your iKlax file? See the source code example.

8. Create an iKlax File with mixing constraints

If you want add mixing constraints in your iKlax file, go to the source code example.

9. Create an iKlax File with author mix

This source code example shows you how create predefined mix in an iKlax file.

H. Resources

1. iKlax Files

This is a little selection of free music in iKlax: see the music.
And if your prefered artist hasn't got any music in iKlax, you can suggest him to create his next tube in iKlax!

2. Applications

These applications use iKlax Libraries:

• The iKlax Creator Series (Free, Standard and Pro) for PC & Mac
• iKlax Player (PC & Mac)
• iPhone iKlax Apps

I. Licence

IKLAX LIBRARIES LICENSE AGREEMENT

The following licence can be revised at anytime by IKLAX MEDIA SAS, THE AUTHORS AND DISTRIBUTORS without any restriction and applies to all the users of the software.

By downloading the software, the user accepts with no restrictions the following terms of use and licence.

This software is proprietary to iKlax Media SAS, is protected under french Software Protection Agency (APP) and is copyrighted (C) by iKlax Media SAS. Its use and disclosure is limited by the terms and conditions of this license agreement. The following terms apply to all files associated with the software.

iKlax Media SAS hereby grant permission to use, copy and distribute this software and its documentation for any non-commercial purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in non-commercial distributions. No written agreement, license, or royalty fee is required for non-commercial uses.

For commercial uses, distribution of this software or for modification on this this software, please contact iKlax Media SAS. (http://www.iklaxmedia.com)

IN NO EVENT SHALL IKLAX MEDIA SAS, THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

IKLAX MEDIA SAS, THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE AND ITS DOCUMENTATION ARE PROVIDED ON AN "AS IS" BASIS, AND IKLAX MEDIA SAS, THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

J. Authors & Partners

Authors

The following authors have contributed to iKlax Libraries and its documentations. All authors are or were employee by iKlax Media SAS. (In alphabetical order of firstname):

• Cedric Trespeuch
• Emmanuel Bouix
• Fabien Gallot
• Laurent Primaux

Partners

• LaBRI (Laboratoire Bordelais de Recherche en Informatique), the laboratory of research in computer science of Bordeaux University (France)
• CNRS (Centre National de la Recherche Scientifique), the french national center of scientific research.
• ESTIA (Ecole Supérieure des Technologies Industrielles Avancées), the engineer school of advanced technologies of Pays Basque (France)

---