turntable/release_notes.txt

DJ Turntable v1.3.0
===================

DJ Turntable demonstrates integrating a Qt Quick application to the Qt audio
interface. The application is compatible with Symbian^3 devices with Qt 4.7.3
or higher, Maemo devices with Qt 4.7.0, Meego 1.2 Harmattan, and Windows 
desktop computers (the Qt libraries are provided with the executable).


FILES
-------------------------------------------------------------------------------

src/main.cpp

- Creates all the required Qt objects and initialises the Declarative runtime.
  The integration of the QML and Qt code is done here.
  
src/TurnTable.h
src/TurnTable.cpp

- Represents the logic of the turntable section of the UI. The Turntable 
  object contains the main audio mixer to which the drum beats and the disc 
  sample are mixed.
  
src/DrumMachine.h
src/DrumMachine.cpp

- Represents the logic of the drum machine section of the UI. Signals of the 
  drum machine QML are mapped directly to this object's slots. The storing and 
  loading of the drum sequences is done here.

src/accelerometerfilter.h

- Handles the accelerometer information from the device's sensor. The signals
  about changes in accelerometer data are mapped directly to the QML slots to 
  rotate the reflection on the record on the turntable.
  
src/sounds/*

- Contains the audio samples used by DJ Turntable.
  
src/qml/DrumMachine/*

- QML files containing the UI controls of the drum machine.

src/qml/InfoScreen/*

- QML files containing the UI controls of the info screen.

src/qml/SampleSelector/*

- QML files containing the UI controls of the sample selector screen.

src/qml/TurnTable.qml

- The main QML file that represents the whole UI of the application.
  All other QML files and elements are children of this file.

install/

- The compiled binaries.


CLASSES AND ELEMENTS USED
-------------------------------------------------------------------------------

The most important Qt classes and QML elements used in the application are
listed here.

Qt / C++ classes
~~~~~~~~~~~~~~~~
 QDeclarativeView - used to interpret QML files 
 QGLWidget        - used to draw QDeclarativeView with Qt OpenGL
 QPointer         - relaxes the use of pointers
 QSettings        - used to store and retrieve user defined beats to / from
                    permanent storage
 QMessageBox      - used to report serious errors
 QVariant         - used as parameters in Qt Signals and Slots between Qt and
                    QML
 QVector          - used to store beat sequences in memory
 std::vector      - used to convert predefined beats stored as byte arrays to
                    QVectors

Qt Mobility classes
~~~~~~~~~~~~~~~~~~~
 QAccelerometer       - gets the inclination of the mobile device
 QAccelerometerFilter - used to filter values of QAccelerometer to save CPU
                        cycles
 QSystemDeviceInfo    - used to detect the profile of the device, for 
                        instance, when the mobile is on silent the volume is 
                        set to 0
 QAudioOutput         - used to access audio device (part of QtMultimediaKit 
                        in Symbian target)

Qt classes used in GE audio engine
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 QAudioOutput   - used to access audio device (part of Qt multimedia module in 
                  desktop and Maemo targets)
 QThread        - used to implement audio functionality in worker thread
 QIODevice      - used to handle audio buffers
 QMutex         - used to synchronise critical sections between worker thread
                  and GUI thread
 QFile          - used to read WAV files

Symbian specific classes
~~~~~~~~~~~~~~~~~~~~~~~~
 MRemConCoreApiTargetObserver,
 CRemConInterfaceSelector,
 CRemConCoreApiTarget          - used to handle volume up/down HW keys on
                                 Symbian devices
 CMMFDevSound                  - used to set the master volume in Symbian
                                 devies, involves a nasty hack

QML elements
~~~~~~~~~~~~
 Flickable         - used to implement view change between the info screen,
                     the turntable, and the drum machine, also used to switch
                     between 1-16 and 17-32 ticks in drum machine
 Repeater          - used to create 32 x 6 drum buttons in drum machine
 Rotation          - used to rotate the 'arm' on top of the record


KNOWN ISSUES
-------------------------------------------------------------------------------

- There is currently some latency when playing audio in Symbian.

- External WAV files can not be opened on Harmattan due to the permissions
  problem.

  
INSTALLATION INSTRUCTIONS
-------------------------------------------------------------------------------

Mobile device (Symbian^3)
~~~~~~~~~~~~~~~~~~~~~~~~~

There are two ways to install the application on the device.

0. The Qt libraries (4.7.3 or higher) must be installed. See the section 
   COMPATIBILITY for more information about the installation.

1. Drag the turntable_1_3_s^3.sis file to the Nokia Ovi Suite while the device
   is connected with the USB cable.

2. After the installation is complete, return to the application menu and
   select the Applications folder.
   
3. Locate the DJ Turntable icon and select it to launch the application.


Mobile device (Maemo)
~~~~~~~~~~~~~~~~~~~~~
0. The Qt libraries (4.7.0 or higher) must be installed. See the section 
   COMPATIBILITY for more information about the installation.

1. Copy the turntable_1_3_fremantle.deb file into a specific folder on the 
   device (for example, 'MyDocs').

2. Start Maemo Filemanager from the application menu.

3. Browse to MyDocs and click turntable_1_3_fremantle.deb. App manager
   will be opened and installation will start.
   
4. Launch the Applications menu.

5. Locate the DJ Turntable icon and select it to launch the application.


Mobile device (MeeGo 1.2 Harmattan)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Copy the turntable_1_3_harmattan.deb file into a specific folder on the
   device.

2. Start Terminal. Type 'ssh root@localhost' to get root access. The password
   is 'rootme'.

3. 'cd' to the directory to which you copied the package.

4. As root, install the package:
   dpkg -i turntable_v1_3_harmattan.deb

5. Locate the DJ Turntable icon from the applications menu and tap it to launch
   the application.


Windows desktop
~~~~~~~~~~~~~~~

1. Extract turntable.zip to the folder of your choosing.

2. Launch the application from turntable.exe.


RUNNING THE APPLICATION
-------------------------------------------------------------------------------

DJ Turntable is a Forum Nokia example that demonstrates integrating a Qt Quick 
application to the Qt audio interface.


Turntable

Play the looping sample with a realistic turntable. The sample can be 
scratched with a finger, played faster, slower, and backwards. The speed of 
the record can be adjusted with the speed slider, the default 1x speed can be 
obtained by double-clicking the speed slider knob. DJ Turntable includes 
Cutoff and Resonance control knobs to alter the sample in real time. The knobs 
are rotated by moving a finger up and down on top of them.


Sample selector

Use the sample selector to change the sample that the turntable is playing by
selecting the desired sample from the directory view. The following 
uncompressed WAV formats are supported:
 
 8-bit unsigned
16-bit unsigned
32-bit float

The application will open the last selected sample on startup. Use the default
sample button on the right under the back button to reset back to the default
sample.


Drum machine
                      
Play and edit the drum beats. There are three predefined beats which can be
played and edited but the edits are not stored. For the user there are three
beats that are saved in the device memory whenever they are edited. Use the
beat selector buttons at the bottom of the view to switch between the beats.
All the beats are 32 ticks long and they contain 6 different drum samples:
hi-hat, hi-hat open, bass drum, snare, cymbal, and cow bell.

The drum machine will play all drum beats at 150 bpm. Changing the speed of
the turntable will affect the playing speed of the drum machine accordingly.


Keyboard shortcuts

The following keyboard shortcuts exist:
Camera zoom up = Volume up
Camera zoom down = Volume down
Space = Start / stop the turntable
Return = Start / stop the drum machine
Key up = Go to the turntable view
Key down = Go to the drum machine view
Key left = View the 1st tick group in the drum machine
Key right = View the 2nd tick group in the drum machine
Key i = Go to the info view
Key s = Go to the sample selector view
Backspace = Return from the info or sample selector view to the previous view


Samples

The turntable melody sample ivory.wav was created by nick Flick3r and it was
downloaded from http://www.freesound.org. The sample follows the
http://creativecommons.org/licenses/sampling+/1.0/ license.


COMPATIBILITY
-------------------------------------------------------------------------------

- Symbian^3 with Qt version 4.7.3 or higher

  1. Download Qt for Symbian (4.7.3 or higher) from qt.nokia.com.
  
  2. Drag qt_installer.sis on top of the device in Nokia Ovi Suite while the 
     device is connected. The SIS package is found in the installation folder 
     of Qt for Symbian (4.7.3 or higher).
     
     
- Maemo with PR1.3 which includes Qt 4.7.0

  1. Use Nokia Ovi Suite to update the device's firmware to PR1.3.


- Meego 1.2 Harmattan


- Windows desktop, the required Qt libraries are provided with the
  turntable binary
    
    
Tested on:

- Nokia N8-00
- Nokia E7-00
- Nokia C6-01
- Nokia N900
- Nokia N950
- Windows 7

Developed with:

- Qt SDK 1.1


VERSION HISTORY
-------------------------------------------------------------------------------
v1.3 Added support for MeeGo 1.2 Harmattan.
v1.2.2 Compatibility with Qt 4.7.2.
v1.2.1 Added error handling to opening of external WAV files.
v1.2 Added possibility to play external WAV files.
v1.1 Updated version for Forum Nokia. 
v1.0 Initial version published in Forum Nokia Projects only.