How to use the control in your projects
First of all let us say that if this guide should not be clear to you, feel free to contact our
support team for any doubt or curiosity you may have: we usually answer all of our customers (and not) questions in less than 24 hours. Note that the purpose of this guide is to give a taste of the main features available inside
Active DJ Studio: for a full list of the available properties, methods and events, take a look to the
Table of contents section and to the available
Tutorials.
A number of working samples has been installed with the setup package: they could be of help in order to integrate what is actually written inside this documentation.
As an integration to this guide, several examples of use of this component, in Visual Basic 6 language, can be found inside the "Samples" folder: if during the setup phase you left the installation directory to its default, you will find them inside "C:\Program Files\Active DJ Studio\Samples".
Now add the control to your current project through the ActiveX controls insertion method of the development environment you are currently using (for this purpose, a small tutorial for some Microsoft environment is available
here).
Before starting sounds management, the control needs to be initialised: for this purpose it's mandatory a call to the
InitDJSystem method; the best place to call this initialisation method is usually the container form initialisation routine: for example, when using Visual Basic 6, it will be the
Form_Load subroutine or, when using Visual C++, it will be the management function of the
WM_INITDIALOG Windows message.
The purpose of calling the
InitDJSystem method is to synchronise the control with its container form, to decide how many players (also known as "decks") will be allocated
(*) and, finally, to choose the
output device (sound card) that will perform the final sound playback for each of the allocated players: the number and descriptions of available output devices can be obtained with a prior call to the
GetOutputDevicesCount and
GetOutputDeviceDesc methods.
When a USB device is plugged or unplugged, the container application will receive a
DeviceChange event: after receiving this event, if you need to remain in sync with available sound cards, you will have to reset the multimedia engine through the
ResetEngine method: after this resetting procedure (whose completion could require some second) it will be again possible enumerating available output devices through the
GetOutputDevicesCount and
GetOutputDeviceDesc methods. At this point you will have to re-initialize the control through the
ResetControl method.
If the multimedia engine shouldn't find any enabled or valid output device, the container application would be notified through the
WarnNoOutputDevice event.
At this point you can decide if you prefer working with single song files or with playlists or both:
If you want to work with single files you can load a song into a player using the LoadSound or LoadSoundFast methods (use the LoadSoundFromRawFile method for sound files in RAW format). From now on you will have the possibility to obtain information about the sound, to seek to a certain position, to play, pause, resume or stop it using the available methods (see How to work with single songs). If the sound file has been stored in memory, for example after being retrieved from a database or from an application resource, you can load it inside a player through the LoadSoundFromMemory method (use the LoadSoundFromRawMemory method for sounds stored in RAW format). In case you should need loading a song from the Internet or from a Shoutcast/Icecast server, you should use the LoadInternetStream method.
In either cases you will have an amount of operations you can do with loaded songs. As a starting point, below is a subset of the available methods and properties:
Control of the volume through mixers: usually every sound card have a mixer which can be used in order to set the card volumes; you can access these information using the following methods:
MixerGetCount to get the number of mixers currently installed: usually one mixer is available for every installed sound card.
Player volume/pitch/equaliser control: you can control how the song is performed in a variety of ways; thanks to the use of DirectSound every player can have a separate control over the following settings:
IsDirectX8Avail retrieves the availability of DirectX version 8 (or higher), needed for using the equaliser
SetEqualizerBand to set the Bass, Middle and Trebles values on a certain frequency
Song duration and position retrieval: you can know the duration and the current position of a playing song thanks to the following methods:
GetSoundDuration to know the duration of a song expressed in number of milliseconds
GetPlaybackTime to know the current playback time expressed in milliseconds
GetPlaybackTimeString to know the current playback time expressed with a formatted string (HH:MM:SS:MsMsMs)
GetCurrentPos to know the current position of a playing song expressed in a chosen unit
GetCurrentPosString to know the current position of a playing song expressed with a formatted string (HH:MM:SS:MsMsMs)
Automatic Fader: allows an automatic management of the fade-in/fade-out process through the following configurable object:
Visual feedback: you can give to the listener a customisable visual feedback of the songs being played through the embedded VU-Meter, Spectrum Analyser, Oscilloscope and Waveform display:
Tags retrieval: many formats add some information, also known as tags, to the song binary in order to allow an automatic identification of the file contents: the availability of this information and its contents can be retrieved using the following methods:
IsTagAvailable determines if a certain type of tag is contained inside the song binary
GetMp3Tag2Data retrieves the full contents of the ID3V2 tag for a MP3 song
General info retrieval: information about the loaded song and the general control status can be obtained using the available properties:
GetChannels retrieves the number of channels of the loaded song (mono, stereo, etc.)
LastError property retrieves the last error code generated by the call to a certain method
During sound loading, streaming and playback, the control will fire a set of predefined events that will give the possibility to the form user interface to be updated accordingly: go to the
Table of contents section of this documentation and refer to the "
Events" chapter for details about each of the available events.
(*) A "player" can be compared to a physical "deck" on a DJ console, the place where you put the vinyl/CD to be played; the developer can create a console with many virtual decks that can play simultaneously many different songs on one or more sound cards, each deck having its own volume/tempo/pitch settings. The availability of a certain number of players (decks) will enable the container application to mix several songs on different output channels, giving for example the ability to play advertising spots while songs are being played/mixed on different output channels: this is very useful for multi-channel radio stations automation software.
