OpenDJMIX Version 1.0
Author : Karl Soulabaille
Licence: GPL Licence
Web Site: http://www.opendjmix.info
=============================================

OpenDJMix is a mp3 dj'ing system. It consist of library for managing & mixing
MP3 plus a Trolltech QT front-end.

It has been tested mainly on Mac Os X and should also work on Linux.
It may work on other system on which QT has been ported as soon as the operating system
support POSIX thread library.

*WARNING* MacOsX wasn't supported anymore as i haven't any more Apple Mac :(

Functionnality are:
   - Linux x86/PPC/AMD64,
   - Loading cbr/vbr stereo mp3 files,
   - Support Alsa (coreAudio and SDL driver are not supported anymore)
   - Support multi-soundcard  (see below)
   - MP3 File library support with sections & BPM support,
   - ID3 Tag support,
   - Support AudioCD and CDDB,
   - Support sample rate from 44100 to 192000 hz (recommanded: 48000/96000 hz),
   - Support byte swapping operation on PowerPc architecture,
   - Support Little Endian/Big Endian sound output device,
   - Support high-end 24 bits device (like M-Audio, Intel HDA...) if device use 32 bits sound format,
   - Support USB Device (require higher buffer size for USB Devices see below),
   - Support Jack Audio Connection Kit,
   - Use benefits of Dual Core/Quad Core CPU,
   - 4-voices turntable front end,
   - 4 voice crossfader with automatic fading,
   - >2 channels output (for room output & headphone management),
   - Support 8 channels using one soundcard (external mixer),
   - Support 4 channels using one soundcard (room & headphone),
   - Support 2 channels using two soundcards (room & headphone),
   - Import most of GDAM song database (ascii format, not xml),
   - XML database,
   - Multithread support so it works better on Hyperthread or dual-core processors,
   - Support Numark Total Control,

Library support :
   - Polynomial sample conversion from -200% to 200%,
   - Parametric number of voice mixing (default: 64),
   - Parametric output mixing voice (default: 8),

Generic requirement:
The software require a fast engouht computer with 512 Mb of ram 
A low latency sound card (Audigy or M-Audio) with high resolution's daci (24 bits is *highly* recommanded),
For PPC, an altivec G4 1 Ghz CPU is recommanded (not supported anymore (sic))
Linux 2.6.23+ kernel with biglock low latency schedule + preempt

Any processor would be supported now (PowerPc & x86 & x86-64...). I hope that future strange cpu would also be working.

The software support multi sound card with Alsa output driver. SDL and CoreAudio doesn't support more than one soundcard so multi output is not working with it.

You can use 4/6/8 channels soundcard for headphone and room output or two soundcard. Better latency is done only using one soundcard ;)


Software requirement:
- GNU Gcc 4.1+, autoconf 2.59, automake 1.9 (works with GCC 3.4 & 4.1),
- Posix thread Library,
- QT 4.3 or greater,
- Libmad 0.96 for mp3 decoding
- ALSA 0.9 sound kernel & Library on Linux operating system
- Expat, for XML database management,
- Libcdio and Libcddb for CDA management,
- Jack Audio Connection Kit (option),

Main library (in kernel/ & lib/ directories) use only STL/posix libraries at this time.
They don't used QT library. Only "opendjmix" program (found in client/qtV2) use it.


