|
How to use the control in your projects |
  
|
|
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. 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 and Visual C++ 6 languages, 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".
The first needed step is to add the control to your project: see the Adding the control to a project section for details.
Starting from version 5.0, Active DJ Studio can manage both DirectSound and ASIO drivers; inside this tutorial we will refer to DirectSound only: information about ASIO drivers management can be found inside the related tutorial How to manage ASIO drivers
Before starting sounds management, the control needs to be initialized: 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 initialization 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.
Purposes of calling the InitDJSystem method are the following:
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.
Each player allocated through the InitDJSystem method generates an audio stream which, after being modified through special effects, can be sent to different destinations; till version 4.x of the control, the unique available destination of the modified audio stream was, through the interaction with DirectSound, the selected output device or, at the best, a specific speaker of the output device; the graph below summarises the old situation:
Starting from version 5.0, the control has more possible choices in order to redirect the audio stream; just take a look to the sample graph below:
As seen in previous graph related to version 4.x, Players 3 and 4 displayed on the graph above still can output their stream directly to DirectSound but now we have some more features. The main new feature is the availability of custom "Stream Mixers" which allows mixing a number of streams generated by different players (in the graph above represented by Players 0, 1 and 2); the mixing result can be redirected to one or more of the following destinations with the possibility to apply further effects (for example changing the volume of the mixed streams or changing its output device):
It's very important to note that the three destinations described above can be applied all at the same time: this means that you can hear what is being played and mixed on your local speakers, at the same time you can send what you are hearing to a Shoutcast/Icecast server and, again at the same time, save what you are hearing into a file on your hard disk. More details about this feature can be found inside the tutorial How to use custom Stream Mixers.
Another feature added starting from version 5.0 is the capability for a player (on the sample above identified by Player 5) to send its audio stream directly to a Shoutcast or Icecast server through the use of an external encoder (Lame.exe for MP3 or OggEnc.exe for Ogg Vorbis). More details about this feature can be found inside the tutorial How to use the control as a source for Shoutcast/Icecast servers.
At this point you can decide if you prefer working with single sound files or with playlists or both:
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 system 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 system mixers currently installed: usually one mixer is available for every installed sound card. MixerGetDesc to retrieve a friendly description of a system mixer. MixerSetMasterVolume/MixerGetMasterVolume to set/get a system mixer Master volume MixerSetWaveVolume/MixerGetWaveVolume to set/get a system mixer Wave volume (Not available under Windows Vista)
Player volume/pitch 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: StreamVolumeSet to set a player volume; StreamBalanceSet to set a player balance SetTempoPerc to set a player tempo SetRatePerc to set a player playback rate SetPitch to set a player playback rate
Special effects: you can apply several types of effects to the sound under playback; check the How to apply special effects to a playing sound tutorial for further details.
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 GetFormattedSoundDuration to know the duration of a song expressed with a formatted string (HH:MM:SS:MsMsMs) 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) GetCurrentHour to know the currently playing hour GetCurrentMinute to know the currently playing minute GetCurrentSecond to know the currently playing second GetCurrentMs to know the currently playing millisecond GetCurrentPercentage to know the currently played percentage GetPlayerStatus to know a player status
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 GetMp3TagVersion obtains the tag version for a MP3 song GetFileTagField retrieves a specific field of a tag GetTagString retrieves a string inside the tag GetMp3Tag2Size retrieves the size of the ID3V2 tag for a MP3 song 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: GetFileType retrieves the format of the loaded song GetChannels retrieves the number of channels of the loaded song (mono, stereo, etc.) GetFrequency retrieves the bitrate of the loaded song GetPlayerStatus retrieves the status of the given player 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. The How to synchronize the container application with the control tutorial will give you some more information about events management.
(*) 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.
|