Configure parameters:
You need to select one output device
 --enable-alsa        For linux alsa sound system
 --enable-coreaudio   For Mac OS (may not work because not tested since many years now!) [obsolete]
 --enable-sdl         For SDL (not tested with latest build and doesn't support multidevice) [obsolete]
 --enable-jack        Enable jack (can be used alone or with Alsa),

 --enable-altivec      Enable use of some specific instruction of PPC (not supported anymore) [obsolete]
 --enable-optimise    Enable use of -O3 which allow optimal speed without any debug information
 --enable-profile     Enable use of gprof for profiling
 --enabl-debug        Enable use of gdb for debuggingggg

For i686+ computer, you can add more optimisation by enabling used of SSE instructions before ./configure:
export CXXFLAGS="-msse"

You can also add -march= and -mtune= parameters depending your processor. Here is example for Core2/Quad.
export CXXFLAGS="-mtune=nocona -march=nocona -msse"

Please see GCC manual for more information about theses flags.

Altivec can be enabled on MacOS/PPC systems but is not supported anymore.

CoreAudio device use float kernel output format & use default bit rate setup on sound system.
It try to open 8/6/4/2 channels for headphone management.
 
Alsa supports devices using Signed 16 bits Little/Big Endian, or Signed 32 bits Little/Big Endian,
The device try to use in order 96 khz, 64, 48, 44 khz. If no one can be used, the software won't start.
It also try to open 8/6/4 channels for headphone management.

SDL supports only 44 khz device Signed 16 bits little endian. This device was created for porting purpose.
It manage only stereo device so there is not any way to use headphone.

Open Sound System will be never supported,

After configuring, you may compile with
make

and install with:
make install

You can cleanup all binaries in source tree by:
make clean

You can do developper documentation by:
cd docs && make doc


Thread priority:
---------------------
The software use RealTime priority for mixing thread.
However, default behaviour of some distribution is not to allow RT-Priorities.
This behaviour can defect OpenDJMix because GUI has the same priority than mixing kernel. 
So sound may break frequently.

You may check it with 'ulimit -e' shell command
If the answer is 0 then, rt-Priority is disable. So - as root - you can allow RT-Prioritees
with 'ulimit -e 99'

Before kernel 2.6.27, if you want to change rtprio for a specific user, you may add the next line to /etc/security/limits.conf:
user            -	rtprio  99

where user is your username.

Best practice specify now to use a group "realtime" in which users that launch RT software will be get in:
To enable realtime group in limits.conf:
@realtime	-	rtprio	99

wARNING: Since Kernel 2.6.27, security model has changed again, i am looking how to enable RT without lauching OpenDJMix as root user

To check if rt thread are available, please check OpenDJMix for messages:
== DEBUG == [posixthread.cpp:234] Setup schedule value for thread from object 5Mixer to value: 99 
..
== DEBUG == [posixthread.cpp:237] Opération non permise

The latest message say that software cannot upgrade thread priority to RT




Launching the GUI / Config file
---------------------------------
The GUI name is OpenDJMix. You can find in source directory client/qtV2/skin.
If you are launching GUI without any config file created before, the GUI will create it when leaving.
The config file is ~/.opendjmix/config

All config information given below setup gui QTv2 only.

Here is an example of Config File:

cdrom/device/0=/dev/dvd
cdrom/device/1=/dev/cdrom
cdrom/device/2=
configuration/generator=DJMix
configuration/version=1.0
database/defaultdb=/home/karl/.opendjmix/database.xml
gui/qtV2/drillfx=4x1/4x0.5/4x0.25
gui/qtV2/vumeter/fall=0.4
gui/qtV2/refreshtime=40
sound/driver=Alsa
sound/alsa/headChannelL=2
sound/alsa/headChannelR=3
sound/alsa/headsoundcard=hw:Intel
sound/alsa/roomChannelL=0
sound/alsa/roomChannelR=1
sound/alsa/roomsoundcard=hw:Intel
sound/fragmentsize=512
sound/nbfragment=4

Customise CDROM drive
----------------------------------
OpenDJMix is able to play AudioCD.
You can put all your cdrom drive into config file.
All devices are setting up in the way
cdrom/device/<n>=<device>

where <n> is the cdrom number that is contigus
and <device> is linux device associated to cdrom drive.

Customise database
------------------------------------
Song and Beats information are saved in database which is an XML file.
You can select database by setting input like this:
database/defaultdb=<databasepathandfile>

where <databasepathandfile> is the full path of xml file.
For example:
database/defaultdb=/home/karl/.opendjmix/database.xml

Setting soundcard
-----------------------------------
Depending output driver, OpenDJMix work with one or two soundcards.
Alsa support one or two soundcard while Jack support one soundcard.
If you are using one soundcard, you need to have 4 channels: 2 for room output and 2 for headphone output,
If you are using two soundcard, two channel on first sound card are used for room output and two channels
of second card are used for headphone.

Because latency, having one soundcard with a minimum of 4 channels is a better choise.

Jack Soundcard options:
---------------------------------
Jack if enabling only if source has been compiled with Jack Option.

For using Jack, you need:
sound/driver=Jack

OpenDJMix create 8 ports. You can setup "room" ports and "head" ports.
sound/jack/roomChannelL=<chan 0>
sound/jack/roomChannelR=<chan 1>

The same option are available for headphone:
sound/jack/headChannelL=<chan 0>
sound/jack/headChannelR=<chan 1>

For example:
sound/jack/roomChannelL=0
sound/jack/roomChannelR=1
sound/jack/headChannelL=2
sound/jack/headChannelR=3

OpenDJMix may start Jack server if necessary. However, we suggest you to start Jack manually beforce
Jack server.


Alsa Soundcard options
----------------------------------
For using Alsa, you need:
sound/driver=Alsa

For setting soundcard sample rate:
sound/alsa/rate=<rate>

where <rate> is the sample rate (must be between 44100 and 192000).
This option is optional, without it the software try rates of
96000,48000,41000

The option for room output are:
sound/alsa/roomChannelL=<chan 0>
sound/alsa/roomChannelR=<chan 1>
sound/alsa/roomsoundcard=<Hardware device>

Where <chan 0> is the left channel output and <chan 1> is the right channel output.
<Hardware device> is the device that should be used. For example: 
sound/alsa/roomChannelL=0
sound/alsa/roomChannelR=1
sound/alsa/roomsoundcard=hw:Intel


The same option are available for headphone:
sound/alsa/headChannelL=2
sound/alsa/headChannelR=3
sound/alsa/headsoundcard=hw:Intel

When using one soundcard, you must take same literal argument to headsoundcard than roomsoundcard. However, roomChannelL should be different than headChannelL and roomChannelR should be different than roomChannelR.
It you are not putting argument in file, then default sound card will be taking (not recommanded behaviour).

When using two soundcard, roomsound should point to a different soundcard than headsoundcard.


Using an external mixer (for Alsa and Jack)
-------------------------------------------
The software can use a 8 channels soundcard for sending *all* turntables sounds to 4 input external mixer (like Behringer DDM 4000 or other...)
To enable the use of external mixer, you need to specify channels in config file:
For example:

sound/alsa/channel1L=0
sound/alsa/channel1R=1
sound/alsa/channel2L=2
sound/alsa/channel2R=3
sound/alsa/channel3L=4
sound/alsa/channel3R=5
sound/alsa/channel4L=7
sound/alsa/channel4R=6

(When using Jack, please changed sound/alsa by sound/jack)
The line that output {L,R} of turntable {1,2,3,4} should be sending to output {0..7} of soundcard.

WARNING: External mixer work only with one soundcard. It doens't support 4 soundcards.


Soundcards Parameters (for Alsa)
---------------------------------
This chapter provides some soundcard OpenDJMix parameters 
All parameters are in ~/.opendjmix/config file.
Fragsize can be configured with parameter "sound/fragmentsize"
Nb of Frag can be configured with parameter "sound/nbfragment"

This is an extract of config file for these two parameters:
sound/fragmentsize=1024
sound/nbfragment=4

Soundcard Name					FragSize		Nb of Frag
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
M-Audio Revolution 7.1	(96Khz, 24 bits)	1024			3
Intel HDA (Analog Devices AD1988B)  (96 Khz, 24 bits)
			(see 1)			512			4
Intel HDA (Connexant) (see 1)			1024			4
USB-Audio Behringer UCA202 (48 Khz/16 bits)	2048			2


(1) It appears that Intel HDA Alsa driver introduce latency. So the number of buffer must be higher
than 2.

(2) USB-Audio require a high fragsize.

When mixing two soundcards with differents parameters, you may use the maximum of fragsize and maximum
of number of frag of both soundcards. That will introduce the higher latency but works usually.

If sound is broken (stop or sound a bit strange), please try higher value (try fragmentsize higher first
then nbfragment).

Refresh GUI behaviour
----------------------
You can change GUI refresh time by changing gui/qtV2/refreshtime. The time is given in ms.
Default is 60 milliseconds.

GUI latency doesn't affect directly sound card latency. However, a low latency consumn more power and 
may give the software inusable.
If a too high latency is setting, then realtime timer (like sound playing time, waveform) may not
enough accurate and software will become inusable also.

A time between 30/80 milliseconds are right value depending your CPU.

For checking right value, you may load a mp3 file into all turntables and look for latency/cpu power.

For changing vumeter fall time, you can setup parameter gui/qtV2/vumeter/fall. Default value is 0.3
Higher value is, higher speed vuleds will turn off


FX behaviour
----------------------
* Drill FX 
Drill FX can be configured as below:
gui/qtV2/drillfx=4x1/4x0.5/4x0.25

This say that play restart at previous beat and play one time, restart a second time to previous beat and play one beat... etc.. 4 time
then it play 4 times a half (0.5) beats (restarting at previous beat each time),
then it play 4 times a quarter (0.25) beats (restarting at previous beat each time),

More FX would be configured later.

Shortcut
-----------------------
GUI support shortcuts that has been designed for French AZERTY keyboard.
Theses shortcuts (called KeyLayout1) can be found into:

If you are looking for designing new keyboard shortcuts, please look at KeyMapper into client/qtV2/skin/keymapper and KeyMapper/KeyLayout1 API.

Please send me new class if you are designed shortcuts.


KeyLayout1 shortcuts
------------------------

Here is the default layout which has been designed for french keyboard (AZERTY):
First column is function, second, third, fourth and fifth are keys for turntable 1/2/3/4.

  - Play/stop keys
    Play/Stop		A		R		U		P
    Set cue point	SHIFT+Z		SHIFT+T		SHIFT+I		SHIFT+^
    Go cue point	Z		T		I		^
       
     

  - Forward/backward
    4 beats backward	Q		F		J		M
    4 beats forward	S		G		K		ù
    1 beats backward	SHIFT+Q		SHIFT+F		SHIFT+J		SHIFT+M
    1 beats forward	SHIFT+S		SHIFT+G		SHIFT+K		SHIFT+ù
    16 beats backward	CTRL+Q		CTRL+F		CTRL+J		CTRL+M
    16 beats forward	CTRL+S		CTRL+G		CTRL+K		CTRL+ù

  - Loop:
    Loop On/Off		&		é		"		'
   Start of loop (99 beats size length)			
   			SHIFT+&		SHIFT+é		SHIFT+"		SHIFT+'
   Restart Loop		CTRL+&		CTRL+é		CTRL+"		CTRL+'
   End of Loop		SHIFT+CTRL+&	SHIFT+CTRL+é	SHIFT+CTRL+	SHIFT+CTRL+'</td></tr>

   - FX
   Stall		1		2		3		[ENTER]
   Scratch		4		5		6		+
   Drill		7		8		9
     
  - Mute
  Mute Room		F1		F3		F5		F7
  Mute Headphone	F2		F4		F6		F8

  - Tap
    Tap			F9		F10		F11		F12


This keymap is also used in xml fr-keymapper.xml.

Creating custom keyboard shortcuts
-----------------------------------
You can create your own keyboard shortcut.
A full example is installed in share/opendjmix directory and is called fr-keymapper.xml
To use it, please add in your user config file ~/.opendjmix/config, the next line:

gui/qtV2/keymapper/xmlfile=<DIR>/keymapper.xml

Where <DIR> must be replaced by directory where xml file is saved in.

If you want to create your own xml file, please check small example file in OpenDJMix source directory at:
client/qtV2/skin/keymapper/xmltest/

You can also start from keymapper.xml file and replace shortcuts by own.


Bug reports
-------------------------
Please open bug on bugtracker if you have any problem. In this way, you can register an account to 
http://www.opendjmix.info/bugtracker/

Registering bug allow me to improve OpenDJMix and give to all user an answer to specific problem.


To Do (+ job done, = job in progress, * job to be done)
--------------------------------------------------------
+ Support of ID3 Tag (done),
* Filters,
- Replace polynomial speed change by an FFT high quality filter (very lower priority),
* DJ's mix effect (phaser, etc..), ==> started (low quality scratch + drill),
+ Hardware device for mixing ;). Lot of jobs coming soon ! [done for Numark Total Control]
+ CDDA support (done! with CDDB) ==> done  for QtV2 client !
- Implement DTD for XML parsing (in fact, replace ### expat by libxml),
* Rewrite some C-coded parts to C++-coded parts (like file* => fstream, exceptions...)
* Improve error management,
+ Start playing without full loaded song (done for both CDA/MP3 !),
* Support of WMA, OGG, ...
+ Rewrote of Database (not very clean code!, lots of bugs have been removed)
+ Suppress Waveform display bug for low level zoom (done since Gui QtV2, it is a new waveform display widget!)
+ Sometimes lock when loading files (done, replace lock() to tryLock(), add some sleep for proper order initialization) (done! no lock since some months now!),
= Video Mixing (some try but doesn't work now!),
+ Crossfader (done),
- Add MMAP I/O for Alsa cards
+ Merge multi soundcard router with mixer (==> lower latency) [done]
+ Support of djing controller (like Numark Total Control) [done]
...



