Introduction

Copyright © 2001-2018 MultiMedia Soft

Introduction

Return to chapter overview

Active DJ Studio is an ActiveX custom control developed by MultiMedia Soft that makes it easy to add sound playback and mixing capabilities to applications written with the most widely-used development environments that accept ActiveX controls; thanks to the integration with DirectShow codecs and with the BASS library, both allowing decoding capabilities for the most common sound formats such as MP3, WAV, Ogg Vorbis and many others, Active DJ Studio allows creating powerful multimedia applications with stunning playback capabilities.

Active DJ Studio can load different sounds at the same time on different virtual decks, known as "players"; a player can be compared to a physical deck on a DJ console, the place where you put the vinyl/CD to be played. You can create a console with many virtual decks that can simultaneously play different songs on one or more sound cards. 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

Each player can have separate volume, tempo, playback rate, pitch and equalizer settings; each player also comes with a set of embedded and configurable visual feedback components such as VU-meter, spectrum analyzer, oscilloscope and waveform.

An embedded automatic fader can easily mix audio tracks loaded inside a playlist with an accurate and configurable fade-in/fade-out.

Many tutorials are available to help you beginning your developments with this powerful control.

Brief summary of available features:

Audio playback

Sound effects

Sound generator

Sound composer

MIDI

Audio streaming to and from the Internet

Video playback

Protocols and sound cards management

Playlists and sound management

CD management

Graphical features

Tags-related features

Misc features

Supported target systems

Audio playback

· Playback of the following audio formats:

- AAC and AAC+ | - MOD Music | - PVF
- AC3 | - Monkey's Audio (APE) | - Speex
- AIFF | - MP3, MP2, MP1 | - SVX
- ALAC | - MP4 | - VOC
- AU | - Musepack | - W64
- CAF (1) | - NIST | - WAV (2)
- CD tracks | - OGG Vorbis | - WavPack
- FLAC | - OPUS | - WMA and WMV (3)
- IRCAM | - PAF |
- M4A | - PCM RAW format |

(1) Support for PCM 8/16/24/32 bits, PCM 32 bits floating point, G711 U-LAW, G711 A-LAW

(2) Support for uncompressed PCM and compressed formats whose ACM codec is installed inside the system

(3) Require the availability of Windows Media Player modules on the target PC

· PCM stream queuing, allowing to play sound streams coming from an external source
· Playback of sound files from memory buffers
· Custom encryption/decryption of sounds

Sound effects

· Volume control
· Volume sliding
· Pre-amplifier
· Automatic Fader and volume automation with possibility to design volume fading curves
· Equalizer
· Auto-equalization of audio tracks through formatted XML files
· BPM (Beats Per Minute) detection
· Beats position detection
· Tempo, Playback rate and Pitch support
· Configurable normalization of sound level
· Reverse playback of audio tracks
· DirectX Media Objects (DMO) effects
· EAX effects (if supported by the sound card)
· Custom DSP effects
· VST effects
· Common filters (low-pass, high-pass, band-pass and stop-band)
· Vocal remover filter
· Real-time DC Offset removal

Sound generator

· Pure wave tones
· Composite or monaural wave tones
· Binaural and multi-channel wave tones
· Sliding wave tones
· Noises
· DTMF tones
· Text to speech strings

Sound composer

· Composing of new mono, stereo or multi-channel (up to 7.1) sound files by mixing together audio data taken from the following audio sources:

- Regular sound files stored inside disk files or inside memory buffers

- The Microsoft Speech API which allows creating audio data from a string of text or from a text file through synthesized voices

MIDI

· Playback of MIDI files
· SoundFonts management
· Events management
· Acquisition of MIDI events from a MIDI input device
· VST Instruments

Audio streaming to and from the Internet

· Playback of audio files stored on an Internet server (not available for MOD music files)
· Playback of Internet radios Shoutcast (versions 1 and 2) Icecast and WMA streams
· Playback of Internet radios streaming in HLS format (HTTP Live Streaming)
· Support for acting as a source for ShoutCAST, IceCast and Windows Media Services streaming servers
· Support for sending to streaming servers (ShoutCAST, IceCast and Windows Media Services), the output of any WASAPI loopback device, allowing to stream any sound being played through an output device also if generated by external and third-party applications (requires Windows Vista and later versions)

Video playback

· Playback of video clips whose DirectShow compatible codecs are installed inside the target system, with support for multiple output windows
· Mixing/blending of video clips inside a video mixer output window, with support for separate preview windows
· Customizable On-Screen-Display (OSD) on the video mixer window
· Customizable On-Screen-Display (OSD) on the video player
· Brightness, contrast, saturation, hue and gamma management of the loaded video clip
· Fullscreen management
· Extraction of the audio track available inside a video clip, allowing to perform silence detection, BPM detection and waveform analysis

Protocols and sound cards management

· DirectSound protocol
· ASIO protocol with the possibility to directly playback the sound stream coming from ASIO input channels of the sound card
· WASAPI protocol on Windows Vista and higher versions
· Management of audio endpoints (CoreAudio) on Windows Vista and higher versions
· Sound card output choice and speakers assignment

Playlists and sound management

· Playlists support (M3U, PLS, WPL)
· New proprietary playlist format (PDJ), allowing to predispose mixing automation and volume automation on each single song and to play encrypted sounds
· Position triggers management
· Cue points management
· Sound waveform analysis
· Delayed playback of songs

CD management

· Playback of CD tracks
· CDDB database queries (through FreeDb servers)
· CD cover pictures retrieval (through Amazon Web Services)

Graphical features

· Real-time embedded visual feedbacks (VU-Meter, Oscilloscope, Spectrum, Waveform display)
· Graphic bars for custom displaying of Vu-Meters, Spectrum and Progress bars
· Display of fade-in and fade-out curves applied to the embedded automatic fader
· Waveform scroller allowing manual and automatic movement of the waveform
· Support for drawing the waveform representation inside a graphical device context (HDC)
· Virtual piano keyboard for MIDI management
· Frames grabbing from video clips
· Volume curve designer
· Enhanced graphical spectrum analyzer

Tags-related features

· Reading of most common frames of the following tag formats (Unicode strings supported):

- APE | - APE
- ID3V1 | - LYRICS3
- ID3V2.2 | - MP4
- ID3V2.3 | - OGG Vorbis
- ID3V2.4 |

· Reading of the following chunks in WAV files:

- CART | - DISP
- BEXT | - LIST INFO

Misc features

· Mixing of songs songs at application level, through custom stream mixers, allowing to save mixing results through the integration with our Active Sound Recorder control or to send mixing results to a streaming server
· Exporting of loaded sound in WAV format (on both disk file or memory buffer)
· Lyrics synchronization through LRC files
· Downloading facility allowing the download of remote files into the local system and, in case of media files of supported format, with the option to load them automatically inside a player when download is completed
· Support for ZIP format
· Integration with our Active Sound Recorder and Active Sound Editor controls
· Being an ActiveX control, it can be instanced inside HTML code

Supported target systems

· From Windows XP up to Windows 10 in both x86 and x64 versions
· From Windows Server 2003 up to Windows Server 2016 in both x86 and x64 versions

IMPORTANT NOTES:

For redistribution of the control with your application, we recommend you to take a close look to the Files to be included with your application section.


Copyright information

Copyright information

© Copyright MultiMedia Soft 2001-2018. ALL RIGHTS RESERVED

MultiMedia Soft product specifications are subject to change without notice.

Trademarks

Active DJ Studio is a registered trademark of MultiMedia Soft.

Active Sound Recorder is a registered trademark of MultiMedia Soft.

Active Sound Editor is a registered trademark of MultiMedia Soft.

Windows, ActiveX, Visual C++, Visual Basic and Visual Studio.NET are registered trademarks of the Microsoft Corporation.

All other brand or product names used in this online help are trademarks of their respective holders.


License agreement

License agreement

PLEASE READ THE FOLLOWING LICENSE AGREEMENT. IT WILL BE NECESSARY FOR YOU TO AGREE TO BE BOUND BY THE TERMS OF THIS AGREEMENT BEFORE BEING PERMITTED TO CONTINUE TO USE THE PRODUCT.

VERY IMPORTANT-CAREFULLY READ : This MultiMedia Soft License Agreement (hereinafter "LICENSE") is a legal agreement between you (either an individual or a single entity) and MultiMedia Soft, for the "Active DJ Studio" ActiveX control (hereinafter " SOFTWARE ").

By installing, copying or otherwise using the SOFTWARE, you agree to be bound by the terms of this LICENSE. If you do not agree to the terms of this LICENSE, you cannot use this SOFTWARE for any purposes.

The SOFTWARE is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The SOFTWARE is licensed, not sold.

I.        LICENSE GRANT for "COMMERCIAL EDITION". This LICENSE grants you the following rights:

A. The SOFTWARE's license is "PER DEVELOPER": this means that one single software developer may use this SOFTWARE on one or more computers until no other developers have access to the computer in order to develop the application that will contain the SOFTWARE. The SOFTWARE is in "use" on a computer when it is loaded into temporary memory (i.e. RAM) or installed into permanent memory (e.g. hard disk, CD-ROM, or other storage device) of that computer. However, installation on a network server for the sole purpose of internal distribution to one or more other computer(s) shall not constitute "use" for which a separate license is required.

B. Solely with respect to electronic documents included with the SOFTWARE, you may make a copy (either in hardcopy or electronic form), provided that the number of copies made shall not exceed the number of licenses you own for that SOFTWARE, and further provided that such copies shall be used only for internal purposes and are not republished or distributed to any third party.

C. You may use the trial versions of the SOFTWARE for the limited purposes of demonstrations and trials.

II.        LICENSE GRANT for "PERSONAL EDITION". This LICENSE is no more available and is replaced by the LICENSE for "COMMERCIAL EDITION" as described in point I above.

III.        TITLE; COPYRIGHT. All title and copyrights in and to the SOFTWARE (including but not limited to any images, photographs, animation, video, audio, music and text incorporated into the SOFTWARE), and any copies of the SOFTWARE are owned by MultiMedia Soft. The SOFTWARE is protected by copyright laws and international treaty provisions. Therefore, you must treat the SOFTWARE like any other copyrighted material, except that you may either (A) make one copy of the SOFTWARE solely for backup or archival purposes or (B) install the SOFTWARE on a single computer provided you keep the original solely for backup or archival purposes.

IV.        ADDITIONAL RIGHTS AND LIMITATIONS.

A. Reverse Engineering, Decompilation, and Disassembly. You may not reverse engineer, decompile, or disassemble the SOFTWARE.

B. No Separation of Components. The SOFTWARE is licensed as a single product and the software programs comprising the SOFTWARE may not be separated for use by more than one user at a time.

C. Rental. You may not rent or lease the SOFTWARE.

D. Software Transfer. You may NOT transfer any of your rights under this LICENSE without written permission by MultiMedia Soft. With the "PERSONAL EDITION" no license transfer is allowed.

E. Temporary LICENSE Transfer for outsourcing development purposes. You may transfer your LICENSE to another developer for the amount of time requested to complete the outsourced development: the transfer must be requested to MultiMedia Soft and, in any case, You are not allowed to request more than one transfer to outsourced developers. With the "PERSONAL EDITION" no license transfer is allowed.

F. Termination. Without prejudice to any other rights, MultiMedia Soft may terminate this LICENSE if you fail to comply with the terms and conditions of this LICENSE. In such event, you must destroy all copies of the SOFTWARE.

V.        REDISTRIBUTABLE COMPONENTS.

A. Sample Code. In addition to the license granted in Section 1, MultiMedia Soft grants you the right to use and modify the source code versions of those portions of the SOFTWARE which are identified in the documentation as the Sample Code and located in the \SAMPLES(xx) subdirectory(s) of the SOFTWARE provided you comply with section 4.c.

B. Redistributable Code. In addition to the license granted in Section 1, MultiMedia Soft grants you a nonexclusive, royalty-free right to reproduce and distribute the object code version of those portions of the SOFTWARE designated in the SOFTWARE as (i) those portions of the SOFTWARE which are identified in the documentation as the OCX ("OCX") Control; (ii) those portions of the SOFTWARE which are identified in the documentation as REDISTRIBUTABLE DLLs ("DLLs"); and (iii) SAMPLE CODE (collectively, "REDISTRIBUTABLES"), provided you comply with Section 4.c.

C. Redistribution Requirements. If you redistribute the REDISTRIBUTABLES, you agree to (i) distribute the REDISTRIBUTABLES in object code form only in conjunction with and as part of your software application product which adds significant and primary functionality and which is designed, developed, and tested to operate in the Microsoft Windows and/or Windows NT environments; (ii) not use MultiMedia Soft's name, logo or trademarks to market your software application product; (iii) include a valid copyright notice on your SOFTWARE; (iv) indemnify, hold harmless, and defend MultiMedia Soft from and against any claims or lawsuits, including attorney's fees, that arise or result from the use and distribution of your software application product; and (v) not permit further distribution of the REDISTRIBUTABLES by your end user.

VI.        THIRD PARTY INTELLECTUAL PROPERTY RIGHTS

A. The SOFTWARE embeds inside its binary code a third party commercial library named BASS: the license of the SOFTWARE does NOT cover the license for the BASS library so, depending upon the nature of your application, you may need to obtain a separated license from the BASS developer (www.un4seen.com)

LIMITED WARRANTY. EXCEPT WITH RESPECT TO REDISTRIBUTABLES, WHICH ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, MULTIMEDIA SOFT WARRANTS THAT THE SOFTWARE WILL PERFORM SUBSTANTIALLY IN ACCORDANCE WITH THE ACCOMPANYING ONLINE HELP MATERIALS.

NO OTHER WARRANTIES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, MULTIMEDIA SOFT DISCLAIMS ALL OTHER WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, WITH REGARD TO THE SOFTWARE. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS, WHICH VARY FROM STATE/JURISDICTION TO STATE/JURISDICTION.

NO LIABILITIES FOR CONSEQUENTIAL DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL MULTIMEDIA SOFT BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE, EVEN IF MULTIMEDIA SOFT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME STATES AND JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.

LICENSEE ACKNOWLEDGES THAT IT HAS READ AND UNDERSTANDS THIS AGREEMENT AND AGREES TO BE BOUND BY ITS TERMS. LICENSEE FURTHER AGREES THAT THIS AGREEMENT IS THE COMPLETE AND EXCLUSIVE STATEMENT OF THE AGREEMENT BETWEEN LICENSEE AND LICENSOR, AND SUPERCEDES ANY PROPOSAL OR PRIOR AGREEMENT, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS RELATING TO THE SUBJECT MATER OF THIS AGREEMENT.


Files to be included with your application

Files to be included with your application

Important note about installed version

This section of the documentation applies to the full purchased version only: the trial version of the component comes with an internal protection schema against fraudulent uses which will block most functionalities when the component is redistributed outside of the development machine where the trial version was originally installed through the provided setup program.

Files that you need to redistribute with your application depend upon the platform target:

· If compiling for "Any CPU"

- the x86 version of the the control's binary AMP3DJ.OCX

- the x86 version of the multimedia engine AdjMmsEng.dll

- the x64 version of the the control's binary AMP3DJ64.OCX

- the x64 version of the multimedia engine AdjMmsEng64.dll

· If compiling specifically for x86

- the x86 version of the the control's binary AMP3DJ.OCX

- the x86 version of the multimedia engine AdjMmsEng.dll

· If compiling specifically for x64

- the x64 version of the the control's binary AMP3DJ64.OCX

- the x64 version of the multimedia engine AdjMmsEng64.dll

You can find redistributable files mentioned above inside the folder in which you installed Active DJ Studio (default "C:\Program Files\Active DJ Studio\Redist").

Important note about the folder chosen for installing our files

In order to avoid the "DLL Hell" problem, it's strongly recommended that you install the mentioned files into the same folder in which you will install the EXE of your container application on the target system and not inside the Windows\System32 or Windows\SysWOW64 folders.

In order for the control to register and work correctly on the target system, the following is a summary of the Microsoft Windows libraries that must be available on the target system:

WINMM.DLL

MSACM32.DLL

OLEAUT32.DLL

OLEPRO32.DLL

DirectX version 9.0c or higher should be available as well. DirectX redistributable modules can be obtained from the Microsoft web site.

Special notes

· If you need dealing with Windows Media Audio files (WMA, ASF, WMV, etc.), the Microsoft Windows Media Format modules must already be installed on the target PC: for Windows XP and previous versions the Windows Media Format modules can be installed using the redistribution setup package (wmfdist.exe) provided by Microsoft. For Windows Vista and later versions there is the need to install the Microsoft's Windows Media Player application (which is usually installed by default).

· For using the component as a source for SHOUTCast or IceCast servers, the following command line encoders must be available on the target system:

- Lame.exe encoder for casting in MP3 format.

- OggEnc.exe encoder for casting in OGG Vorbis format.

- FdkAac.exe encoder for casting in AAC+ format.

· If you are using the Microsoft Visual Studio "Package and Deployment Wizard" for packaging your applications, be sure that Oleaut32.dll and Olepro32.dll libraries are taken from your Windows\System32 directory: by default this wizard makes use of an outdated version of the mentioned libraries that could cause failures while registering any ActiveX control on the target system.


Product history

Product history

Version 10.1.1.0

Important note about rebuilding of the container application

In order to fix an issue that caused a parameter overflow, starting from version 9 of the control we were forced to slightly change our internal architecture.

In case your code should be using the MidiStreamEventNotification event, there may be the need to slightly change your original source code because its nMidiParam1 and nMidiParam2 parameters are now 32 bits.

New features

· Added the possibility to set the index of the next playlist's item to be executed

New methods

PlayListNextIndexSet

Version 10.1.0.0

New features

· Added the possibility to apply current audio settings of a player to an editing session of the Active Sound Editor component
· Added the possibility to modify settings of the proxy server
· Added support for composing on one single player multi-channel audio streams through the mixing of several audio files and speech texts
· Added the possibility to retrieve the index of the playlist's item currently being executed
· Added the possibility to retrieve, before starting or during playback, the table containing the execution order of shuffled playlist's items

New properties

SoundComposer (COM object)

New methods

GetPlayerHandle

PlayListCurrIndexGet

PlayListExecOrderTableGet

SetProxyConfiguration

New events

SoundComposerItemStart

SoundComposerItemDone

New COM objects

· SoundComposer

Methods

SoundComposer.SessionCreate

SoundComposer.SessionAutomaticStopWhenDoneGet

SoundComposer.SessionAutomaticStopWhenDoneSet

SoundComposer.SessionItemsCountGet

SoundComposer.SessionLoad

SoundComposer.SessionSave

SoundComposer.ItemSoundFileAdd

SoundComposer.ItemSoundFileMemoryAdd

SoundComposer.ItemSoundFileMemoryRawAdd

SoundComposer.ItemSoundFileRawAdd

SoundComposer.ItemSoundFileLoadRangeGet

SoundComposer.ItemSoundFileRawInfoGet

SoundComposer.ItemSoundFileVolumeSmoothingGet

SoundComposer.ItemSoundFileVolumeSmoothingSet

SoundComposer.ItemSpeechFromFileAdd

SoundComposer.ItemSpeechFromStringAdd

SoundComposer.ItemSpeechFileSet

SoundComposer.ItemSpeechStringSet

SoundComposer.ItemSpeechVoiceGet

SoundComposer.ItemSpeechVoiceSet

SoundComposer.ItemAmplitudeGet

SoundComposer.ItemAmplitudeSet

SoundComposer.ItemAppendNext

SoundComposer.ItemChannelGet

SoundComposer.ItemChannelSet

SoundComposer.ItemContentGet

SoundComposer.ItemFriendlyNameGet

SoundComposer.ItemFriendlyNameSet

SoundComposer.ItemInfoGet

SoundComposer.ItemIsPlaying

SoundComposer.ItemOffsetGet

SoundComposer.ItemOffsetSet

SoundComposer.ItemPlaybackPositionGet

SoundComposer.ItemRemove

SoundComposer.ItemTypeGet

SoundComposer.ItemUniqueIdGet

Version 10.0.0.0

New features

· Added support for streaming in AAC+ (HE-AAC) format when acting as a source for ShoutCAST and IceCast servers through the external encoder FdkAac.exe
· Added support for playing sound while manually scrolling through the mouse the waveform scroller
· Added support for retrieving contents of the "PRIV" frame from ID3V2 tags
· Custom stream mixers can now be created as multi-channel (up to 8 channels) and players can be attached on specific speakers of the mixer
· Custom stream mixers can now support "surround mode", meaning that a stereo or mono audio stream can be mirrored on all of the output channels of the stream mixer
· Added support for playback of Internet streams in HLS format (HTTP Live Streaming)
· Peaks displayed on the waveform visual feedback during playback are now reported to the container application through a dedicated event
· Added support for retrieving, during playback, peak levels and RMS (Root Mean Square) levels for mono, stereo and multi-channel audio streams
· Delayed playbacks can be now set through a specific date and time and not only through a delay
· Added the possibility to retrieve the buffer containing waveform's peaks from the waveform analyzer
· Added the possibility to stop the fader object

New methods

StreamMixerCreateWithSurround

StreamMixerPlayerAddToSpeaker

StreamPeakLevelsGet

DelayedPlayback.ListAddItemByDate

DelayedPlayback.ListAddItemByDateEx

Fader.Stop

TagsReader.ID3V2_PrivateFrameFileGet

TagsReader.ID3V2_PrivateFrameMemoryFileGet

TagsReader.ID3V2_PrivateFrameOwnerGet

TagsReader.ID3V2_PrivateFrameSizeGet

Waveform.PeaksBufferLengthGet

Waveform.PeaksBufferGet

WaveformScroller.PlaybackOnScrollEnable

WaveformScroller.PlaybackOnScrollInfoGet

New events

WaveformValueChange

Version 9.1.3.0

New features

· The MidiStreamEventNotification event can now receive 32 bits values for the nMidiParam1 and nMidiParam2 parameters.

Version 9.1.2.0

New features

· Added the possibility to load an Internet stream using a specific audio format, allowing a faster load when the decoder is the correct one for the given audio format
· Added the possibility to load an audio file from the Internet starting from a specific position

New methods

LoadInternetStreamEx

Version 9.1.1.0

New features

· Added the possibility to load an Internet stream using a specific audio format, allowing a faster load when the decoder is the correct one for the given audio format
· Added the possibility to load a MIDI SoundFont from a memory buffer or from a ZIP file

New methods

LoadInternetStreamWithFormat

MIDI.SoundFontInitFromMemory

MIDI.SoundFontInitFromZip

Version 9.1.0.0

New features

· Added the possibility to render input channels of an ASIO device directly to the output channels of the same device

New methods

ASIO.DeviceListenInputStart

ASIO.DeviceListenInputPause

ASIO.DeviceListenInputResume

ASIO.DeviceListenInputStop

ASIO.DeviceListenInputPlayerGet

Version 9.0.0.0

New features

· Added the possibility to load audio files directly from ZIP files with support for AES encryption/decryption
· Added basic support for ZIP files management
· New interface design for accessing special effects
· Added new special effects with multichannel support (chorus, echo, phaser, compressor, distortion, freeverb and auto-wah)

New properties

Effects (COM object)

ZIP (COM object)

New methods

LoadSoundFromZip

LoadSoundFastFromZip

LoadSoundSyncFromZip

VideoPlayer.DurationGet

VideoPlayer.PositionGet

New events

ZipOperationStart

ZipOperationPerc

ZipOperationDone

New COM objects

· Effects

Methods

Effects.AutoWahApply

Effects.AutoWahIsApplied

Effects.AutoWahReset

Effects.BassBoostApply

Effects.BassBoostIsApplied

Effects.BassBoostReset

Effects.ChannelsRemapApply

Effects.ChannelsRemapIsApplied

Effects.ChannelsRemapReset

Effects.ChorusApply

Effects.ChorusIsApplied

Effects.ChorusReset

Effects.CompressorApply

Effects.CompressorIsApplied

Effects.CompressorReset

Effects.DcOffsetRemovalEnable

Effects.DcOffsetRemovalIsEnabled

Effects.DirectXEffectApply

Effects.DirectXEffectIsApplied

Effects.DirectXEffectReset

Effects.DirectXEffectParamsGet

Effects.DirectXEffectParamsSet

Effects.DistortionApply

Effects.DistortionIsApplied

Effects.DistortionReset

Effects.EchoApply

Effects.EchoIsApplied

Effects.EchoReset

Effects.EqualizerEnable

Effects.EqualizerIsEnabled

Effects.EqualizerBandAdd

Effects.EqualizerBandGainSet

Effects.EqualizerLoadPresets

Effects.EqualizerBandCountGet

Effects.EqualizerBandParamsGet

Effects.EqualizerReset

Effects.EqualizerLoadFromFile

Effects.EqualizerSaveToFile

Effects.EqualizerBandRemove

Effects.EqualizerBandParamsSet

Effects.EqualizerBandFrequencyGet

Effects.FilterApply

Effects.FilterIsApplied

Effects.FilterReset

Effects.FilterVocalRemoverApply

Effects.FilterVocalRemoverIsApplied

Effects.FilterVocalRemoverReset

Effects.FreeverbApply

Effects.FreeverbIsApplied

Effects.FreeverbReset

Effects.MPXEnable

Effects.MPXIsEnabled

Effects.MPXSetVocalAttenuation

Effects.MPXInvertChannels

Effects.NormalizationEnable

Effects.NormalizationIsEnabled

Effects.PhaserApply

Effects.PhaserIsApplied

Effects.PhaserReset

Effects.PlaybackTempoSet

Effects.PlaybackTempoGet

Effects.PlaybackRateSet

Effects.PlaybackRateGet

Effects.PlaybackPitchSet

Effects.PlaybackPitchGet

Effects.PreAmplifierEnable

Effects.PreAmplifierIsEnabled

Effects.PreAmplifierValueGet

Effects.PreAmplifierValueSet

Effects.PreAmplifierSpeakerValueGet

Effects.PreAmplifierSpeakerValueSet

Effects.SoundDirectionEnable

Effects.SoundDirectionIsEnabled

Effects.SoundDirectionSet

Effects.SoundDirectionGet

· ZIP

Methods

ZIP.Create

ZIP.Close

ZIP.EntriesCountGet

ZIP.EntryAdd

ZIP.EntryAddFromMemory

ZIP.EntryExtractToFile

ZIP.EntryExtractToMemory

ZIP.EntryNameGet

ZIP.EntryRemove

ZIP.EntryUncompressedSizeGet

ZIP.IsProtected

ZIP.Open

ZIP.Save

Version 8.2.1.0

New features

· Added the possibility to enable the loading, through the LoadSound method, of the audio track of video clips not supported natively but supported by DirectShow installed codecs

New methods

DirectShowAutoLoadEnable

IsDirectShowLoadedFile

Version 8.2.0.0

New features

· Added support for using the video mixer in combination with the Automatic Embedded Fader
· Added support for obtaining information about volume automation points and cue points of items loaded from a PDJ playlist

New properties

Fader.CheckItemsDurationOnStart

New methods

PlayListItemVolAutomGetMixPos

PlayListItemVolAutomPointCountGet

PlayListItemVolAutomPointNameGet

PlayListItemVolAutomPointParamsGet

PlayListItemCuePointCountGet

PlayListItemCuePointGet

Version 8.1.0.0

New features

· Added support for receiving CoreAudio and CD drives related events through a callback instead of standard events

New methods

CallbackForCdDrivesEventsSet

CallbackForCoreAudioEventsSet

Version 8.0.0.0

New features

· Added support for generating various kinds of sound, like pure and monaural wave tones, binaural and multi-channel wave tones, sliding wave tones, noises, DTMF tones and text to speech strings
· Added support for displaying the On Screen Display (OSD) on the video player without the need of the video mixer
· Added support for receiving player related events through a callback instead of standard events
· Added support for loading sound files and Internet streams in OPUS sound format
· Added a new enhanced version of the spectrum analyzer with extended graphic capabilities

New properties

SoundGenerator (COM object)

SpectrumEnh (COM object)

Spectrum.UseLogarithmic

New methods

CallbackForPlayersEventsSet

VideoPlayer.OSDEnable

VideoPlayer.OSDIsEnabled

VideoPlayer.OSDKeyColorSet

VideoPlayer.OSDKeyColorGet

VideoPlayer.OSDItemBitmapAdd

VideoPlayer.OSDItemBitmapChange

VideoPlayer.OSDItemBitmapGet

VideoPlayer.OSDItemOutlineTextAdd

VideoPlayer.OSDItemOutlineTextChange

VideoPlayer.OSDItemPictureFileAdd

VideoPlayer.OSDItemPictureFileChange

VideoPlayer.OSDItemPictureMemoryAdd

VideoPlayer.OSDItemPictureMemoryChange

VideoPlayer.OSDItemRectangleAdd

VideoPlayer.OSDItemRectangleChange

VideoPlayer.OSDItemTextAdd

VideoPlayer.OSDItemTextChange

VideoPlayer.OSDItemAlphaGet

VideoPlayer.OSDItemAlphaSet

VideoPlayer.OSDItemChangeAlignment

VideoPlayer.OSDItemIsOnVisibleArea

VideoPlayer.OSDItemMove

VideoPlayer.OSDItemRectGet

VideoPlayer.OSDItemRemove

VideoPlayer.OSDItemScrollByPixels

VideoPlayer.OSDItemShow

VideoPlayer.OSDItemZOrderGet

VideoPlayer.OSDItemZOrderSet

WaveformScroller.GetViewLength

New COM objects

· SoundGenerator

Methods

SpeechVoicesNumGet

SpeechVoiceAttributeGet

StreamCreateTone

StreamCreateNoise

StreamCreateDtmfString

StreamCreateSlidingTone

StreamCreateSpeechFromString

StreamCreateSpeechFromFile

StreamCreateMultiChannelEmpty

StreamChannelAddDtmfString

StreamChannelAddNoise

StreamChannelAddSlidingTone

StreamChannelAddSpeechFromString

StreamChannelAddSpeechFromFile

StreamChannelAddTone

StreamChannelElementsCountGet

StreamChannelElementUniqueIdGet

StreamChannelEmpty

StreamChannelIsEmpty

StreamElementAmplitudeSet

StreamElementAmplitudeGet

StreamElementDtmfStringGet

StreamElementDurationGet

StreamElementNoiseTypeGet

StreamElementOffsetGet

StreamElementRemove

StreamElementSlidingToneFrequenciesGet

StreamElementSlidingToneTypeGet

StreamElementSpeechTextGet

StreamElementSpeechVoiceGet

StreamElementToneFrequencySet

StreamElementToneFrequencyGet

StreamElementToneTypeGet

StreamElementTypeGet

· SpectrumEnh

Methods

Create

SetBackPictureFromFile

SetBackPictureFromHandle

SetHwnd

Show

SettingsGeneralGet

SettingsGeneralSet

SettingsRulersGet

SettingsRulersSet

SettingsWaveGet

SettingsWaveSet

Version 7.4.5.0

New features

· Added the possibility to remove all of the existing OSD items of the video mixer through a single call to the VideoMixer.OSDItemRemove
· Added the possibility to modify, on a PDJ playlist's item which is already playing, existing volume automation points which have still not been reached by the playback position
· Added the possibility to modify, on a PDJ playlist's item which is already playing, the mixing and ending point through the already existing PlayListItemVolAutomSetMixPos method

New methods

PlayListItemVolAutomPointModify

Version 7.4.4.0

New features

· Added the possibility to load waveform peaks from a memory buffer filled with contents of a peaks file

New methods

Waveform.PeaksLoadFromMemory

Version 7.4.3.0

New features

· Added the possibility to apply a list of sound fonts as system default

New methods

MIDI.SoundFontListApplyAsDefault

Version 7.4.2.0

New features

· Added support for loading encrypted songs stored inside a memory buffer
· Improved the smoothness of volume curves during volume sliding operations and during volume automation

New methods

LoadEncryptedSoundFromMemory

LoadEncryptedSoundFromMemorySync

Version 7.4.1.0

New features

· Added support for enabling the looping of a specific sound range on a player whose playback is already started

New methods

PlaySoundEnableLoop

Version 7.4.0.0

New features

· Added support for offline decoding of the audio stream of various media formats
· Added support for taking screenshots of what is being rendered on a window of the video player
· Added support for taking screenshots of what is being rendered on the window of the video mixer

New properties

MediaFileDecoder (COM object)

New methods

VideoPlayer.ScreenshotSaveToFile

VideoMixer.ScreenshotSaveToFile

New COM objects

· MediaFileDecoder

Methods

Initialize

FileOpen

FileOpenRaw

FileClose

FileLengthGet

FileDataGet

FileDurationGet

FilePositionGet

FilePositionSet

FileChunkLengthGet

FileInfoGet

Version 7.3.0.0

New features

· Added support for downloading remote files from HTTP and FTP sites with the option to automatically load media files of supported format inside a player when download is completed

New properties

Downloader (COM object)

New events

DownloaderSessionStarted

DownloaderSessionProgress

DownloaderSessionStopped

DownloaderSessionFailed

DownloaderSessionCompleted

DownloaderSessionInvalidFile

New COM objects

· Downloader

Methods

Create

Destroy

SessionDataSizeGet

SessionStartToFile

SessionStartToMemory

SessionStartToPlayer

SessionStop

SetTimeouts

Version 7.2.0.0

New features

· Added possibility to define certain parameters used during connection to an Internet sound stream (timeouts, buffer length, FTP passive mode, etc.)
· Added possibility to invert channels of a MPX Karaoke file
· Added possibility to detect in real time silent portions of a sound stream during playback
· Added possibility to detect the initial/final silent portions and the duration of a sound file without the need to effectively load it inside a player
· Added possibility to obtain the amount of sound data that still need to be processed by a sound stream queue
· Management for MPX Karaoke audio files can be now enabled also if no sound is still loaded
· Added possibility to access loaded BASS modules
· Added possibility to access the handle to the playback stream generated by BASS, allowing to apply special effects implemented inside external BASS plugins
· Added support for loading, through external BASS plugins, audio files and Internet streams whose format is not directly supported by the multimedia engine
· Added possibility to preload MIDI sound fonts and/or MIDI samples allowing to avoid CPU spikes during playback of MIDI streams
· Added support for detecting "track", "copyright" and "instrument" markers in MIDI streams
· Added possibility to play in stereo mono streams on ASIO devices
· On Windows XP and Windows Server 2003 added possibility to access volume and mute settings on all of the available mixer's lines
· Added possibility to move the final position of a playback session without interruption of the sound flow

New methods

BassModuleGet

BassPluginStreamCreateFunc

BassStreamGet

InternetSettingsGet

InternetSettingsSet

MixerVolumeGet

MixerVolumeSet

MixerMuteGet

MixerMuteSet

MPXInvertChannels

StreamQueueBufferedDataGet

SilenceDetectionOnFile

SilenceDetectionOnPlayer

SilenceDetectionRealTimeEnable

SilenceDetectionRealTimeParamsSet

StreamVolumeLevelGet

StreamVolumeLevelSet

ASIO.DeviceMonoToStereoSet

MIDI.StreamEventApply

MIDI.StreamEventValueGet

MIDI.StreamEventsEnableNotifications

MIDI.StreamEventsEnum

MIDI.StreamEventsEnumFromRange

MIDI.StreamEventsEnumItemGet

MIDI.StreamEventsListApply

MIDI.StreamEventsListItemAdd

MIDI.StreamEventsListItemCountGet

MIDI.StreamEventsListItemGet

MIDI.StreamEventsListItemModify

MIDI.StreamEventsListItemRemove

MIDI.StreamEventsListItemUniqueIdGet

MIDI.StreamEventsRawApply

MIDI.PreloadSamples

MIDI.SoundFontLoad

MIDI.SoundFontUnload

VideoPlayer.EnableDsErrorMessages

VST.InstrumentStreamEventApply

WaveformScroller.SettingsGet

WaveformScroller.SettingsSet

WaveformScroller.SettingsParamGet

WaveformScroller.SettingsParamSet

New events

MidiStreamEventNotification

SilenceDetectionStateChange

Version 7.1.0.0

New features

· When a parameter of a VST plug-in is changed through the embedded editor, the container application is immediately notified about the index of the changed parameter and about the new value

New events

VstParamChangedValue

Version 7.0.0.0

New features

· Added support for WASAPI protocol on Windows Vista and higher versions
· Under Windows Vista and later versions, added support for sending to streaming servers, like ShoutCAST or Windows Media Services, the output of any WASAPI loopback device, allowing to stream any sound being played through an output device also if generated by external and third-party applications
· Added support for MIDI
· Added support for native x64 VST effects
· Added support for VST Instruments
· Added possibility to enumerate sample rates supported by a specific ASIO device
· Change of playback rate (audio only) can be raised up to +4000%
· Added support for a new video playback mode, based upon DirectSound, which allows a better synchronization between audio and video streams (AUDIO_RENDERER_MODE_CUSTOM_2)
· Added the possibility to change on the fly the output device of the audio stream when the selected mode is AUDIO_RENDERER_MODE_DS_STANDARD
· Added support for obtaining the aspect ratio of the video stream
· Added blacklist support for DirectShow filters
· Added support for displaying on the OSD of the video mixer a picture file loaded from a memory buffer
· Improved support for displaying PNG transparent pictures on the OSD of the video mixer without loosing original alpha layer transparency embedded inside the PNG file
· Added support for horizontally and vertically scrolling, with custom speed, any of the items on the OSD of the video mixer
· Added support for modifying brightness, contrast, saturation, hue and gamma of the loaded video clip
· Added support for showing the property page, if available, of the DirectShow filters available in the filter graph of a loaded video clip
· On x64 versions of Windows, container applications compiled specifically for x86 and container applications compiled specifically for x64 can be run at the same time without conflicts
· Added support for volume sliding and smoothing with full support for custom volume curves without the need to create a volume automation procedure
· Added support for video files in playlists managed by the internal fader
· Added support for rendering a video clip in full screen, also on a multi-monitor system
· Added support for resizing the output picture of video frames grabbed from a video clip
· Added support for custom volume curves to the embedded fader
· Added support for setting the system default audio device on Windows Vista, Windows 7 and Windows 8
· Added possibility to set the priority for DMO effects
· Added support for acting as a source for ShoutCAST version 2 servers
· Added a new user interface element for scrolling (manual or automatic) of the sound's waveform

New properties

BufferUpdateTime

MIDI (COM object)

WASAPI (COM object)

WaveformScroller (COM object)

New methods

CastingCreateFromWasapiLoopback

CastingWmaPubPointOpenFromWasapiLoopback

CastingWmaNetworkOpenFromWasapiLoopback

CastingSendMetaData

CastingSendMetaDataString

FromMsToFormattedTime

PlaybackRateRatioGet

PlayListNextIndexGet

SetDirectXEffectEx

SoundPositionGet

SoundDurationGet

SoundPositionStringGet

SoundDurationStringGet

StreamVolumeSlide

StreamVolumeSlideEx

StreamVolumeIsSliding

StreamVolumeSmoothingSet

StreamVolumeSmoothingSetEx

VideoFiltersBlacklistItemAdd

VideoFiltersBlacklistItemRemove

VideoFiltersBlacklistReset

ASIO.DeviceSampleRateCurrentGet

ASIO.DeviceSampleRateSupportedCountGet

ASIO.DeviceSampleRateSupportedGet

CoreAudioDevices.TypeGet

CoreAudioDevices.DisplaySoundApplet

CoreAudioDevices.DefaultSet

Fader.FadeInVolumeCurveSet

Fader.FadeInVolumeCurveSetEx

Fader.FadeOutVolumeCurveSet

Fader.FadeOutVolumeCurveSetEx

VideoMixer.OSDItemPictureMemoryAdd

VideoMixer.OSDItemPictureMemoryChange

VideoMixer.OSDItemBitmapGet

VideoMixer.OSDItemMovementSet

VideoMixer.OSDItemOutlineTextAdd

VideoMixer.OSDItemOutlineTextChange

VideoPlayer.AudioRendererDelayGet

VideoPlayer.AudioRendererDelaySet

VideoPlayer.GetAspectRatio

VideoPlayer.ForceWideScreen

VideoPlayer.FiltersInGraphHasPropertyPage

VideoPlayer.FiltersInGraphShowPropertyPage

VideoPlayer.FiltersInGraphGetClsid

VideoPlayer.ImageAdjustEnable

VideoPlayer.ImageAdjustIsEnabled

VideoPlayer.ImageAdjustPropertySet

VideoPlayer.ImageAdjustPropertyGet

VideoPlayer.ImageAdjustPropertyRangeGet

VideoPlayer.FrameGrabberOutputResizeSet

VideoPlayer.FullscreenMonitorCountGet

VideoPlayer.FullscreenMonitorNameGet

VideoPlayer.FullscreenMonitorPositionGet

VideoPlayer.FullscreenMonitorPredispose

VideoPlayer.FullscreenMonitorRemove

VideoPlayer.FullscreenMonitorActivate

VideoPlayer.FullscreenMonitorIsActivated

VideoPlayer.VideoTransformIsAvailable

VideoPlayer.VideoWindowChangeTarget

VST.InstrumentLoad

VST.InstrumentFree

VST.GetType

VST.InstrumentEventApply

VST.InstrumentEventRawApply

VST.EffectLoad

VST.EffectFree

VST.EffectEnable

VST.EffectFlush

Waveform.UseHalfColorForPeaks

New events

CastingWasapiLoopbackStart

CastingWasapiLoopbackStop

DisplayConfigurationChanged

MidiMarkerNotification

MidiEventNotification

MidiKeyboardNotification

PlayerDisconnected

VolumeSlideCompleted

WaveScrollerMouseNotification

WaveScrollerManualScroll

New COM objects

· WaveformScroller

Methods

Create

Show

Move

Destroy

SetDisplayLength

Refresh

SetCursor

SetBackPictureFromFile

SetBackPictureFromHandle

GetGraphicalSettings

SetGraphicalSettings

GetGraphicalSettingsParam

SetGraphicalSettingsParam

· WASAPI

Methods

AttachCaptureDeviceToPlayer

DeviceGetCount

DeviceGetDesc

DeviceStartShared

DeviceStartExclusive

DeviceStop

DeviceChannelsGet

DeviceIsStarted

DeviceLatencyGet

DeviceVolumeGet

DeviceVolumeSet

DeviceMuteGet

DeviceMuteSet

DeviceIsFormatSupported

DeviceSharedFormatGet

DeviceCoreAudioIndexGet

· MIDI

Methods

BpmGet

BpmSet

ChannelsGet

ChannelsSet

DecayModeSet

EventApply

EventsEnableNotifications

EventsEnum

EventsEnumFromRange

EventsEnumItemGet

EventsListApply

EventsListItemAdd

EventsListItemCountGet

EventsListItemGet

EventsListItemModify

EventsListItemRemove

EventsListItemUniqueIdGet

EventsRawApply

EventValueGet

KeyboardCreate

KeyboardDestroy

KeyboardNote

KeyboardRangeSet

KeyboardMove

KeyboardRefresh

KeyboardShow

KeyboardGraphicalSettingsGet

KeyboardGraphicalSettingsSet

InputDevicesCountGet

InputDevicesEnum

InputDevicesInfoGet

InputDevicesStart

InputDevicesStartOnPlayer

InputDevicesStop

MarkersEnableNotifications

MarkersEnum

MarkersEnumItemGet

PulsesPerQuarterNoteGet

SeekToPosition

SoundDurationGet

SoundFontApply

SoundFontDefaultConfigGet

SoundFontDefaultGet

SoundFontDefaultSet

SoundFontFree

SoundFontInit

SoundFontInfoStringGet

SoundFontInfoNumGet

SoundFontsInStreamEnum

SoundFontsInStreamItemGet

SoundFontListApply

SoundFontListItemAdd

SoundFontListItemCountGet

SoundFontListItemRemove

SoundFontListItemUniqueIdGet

SoundFontPresetDescGet

SoundFontVolumeGet

SoundFontVolumeSet

SoundPositionGet

StreamQueueStart

StreamQueueStop

TempoPercGet

TempoPercSet

TrackCountGet

TrackTagsEnum

TrackTagsItemGet

TrackVolumeGet

TrackVolumeSet

TriggerAdd

TriggerSetPos

VoicesDefaultGet

VoicesDefaultSet

VoicesGet

VoicesSet

Important change affecting backward compatibility when dealing with DirectSound drivers

Till version 5.x of the component, the StreamVolumeLevelSet method was used to set the volume directly on the DirectSound buffer used for performing playback, allowing a smaller latency on volume changes. Starting from version 6.0 of the component, the volume set through this method no more applies to the DirectSound buffer directly but only to the internal volume-related DSP used for volume sliding purposes, so the volume change will be affected by the DirectSound latency.

In order to continue setting the volume directly on the DirectSound buffer as seen for versions till 5.x, you should change your existing source code and use the new StreamVolumeDirectSoundBufferSet method in place of the StreamVolumeLevelSet method.

Version 6.1.0.0

New features

· Added support for vocal remover filter
· Improved support for getting information about Audio CDs from the Amazon store
· Added the possibility to enable/disable the equalizer in one single shot

New methods

AmazonStoreCdInfoCreate

AmazonStoreCdInfoGet

AmazonStoreCdCoverPictureFileGet

AmazonStoreCdNavigateToUrl

AmazonStoreCdTrackTitleGet

EqualizerEnable

FilterVocalRemoverApply

FilterVocalRemoverReset

GraphicBarsManager.SetFlatBorder

Version 6.0.0.0

New features

· Inside the embedded fader, possibility to set a target level for the volume of the player fading-in
· Frames grabbing from video clips
· Support for switching the audio stream of video clips
· Support for loading, for volume curve designer and waveform analyzer, a background picture in one of the following formats: BMP, GIF, PNG, JPEG, TIFF
· Support for saving the view of the waveform inside a picture file in one of the following formats: BMP, GIF, PNG, JPEG, TIFF
· Support for retrieving CDDB text information in UTF-8 format
· Under Windows Vista and higher versions support for managing audio endpoints (CoreAudio):

* Support for enumerating and managing audio endpoints

* Possibility to control volume and mute and to display Vu-Meters for each channel of each render or capture device.

* If available inside the driver, support for accessing the "Mic Boost" setting of capture devices.

* If available inside the driver, possibility to be notified when the status of a "jack-sensing aware" channel changes.

· Real-time DC Offset removal
· Support for reading most common frames of the following tag formats: ID3V1, ID3V2.2, ID3V2.3, ID3V2.4, LYRICS3, WMA, APE, OGG Vorbis, MP4, FLAC
· Support for reading the following frames of the ID3V2 tag format (others may be added upon request): TIT1, TIT2, TIT3, TALB, TOAL, TRCK, TPOS, TSST, TSRC, TPE1, TPE2, TPE3, TPE4, TOPE, TEXT, TOLY, TCOM, TMCL, TIPL, TENC, TBPM, TLEN, TKEY, TLAN, TCON, TFLT, TMED, TMOO, TCOP, TPRO, TPUB, TOWN, TRSN, TRSO, TOFN, TDLY, TDEN, TDOR, TDRC, TDRL, TDTG, TSSE, TSOA, TSOP, TSOT, WCOM, WCOP, WOAF, WOAR, WOAS, WORS, WPAY, WPUB, COMM, APIC, USLT, SYLT, ETCO, GEOB, MCDI, COMR, OWNE, POPM, PCNT, TXXX, WXXX, USER.
· Support for reading CART, BEXT and LIST INFO chunks in WAV files
· Support for opening filenames with UNICODE characters
· VideoMixer.OSDItemTextAdd and VideoMixer.OSDItemTextChange methods can now accept UNICODE characters
· Support for displaying Unicode-aware "common dialogs" from environments not supporting Unicode pathnames directly (like VB6)
· Support for setting the amount of buffer that must be filled before starting playback of Internet streams
· Support for obtaining the HWND of the video player windows and of the video mixer window
· Added possibility to get/set the decoder for video formats managed by FFDSHOW
· Support for retrieving the CD identifier for querying Microsoft's servers, for querying MusicBrainz's server and for obtaining the UPC code of the album
· Support for drawing the waveform representation inside a graphical device context (HDC) allowing the rendering of a scrolling waveform during playback

New properties

CoreAudioDevices (COM Object)

TagsReader (COM Object)

New methods

CommonDialogShowOpen

CommonDialogShowSave

CommonDialogGetInfoFromLastOpen

CommonDialogGetInfoFromLastSave

DcOffsetRemovalEnable

Fader.FadeInTargetVolumeGet

Fader.FadeInTargetVolumeSet

GetMp3BitrateType

GetInternetBufferLength

SetInternetBufferLength

SetSmoothingTimeOnSeekOps

VideoFiltersBlacklistDisable

VideoFiltersFfdShowIsAvailable

VideoFiltersFfdShowDecoderGet

VideoFiltersFfdShowDecoderSet

VideoPlayer.AudioMultiStreamCheck

VideoPlayer.AudioMultiStreamGetCount

VideoPlayer.AudioMultiStreamGetName

VideoPlayer.AudioMultiStreamSelect

VideoPlayer.FrameGrabberInit

VideoPlayer.FrameGrabberExit

VideoPlayer.FrameGrabberExecToFile

VideoPlayer.FrameGrabberExecToMemory

VideoPlayer.FrameGrabberResultsGetAvailableType

VideoPlayer.FrameGrabberResultsGetPixelColor

VideoPlayer.FrameGrabberResultsGetBitmapsCount

VideoPlayer.FrameGrabberResultsGetBitmap

VideoPlayer.FrameGrabberResultsGetFilesCount

VideoPlayer.FrameGrabberResultsGetFilePathname

VideoPlayer.VideoWindowGetHWND

VideoMixer.GetHWND

Waveform.BitmapViewSaveToFile

Waveform.BitmapViewSaveToMemory

Waveform.BitmapViewDrawToHdc

Waveform.BitmapViewVerticalLineAdd

Waveform.BitmapViewVerticalLineRemove

Waveform.BitmapViewGetWidth

New events

CdCoverURLsAvailableEx

CdCoverPictureFileAvailableEx

CoreAudioDeviceStateChanged

CoreAudioDeviceAdded

CoreAudioDeviceRemoved

CoreAudioDefaultDeviceChanged

CoreAudioVolumeChange

CoreAudioDeviceVuMeterChange

New COM objects

· CoreAudioDevices

Methods

Enum

Free

CapturePartChannelCountGet

CapturePartChannelVolumeGet

CapturePartChannelVolumeSet

CountGet

DescGet

DefaultGet

ChannelCountGet

ChannelVolumeGet

ChannelVolumeSet

JackCountGet

JackDescriptorGet

MasterVolumeGet

MasterVolumeSet

MicBoostChannelCountGet

MicBoostChannelLevelGet

MicBoostChannelLevelSet

MuteGet

MuteSet

RenderPartChannelCountGet

RenderPartChannelVolumeGet

RenderPartChannelVolumeSet

RenderPartMuteGet

RenderPartMuteSet

StatusGet

VuMeterMasterPeakValueGet

VuMeterChannelPeakValueGet

VuMeterEnableNotifications

· TagsReader

Methods

ALL_AnalyzeSoundOnPlayer

ALL_AnalyzeSoundFile

ALL_CommonFrameGet

APE_TextFieldGet

APE_UserFieldGet

APE_UniqueFramesCountGet

APE_UniqueFramesIdGet

FLAC_UniqueFramesCountGet

FLAC_UniqueFramesIdGet

FLAC_TextFrameGet

FLAC_PictureFrameInfoGet

FLAC_PictureFrameTypeGet

FLAC_PictureFrameSizeGet

FLAC_PictureFrameBitmapGet

FLAC_PictureFrameFileGet

FLAC_PictureFrameMemoryFileGet

FLAC_PictureFrameCountGet

ID3V1_FieldGet

ID3V2_FrameCountGet

ID3V2_TextFrameGet

ID3V2_URLFrameGet

ID3V2_PictureFrameInfoGet

ID3V2_PictureFrameTypeGet

ID3V2_PictureFrameSizeGet

ID3V2_PictureFrameBitmapGet

ID3V2_PictureFrameFileGet

ID3V2_PictureFrameMemoryFileGet

ID3V2_CommentFrameGet

ID3V2_CommentFrameInfoGet

ID3V2_UnsynchLyricsFrameGet

ID3V2_UnsynchLyricsFrameInfoGet

ID3V2_SynchLyricsFrameGet

ID3V2_SynchLyricsFrameInfoGet

ID3V2_SynchLyricsFrameInfoNumGet

ID3V2_EventTimingsFrameEventCountGet

ID3V2_EventTimingsFrameEventInfoGet

ID3V2_GeneralObjectFrameSizeGet

ID3V2_GeneralObjectFrameInfoGet

ID3V2_GeneralObjectFrameFileGet

ID3V2_GeneralObjectFrameMemoryFileGet

ID3V2_MusicCdIdentifierFrameSizeGet

ID3V2_MusicCdIdentifierFrameGet

ID3V2_CommercialFrameInfoGet

ID3V2_CommercialFrameReceivedAsGet

ID3V2_CommercialFramePictureSizeGet

ID3V2_CommercialFramePictureBitmapGet

ID3V2_CommercialFramePictureFileGet

ID3V2_CommercialFramePictureMemoryFileGet

ID3V2_OwnershipFrameInfoGet

ID3V2_PopularimeterFrameEmailGet

ID3V2_PopularimeterFrameRatingGet

ID3V2_PopularimeterFrameCounterGet

ID3V2_PlayCounterFrameCountGet

ID3V2_UserTextFrameGet

ID3V2_UserTextFrameDescriptionGet

ID3V2_UserURLFrameGet

ID3V2_UserURLFrameDescriptionGet

ID3V2_TermsOfUseFrameGet

ID3V2_TermsOfUseFrameLanguageGet

ID3V2_UniqueFramesCountGet

ID3V2_UniqueFramesIdGet

LYRICS3_TextFieldGet

LYRICS3_LyricsGet

LYRICS3_ImageLinkGet

MP4_UniqueFramesCountGet

MP4_UniqueFramesIdGet

MP4_TextFrameGet

MP4_PictureFrameMimeGet

MP4_PictureFrameSizeGet

MP4_PictureFrameBitmapGet

MP4_PictureFrameFileGet

MP4_PictureFrameMemoryFileGet

MP4_PictureFrameCountGet

OGG_UniqueFramesCountGet

OGG_UniqueFramesIdGet

OGG_TextFrameGet

OGG_UserFrameGet

WAV_CartChunkTextFieldGet

WAV_CartChunkTimeMarkerFieldGet

WAV_BextChunkTextFieldGet

WAV_BextChunkBinaryFieldGet

WAV_ListInfoChunkFrameGet

WAV_ListInfoChunkUniqueFramesCountGet

WAV_ListInfoChunkUniqueFramesIdGet

WMA_UniqueFramesCountGet

WMA_UniqueFramesIdGet

WMA_TextFrameGet

WMA_PictureFrameInfoGet

WMA_PictureFrameTypeGet

WMA_PictureFrameSizeGet

WMA_PictureFrameBitmapGet

WMA_PictureFrameFileGet

WMA_PictureFrameMemoryFileGet

WMA_PictureFrameCountGet

Version 5.6.0.0

New features

· Added support for managing all entries inside a playlist stored inside a web server and loaded through the LoadInternetStream method: nested playlists are supported as well
· After loading with success an Internet stream and after catching the StreamLoaded event, it's now possible to retrieve the exact URL of the Internet stream through the GetLoadedSoundFile method; if the loaded stream should be an item of an Internet playlist, the new StreamLoadedFromInetPlaylist event would report the exact URL.

New events

StreamLoadedFromInetPlaylist

Version 5.5.0.0

New features

· Added possibility to manually resize visual feedbacks: useful when a resize of the hosting window occurs

New methods

Oscilloscope.Resize

Spectrum.Resize

VUMeter.Resize

Waveform.Resize

Version 5.4.0.0

New features

· Added support for playback with floating point quality for files encoded with floating point quality or with a resolution higher than 16 bits per sample
· Improved support for managing sound files in WMA Professional format

New methods

GetWmaCodecString

Version 5.3.0.0

New features

· Added looping capabilities to video playback

New methods

VideoPlayer.PlayRangeWithLoop

VideoPlayer.PlayRangeDisableLoop

PlaySoundDisableLoop

Version 5.2.0.0

New features

· Added support for compilation with "Any CPU" on x64 versions of Windows

Version 5.1.0.0

New features

· Possibility to be notified when the connection to an Internet stream begins
· Possibility to be notified about the buffering advancement when connecting to an Internet stream
· Added a new implementation of the PDJ playlist format, allowing its usage with encrypted songs without fader features: this allows its usage with the embedded fader

New methods

GetSoundOriginalDuration

GetFormattedSoundOriginalDuration

New events

DownloadPercentage

StreamConnecting

Version 5.0.0.0

New features

· Possibility, through custom stream mixers, to mix songs at application level, allowing to save mixing results through the integration with our Active Sound Recorder control or to send mixing results to a streaming server; the output of each stream mixer allows applying special effects like visual feedbacks, output change, volume change, preamplifier, equalizer, DMO, etc.
· Support for ASIO drivers with the possibility to directly playback the sound stream coming from ASIO input channels of the sound card
· Support for acting as a source for ShoutCAST, IceCast and Windows Media Services streaming servers
· Support for sending sound in WMA format to a specific network port
· Reduced latency when playing the sound coming from a an input channel opened by Active Sound Recorder
· Support for configurable normalization of sound level
· Equalizer bands can now be set for frequencies under 80 Hz
· Support for video mixing/blending
· Audio management for playback of video clips totally rewritten, allowing to play the audio track through ASIO drivers
· Mixing/blending of video clips inside a video mixer output window, with support for separate preview windows
· Support for customizable On-Screen-Display (OSD) on the video mixer window
· Video clips can be rendered on more than one output window in perfect sync
· Latency between audio and video tracks of video clips can be now configured
· Support for loading a video clip from a memory buffer
· If allowed by the DirectShow codec, possibility to proceed by steps inside a video clip
· Possibility to obtain further information about loaded video clips, like codecs used for audio and video streams and number of "frames per second"
· Support for volume automation with possibility to design volume curves
· Support for new proprietary playlist format (PDJ), allowing to predispose mixing automation and volume automation on each single song and to play encrypted sounds
· Support for video files inside playlists
· Support for ALAC, Speex, Musepack e Monkey's Audio (APE) audio formats
· Support for reading BEXT and CART chunks in WAV files
· Most common tags (author, title, album, year and genre) can be retrieved for ID3V1, ID3V2, WMA, Ogg, APE and MP4 tags
· Knowing artist and album title, possibility to retrieve the purchase page for the related CD from the Amazon store
· Knowing artist and track title, possibility to online retrieve lyrics content
· VU-Meter can now reflect volume changes
· Support for stream queuing, allowing to play sound streams coming from an external source
· Support for common filters (low-pass, high-pass, band-pass and stop-band)
· The number of spectrum bands can be now defined in the range 8-64
· Support for extraction of the audio track available inside a video clip, allowing to perform silence detection, BPM detection and waveform analysis

New properties

ASIO (COM Object)

VideoMixer (COM Object)

VolumeAutomation (COM Object)

New methods

AudioExtensionAdd

CastingIsActive

CastingCreateFromStreamMixer

CastingCreateFromPlayer

CastingStart

CastingStop

CastingSetTitle

CastingGetXmlStatistics

CastingWmaPubPointOpenForStreamMixer

CastingWmaPubPointOpenForPlayer

CastingWmaNetworkOpenForStreamMixer

CastingWmaNetworkOpenForPlayer

CastingWmaSetTag

CastingWmaGetInfo

CastingWmaConnectedIPGetCount

CastingWmaConnectedIPGetDesc

CdNavigateToPurchasePage

CuePointsGetName

DetectSoundSilence

GetFileTagField

GetOutputDeviceDriverType

GetSampleRate

SetSampleRate

GetWavChunkBinaryInfo

GetWavChunkNumericInfo

GetWavChunkStringInfo

HwMixingEnable

HwMixingIsSupported

FilterApply

FilterReset

InitDriversType

IsWavChunkAvailable

LoadSoundFastFromMemory

LoadSoundFromMemorySync

NormalizationEnable

PlayListAddItemWithTag

PlayListCreateAutomation

PlayListSaveAutomation

PlayListStop

PlayListItemVolAutomSetMixPos

PlayListItemVolAutomPointAdd

PlayListItemVolAutomPointRemove

PlayListItemCuePointAdd

PlayListItemCuePointRemove

PlaySoundFromRecorderEx

SoundLyricsRequest

SoundLyricsGet

Spectrum.SetNumberOfBands

StreamMixerCreate

StreamMixerPlayerAdd

StreamMixerPlayerRemove

StreamVolumeGet

StreamVolumeSet

StreamBalanceGet

StreamBalanceSet

StreamOutputDeviceGet

StreamOutputDeviceSet

StreamOutputSpeakerGet

StreamOutputSpeakerSet

StreamOutputSpeakerSwap

StreamOutputSpeakersRearAndCenterSwap

StreamMixerGetIdFromOutput

StreamQueueCreate

StreamQueuePushData

VideoPlayer.AudioDelaySet

VideoPlayer.AudioDelayGet

VideoPlayer.IsVideoStreamAvailable

VideoPlayer.IsAudioStreamAvailable

VideoPlayer.Forward

VideoPlayer.Rewind

VideoPlayer.VideoWindowAdd

VideoPlayer.VideoWindowMove

VideoPlayer.VideoWindowShow

VideoPlayer.AudioTrackExtract

VideoPlayer.AudioTrackExtractAbort

VideoPlayer.AudioTrackGetMemoryPtr

VideoPlayer.AudioTrackGetMemorySize

VideoPlayer.AudioTrackGetTempFilePathname

VideoPlayer.AudioTrackGetTempFileSize

VideoPlayer.AudioTrackFree

VideoPlayer.AudioRendererModeSet

VideoPlayer.AudioRendererModeGet

VideoPlayer.AudioRendererDsDeviceGetCount

VideoPlayer.AudioRendererDsDeviceGetDesc

VideoPlayer.AudioRendererDsDeviceSet

VideoPlayer.AudioRendererDsDeviceGet

VideoPlayer.IsDirectShowAvail

VideoPlayer.VideoStreamSendToActiveMovieWin

VideoPlayer.AttachToVideoMixer

VideoPlayer.DetachFromVideoMixer

VideoPlayer.VideoStreamKeepAspectRatio

VideoPlayer.SeekToNextFrame

VideoPlayer.SeekToPreviousFrame

VideoPlayer.FramesNumberGet

VideoPlayer.FramesAverageRateGet

VideoPlayer.CodecVideoDescGet

VideoPlayer.CodecAudioDescGet

VideoPlayer.FiltersInGraphGetCount

VideoPlayer.FiltersInGraphGetName

VideoPlayer.LoadFromMemory

VideoPlayer.LoadFromMemoryForEAX

VideoPlayer.LoadFromMemoryForTempoChange

VideoPlayer.LoadFromMemorySync

VideoPlayer.LoadFromMemorySyncForEAX

VideoPlayer.LoadFromMemorySyncForTempoChange

VuMeter.KeepCountOfVolume

WmaBitrateCount

WmaBitrateGet

New events

AudioExtractFromVideoStart

AudioExtractFromVideoPerc

AudioExtractFromVideoDone

CastingPlayerDone

CastingPlayerPerc

CastingPlayerStart

CastingStreamMixerStart

CastingStreamMixerStop

PlaylistSoundLoaded

SoundLyricsAvailable

StreamQueueStalled

VolumeAutomationLoaded

VolumeAutomationPointReached

VolumeCurveDesignerChanged

WaveAnalysisDone

WmaNetworkClientConnect

New COM objects

· VolumeAutomation

Properties

CurveDesigner

PositionUnit

ScaleType

Methods

Load

IsSliding

PointAdd

PointEnable

PointGetCount

PointGetName

PointGetNext

PointGetParams

PointIsEnabled

PointRemove

PointSetParams

Reset

Save

· CurveDesigner

Methods

Create

Destroy

DisplayCurveType

GetGraphicalSettings

GetPoints

Move

Refresh

SetBackPictureFromFile

SetBackPictureFromHandle

SetGraphicalSettings

Show

SetPoints

· ASIO

Methods

AttachInputChannelToPlayer

ControlPanelDisplay

DeviceChannelVolumeGet

DeviceChannelVolumeSet

DeviceGetChannelsCount

DeviceGetChannelDesc

DeviceGetCount

DeviceGetDesc

DeviceGetDriverPathname

DeviceGetIndexFromOutput

DeviceGetOutputIndex

DeviceIsStarted

DeviceLatencyGet

DeviceMasterVolumeGet

DeviceMasterVolumeSet

DeviceStart

DeviceStop

PlayerOutputChannelSet

PlayerOutputChannelGet

· VideoMixer

Methods

BackgroundColorSet

Create

Destroy

Move

PlayerAlphaGet

PlayerAlphaSet

PlayerNormalizedRectGet

PlayerNormalizedRectSet

PlayerNormalizedRectSetIdeal

PlayerZOrderGet

PlayerZOrderSet

OSDBackgroundBitmapSet

OSDBackgroundPictureFileSet

OSDEnable

OSDIsEnabled

OSDItemAlphaGet

OSDItemAlphaSet

OSDItemBitmapAdd

OSDItemBitmapChange

OSDItemChangeAlignment

OSDItemIsOnVisibleArea

OSDItemMove

OSDItemNormalizedRectGet

OSDItemPictureFileAdd

OSDItemPictureFileChange

OSDItemRemove

OSDItemRectangleAdd

OSDItemRectangleChange

OSDItemScrollByPixels

OSDItemShow

OSDItemTextAdd

OSDItemTextChange

OSDItemZOrderGet

OSDItemZOrderSet

OSDKeyColorGet

OSDKeyCOlorSet

OSDNormalizedRectGet

OSDNormalizedRectSet

Reset

Show

Version 4.3.0.0

New methods

SetNetAgent

VideoPlayer.LoadSync

VideoPlayer.LoadSyncForEAX

VideoPlayer.LoadSyncForTempoChange

Fixed bugs

See the technical support page

Version 4.2.0.0

New methods

GetPitchFloat

SetPitchFloat

Fixed bugs

See the technical support page

Version 4.1.0.0

New methods

GetPlaybackTime

GetPlaybackTimeString

Fixed bugs

See the technical support page

Version 4.0.0.0

New features

· Reverse playback
· Support for Karaoke MPX files
· Availability of spectrum bands values for custom graphics
· Pre-amplification (as seen in WinAmp)
· Improved support for creating custom equalizers with more than 50 bands
· Automatic equalization for each file loaded through custom XML equalization files
· Equalizer bands can now be set for frequencies lower than 80 Hz
· Horizontal and vertical graphic bars for custom rendering of VU-Meter, spectrum and progress bars
· Video playback through DirectShow with support for audio effects on the audio track of video clips
· Custom DSP (Digital Signal Processing) management
· Support for VST effects
· Sound card availability is no more required for performing waveform analysis
· Various settings (volume, pitch, tempo, etc.) can now be set without the need to load a sound
· Added support for background pictures on visual feedbacks
· Beats detection
· Support for WPL playlists
· Support for Internet streams in M3U, PLS and ASX formats
· More control on the loading of long playlists through dedicated events for start, percentage and stop detection
· Possibility to load a single playlist into a fader object (previous versions required that each involved player had an already loaded playlist)
· Possibility to load a playlist file or the whole content of a directory into a loaded playlist
· Improved triggers management
· Cue points management, also through external XML files which can be loaded automatically for each loaded song
· Support for delayed playback: a song is loaded and scheduled for playback after a defined time-slice
· Support for lyrics synchronization through LRC files
· Support for new sound formats: W64, AU, PAF, SVX, NIST, VOC, IRCAM, PVF and CAF
· Support for RAW formats (PCM and Dialogic VOX)
· Support for saving into a file peaks obtained from an analysis of the sound’s waveform

New properties

CustomDSP (COM object)

DelayedPlayback (COM object)

EnableAutoEqualiz

EnableMixingFeatures

GraphicBarsManager (COM object)

VideoPlayer (COM object)

VST (COM object)

New methods

BeatsDetectEnableRT

BeatsDetectGetBeatPos

BeatsDetectGetBeatsCount

BeatsDetectGetParams

BeatsDetectRequest

BeatsDetectSetParams

BeatsDetectSetRange

CdRequestAlbumInfo

CuePointsAdd

CuePointsEnable

CuePointsGetCount

CuePointsGetPos

CuePointsIsEnabled

CuePointsLoadFromFile

CuePointsRemove

CuePointsSaveToFile

CuePointsSetPos

EqualizerBandAdd

EqualizerBandGetFrequency

EqualizerBandGetParams

EqualizerBandRemove

EqualizerBandSetParams

EqualizerReset

EqualizerBandGetCount

EqualizerBandSetGain

EqualizerLoadFromFile

EqualizerLoadPresets

EnableCdTracksPrebuff

Fader.Display.SetBackPictureFromFile

Fader.Display.SetBackPictureFromHandle

Fader.PlayListUseSingle

GetBitsPerSample

GetCdTrackDurationMs

GetCurrentPercentageFloat

GetFormattedSoundFileDuration

GetLoadedSoundFile

GetPlayerSpeaker

GetSoundFileDuration

LoadSoundFromEditingSession

LoadSoundFromRawFile

LoadSoundFromRawMemory

LrcIdTagGet

LrcLoad

LrcNotifEnableGet

LrcNotifEnableSet

LrcNotifTimingsGet

LrcNotifTimingsSet

LrcTimeTagsSimpleGetAt

LrcTimeTagsSimpleGetCount

LrcTimeTagsEnhGetAt

LrcTimeTagsEnhGetCount

MixerGetCount

MixerGetDesc

MixerGetMasterMute

MixerGetMasterVolume

MixerGetMicrophoneMute

MixerGetMicrophoneVolume

MixerGetWaveMute

MixerGetWaveVolume

MixerSetMasterMute

MixerSetMasterVolume

MixerSetMicrophoneMute

MixerSetMicrophoneVolume

MixerSetWaveMute

MixerSetWaveVolume

MPXEnable

MPXSetVocalAttenuation

Oscilloscope.SetBackPictureFromFile

Oscilloscope.SetBackPictureFromHandle

PlayListAddItemEx

PlayListLoadSync

PreamplifierEnable

PreAmplifierGetSpeakerValue

PreamplifierGetValue

PreAmplifierSetSpeakerValue

PreamplifierSetValue

ResetControl

ResetEngine

SoundDirectionEnable

SoundDirectionGet

SoundDirectionSet

Spectrum.GetTable

Spectrum.SetBackPictureFromFile

Spectrum.SetBackPictureFromHandle

TriggersAdd

TriggersEnable

TriggersGetCount

TriggersGetPos

TriggersIsEnabled

TriggersRemove

TriggersSetPos

VUMeter.SetBackPictureFromFile

VUMeter.SetBackPictureFromHandle

Waveform.PeaksLoad

Waveform.PeaksSave

Waveform.SetBackPictureFromFile

Waveform.SetBackPictureFromHandle

New events

BeatsAvailableOffline

BeatDetectedRealTime

CuePointReached

CuePointsLoaded

EqualizerLoaded

LrcAdvanceTimeLineFull

LrcFileAvailable

LrcRealTimeLineFull

LrcRealTimeLinePortion

PlayListLoadDone

PlayListLoadPerc

PlayListLoadStart

SoundDurationChanged

SpectrumValueChange

VstParamChanged

VstEditorResized

WarnNoOutputDevice

New COM objects

· CustomDSPs

Methods

Enable

ExternalEditorGetInfo

ExternalEditorShow

ExternalGetParameters

ExternalLoad

ExternalSendCommand

ExternalSetFunction

ExternalSetParameters

Free

InternalLoad

InternalSetFunction

UseFloatSamples

· GraphicBarsManager

Methods

Create

Destroy

GetGraphicalSettings

GetGraphicalSettingsParam

GetRange

GetValue

Move

Refresh

SetGraphicalSettings

SetGraphicalSettingsParam

SetRange

SetValue

Show

· DelayedPlayback

Properties

AllowOverlapping

Methods

ItemGetDuration

ItemGetFadeTime

ItemGetLoopCount

ItemGetRange

ItemPlayNow

ItemResetDelay

ItemSetFadeTime

ItemSetLoopCount

ItemSetRange

ListAddItem

ListAddItemEx

ListGetCount

ListRemoveItem

· VideoPlayer

Methods

Close

Create

IsSeekable

GetDuration

GetNativeSize

GetPosition

Load

LoadForEAX

Move

Pause

Play

PlayRange

Resume

Seek

Show

Stop

· VST

Methods

EditorGetInfo

EditorMove

EditorShow

Enable

Flush

Free

GetInfo

GetInfoString

Load

ProgramGetCurrent

ProgramNameGet

ProgramNameSet

ProgramParamGetDefaultValue

ProgramParamGetInfo

ProgramParamGetValue

ProgramParamSetValue

ProgramSetCurrent

ProgramsGetCount

Version 3.5.0.0

New methods

GetOutputDeviceUniqueID

Version 3.4.0.0

New features

The waveform analysis can now be aborted

New methods

Waveform.AnalyzeAbort

Version 3.3.0.0

New methods

GetCdTrackDurationMs

EnableCdTracksPrebuff

Fixed bugs

See the technical support page

Version 3.2.0.0

New methods

GetTempoPerc

GetRatePerc

GetPitch

Fixed bugs

See the technical support page

Version 3.1.0.0

New properties

Oscilloscope.Type

Oscilloscope.ZoomPerc

Spectrum.ZoomPerc

VUMeter.ZoomPerc

Fixed bugs

See the technical support page

Version 3.0.0.0

New features

· Support for looping a certain sound or portions of it.
· Smoothing on PlaySound call
· Detection of silent portions at the start and end of the sound
· Support for the following formats: AIFF, FLAC, AAC, MP4 (sound only), AC3, Wavpack, ALAC
· Support for multi-channel songs in the following formats: WAV, AIFF, OGG e WMA
· Possibility to load songs encrypted using the CryptSound™ application
· Multi-speakers management (Stereo, Quadraphonic, 5.1 and 7.1)
· Waveform analysis and generation of sized bitmap views of the whole waveform or portions of it
· Export of a loaded sound in WAV format
· Support for Internet streams loading and playback
· EAX special effects
· Better integration with the Active Sound Recorder ActiveX control
· Support for retrieving CDDB information from FreeDb servers
· Support for retrieving CD cover pictures from Amazon Web Services

New properties

EnableSpeakers

New methods

CddbGetAlbumInfo

CddbGetTrackTitle

CddbGetServerName

CddbRequestAlbumInfo

CddbRequestServersList

CddbSetProxyDetails

CopyExportedWavToMemory

ForceSpeakersAssignment

GetCdCoverPictureFile

GetCdCoverPictureURL

GetControlVersion

GetEAXEffect

GetEAXEffectWetDryMix

GetEngineVersion

GetForwardRewindGranularity

GetMaxAvailablePlayers

GetOutputSpeakersConfig

GetOutputSpeakersCount

GetPlayerOutputDevice

GetPlayerSpeakersCount

IsEaxAvailable

IsEaxAvailableOnOutputDevice

LoadEncryptedSound

LoadInternetStream

LoadSoundForEAX

LoadSoundFromRecordingSession

LoadSoundInMono

LoadSoundSync

PlaySoundFromRecorder

PlaySoundLoop

PlaySoundRange

PlaySoundRangeLoop

RequestSilenceDetection

RequestSoundExportToWav

SetAutomaticSilenceDetection

SetEAXEffect

SetEAXEffectPresets

SetEAXEffectWetDryMix

SetForwardRewindGranularity

SetOutputSpeakersConfig

SetPlayerSpeaker

SetSmoothingTimeLength

StopSoundFromRecorder

SwapPlayersSpeakers

SwapSpeakersRearAndCenter

Waveform.AnalyzeFullSound

Waveform.CreateFileBitmapView

Waveform.CreateMemoryBitmapView

Waveform.GetBitmapViewWidth

New events

CdCoverPictureFileAvailable

CdCoverURLsAvailable

CddbAlbumInfoAvailable

CddbServersListAvailable

CdReadTrackPercentage

CdReadTrackStart

CdReadTrackStop

DownloadBuffering

DownloadComplete

ExportToWavPerc

ExportToWavStart

ExportToWavStop

MetaTagChanged

PlayListSoundLoadFailure

PlayListStreamLoaded

RangeLoopDone

ServerClosed

SilencePosAvailable

SoundSyncLoaded

StreamLoaded

WaveAnalysisStart

WaveAnalysisPerc

WaveAnalysisStop

Version 2.5.0.0

New methods

PlayListCreateSpeed

Fixed bugs

See the technical support page

Version 2.4.0.0

New features

In order to avoid locking problems with old CD drivers, the CD monitoring is now disabled by default: use the EnableCdMonitor method to enable it back..

Version 2.3.0.1

New features

Reintroduced the LoadSoundFast method for MP3 files.

New methods

LoadSoundFast

Fixed bugs

See the technical support page

Version 2.3.0.0

New features

Added the possibility to disable the monitoring of the status of the available CD drives: this will enable other applications to access CD drives, with outdated device drivers, that don't allow multiple-access.

New methods

EnableCdMonitor

Fixed bugs

See the technical support page

Version 2.2.0.0

New features

Added support for DirectX Media Objects

New methods

GetDirectXEffect

GetDirectXEffectParams

SetDirectXEffect

SetDirectXEffectParams

SetRewindOnEOF

Fixed bugs

See the technical support page

Version 2.1.0.0

New features

· Added compatibility with Borland Delphi and Borland C++ Builder
· Added support for changing the DirectSound buffer length for a better control over output devices latency

New Properties

BufferLength

CheckOutputDevicesLatency

New methods

GetOutputDeviceLatency

GetOutputDeviceMinBufferLength

Fixed bugs

See the technical support page

Version 2.0.0.0 - Changed the product name from Active MP3 DJ Studio to Active DJ Studio

New features

· Added the possibility of choosing and changing the output device during playback
· Added support for the following sound formats: WAV, OGG Vorbis, WMA (requires Windows Media components installed), MOD, MTM, S3M, XM, IT and MO3
· Added support for Audio CD operations and for Audio CD tracks playback
· Added support for Audio CD identification retrieval
· Added support for sound files stored in memory
· Added support for changing Tempo, Playback rate and Pitch of the loaded sound
· Added automatic BPM detection of the loaded sound
· Improved support for visual feedbacks through an "object oriented" approach
· Added Waveform visual feedback
· Added support for creating an automatic Fader
· Added support for triggers

New Properties

VUMeter

Spectrum

Oscilloscope

Waveform

Fader

LastError

New methods

SetTempoPerc

SetRatePerc

SetPitch

GetFormattedTime

GetUpdatedSoundDuration

GetUpdatedFormattedSoundDuration

IsDirectX8Avail

SetEqualizerBand

SetEqualizerBandGain

SetAutomaticBPM

RequestSoundBPM

SetPlayerVolumeEx

AddTrigger

RemoveTrigger

GetCdDrivesCount

GetCdDriveDesc

GetCdDriveLetter

PlayListLoadFromCd

LoadTrackFromCd

PerformActionOnCd

GetCdStatus

GetCdIdentification

GetCdNumTracks

GetCdTrackDuration

GetCdTrackPathname

CloseSound

ReadSoundInfo

IsTagAvailable

GetTagString

GetMp3Tag2Size

GetMp3Tag2Data

GetFileType

GetChannels

GetFrequency

LoadSoundFromMemory

GetPlayerVolume

GetPlayerVolumeEx

IsWmaAvailable

New events

SoundClosed

PlayListSoundLoaded

OutputDeviceChanged

DurationChanged

BPMAvailable

FadingVolumeChanged

FadingPointReached

FadeInStarted

FadeInCompleted

FadeOutStarted

FadeOutCompleted

TriggerReached

CdPlayerStatusChanged


Deprecated elements

Deprecated elements

With respect to previous versions of the control some of the control's methods have been deprecated. These obsolete methods should not be used in new development projects. They have been maintained internally for backward compatibility only and they will not be documented here nor supported in the future. Furthermore, these obsolete elements will not be displayed by Intellisense and, in Visual C++, will not be inserted inside the wrapper class.

The following is the full list of obsolete properties and methods with the current alternative you should use from now on.

Old property, method or event name | Current alternative
SetPriority (1) | Dropped: with the latest internal changes this property is not needed
PlayerUseDirectSound (1) | Dropped: with the latest internal changes this property is not needed
GetMp3StreamTypeFrequency (1) | GetFrequency method
GetMp3StreamTypeChannels (1) | GetChannels method
SetSoundPitch (1) | Effects.PlaybackRateSet method
CreateFeedbacks (1) | VUMeter.Create, Spectrum.Create, Oscilloscope.Create methods
SetVUMeter (1) | see VUMeter object properties
SetSpectrum (1) | see Spectrum object properties
SetOscilloscope (1) | see Oscilloscope object properties
ShowVUMeter (1) | VUMeter.Show method
ShowSpectrum (1) | Spectrum.Show method
ShowOscilloscope (1) | Oscilloscope.Show method
SetEqualizerValues (1) | Effects.EqualizerBandAdd and EqualizerBandSetGain methods combination
ForwRewGranularityType (2) | GetForwardRewindGranularity and SetForwardRewindGranularity methods
ForwRewGranularity (2) | GetForwardRewindGranularity and SetForwardRewindGranularity methods
PlaySoundFromTo (2) | PlaySoundRange and PlaySoundRangeLoop methods
GetUpdatedSoundDuration (2) | SoundDurationGet method
GetUpdatedFormattedSoundDuration (2) | SoundDurationStringGet method
Waveform.Resolution (2) | Waveform.UpdateResolution property
SetEqualizerBand (3) | Effects.EqualizerBandAdd method
SetEqualizerBandGain (3) | Effects.EqualizerBandGainSet method
SetMixerMasterVolume (3) | MixerVolumeSet with nComponentType parameter set to COMPONENTTYPE_DST_SPEAKERS
GetMixerMasterVolume (3) | MixerVolumeGet with nComponentType parameter set to COMPONENTTYPE_DST_SPEAKERS
SetMixerWaveVolume (3) | MixerVolumeSet with nComponentType parameter set to COMPONENTTYPE_SRC_WAVEOUT
GetMixerWaveVolume (3) | MixerVolumeGet with nComponentType parameter set to COMPONENTTYPE_SRC_WAVEOUT
GetMixersCount (3) | MixerGetCount method
GetMixerDesc (3) | MixerGetDesc method
GetSpectrumTable (3) | Spectrum.GetTable method
AddTrigger (3) | TriggersAdd method
RemoveTrigger (3) | TriggersRemove method
DurationChanged event (3) | SoundDurationChanged event (the returned duration expressed in seconds in now in floating point)
GetPlayerVolume (4) | StreamVolumeLevelGet method
SetPlayerVolume (4) | StreamVolumeLevelSet method
GetPlayerVolumeEx (4) | StreamVolumeLevelGet method
SetPlayerVolumeEx (4) | StreamVolumeLevelSet method
SetPlayerBalance (4) | StreamBalanceSet method
GetPlayerOutputDevice (4) | StreamOutputDeviceGet method
SetPlayerOutputDevice (4) | StreamOutputDeviceSet method
GetPlayerSpeaker (4) | StreamOutputSpeakerGet method
SetPlayerSpeaker (4) | StreamOutputSpeakerSet method
SwapPlayersSpeakers (4) | StreamOutputSpeakerSwap method
SwapSpeakersRearAndCenter (4) | StreamOutputSpeakersRearAndCenterSwap method
GetMp3Tag1Field (4) | GetFileTagField method
PlaySoundFromRecorder (4) | PlaySoundFromRecorderEx method
WaveAnalysisStop (4) | WaveAnalysisDone event
VideoPlayer.Create (4) | VideoPlayer.VideoWindowAdd method
VideoPlayer.Move (4) | VideoPlayer.VideoWindowMove method
VideoPlayer.Show (4) | VideoPlayer.VideoWindowShow method
Waveform.CreateFileBitmapView (5) | Waveform.BitmapViewSaveToFile
Waveform.CreateMemoryBitmapView (5) | Waveform.BitmapViewSaveToMemory
Waveform.GetBitmapViewWidth (5) | Waveform.BitmapViewGetWidth
CdCoverURLsAvailable event (5) | CdCoverURLsAvailableEx event
CdCoverPictureFileAvailable event (5) | CdCoverPictureFileAvailableEx event
GetFormattedTime (6) | FromMsToFormattedTime method
GetCurrentPos (6) | SoundPositionGet method
GetPlaybackTime (6) | SoundPositionGet method
GetSoundDuration (6) | SoundDurationGet method
GetSoundOriginalDuration (6) | SoundDurationGet method
GetCurrentPosString (6) | SoundPositionStringGet method
GetPlaybackTimeString (6) | SoundPositionStringGet method
GetFormattedSoundDuration (6) | SoundDurationStringGet method
GetFormattedSoundOriginalDuration (6) | SoundDurationStringGet method
SetSmoothingTimeLength (6) | StreamVolumeSmoothingSet and StreamVolumeSmoothingSetEx methods
VST.Load (6) | VST.EffectLoad method
VST.Free (6) | VST.EffectFree method
VST.Enable (6) | VST.EffectEnable method
VST.Flush (6) | VST.EffectFlush method
VideoPlayer.AudioDelayGet (6) | VideoPlayer.AudioRendererDelayGet method
VideoPlayer.AudioDelaySet (6) | VideoPlayer.AudioRendererDelaySet method
VstParamChanged event (6) | VstParamChangedValue method
GetInternetBufferLength (7) | InternetSettingsGet method with nSetting parameter set to INET_SETTING_BUFFER_LENGTH
SetInternetBufferLength (7) | InternetSettingsSet method with nSetting parameter set to INET_SETTING_BUFFER_LENGTH
StreamVolumeGet (7) | StreamVolumeLevelGet method
StreamVolumeSet (7) | StreamVolumeLevelSet method
DetectSoundSilence (7) | SilenceDetectionOnPlayer method
SetAutomaticSilenceDetection (7) | SilenceDetectionOnPlayerLoadAutoSet method
RequestSoundSilenceDetection (7) | SilenceDetectionOnPlayerRequest method
MixerSetMasterVolume (7) | MixerVolumeSet with nComponentType parameter set to COMPONENTTYPE_DST_SPEAKERS
MixerGetMasterVolume (7) | MixerVolumeGet with nComponentType parameter set to COMPONENTTYPE_DST_SPEAKERS
MixerSetWaveVolume (7) | MixerVolumeSet with nComponentType parameter set to COMPONENTTYPE_SRC_WAVEOUT
MixerGetWaveVolume (7) | MixerVolumeGet with nComponentType parameter set to COMPONENTTYPE_SRC_WAVEOUT
MixerSetMasterMute (7) | MixerMuteSet with nComponentType parameter set to COMPONENTTYPE_DST_SPEAKERS
MixerGetMasterMute (7) | MixerMuteGet with nComponentType parameter set to COMPONENTTYPE_DST_SPEAKERS
MixerSetWaveMute (7) | MixerMuteSet with nComponentType parameter set to COMPONENTTYPE_SRC_WAVEOUT
MixerGetWaveMute (7) | MixerMuteGet with nComponentType parameter set to COMPONENTTYPE_SRC_WAVEOUT
MixerSetMicrophoneVolume (7) | MixerVolumeSet with nComponentType parameter set to COMPONENTTYPE_SRC_MICROPHONE
MixerGetMicrophoneVolume (7) | MixerVolumeGet with nComponentType parameter set to COMPONENTTYPE_SRC_MICROPHONE
MixerSetMicrophoneMute (7) | MixerMuteSet with nComponentType parameter set to COMPONENTTYPE_SRC_MICROPHONE
MixerGetMicrophoneMute (7) | MixerMuteGet with nComponentType parameter set to COMPONENTTYPE_SRC_MICROPHONE
WaveformScroller.GetGraphicalSettings (7) | WaveformScroller.SettingsGet method
WaveformScroller.SetGraphicalSettings (7) | WaveformScroller.SettingsSet method
WaveformScroller.GetGraphicalSettingsParam (7) | WaveformScroller.SettingsParamGet method
WaveformScroller.SetGraphicalSettingsParam (7) | WaveformScroller.SettingsParamSet method
MIDI.EventApply (7) | StreamEventApply method
MIDI.EventValueGet (7) | StreamEventValueGet method
MIDI.EventsEnableNotifications (7) | StreamEventsEnableNotifications method
MIDI.EventsEnum (7) | StreamEventsEnum method
MIDI.EventsEnumFromRange (7) | StreamEventsEnumFromRange method
MIDI.EventsEnumItemGet (7) | StreamEventsEnumItemGet method
MIDI.EventsListApply (7) | StreamEventsListApply method
MIDI.EventsListItemAdd (7) | StreamEventsListItemAdd method
MIDI.EventsListItemCountGet (7) | StreamEventsListItemCountGet method
MIDI.EventsListItemGet (7) | StreamEventsListItemGet method
MIDI.EventsListItemModify (7) | StreamEventsListItemModify method
MIDI.EventsListItemRemove (7) | StreamEventsListItemRemove method
MIDI.EventsListItemUniqueIdGet (7) | StreamEventsListItemUniqueIdGet method
MIDI.EventsRawApply (7) | StreamEventsRawApply method
MidiEventNotification (7) | MidiStreamEventNotification event
SetTempoPerc (9) | Effects.PlaybackTempoSet method
GetTempoPerc (9) | Effects.PlaybackTempoGet method
SetRatePerc (9) | Effects.PlaybackRateSet method
GetRatePerc (9) | Effects.PlaybackRateGet method
SetPitch (9) | Effects.PlaybackPitchSet method
GetPitch (9) | Effects.PlaybackPitchGet method
SetPitchFloat (9) | Effects.PlaybackPitchSet method
GetPitchFloat (9) | Effects.PlaybackPitchGet method
PlaybackRateRatioGet (9) | Effects.PlaybackRateRatioGet method
GetDirectXEffect (9) | Effects.DirectXEffectIsApplied method
SetDirectXEffect (9) | Effects.DirectXEffectApply method
SetDirectXEffectEx (9) | Effects.DirectXEffectApply method
GetDirectXEffectParams (9) | Effects.DirectXEffectParamsGet method
SetDirectXEffectParams (9) | Effects.DirectXEffectParamsSet method
MPXEnable (9) | Effects.MPXEnable method
MPXSetVocalAttenuation (9) | Effects.MPXSetVocalAttenuation method
MPXInvertChannels (9) | Effects.MPXInvertChannels method
SoundDirectionEnable (9) | Effects.SoundDirectionEnable method
SoundDirectionGet (9) | Effects.SoundDirectionGet method
SoundDirectionSet (9) | Effects.SoundDirectionSet method
PreAmplifierEnable (9) | Effects.PreAmplifierEnable method
PreAmplifierGetValue (9) | Effects.PreAmplifierValueGet method
PreAmplifierSetValue (9) | Effects.PreAmplifierValueSet method
PreAmplifierGetSpeakerValue (9) | Effects.PreAmplifierSpeakerValueGet method
PreAmplifierSetSpeakerValue (9) | Effects.PreAmplifierSpeakerValueSet method
EqualizerBandAdd (9) | Effects.EqualizerBandAdd method
EqualizerBandRemove (9) | Effects.EqualizerBandRemove method
EqualizerBandSetGain (9) | Effects.EqualizerBandGainSet method
EqualizerLoadPresets (9) | Effects.EqualizerLoadPresets method
EqualizerBandGetCount (9) | Effects.EqualizerBandCountGet method
EqualizerBandGetParams (9) | Effects.EqualizerBandParamsGet method
EqualizerBandSetParams (9) | Effects.EqualizerBandParamsSet method
EqualizerReset (9) | Effects.EqualizerReset method
EqualizerEnable (9) | Effects.EqualizerEnable method
EqualizerBandGetFrequency (9) | Effects.EqualizerBandFrequencyGet method
EqualizerLoadFromFile (9) | Effects.EqualizerLoadFromFile method
EqualizerSaveToFile (9) | Effects.EqualizerSaveToFile method
FilterApply (9) | Effects.FilterApply method
FilterReset (9) | Effects.FilterReset method
NormalizationEnable (9) | Effects.NormalizationEnable method
DcOffsetRemovalEnable (9) | Effects.DcOffsetRemovalEnable method
FilterVocalRemoverApply (9) | Effects.FilterVocalRemoverApply method
FilterVocalRemoverReset (9) | Effects.FilterVocalRemoverReset method
VideoPlayer.GetDuration (9) | VideoPlayer.DurationGet method
VideoPlayer.GetPosition (9) | VideoPlayer.PositionGet method
LoadInternetStreamWithFormat (10) | LoadInternetStreamEx method

(1) Deprecated starting from version 2

(2) Deprecated starting from version 3

(3) Deprecated starting from version 4

(4) Deprecated starting from version 5

(5) Deprecated starting from version 6

(6) Deprecated starting from version 7

(7) Deprecated starting from version 7.2

(9) Deprecated starting from version 9

(10) Deprecated starting from version 9.1.2.0


How to contact MultiMedia Soft

How to contact MultiMedia Soft

Apart from the quality of our products, one of our strongest points is a superior customer support: we always answer technical questions, sent through our Contact us web page, within the first 24 hours also on Saturday and on Sunday.

Through our web site

Contact page

http://www.multimediasoft.com/contact/

Forum

http://www.multimediasoft.com/forum

Through Postal address:

MultiMedia Soft

Strada Pelizzina 21

10081 Castellamonte (TO)

Italy

Through Telephone:

+39 0124 640005 Number provided for Italian speaking only: in order to avoid language misunderstandings, no phone support is available in languages different from Italian so, in order to submit your questions in English, please, fill the form provided on our contact page or, in alternative, use our forum.

Through Fax:

+39 0124 233112758

+39 02 700433430


How to report bugs to technical support

How to report bugs to our technical support

If you should experience problems using the control, you are encouraged to contact our customer support specifying the following topics:

· Operating system (Windows XP, Vista, 7, etc.) and version
· Name, Release and Version of the programming environment (e.g. Visual Basic 6 SP5 or Visual Studio.NET 2008).
· If needed, create a log file generated by the Microsoft's DxDiag.exe application and send it to us for evaluation.
· If possible, prepare a little project that reproduces the problem on your system: being able to reproduce the problem on our systems will speed up the problem solution.
· An accurate description of the steps to reproduce the issue.

We will try to solve the problem as soon as possible and, if required, we will inform you when the fixed control will be available.


Tutorials

Tutorials

How to install the control on your development PC

How to add the control to your projects

Adding the control to a project

Adding the control to a Visual Basic 6 project

Adding the control to a Visual C++ 6 project

Adding the control to a Visual Studio.NET project

How to use the control in your projects

How to synchronize the container application with the control

How to use the control inside a web page

How to deal with multi-player features

How to work with single songs and video clips

How to access settings of audio devices in Windows Vista and later versions

How to work with multiple output devices and speakers

How to manage audio flow through WASAPI

How to manage ASIO drivers

How to create and manage a playlist

How to use the Automatic Fader

How to use custom Stream Mixers

How to play video files through DirectShow

How to render video clips in full screen

How to grab frames from video files

How to use the video mixer

How to combine the video mixer and the automatic fader

How to deal with MIDI protocol

How to manage Volume Automation

How to create custom volume curves

How to use the embedded Visual Feedbacks

How to use the Enhanced Spectrum Analyzer

How to perform custom feedbacks rendering using graphic bars

How to obtain the sound's waveform

How to scroll the sound's waveform during playback

How to mix your songs

How to use the control as a source for streaming servers like SHOUTcast

How to create and use an Equalizer

How to apply special effects to a playing sound

How to manage custom DSP effects

How to manage VST effects

How to detect beats positions and BPM

How to add Triggers and Cue Points to a player

How to retrieve information about loaded songs

How to read TAG information in sound files

How to retrieve basic TAG information from the sound loaded into a player

How to deal with latency

How to play Internet streams and radio stations

How to protect your music through encryption

How to export the loaded song into a WAV file

How to load and play sounds recorded by Active Sound Recorder

How to get Audio CD info using CDDB servers and Amazon catalogue

How to get pictures of CD covers

How to manage delayed playbacks

How to manage lyrics coming from LRC files

How to manage Unicode characters in filenames and tags

How to access BASS library functionalities directly

How to detect silent portions of sound files

How to manage download sessions

How to decode media files

How to generate wave tones, noises, DTMF tones and text to speech

How to manage ZIP files

How to use Mnemonic Constants


How to install the control on your development PC

How to install the control on your development PC

This product has been developed for use with programming environments that support ActiveX custom controls: each development environment uses a different procedure in order to add an ActiveX control to a project so, if you need to add this control to your project, refer to the development environment documentation.

In order to install this product on your system, follow the steps listed below:

· Be sure to exit any application currently running on your system
· Launch the downloaded amp3dj.exe (amp3dj_t.exe for the trial version) file and follow the contained instructions.
· Once the setup package has installed all the needed files, it will automatically register our ActiveX control inside the system registry of your PC
· From now on you will be able to add the control to your projects. For details about inserting the control into a project, take a look to the Adding the control to a project section.


Adding the control to a project

Adding the control to a project

Each development environment has its own procedure in order to add an ActiveX control to the project under development. Here follows a small summary of procedures needed in order to add our control to projects developed using some of the most diffused Microsoft environments.

· Visual Basic 6
· Visual C++ 6
· Visual Studio.NET


Adding the control to a Visual Basic 6 project

Adding the control to a Visual Basic 6 project

Find below required steps:

· Open the project you are working on
· Choose the "Project/Components" menu item
· From the "Controls" tab, check the "Active DJ Studio ActiveX Control" element as seen in the screenshot below:

· Once the control has been inserted inside the project, the following icon should appear inside your development environment toolbox

· Now you can select the control icon inside the toolbox and drag it into the container form; the following icon will appear on the form (note that this icon will be invisible at runtime)

· Note that you can add more than one instance of the control but the total of the allocated players cannot exceed the maximum number available for the purchased edition.
· You can now start developing your code around the control as described inside the How to use the control in your projects section


Adding the control to a Visual C++ 6 project

Adding the control to a Visual C++ 6 project

Find below required steps:

· Open the project you are working on
· Choose the "Project/Add To Project/Components and Controls..." menu item
· From the "Components and Controls Gallery" select the "Registered ActiveX controls" folder
· From the "Components and Controls Gallery", select the "Active DJ Studio Control" element as seen in the screenshot below and press the Insert button

· Press the "OK" button on the message box and dialog box that will appear.

· Now press the "Close" button of the "Components and Controls Gallery" that will take you again to your project working area
· Once the control has been inserted inside the project, the following icon should appear inside your development environment toolbox

· Now you can select the control icon inside the toolbox and drag it into the dialog box under editing; the following icon will appear on the dialog box (note that this icon will be invisible at runtime)

· Note that you can add more than one instance of the control but the total of the allocated players cannot exceed the maximum number available for the purchased edition.
· You can now start developing your code around the control as described inside the How to use the control in your projects section.


Adding the control to a Visual Studio.NET project

Adding the control to a Visual Studio.NET project

First of all, if you are developing a Winform based application inside Visual Studio.NET, we strongly suggest you evaluating our .NET native component Audio DJ Studio for .NET

That said, here follow the steps required to add this ActiveX control to a .NET project:

· Open the project you are working on
· If not already visible, open the Toolbox of Visual Studio.NET.
· Right click the mouse button over the Toolbox surface.
· Select the "Add/Remove Items..." menu item (if still using Visual Studio.NET 2002 use the "Customize Toolbox..." menu item); this will open the "Customize Toolbox" dialog box.
· Select the "COM components" tab
· Between the installed COM components find the component named "Active DJ Studio Control" as displayed below

· Pressing the "OK" button will bring you again to your project working area
· Once the control has been inserted inside the project, the following icon should appear inside your toolbox

· Now you can select the control icon inside the toolbox and drag it into the dialog box under editing; the following icon will appear on the dialog box (note that this icon will be invisible at runtime) and two references to the control will be automatically added to the "References" section of the Project

· Note that you can add more than one instance of the control but the total of the allocated players cannot exceed the maximum number available for the purchased edition.
· You can now start developing your code around the control as described inside the How to use the control in your projects section

Using the control inside Microsoft Visual C++.NET with MFC

The use of ActiveX controls within projects developed using Visual C++.NET and MFC creates particular issues users must be aware of: as for Visual C++ 6.0, ActiveX controls require wrapper classes in order to be used in this environment. Usually these wrapper classes should be generated automatically by the development environment through a dedicated wizard but, due to a bug inside Visual C++.NET (2003, 2005 and 2008), wrapper classes will result incomplete when dealing with ActiveX controls that, in order to maintain backward compatibility, alternates identifiers of properties and methods. For this reason our control comes with its already generated C++ wrapper classes, installed by the setup package inside the "wrappers\cpp.net" directory (by default the complete path should be "C:\Program Files\Active DJ Studio\wrappers\cpp.net").

This issue implies to perform some manual action when creating a variable associated to the control:

· Dragging the control's icon from the Toolbox, insert an instance of Active DJ Studio inside the container dialog box
· Copy wrapper files contained inside the "C:\Program Files\Active DJ Studio\wrappers\cpp.net" into your project directory:
· Add the just mentioned wrapper files to your project.
· Open the header file of the dialog box class (supposing that our application's name will be TestApp the header file will be named TestAppDlg.h)
· Insert the following includes:

#include "amp3dj.h"

· Inside the CTestAppDlg class, declare a variable of type CAmp3dj that will represent the control in your code:

CAmp3dj      m_djStudio;

· In case you should need using any of the available COM objects inside your code, add the related wrapper file; if for example you should need accessing the Spectrum COM object you will have to add the following line of code:

#include "Spectrum.h"

· Open the source file of the dialog class TestAppDlg.cpp
· Search the CTestAppDlg::DoDataExchange override function and insert the following code (here we assume that the development environment will assign the identifier IDC_AMP3DJCTRL1 to the control):

DDX_Control(pDX, IDC_ACTIVESOUNDAMP3DJCTRL1, m_djStudio);

· Just for testing purposes, search the CTestAppDlg::OnInitDialog handler function and insert the following code:

m_djStudio.InitDJSystem (2, (long) GetSafeHwnd (), 0, 0, 0, 0);

m_djStudio.AboutBox ();

· Now compile and run the project: you will see the control's about box displayed before showing the main dialog box of the application.


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 currently 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 (or to the alternative InitDJSystemEx method); the best place to call this initialization 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 handler function of the WM_INITDIALOG Windows message.

Important note

All of our audio-related components share the same instance of the multimedia engine AdjMmsEng.dll or AdjMmsEng64.dll whose initialization/disposal requires a certain amount of time because it needs to negotiate with the underlying Windows multimedia system and the sound card drivers: this operation, depending upon the system and quality of sound card drivers in use, may require some second.

In order to obtain a better efficiency when instancing the component on multiple container forms within the same application, it would be highly recommended hosting and initializing, through the InitDJSystem method, an instance of the component inside a form that will stay alive for the full life of the container application, for example the application's main form: although this instance of the component may stay hidden and may never be used, the memory footprint would be in any case irrelevant but it would keep the multimedia engine alive, allowing a faster loading/disposal when the container form is closed/opened.

Purposes of calling the InitDJSystem methods are the following:

· synchronizing the control with its container form
· deciding how many players (*), also known as "virtual decks", will be allocated
· choosing 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. The current output device can be changed at any time using the StreamOutputDeviceSet method: this features is very useful if you need a monitor output for your headphones. For further details about the Multi-player management, take a look to the How to deal with multi-player features section.

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):

· Directly to DirectSound
· Through the use of an external encoder (Lame.exe for MP3, Fdkaac.exe for AAC+, OggEnc.exe for Ogg Vorbis), to a Shoutcast or Icecast server: in this case the control behaves as a Shoutcast/Icecast source.
· In combination with our Active Sound Recorder control, directly to an output file whose format can be predisposed inside Active Sound Recorder itself.

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, Fdkaac.exe for AAC+, 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:

· If you want to work with single sound files see the How to work with single songs and video clips tutorial.
· If you prefer to work with playlists see the How to create and manage a playlist tutorial.

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.

MixerVolumeSet/MixerVolumeGet to set/get the volume of a system mixer

MixerMuteSet/MixerMuteGet to set/get the mute state of a system mixer

When dealing with Windows Vista and higher versions, mixers can be managed more easily through the usage of the CoreAudioDevices object: see the How to access settings of audio devices in Windows Vista and later versions tutorial for further information about this feature.

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:

StreamVolumeLevelSet to set the volume on the given player

StreamVolumeSlide and StreamVolumeSlideEx to start a volume sliding on the given player

StreamBalanceSet to set the balance on the given player

Effects.PlaybackTempoSet to set the tempo on the given player

Effects.PlaybackRateSet to set the playback rate on the given player

Effects.PlaybackPitchSet to set the pitch on the given player

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:

SoundDurationGet to know the duration of a song expressed in number of milliseconds

SoundDurationStringGet to know the duration of a song expressed with a formatted string (HH:MM:SS:MsMsMs)

SoundPositionGet to know the current position of a playing song expressed in a chosen unit

SoundPositionStringGet 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:

Fader

Visual feedback: you can give to the listener a customizable visual feedback of the songs being played through the embedded VU-Meter, Spectrum Analyser, Oscilloscope andWaveform display:

VUMeter

Spectrum

Oscilloscope

Waveform

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: refer to the "Events" chapter of this documentation 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.


How to synchronize the container application with the control

How to synchronize the container application with the control

Return to chapter overview

Some method available inside Active DJ Studio performs lengthy operations which, on a single-threaded environment, could block the user interface of the container application also for several seconds: just think about the time requested to perform the waveform analysis for a song longer than 5 minutes and you will perfectly understand that this operation couldn't be completed in less than one second.

In order to avoid this kind of blocks, the control performs lengthy operations inside secondary threads; the main side effect of this multithreaded approach is the fact that, when the method call returns, the requested operation could still be running in the background so requested data wouldn't be already available and any method call trying to access data would fail by returning an error code; for this reason it's very important that the container application synchronizes itself with events fired by the control.

Just to make a practical example, let's take the mentioned waveform's analysis calculation for having a better understanding of the issue: the container application requests the calculation of the sound's waveform through a call to the Waveform.AnalyzeFullSound method; when this method returns, the waveform is still being calculated in background and the container application will be notified about calculation advancement through the following events:

· WaveAnalysisStart : this event is generated immediately before starting the secondary calculation thread; the container application could catch it in order to display a hidden progress bar that could be used to notify the user about the analysis advancement.
· WaveAnalysisPerc : this event is generated during the calculation; the container application could catch it in order to modify the mentioned progress bar value
· WaveAnalysisDone : this event is generated immediately before closing the secondary thread; the container application could catch it in order to hide back the progress bar and, eventually, to display a message to the user

After receiving the last event, the container application could request further operations with the calculated waveform, for example it could request to obtain the bitmap representation of the waveform through a call to the Waveform.BitmapViewSaveToFile method: it's very important to remember that a call to a method of a certain ActiveX control should be never performed from within a management function of an event generated by the same ActiveX control: this is usually cause of errors and dead-lock situations and it's a practice that should be always avoided; the best approach in cases like this would be using the WaveAnalysisDone event to trigger a one shot-timer and to call the Waveform.BitmapViewSaveToFile method from within the management function of the timer's event.

As a further suggestion, keep management functions of events generated by the component as fast/short as possible and never use them in order to display messages or dialog boxes which require user interaction.


How to use the control inside a web page

How to use the control inside a web page

Active DJ Studio is marked as "safe for scripting" and "safe for initialization" so it can be inserted and used from within a HTML web page. As you may know, the technique for adding ActiveX controls inside HTML code is the use of the <OBJECT> tag as displayed on the following HTML code:

<OBJECT id="Amp3dj1"

classid="clsid:6F714D46-E4EF-11D4-93EF-00D0D7032099"

width="1" height="1"

style="visibility:hidden">

</OBJECT>

Obviously the code above will not work if the control is not already installed and registered on the client machine; in order to download, install and register the control on a client machine, you will need to modify the code in the following way (observe text in red color):

<OBJECT id="Amp3dj1"

classid="clsid:6F714D46-E4EF-11D4-93EF-00D0D7032099"

codebase="http://yourserver/amp3dj.cab"

width="1" height="1" style="visibility:hidden">

</OBJECT>

the "codebase" attribute is used in order to determinate the remote location of the control's CAB file which contains the Amp3dj.ocx control and the needed dependencies: this CAB file (digitally signed) is not included with the original installation package and can be requested by registered customer contacting our support team.

Through the "codebase" attribute it's also possible managing control's versioning: in this way, in case the client PC should already contain an outdated version of the control, the browser could request to re-download and re-install the CAB file containing the latest version of the control. Versioning can be managed modifying the OBJECT tag like this (observe text in red color):

<OBJECT id="Amp3dj1"

classid="clsid:6F714D46-E4EF-11D4-93EF-00D0D7032099"

codebase="http://yourserver/amp3dj.cab#Version=5,0,0,0"

width="1" height="1" style="visibility:hidden">

</OBJECT>

It's important to note that the Amp3dj.ocx control requires a runtime license so, in order to let it work inside a web page, you will have to embed the LPK license file inside the HTML code as described below:

<OBJECT CLASSID="clsid:5220CB21-C88D-11cf-B347-00AA00A28331">

 <PARAM NAME="LPKPath" VALUE="amp3dj.lpk">

</OBJECT>

it's mandatory that the <OBJECT> tag above, containing the LPK file, must be inserted inside the HTML code BEFORE any other <OBJECT> tag.

Due to the fact that only one LPK object can be embedded inside the HTML code, if you should need using more than one ActiveX control inside your page, you will have to create a LPK file including all of them. Details about creation of LPK files can be found on the Microsoft web site. If you are a registered user and if you should need assistance in creating the LPK file, feel free to contact our support team.

How to set/modify control's properties

The <OBJECT> tag we used earlier sets the value of the control's properties to their default. How do we go about setting them to a different 'default' value at design-time? The answer is to add a <PARAM> tag to the code. The example below sets the EnableSpeakers value to 1, which means that the speakers assignment will be enabled.

<OBJECT id="Amp3dj1"

classid="clsid:6F714D46-E4EF-11D4-93EF-00D0D7032099"

codebase="http://yourserver/amp3dj.cab"

width="1" height="1" style="visibility:hidden">

<param name="EnableSpeakers" value="0">

</OBJECT>

Control's properties can be also modified at runtime through scripting (Javascript, VBScript, ecc.) like in the example below:

<script language="javascript">

// enable speakers assignment

Amp3dj1.EnableSpeakers = 1;

</script>

How to call control's methods

Due to the fact that this specific control doesn't have a user interface, web pages will have to interact with him through scripting: supposing that you have an initialization routine for your web page, it should look like the following one:

<script language="javascript">

function Init ()

{

try

{

  // allocate one player on the default sound card

Amp3dj1.InitDJSystem (1, 0, 0, 0, 0, 0);

}

catch (e)

{

  // probably the control is still not installed: this function will be called again

  // after the control installation so we can exit right now

  return;

}

// enable speakers assignment

Amp3dj1.EnableSpeakers = 1;

}

</script>

The try/catch block is quite useful in order to avoid annoying warning messages caused by the script being executed before the control is fully downloaded/installed.

How to handle control's events

During a playback session, you could have the need to handle events fired by the control: catching events is quite straight-forward and, in Javascript, you can use a way like this:

<script FOR="Amp3dj1" EVENT="SoundLoaded(nPlayer, nItemIndex)">

 EventSoundLoaded (nPlayer, nItemIndex);

</script>

The code above will catch the SoundLoaded event and will call the specific function that will perform the needed actions, like displaying the control's status or enabling some button on the web page's user interface:

function EventSoundLoaded (nPlayer, nItemIndex)

{

 document.getElementById ("Play").disabled = false;

 document.getElementById ("Stop").disabled = false;

}

How to display visual feedbacks on a web page

As you may know, graphical features embedded inside the control need to rely on an existing window control and on its surface in order to perform graphical rendering; when the control is inserted inside a form or inside a dialog box, the only task you have to perform is to add a picture control and to "connect" to its window handle; with web pages this is quite more difficult because HTML elements don't expose their window handle; for this reason we have created a further very small OCX control to add to your web pages with the purpose of performing graphical rendering on its surface.

This new control is named MmsGraphSurface.ocx and is installed and registered with our product's setup package for immediate usage. This control is very basic and exposes the following properties and methods:

BackColor property: the color used to render the graphical surface (default is set to Black)

hWnd property: the control's window handle (also known as HWND); this property (read-only) is used to connect the graphical control to the recorder control

SetBackgroundImage method: allows setting a background image, in form of a Windows bitmaps handle (also known as HBITMAP), that will be rendered on the control's surface

The graphical control can be instanced inside HTML using the following code:

<OBJECT id="GraphSurfaceForVuMeter"

     classid="clsid:1C671DB5-E86A-4951-BD4E-0E4D0F7F4248"

     width="50" height="100" style="visibility:hidden" >

   <param name="BackColor" value="0">

</OBJECT>

Obviously you can add more than one instance of the control depending upon the number of graphical rendering you need to obtain.

At this point you can start using the graphical surface of this control connecting it to the recorder control in a way like this:

function CreateVuMeter ()

{

     // create the embedded Vu-Meter

     Amp3dj1.VuMeter.Create (GraphSurfaceForVuMeter.hWnd);

     Amp3dj1.VuMeter.Show (1);

}

or, if you need to display the static bitmap of the recorded sound's waveform, after having completed the waveform analysis, in a way like this:

<OBJECT id="GraphSurfaceForWaveform"

     classid="clsid:1C671DB5-E86A-4951-BD4E-0E4D0F7F4248"

     width="500" height="250" style="visibility:hidden" >

   <param name="BackColor" value="0">

</OBJECT>

function DisplaySoundWaveform ()

{

     // get the dimensions of the display surface

     m_width = document.getElementById ("GraphSurfaceForWaveform").offsetWidth;

     m_height = document.getElementById ("GraphSurfaceForWaveform").offsetHeight;

     // obtain and display the full sound's waveform

     var hBitmap = Amp3dj1.Waveform.BitmapViewSaveToMemory  (0, 0, -1, m_width, m_height, 2);

     GraphSurfaceForWaveform.SetBackgroundImage (hBitmap);

}

If you want to see a basic web page with some real coding, graphical rendering and waveform analysis, you can follow this link to our test page.

Another sample web page, simulating a sort of Internet Radio, is available on the following link.


How to deal with multi-player features

How to deal with multi-player features

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.

The number of players allocated by a single control instance is defined using the nTotalPlayers parameter of the InitDJSystem method.

A couple of possible questions:

· "In order to define the player output device, the InitDjSystem method supports only four parameters: what happens if I have the Deluxe edition and I set the nTotalPlayers parameter to 6?"

In this case the 4 nOutputX parameters will define the output device for players 0, 1, 2 and 3 (players are zero-based) while players 4 and 5 will automatically output to the system default sound card. Output device for players 4 and 5 can be changed at a later time using the StreamOutputDeviceSet method. An alternative approach would be instantiating 2 controls, the first one allocating 4 players and the second one allocating 2 players.

· "If I need to allocate 12 players, how can I set for each of them a specific output device?"

In this case you need to allocate on your form 3 separate instances of the control, each of them calling the respective InitDJSystem method and each of them setting the nTotalPlayers parameter to 4 (3 * 4 = 12). In this way each of the instanced control will have the possibility to assign to each allocated player the respective output device.


How to work with single songs and video clips

How to work with single songs and video clips

As already stated in the How to use the control in your projects section, the first thing to do is to call the InitDJSystem method (in the form or dialog initialisation routine).

At this point the methods you can use are the following:

LoadSound, LoadSoundFast or LoadSoundFromRawFile to load a song from the hard disk

LoadSoundFromMemory or LoadSoundFromRawMemory to load a song from a memory buffer

LoadInternetStream to load a song from the Internet or from a Shoutcast/Icecast server

PlaySound to playback the loaded song

PlaySoundLoop to playback the loaded song in looping mode

PlaySoundRange to playback a portion of the loaded song

PlaySoundRangeLoop to playback a portion of the loaded song in looping mode with the capability of setting the exact number of loops

PauseSound to pause the currently playing song

ResumeSound to resume a paused song

StopSound to stop the currently playing song

SeekSound to seek the song to a given position

ForwardSound to forward the song of a certain amount

RewindSound to rewind the song of a certain amount

CloseSound to discard the loaded song from memory: note that once the container form will be closed, you won't need to do any clean-up action: the control will automatically free each previously allocated resource.

or the following methods of the VideoPlayer object to load and play a video clip file:

VideoPlayer.Create to create a new video player object

VideoPlayer.Load or VideoPlayer.LoadForTempoChange to load a video from the hard disk

VideoPlayer.Play to playback the loaded video

VideoPlayer.PlayRange to playback a portion of the loaded video

VideoPlayer.Pause to pause the currently playing video

VideoPlayer.Resume to resume a paused video

VideoPlayer.Stop to stop the currently playing video

VideoPlayer.Seek to seek the video to a given position

VideoPlayer.Forward to forward the video position of a certain amount

VideoPlayer.Rewind to rewind the video position of a certain amount

VideoPlayer.Close to discard the loaded video from memory: note that once the container form will be closed, you won't need to do any clean-up action: the control will automatically free each previously allocated resource.


How to access settings of audio devices in Windows Vista and later versions

How to access settings of audio devices in Windows Vista and later versions

 Return to chapter overview

[This tutorial applies to Windows Vista and later versions only]

Starting from Windows Vista, Microsoft has rewritten the multimedia sub-system of the Windows operating system from the ground-up; at the same time Microsoft introduced a new API, also known as Core audio API, which allows interacting with the multimedia sub-system and with audio endpoint devices (sound cards).

The Core Audio APIs implemented in Windows Vista and higher versions are the following:

• Multimedia Device (MMDevice) API. Clients use this API to enumerate the audio endpoint devices in the system.

• DeviceTopology API. Clients use this API to directly access the topological features (for example, volume controls and multiplexers) that lie along the data paths inside hardware devices in audio adapters.

• EndpointVolume API. Clients use this API to directly access the volume controls on audio endpoint devices. This API is primarily used by applications that manage exclusive-mode audio streams.

• Windows Audio Session API (WASAPI). Clients use this API to create and manage audio streams to and from audio endpoint devices.

Audio DJ Studio for .NET encapsulates a small portion of these APIs inside a set of methods and events which allow communicating with audio endpoint devices and to request information about their status, to obtain/set the volume level, to mute/unmute specific channels, to report values of embedded VU-meters and so on.

All of the mentioned stuffs, with the exception of WASAPI, are accessible through the CoreAudioDevices COM object accessible through the CoreAudioDevices property. This tutorial doesn't describe management of audio flow for playback and recording through WASAPI: this specific topic is described inside the tutorial How to manage audio flow through WASAPI.

If you open the "Sound" applet available inside the Control Panel of Windows Vista and higher versions, you will see on the "Playback" tab a list of audio rendering devices:

If you click the "Recording" tab you will see a list of audio capture devices:

For both "Playback" and "Recording" devices, respect to versions of Windows older than Vista (XP and earlier versions) devices are not seen as a single sound card having different set of input or output channels but each device is seen as a separate entity which is now called "audio endpoint device".

The new Core audio API distinguishes "Playback" devices from "Recording" devices by discriminating the direction of audio data flow:

· "Render audio endpoint devices" are playback devices where audio data flows from the application to the audio endpoint device, which renders the stream..
· "Capture audio endpoint devices" are recording devices where audio data flows from the audio endpoint device, that captures the stream, to the application..

Each audio endpoint device is displayed by the Control Panel with a set of information as seen in the following image:

After selecting a specific audio endpoint device and pressing the "Properties" button, a new set of tabs related to settings of the selected device will be displayed:

If supported by the sound card driver, you could find information about Jacks available on the sound card connector (channels mapping, location, size and color).

By clicking the "Levels" tab you would have the possibility to set the volume of the end point and also its "mute" state and channels balance:

The sound applet of the Windows control panel can be programmatically displayed through the CoreAudioDevices.DisplaySoundApplet method.

The coverage of Core audio API implemented by our component can be summarized in the following points:

Enumeration and status retrieval of audio endpoint devices

Volume, balance and muting management

VU-Meters of audio endpoint devices

Jacks description

Parts management

Enumeration and status retrieval of audio endpoint devices

Audio end point devices are enumerated through the CoreAudioDevices.Enum method: this method allows discriminating which devices need to be enumerated depending upon their current status: for example you could decide to omit from enumeration devices which are installed but disabled or devices which are installed and enabled but not plugged to a physical input/output device like the speakers or the microphone: as you may know, starting from Windows Vista sound card drivers can implement the so called "jack sensing" which allows the system to be informed if no physical input/output device is plugged-in.

During the enumeration, the component will internally create two separate lists, one for "Render" devices and one for "Capture" devices; each single element inside each separate list will be accessible through its zero-based index. The number of devices added to each list can be obtained through the CoreAudioDevices.CountGet method. Once you have the total number of devices for each list you can obtain further information through the following methods:

· CoreAudioDevices.DescGet allows retrieving the friendly name and description of the device
· CoreAudioDevices.StatusGet allows retrieving the status of the device which may change during the application lifetime; as an alternative, the container application can be informed in real time about changes of the device status by catching the CoreAudioDeviceStateChange event: this may happen when a USB device is plugged-in or unplugged or when the Microphone is plugged/unplugged from its connector.
· CoreAudioDevices.ChannelCountGet allows retrieving the total number of input or output channels for the device.
· CoreAudioDevices.JackCountGet allows retrieving the total number of jacks available inside the connector of the device
· CoreAudioDevices.TypeGet allows retrieving the type of device

You can determine the current system default audio endpoint device through the CoreAudioDevices.DefaultGet method; as an alternative, the container application can be notified about changes to the system default device by catching the CoreAudioDeviceDefaultChange event. The possibility to programmatically set the system default device is given by the CoreAudioDevices.DefaultSet method.

In case a USB audio device should be added to the system, for example when an USB sound card is installed for the first time, the container application can be informed in real time by catching the CoreAudioDeviceAdded event.

When a device has been added to the system, it may still be reported as "Disabled" due to the jack-sensing feature that keeps a device disabled until a Microphone or the Line-In jacks are not physically plugged into the system; when the audio device should be set as "Enabled" or should be set as "Disabled" one or more CoreAudioDeviceStateChange events would be generated.

If the USB audio device should be uninstalled from the system, by physically removing the audio device and by uninstalling its driver from the system, the CoreAudioDeviceRemoved event would be generated.

After catching these events, as well as the CoreAudioDeviceStateChange event, it would be worth for the container application to perform a new enumeration through a new call to the CoreAudioDevices.Enum method in order to keep updated the lists of render and capture devices.

When the access to audio endpoint devices is no more needed, related resources can be released by calling the CoreAudioDevices.Free method.

Volume, balance and muting management

For each audio endpoint device, the application can retrieve/set the following type of volumes:

· Master volume: can be obtained through the CoreAudioDevices.MasterVolumeGet method and modified through the CoreAudioDevices.MasterVolumeSet method.
· Single channels volume: after having determined the number of available channels through the CoreAudioDevices.ChannelCountGet method, the volume of each single available channel can be obtained through the CoreAudioDevices.ChannelVolumeGet method and modified through the CoreAudioDevices.ChannelVolumeSet method.
· Mute status: can be obtained through the CoreAudioDevices.MuteGet method and modified through the CoreAudioDevices.MuteSet method.

For all of the elements above, the container application can be informed in real time about changes made by the Windows Control Panel or by other applications by catching the CoreAudioDeviceVolumeChange event.

Volume applied to the various audio endpoint devices can be expressed in percentage linear values or in dB: a value in dB is based upon a logarithmic scale following the rules below:

· value -100 mutes the sound
· values higher than -100 and smaller than 0.0 attenuate the sound
· value 0 keeps sound level unchanged
· values higher than 0 amplify the sound

from the "Sound" applet of the control panel you can decide which unit of measure adopt by clicking the edit box of the volume with the right mouse button: after the click the context menu with available units of measure will appear as seen on the screenshot below:

Using volume-related methods mentioned above you can decide the unit of measure of the volume obtained/set into the audio endpoint volume.

IMPORTANT NOTE ABOUT UNITS OF MEASURE:When dealing with values expressed in percentage the effective value can have different meaning depending upon the implementation of the sound card driver: for example, usually a percentage value of 100 is assumed as 0 dB: this is not the case when dealing with Core Audio API because, if the sound card driver allows applying a volume range from -100 dB (total silence) to +20 dB (sound amplification of +20 dB), a percentage value of 100 would mean that the applied volume is +20 dB. The range of volume values accepted by the sound card driver, together with the supported value stepping, can be obtained by calling the CoreAudioDevices.MasterVolumeGet method.

IMPORTANT NOTE ABOUT CONVERSION BETWEEN UNITS OF MEASURE: When setting a volume expressed in percentage through one of our component's methods, the value displayed inside the "Sound" applet of the Control Panel may report a value slightly different respect to the one effectively set: this issue is due to a rounding problem when converting from percentage to dB (all values are stored in dB inside the driver); if this should be a problem for you, in order to avoid this minor issue you should always use dB as unit of measure when calling our component's methods and to set the "Sound" applet of the Control Panel to display values in dB instead of the percentage default.

VU-Meters of audio endpoint devices

As we have seen in one of the images above, most audio endpoint devices have a related VU-Meter which allows detecting activities on the audio data flow. It's important to note that these VU-meters will not only report audio activities related to the container application but will report any activity performed by any running application on that specific audio endpoint device. When dealing with capture devices, it must be remarked that the VU-Meter will not act as a sort of monitor but will only report activities of recording/capture sessions performed by the container application or by other applications running inside the system: as an example, you can see VU-meters moving inside the "Recording" tab of the "Sound" applet of the Control Panel because the applet itself starts a capture session.

The container application can obtain peak levels for an audio endpoint device by enabling monitoring of VU-meter activities through the CoreAudioDevices.VuMeterEnableNotifications method. After enabling the monitoring, the container application will receive the CoreAudioDeviceVuMeterChange event each time a new peak value is detected; at this point peak levels can be obtained for the master channel trough the CoreAudioDevices.VuMeterMasterPeakValueGet method and for each single separate channel of the audio endpoint device trough the CoreAudioDevices.VuMeterChannelPeakValueGet method: as mentioned before, the number of available channels can be determined through the CoreAudioDevices.ChannelCountGet method.

Jacks description

The connector of a sound card has a set of jacks which can be used to connect input devices (for example a microphone) and output devices (for example one or more set of speakers). Modern sound card drivers allow enumerating all of the available jacks and, for each jack, can report a set of information like the location (for example rear or front panel of the PC), size (for example 1/8-inch or 1/4-inch), color (usually speakers are connected to the green jack and the microphone to the cyan jack) and channels mapping (for example, render devices configured for working with a 5.1 channel configuration can report if the jack is used for front speakers or rear speakers or center/subwoofer speakers).

The number of available jacks can be determined through the CoreAudioDevices.JackCountGet method; once the total number of jacks is available, you can obtain information for each single jack through the CoreAudioDevices.JackDescriptorGet method.

Parts management

A certain number of sound card drivers add the possibility to access subunits, also known as "parts", which allow defining further parameters related to volume settings or to muting settings; usually these subunits are accessible from the "Levels" tab of a specific audio device and can be available for both render and capture devices.

A typical example, for capture devices, is the microphone boost setting which allows applying an amplification of the audio data incoming from the microphone. When available, this setting can be accessed through the Control Panel in the following way:

· open the Control Panel
· open the Sound applet
· select the "Recoding" tab
· if available, select the "Microphone" capture device
· press the "Properties" button
· select the "Levels" tab: if the driver implements microphone boost you should see something similar:

By acting on the slider of the "Microphone Boost" setting, by default set to 0 dB, it will be possible to increase the amplification applied to the incoming audio data: note that there is a maximum range available and that increasing/decreasing of the value in dB is not linear but made up of predefined steps: the image above is for a Microphone whose maximum boost can be set to +30 dB and each increase/decrease step is of 10 dB: in this case the boost value could be only set to the following values: +0 dB, +10 dB, +20 dB and +30 dB.

Our component can act on the "Microphone Boost" setting using the following methods:

· CoreAudioDevices.CapturePartChannelCountGet with nPartId parameter set to CAPTURE_PART_MIC_BOOST allows to obtain the number of channels of the microphone on which it's possible to apply the amplification: if the returned value should be 0, this would mean that the "Microphone Boost" setting is not implemented by the sound card driver.
· CoreAudioDevices.CapturePartChannelVolumeGet, again with nPartId parameter set to CAPTURE_PART_MIC_BOOST, allows to obtain the current boost level for each channel; as a second task, this method allows obtaining the range of supported boost values and the supported stepping.
· CoreAudioDevices.CapturePartChannelVolumeSet allows to modify the boost level for each channel.

Another example, this time for render devices, is the possibility to set if and how the CD Audio, the Microphone and the Line In channel will work as playback devices. When available, these settings can be accessed through the Control Panel in the following way:

· open the Control Panel
· open the Sound applet
· select the "Playback" tab
· select a render device (in this case we will use the "Speakers" device implemented by the "VIA High Definition Audio" driver)
· press the "Properties" button
· select the "Levels" tab: if the driver implements management of parts you should see something similar:

In the screenshot above we have remarked the "Microphone" part just because what will be said hereafter is related to this specific setting but it could be applied to all of the other available parts. By acting on the "Microphone" slider you can modify the volume of the sound incoming from the microphone and by clicking the small blue speaker's icon you can mute or unmute the channel; the "balance" button allows defining different volume levels for the left and right channel of the microphone.

Our component allows accessing all of the mentioned settings through the following methods:

· CoreAudioDevices.RenderPartChannelCountGet with nPartId parameter set to RENDER_PART_MIC allows to obtain the number of channels of the microphone on which it's possible to apply the volume change: if the returned value should be 0, this would mean that the "Microphone" part is not implemented by the sound card driver.
· CoreAudioDevices.RenderPartChannelVolumeGet, again with nPartId parameter set to RENDER_PART_MIC, allows to obtain the current volume level for each channel; as a second task, this method allows obtaining the range of supported volume level values and the supported stepping.
· CoreAudioDevices.RenderPartChannelVolumeSet allows to modify the volume level for each channel.
· CoreAudioDevices.RenderPartMuteGet allows to obtain the muting state of the part.
· CoreAudioDevices.RenderPartMuteSet allows modifying the muting state of the part.

Samples of usage of access to audio devices in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- CoreAudioDevices


How to work with multiple output devices and speakers

How to work with multiple output devices and speakers

Inside this tutorial we will see how to manage output devices having a DirectSound compatible sound card driver (WDM). For output devices having an ASIO driver you can check the How to manage ASIO drivers tutorial.

Output devices management

If the target system has more than one output device, also known as "sound card", compatible with DirectSound, you can force each of the allocated players to redirect its output to a specific device: the number and friendly description of available output devices can be obtained using the GetOutputDevicesCount and GetOutputDeviceDesc methods: once you have obtained the list of installed devices, you can initialize each player's output through a single call to the InitDJSystem method, passing the device index to the nOutputX parameters; the output device returned when calling the GetOutputDeviceDesc method with parameter 0 is always the system default device set through the Windows Control Panel: in case the system default output device should be changed through the Control Panel, the container application would be notified of the change through the DeviceChange event.

During the container application execution there could be the need to change "on the fly" the output device for a certain player: the current output device can be obtained through a call to the StreamOutputDeviceGet method and the output device change can be performed through the StreamOutputDeviceSet method; the capability of changing the output device on a plying sound is very useful if you need a monitor output for your headphones. It's important to note that the switch of the output device can be performed without problems when the player is in "Playing", "Paused" or "Stopped" state. If the output device is changed successfully, an OutputDeviceChanged event is fired.

Speakers management

Starting from Windows Vista, Microsoft has totally rewritten from the ground up the Windows multimedia subsystem so speakers management depends upon the Windows version in use:

· Speakers management under Windows XP and older versions of Windows
· Speakers management under Windows Vista and newer versions of Windows

Speakers management under Windows XP and older versions of Windows

Most sound cards can have more than plain stereo output in order to support surround sound or in order to support multi-player features: this control allows playback of multi-channel sound files (for WAV, AIFF, OGG Vorbis and WMA formats) loaded through the LoadSound method and, at the same time, it can support speakers assignment.

Speakers assignment can be usually set through the Control Panel as seen on the screenshot below:

after pressing the "Advanced..." button you will see the following dialog box:

If your application needs to manage speakers assignment, the first thing to do is setting the EnableSpeakers property to TRUE: this property must be set at design-time; setting this property at runtime will not have any effect and will be simply ignored.

Once the speakers management has been enabled and the control has been initialized through the InitDJSystem or InitDJSystemEx methods, the control can retrieve the actual number of speakers enabled on an output device through the GetOutputSpeakersConfig method and change it through the SetOutputSpeakersConfig method. It's important to note that some specific sound card software (for example the Sound Blaster Audigy 2 NX) could override these settings so you should modify the speakers setup for this sound card using the sound card's proprietary control panel.

The current speakers configurations supported by the control are the following:

· Sound cards with 1 plain stereo output (2 speakers)

This configuration allows 1 single player to play 1 stereo sound.

In alternative, this configuration allows 2 different players to play 2 different mono sounds on the following speakers:

1. Left speaker

2. Right speaker

· Sound cards with 2 stereo outputs (4 speakers), also known as Quadraphonic

This configuration allows 2 different players to play 2 stereo sounds on the following speakers:

1. Front speakers

2. Rear speakers

In alternative, this configuration allows 4 different players to play 4 different mono sounds on the following speakers:

1. Front-Left speaker

2. Front-Right speaker

3. Rear-Left speaker

4. Rear-Right speaker

· Sound cards with 3 stereo outputs (6 speakers), also known as 5.1

This configuration allows 3 different players to play 3 stereo sounds on the following speakers:

1. Front speakers

2. Rear speakers

3. Center speakers

In alternative, this configuration allows 6 different players to play 6 different mono sounds on the following speakers:

1. Front-Left speaker

2. Front-Right speaker

3. Rear-Left speaker

4. Rear-Right speaker

5. Center speaker

6. LFE speaker that, usually, is attached to a subwoofer

· Sound cards with 4 stereo outputs (8 speakers), also known as 7.1

This configuration allows 4 different players to play 4 stereo sounds on the following speakers:

1. Front speakers

2. Rear speakers

3. Center speakers

4. Rear-center speakers

In alternative, this configuration allows 8 different players to play 8 different mono sounds on the following speakers:

1. Front-Left speaker

2. Front-Right speaker

3. Rear-Left speaker

4. Rear-Right speaker

5. Center speaker

6. LFE speaker that, usually, is attached to a subwoofer

7. Rear Center-Left speaker

8. Rear Center-Right speaker

When the container application is started the control will automatically enumerate the available speakers for each installed output device and the container application will be able retrieving the number of available speakers through the GetOutputSpeakersCount method or, in alternative, through the GetPlayerSpeakersCount method. Some specific output device (for example the Maya EX7 sound card) will always return 2 speakers also if it supports up to 8 mono speakers: in this case the container application can force the speakers assignment through a call to the ForceSpeakersAssignment method.

Some specific output device (again the Maya EX7 sound card) will invert the Rear and Center speakers assignment: you can get rid of this situation through the StreamOutputSpeakersRearAndCenterSwap method.

The StreamOutputSpeakerGet and StreamOutputSpeakerSet methods allow a given player to obtain/redirect its output to a specific speaker of the current output device; if two allocated players are currently using two different speakers on the same output device, you can swap their speakers assignment through a call to the StreamOutputSpeakerSwap method: note that it's not allowed swapping speakers of players currently redirecting their output to different output devices.

Note on subwoofer assignment: the control maps the Center mono speaker as a Left channel and the Subwoofer mono speaker as a Right channel: some commercial Home Theatre system inverts these speakers: the control cannot manage this situation so, when using the control with these kind of systems, the final user will have to swap cables for Center and Subwoofer speakers.

Speakers management under Windows Vista and newer versions of Windows

Most sound cards can have more than plain stereo output in order to support surround sound or in order to support multi-player features: this control allows playback of multi-channel sound files (for WAV, AIFF, OGG Vorbis and WMA formats) loaded through the LoadSound method and, at the same time, it can support speakers assignment.

Speakers configuration is not available through CoreAudio APIs so it cannot be modified programmatically but only through the Sounds applets of the Windows control panel as seen on the screenshot below:

after pressing the "Configure..." button you will see the following dialog box:

By default the sound card should have "Stereo" enabled so, if you want enable speakers management depending upon the capabilities of the sound card in use, you will have to change a different option under the "Audio channels" listbox. If for example you should need to enable all of the 8 speakers available inside a 7.1 sound card, you will have to select the "7.1 Surround" option as seen on the screenshot below:

When the container application is started the control will automatically enumerate the available speakers for each installed output device and the container application will be able retrieving the number of available speakers through the GetOutputSpeakersCount method or, in alternative, through the GetPlayerSpeakersCount method. It's important to note that, if the default "Stereo" option should be selected from the Control Panel, the system will always return 2 speakers also if the sound card has 8 physical speakers: under Windows Vista and higher versions there is no documented way to force changing the speakers configuration programmatically (meaning that calls to the SetOutputSpeakersConfig method will have no effect) so the final user will have to be instructed about changing the speaker settings inside the Control Panel as described above in order to be able exploiting all of the available physical speakers.

It's important to note that not all sound card drivers implement the "Configure" feature as seen on the screenshot above: in certain cases, for example with the M-Audio Delta 1010LT sound card, you will have to enable multi-channel by selecting the appropriate playback format; this feature can be achieved as seen on the screenshot below:

after pressing the "Properties" button select the "Advanced" tab:

and select the appropriate playback format: as you can see, in this case you don't have much options for multi-channel.

Some specific output device will invert the Rear and Center speakers assignment: you can get rid of this situation through the StreamOutputSpeakersRearAndCenterSwap method.

The StreamOutputSpeakerGet and StreamOutputSpeakerSet methods allow a given player to obtain/redirect its output to a specific speaker of the current output device; if two allocated players are currently using two different speakers on the same output device, you can swap their speakers assignment through a call to the StreamOutputSpeakerSwap method: note that it's not allowed swapping speakers of players currently redirecting their output to different output devices.

Note on subwoofer assignment: the control maps the Center mono speaker as a Left channel and the Subwoofer mono speaker as a Right channel: some commercial Home Theatre system inverts these speakers: the control cannot manage this situation so, when using the control with these kind of systems, the final user will have to swap cables for Center and Subwoofer speakers.

Samples of use of speakers and output devices management in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- OutputDevices

- SpeakersManager


How to manage audio flow through WASAPI

How to manage audio flow through WASAPI

[This tutorial applies to Windows Vista and later versions only]

Starting from Windows Vista, Microsoft has rewritten the multimedia sub-system of the Windows operating system from the ground-up; at the same time Microsoft introduced a new API, also known as Core audio API, which allows interacting with the multimedia sub-system and with audio endpoint devices (sound cards).

The Core Audio APIs implemented in Windows Vista and higher versions are the following:

• Multimedia Device (MMDevice) API. Clients use this API to enumerate the audio endpoint devices in the system.

• DeviceTopology API. Clients use this API to directly access the topological features (for example, volume controls and multiplexers) that lie along the data paths inside hardware devices in audio adapters.

• EndpointVolume API. Clients use this API to directly access the volume controls on audio endpoint devices. This API is primarily used by applications that manage exclusive-mode audio streams.

• Windows Audio Session API (WASAPI). Clients use this API to create and manage audio streams to and from audio endpoint devices.

All of the mentioned stuffs, with the exception of WASAPI, are accessible through the CoreAudioDevices COM object accessible through the CoreAudioDevices property as described inside the tutorial How to access settings of audio devices in Windows Vista and later versions.

In general, WASAPI operates in two modes:

· In exclusive mode (also called DMA mode), unmixed audio streams are rendered directly to the audio adapter and no other application's audio will play and signal processing has no effect. Exclusive mode is useful for applications that demand the least amount of intermediate processing of the audio data or those that want to output compressed audio data such as Dolby Digital, DTS or WMA Pro over S/PDIF.

· In shared mode, audio streams are rendered by the application and optionally applied per-stream audio effects known as Local Effects (LFX) (such as per-session volume control). Then the streams are mixed by the global audio engine, where a set of global audio effects (GFX) may be applied. Finally, they're rendered on the audio device. Differently from Windows XP and older versions, there is no more direct path from DirectSound to the audio drivers, indeed DirectSound and MME are totally emulated through WASAPI working in shared mode, which results in pre-mixed PCM audio that is sent to the driver in a single format (in terms of sample rate, bit depth and channel count). This format is configurable by the end user through the "Advanced" tab of the Sounds applet of the Control Panel as seen on the picture below:

In order to enable the usage of WASAPI you must call the InitDriversType method with the nDriverType parameter set to DRIVER_TYPE_WASAPI. The call to the InitDriversType method is mandatory before performing calls to the InitDJSystem (or InitDJSystemEx), GetOutputDevicesCount and GetOutputDeviceDesc methods: if the InitDriversType method should be called at a later time, it would report back an error; if for any reason you should need calling it at a later time, you would need performing the following sequence of calls:

1. ResetEngine method

2. InitDriversType method

3. Eventual new enumeration of output devices through the GetOutputDevicesCount and GetOutputDeviceDesc methods.

4. ResetControl method

After initializing the usage of WASAPI through the InitDriversType method, Active DJ Studio gives access to WASAPI itself through the WASAPI COM object accessible through the WASAPI property.

WASAPI can manage three different types of devices:

· Render devices are playback devices where audio data flows from the application to the audio endpoint device, which renders the audio stream..
· Capture devices are recording devices where audio data flows from the audio endpoint device, that captures the audio stream, to the application..
· Loopback devices are recording devices that capture the mixing of all of the audio streams being rendered by a specific render device, also if audio streams are being played by third-party multimedia application like Windows Media Player: each render device always has a corresponding loopback device.

Available WASAPI devices can be enumerated through the WASAPI.DeviceGetCount and WASAPI.DeviceGetDesc methods: if you only need enumerating render devices you can also use the GetOutputDevicesCount and GetOutputDeviceDesc methods. In both cases, only devices reported as "Enabled" by the system will be listed: unplugged or disabled devices will not be enumerated.

As seen for DirectSound and for ASIO, the index of the output device used for playback of each single player can be set through the InitDJSystem (or InitDJSystemEx) method. Before using an output device for playback, starting the device itself is a mandatory operation: for exclusive mode you can use the WASAPI.DeviceStartExclusive method while for shared mode you can use the WASAPI.DeviceStartShared method. In both cases the started device can be stopped through the WASAPI.DeviceStop method. You can check if a device is already started through the WASAPI.DeviceIsStarted method.

For exclusive mode you need to start the device by specifying, inside the call to the WASAPI.DeviceStartExclusive method, the playback format which is represented by the frequency and number of channels: you can know if a WASAPI device supports a specific format through the WASAPI.DeviceIsFormatSupported method.

For shared mode you directly rely on the playback format chosen from the Sound applet of the Windows control panel: you can know which is the current format through the WASAPI.DeviceSharedFormatGet method.

WASAPI devices can support multi-channel configuration: this specific setting is not available through CoreAudio APIs so it cannot be modified programmatically but only through the Sounds applets of the Windows control panel; how to perform speakers configuration is briefly described inside the section Speakers management under Windows Vista and newer versions of Windows of the tutorial How to work with multiple output devices and speakers . After performing speakers configuration, you can know how many channels are assigned to a certain WASAPI device through the WASAPI.DeviceChannelsGet method.

WASAPI clients can individually control the volume level of each audio session. WASAPI applies the volume setting for a session uniformly to all of the streams in the session; you can modify the session volume through the WASAPI.DeviceVolumeSet method and to retrieve the current volume through the WASAPI.DeviceVolumeGet method. In case you should need to get/set the master volume for the given WASAPI device, shared by all running processes, you should use the CoreAudioDevices.MasterVolumeGet / CoreAudioDevices.MasterVolumeSet methods.

This latest topic brings to mind an important issue: while the list of CoreAudio devices, depending upon the value of the nStateMask parameter of the CoreAudioDevices.Enum method, may not contain unplugged or disabled devices, the list of WASAPI devices will always contain all of the devices installed inside the system, also if currently unplugged or disabled: in order to know the one-to-one correspondence between a specific WASAPI device and a specific CoreAudio device, which may be listed at different positions inside the respective lists, you should use the WASAPI.DeviceCoreAudioIndexGet method: with this method, given the zero-based index of the device inside the list of WASAPI devices, you could be informed about the corresponding zero-based index of the same physical device inside the list of CoreAudio devices.

As a final feature, WASAPI gives the possibility to perform a direct playback on a render device of audio data actually being received through a capture device or through a loopback device: this can be performed through the WASAPI.AttachInputDeviceToPlayer method.

The configuration of audio devices is not static: for example when dealing with USB connected audio devices the configuration may change when a USB device is plugged/unplugged or when speakers or headphones are physically inserted or removed from respective connectors. When the configuration of audio devices changes, it could be needed to enumerate again the available output devices and to properly assign them to the instanced players by resetting the multimedia engine and the control as described at the beginning of this tutorial.

In case a USB audio device should be added to the system, for example when an USB sound card is installed for the first time, the container application can be informed in real time by catching the CoreAudioDeviceAdded event.

When a device has been added to the system, it may still be reported as "Disabled" due to the jack-sensing feature that keeps a device disabled until the speakers are not physically plugged into the sound card; when the audio device is set as "Enabled" or "Disabled", one or more CoreAudioDeviceStateChange events could be generated.

If the USB audio device should be uninstalled from the system, by physically removing the audio device and by uninstalling its driver from the system, the CoreAudioDeviceRemoved event would be generated.

As mentioned, you could receive more than one CoreAudioDeviceStateChange event at the same time so, when eventually starting the reset procedure, you should ignore CoreAudioDeviceStateChange events after the first one.

In order to allow applying further effects to the audio stream being processed by a specific render device, we had the need to internally create an embedded "Stream Mixer" for each output device; this approach is quite similar to what has been described inside the How to use custom Stream Mixers tutorial but in this case you don't need to allocate a new custom Stream Mixer through your own code because the control will automatically allocate it for you. Below you can see the architecture applied:

In case the output of Player 0 and/or Player1 should be redirected to a different output device, the StreamOutputDeviceSet method would automatically disconnect the PCM stream from the internal Stream Mixer of the current output device and will reconnect it to the internal Stream Mixer of the new output device.

As for custom Stream Mixers described inside the How to use custom Stream Mixers tutorial, also in this case the Stream Mixer owns a unique identifier that can be obtained through the StreamMixerGetIdFromOutput method: through this unique identifier you can apply further effects to the mixed streams, for example you could apply a custom DSP or modify the Preamplifier volume: for this purpose the unique identifier can be used in place of the nPlayer parameter for all of the methods that will modify the output stream, like volume-related methods and all of the methods described inside the How to apply special effects to a playing sound tutorial. For obvious reasons, respect to custom Stream Mixers, you cannot redirect the mixed stream in output from the Stream Mixer to a different output device.

As seen on the graphic above, as for custom Stream Mixers, the Mixed stream being sent to the output device can be redirected to one of the following destinations:

· Through the use of an external encoder (Lame.exe for MP3, Fdkaac.exe for AAC+, OggEnc.exe for Ogg Vorbis), to a Shoutcast or Icecast server: in this case the control behaves as a Shoutcast/Icecast source.
· In combination with our Active Sound Recorder control, directly to an output file whose format can be predisposed inside Active Sound Recorder itself.

Samples of usage of WASAPI in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- WasapiInputPlayer

- WasapiSpeakersManager

If the Active Sound Suite package has been installed, a further sample demonstrating the possibility to record and casting the output of the stream mixer is available:

- WasapiStreamMixer


How to manage ASIO drivers

How to manage ASIO drivers

ASIO (Audio Stream Input/Output) is a sound card driver protocol for digital audio specified by Steinberg, providing a low-latency and high fidelity interface between a software application and a computer's sound card. ASIO bypasses the normal audio path from the user application through layers of intermediary Windows operating system software, so that the application connects directly to the hardware of the sound card. Each layer that is bypassed means a reduction in latency, the delay between an application sending sound to the sound being reproduced by the sound card.

By default Active DJ Studio enumerates output devices (sound cards) supporting the DirectSound protocol: in order to let Active DJ Studio enumerating devices supporting ASIO drivers, you need to make a call to the InitDriversType method and to specify which kind of drivers/protocols your application will support and, in case you should need supporting both ASIO and DirectSound at the same time, in which order; if a certain sound card should support both DirectSound and ASIO drivers, it would be enumerated as two different sound cards, one supporting DirectSound and one supporting ASIO (*).

The call to the InitDriversType method is mandatory before performing calls to the InitDJSystem, GetOutputDevicesCount and GetOutputDeviceDesc methods: if the InitDriversType method should be called at a later time, it would report back an error; if for any reason you should need calling it at a later time, you would need performing the following sequence of calls:

1. ResetEngine method

2. InitDriversType method

3. Eventual new enumeration of output devices through the GetOutputDevicesCount and GetOutputDeviceDesc methods.

4. ResetControl method

After having initialized the type of driver(s) in use through the InitDriversType method, it will be possible enumerating available output devices through the GetOutputDevicesCount and GetOutputDeviceDesc methods: depending upon the drivers set, these methods will return the overall list of available output devices (DirectSound + ASIO) so it will be possible setting them inside the nOutputx parameters of the InitDJSystem method. At a later time you can obtain the driver in use by a specific output device through the GetOutputDeviceDriverType method.

If the InitDriversType method should be set to initialize the use of ASIO devices, you could access specific ASIO features through methods exposed by the ASIO property that implements the ASIO COM object:

· Enumerating available ASIO devices through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it's important to note that this kind of enumeration will only report existing ASIO devices and not the overall list of available output devices as reported by the GetOutputDevicesCount and GetOutputDeviceDesc methods.
· Obtaining the zero-based index of an ASIO device inside the overall list of available output devices through the ASIO.DeviceGetOutputIndex method.
· Given the zero-based index of an ASIO device inside the overall list of available output devices, obtaining the zero-based index of the same ASIO device inside the list of available ASIO devices through the ASIO.DeviceGetIndexFromOutput method.
· For each ASIO device, enumerating the list of available input and output channels through the ASIO.DeviceGetChannelsCount and ASIO.DeviceGetChannelDesc methods.
· Displaying the control panel provided by the ASIO driver of a specific device through the ASIO.ControlPanelDisplay method.
· Obtaining the absolute pathname of the file containing the ASIO driver of a specific ASIO device through the ASIO.DeviceGetDriverPathname method.
· Starting and stopping the usage of a specific ASIO device through the ASIO.DeviceStart and ASIO.DeviceStop methods.

The call to the ASIO.DeviceStart method is mandatory in order to perform playback of the loaded sound on a specific ASIO device. You can know if a specific ASIO device is already started through the ASIO.DeviceIsStarted method.

After starting an ASIO device, it will be possible performing the following tasks:

· Playing a sound on the device
· Using input channels as playback channels through the ASIO.AttachInputChannelToPlayer method: this allows to get sound coming from an input channel of the ASIO device, for example the Line-in or the Microphone, and to send it in playback with very low latency.
· Redirecting the output of a certain player to a specific output channel through the ASIO.PlayerOutputChannelSet and ASIO.PlayerOutputChannelGet methods: with multi-channels sound cards (5.1 and 7.1) this allows performing speakers management.
· Getting and setting the volume for input and output channels through the ASIO.DeviceMasterVolumeGet and ASIO.DeviceMasterVolumeSet methods (applies the same volume level to all channels in one shot) and through the ASIO.DeviceChannelVolumeGet and ASIO.DeviceChannelVolumeSet methods (applies the volume level on a specific channel allowing separate volume level for each channel).
· Obtaining the current latency, expressed in samples per second, for input and output channels as reported by the ASIO driver itself through the ASIO.DeviceLatencyGet method.

An interesting feature of ASIO devices is the channel mirroring, a capability that allows replicating the same sound on more output channels of the same ASIO device; this can be obtained with a specific setting of the nChannelMode parameter of the ASIO.DeviceStart method:

· when the nChannelMode parameter is set to ASIO_CHANNEL_MODE_MIRROR_STEREO, the control will mirror the output of channel "0" to other pair channels (2, 4, etc.) and the output of channel "1" to other odd channels (3, 5, etc.). When playing a stereo sound on an ASIO device having 8 output channels, this will allow hearing the same stereo sound on the 4 available channel pairs.
· when the nChannelMode parameter is set to ASIO_CHANNEL_MODE_MIRROR_MONO, the control will mirror the output of channel "0" to all of the other available channels (1, 2, 3, 4, etc.). When playing a mono sound on an ASIO device having 8 output channels, this will allow hearing the same mono sound on all of the 8 channels.

With regards to playback of loaded sounds, it's important to note that the possibility to redirect the sound stream to output devices having different nature (ASIO or DirectSound) has been maintained. In order to achieve this feature we had the need to internally create an embedded "Stream Mixer" for each output device; this approach is quite similar to what has been described inside the How to use custom Stream Mixers tutorial but in this case you don't need to allocate a new custom Stream Mixer through your own code because the control will automatically allocate it for you. Below you can see the architecture applied:

In case the output of Player 0 and/or Player1 should be redirected to a different output device, the StreamOutputDeviceSet method would automatically disconnect the PCM stream from the internal Stream Mixer of the current output device and will reconnect it to the internal Stream Mixer of the new output device.

As for custom Stream Mixers described inside the How to use custom Stream Mixers tutorial, also in this case the Stream Mixer owns a unique identifier that can be obtained through the StreamMixerGetIdFromOutput method: through this unique identifier you can apply further effects to the mixed streams, for example you could apply a custom DSP or modify the Preamplifier volume: for this purpose the unique identifier can be used in place of the nPlayer parameter for all of the methods that will modify the output stream, like volume-related methods and all of the methods described inside the How to apply special effects to a playing sound tutorial. For obvious reasons, respect to custom Stream Mixers, you cannot redirect the mixed stream in output from the Stream Mixer to a different output device.

As seen on the graphic above, as for custom Stream Mixers, the Mixed stream being sent to the output device can be redirected to one of the following destinations:

· Through the use of an external encoder (Lame.exe for MP3, Fdkaac.exe for AAC+, OggEnc.exe for Ogg Vorbis), to a Shoutcast or Icecast server: in this case the control behaves as a Shoutcast/Icecast source.
· In combination with our Active Sound Recorder control, directly to an output file whose format can be predisposed inside Active Sound Recorder itself.

IMPORTANT NOTE ABOUT PERFORMANCES: When the output of the stream mixer is sent to the recorder control and/or to a streaming server, a too much low latency set into the ASIO driver could cause unwanted gargling on the audio stream: in this specific case it's recommended that the latency of the ASIO driver is set to 512 samples per second or higher.

In case you should simply need to render audio data incoming from one or more input channels to one or more output channels directly, with the advantage of a smaller CPU footprint, a possible alternative to the ASIO.DeviceStart method would to invoke the ASIO.DeviceListenInputStart method: the limitation of this approach would be the fact that you would loose the capability to record or cast incoming audio data. When the ASIO device is started in this way, you may pause direct playback through the ASIO.DeviceListenInputPause method and resume playback through the ASIO.DeviceListenInputResume method.

In this case direct playback is not performed through the stream mixer described above, as incoming audio data is rendered directly to the output channel(s), but you can still apply special effects to audio data being rendered by obtaining the index of the involved internal player through the ASIO.DeviceListenInputPlayerGet method and by using the returned index with any of the methods of the Effects COM object or with the StreamVolumeLevelSet method.

Also in this case, the ASIO device can be stopped through the ASIO.DeviceStop method.

Samples of usage of ASIO drivers in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- AsioList

- AsioSpeakersManager

- AsioVideoPlayer

If the Active Sound Suite package has been installed, a further sample demonstrating the possibility to record and casting the output of the stream mixer is available:

- AsioStreamMixer

(*) The possibility for a certain output device to support both DirectSound and ASIO at the same time could be compromised if the specific driver in use shouldn't be able to manage the situation: usually in these cases, quite limited in our experience, it will be only possible playing back the loaded sound through the ASIO protocol.


How to create and manage a playlist

How to create and manage a playlist

Supported standard playlist formats are the following:

· M3U
· PLS
· WPL

Starting from version 5.0 of the control, MultiMedia Soft has introduced a new proprietary playlist format named PDJ; this new format allows adding volume points automation and cue points management to playlist's elements and also the use of encrypted sounds generated using the CryptSound™ application; for details about the use of this new format refer to the How to manage Volume Automation tutorial.

When using the PDJ format with one single player, the availability of mixing points, cue points and volume automation points is not mandatory: you can in any case use this format as other common playlist formats as seen below (note that, respect to usage with volume automation attributes, the tag FaderPlayList is in this case changed into NormalPlayList):

<?xml version="1.0"?>

<NormalPlayList>

<PlayListItems>

 <Item pathname="C:\sounds\drumtrik01_120bpm.wav" />

 <Item pathname="C:\sounds\drumtrik17_86bpm.wav" />

 <Item pathname="C:\sounds\drumtrik14_132bpm.wav" />

</PlayListItems>

</NormalPlayList>

In a similar way, in case you should need using encrypted sounds with a single player, you could have something like this:

<?xml version="1.0"?>

<NormalPlayList>

<PlayListItems>

 <Item pathname="C:\sounds\drumtrik01_120bpm.bxx" DecryptKey="20041C2645684A1BAA30237EF02E7F2A"/>

 <Item pathname="C:\sounds\drumtrik17_86bpm.bxx" DecryptKey="20041C2645684A1BAA30237EF02E7F2A"/>

 <Item pathname="C:\sounds\drumtrik14_132bpm.bxx" DecryptKey="20041C2645684A1BAA30237EF02E7F2A"/>

</PlayListItems>

</NormalPlayList>

The use of the "bxx" extension for encrypted files pointed by a PDJ playlist file allows the component to recognize these files as encrypted audio files. Although not mandatory, it's always suggested the use of this extension for encrypted audio files pointed by a playlist file in PDJ format.

A normal playlist can be created from scratch using the PlayListCreate or, in alternative, the PlayListCreateSpeed methods.

In case you should need adding volume automation features to your playlist, you could use the PlayListCreateAutomation method; further information about the use of Volume Automation can be found inside the How to manage Volume Automation tutorial.

If a playlist already exists on your PC, you can load it into a player through the PlayListLoad method; a call to this method won't return control to the container application until the playlist has been loaded completely so, if the playlist should be very long, it could block your user interface for a while; for this reason there is the possibility to call the PlayListLoadSync method which will perform playlist analysis and loading in a separate thread: the container application is informed about the loading advancement through the PlayListLoadStart, PlayListLoadPerc and PlayListLoadDone events.

A playlist can also be created directly from a CD using the PlayListLoadFromCd method that will automatically load all the available CD audio tracks.

At runtime, when an item of the playlist is loaded into the player, the PlaylistSoundLoaded event is generated. If the loading fails, for example because the format of the item is not supported or because the item is not available inside the system, the PlaylistSoundLoadFailure event is generated.

A playlist, loaded from disk or created from scratch, can be modified through the following methods:

PlayListAddItem to add a new song to the playlist

PlayListAddItemEx to add a new song or the contents of another playlist or the contents of a directory to the playlist

PlayListAddItemWithTag to add a new song to the playlist with an associated tag string: this tag string will be reported by the PlaylistSoundLoaded event when the item is loaded into the player at runtime.

PlayListRemoveItem to remove a song from the playlist

PlayListMoveItem to change the position of a song

PlayListGetCount to retrieve the number of songs currently in the playlist

PlayListGetItemString to retrieve information about a chosen song

PlayListSetLoop to make the playlist loop when it has been executed completely

PlayListSetShuffle to set a random playing order of the playlist songs: when the "shuffle" option is selected, you may know which item is currently being rendered through the PlayListCurrIndexGet method, which will be the next item to be rendered though the PlayListNextIndexGet method and the full ordered table of indexes that will be executed through the PlayListExecOrderTableGet method. You may modify the next index of the item to be executed through the PlayListNextIndexSet method.

Once the playlist has been filled you can save it on your PC using the PlayListSave method.

When the playlist has been loaded with volume automation enabled, the following methods can be used to modify contained items:

PlayListItemVolAutomPointAdd to add a new volume automation point to an existing item

PlayListItemVolAutomSetMixPos to modify mixing positions of an existing item

PlayListItemVolAutomPointRemove to remove a volume automation point from an existing item

PlayListItemCuePointAdd to add a new cue point to an existing item

PlayListItemCuePointRemove to remove a cue point from an existing item

The playlist can be executed using the following methods:

PlayListExecute to start the playlist execution from the beginning

PlayListExecNext to execute the next song

PlayListExecPrev to execute the previous song

PlayListExecAt to execute the song at the given position

PlayListStop to stop the automatic execution of the playlist

Playlists can also be used, through the embedded Automatic Fader, for cross-fading between two players: for details about using the Automatic Fader refer to the How to use the Automatic Fader section.

A playlist file can consist of both audio tracks and/or video clips: based upon the file extension, the control will decide if the file to be loaded is an audio track or a video clip; for formats like MP4 and WMV, which can be supported in both ways but which are considered as video clips by default, you can use the AudioExtensionAdd method in order to load them as simple audio tracks and to ignore the contained video stream.

Samples of use of playlists in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- Playlists

- Fader


How to use the Automatic Fader

How to use the Automatic Fader

The embedded Automatic Fader can easily manage the cross-fading between two songs loaded inside two different players (also know as "decks"): the Fader object, internally implemented as a COM object, is dedicated to this purpose and can be accessed through the control's Fader property.

When you need using the Fader object inside your development, you need to initialise it through a call to the Fader.Init method, passing the fading type (playlist based or single song based) and the two involved players identifiers.

The fading type can be:

· single song based: In this case the cross-fading between the two involved players is performed through the respective loaded songs.
· double playlist based: In this case the cross-fading between the two involved players is performed getting sounds from the respective loaded playlists.
· single playlist based: In this case the cross-fading between the two involved players is performed getting sounds from the playlist loaded inside one single player: the specific player whose playlist will be used can be set through a call to the Fader.PlayListUseSingle method.

IMPORTANT NOTE ABOUT USAGE OF VIDEO CLIPS: when using video clips in conjunction with the automatic fader, it's recommended avoiding the usage of more than one output window for each player or on slower PCs you may experience some audio stuttering during the fading between the two involved players.

Fading types described above can be started through a call to the Fader.StartManualFading method and, if needed, stopped through the Fader.Stop method: by default the multimedia engine will check the availability of at least two songs or video clips having a duration longer than the total mixing time: without this availability the multimedia engine will return error ERR_CANNOT_FADE_SMALL_SONGS (-45); this behaviour can be modified by setting the Fader.CheckItemsDurationOnStart property to "False".

Once the Fader object has been initialized you can configure its behaviour through a set of dedicated properties that will manage the fade-in/fade-out transition.

As you can see on the graphic below, by default cross-fading is based upon a Time/Volume combination:

The target volume for fade-in is by default set to 100% (0 dB) but this can be modified using the Fader.FadeInTargetVolumeSet method.

We have also added a Time/Playback-rate combination that allows the creation of the so called "Breakdown effect" that simulates the switch off of the deck rotor engine: you can choose this behaviour through the following property:

Fader.FadeOutMode

The available properties are the following:

Fader.FadeStartFromEnd: expressed in milliseconds, determines when the fader will automatically start the cross-fading

Fader.FadeOutLength: expressed in milliseconds, determines the duration of the fade-out phase

Fader.FadeInLength: expressed in milliseconds, determines the duration of the fade-in phase

Fader.FadeInSeekPos: expressed in milliseconds, determines the initial position of the song fading-in: in case that the song fading-in is in "paused" state, this parameter is ignored and the actual position is taken.

Fader.FadeOutDelayFromMixStart: expressed in milliseconds, determines the delay applied for the fade-out

Fader.FadeInDelayFromMixStart: expressed in milliseconds, determines the delay applied for the fade-in

Fader.FadeInEnabled: boolean value that determines if the fade-in is enabled

Fader.FadeOutEnabled: boolean value that determines if the fade-in is enabled

In case you should need to give the possibility to start a manual cross-fading, without the need to wait reaching the predisposed position, you can use the Fader.StartManualFading method.

The total time required for the cross-fading is immediately available inside the Fader.TotalMixingTime property (read-only).

If you need to disable the use of the Automatic Fader, you will have to call the Fader.Exit method that will remove the involved synchronisation; a new call to the Fader.Init method will enable again the Automatic Fader.

You can synchronize the container application with the cross-fading process catching a set of predefined events:

FadingPointReached: occurs when the playback of the song that will fade-out reaches the Fader.FadeStartFromEnd position

FadingVolumeChanged: occurs several times, for each of the involved players, during the volume sliding: allows to know in real-time the player's volume.

FadeInStarted: occurs when the song fading-in starts playing

FadeInCompleted: occurs when the fade-in is completed

FadeOutStarted: occurs when the song fading-out starts lowering its volume

FadeOutCompleted: occurs when the fade-out is completed

All of the graphics above show the volume fade as linear but the automatic fader can be also set to work with different kinds of volume curve as seen for volume automation.

Specific volume curves can be set through the Fader.FadeInVolumeCurveSet or Fader.FadeInVolumeCurveSetEx for fade-in and through the Fader.FadeOutVolumeCurveSet and Fader.FadeOutVolumeCurveSetEx for fade-out.

The control comes with a set of fixed curves and with the possibility to design custom curves based upon Bézier curves.

Linear curve

Exponential curve

Cosine curve

Smooth curve

Custom Bézier curve based upon two control points.

Custom curves can be designed directly inside the user interface of the container application through the VolumeAutomation.CurveDesigner property which implements the CurveDesignerMan class: this specific object manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic above). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

The Fader.Display property

Another useful feature of the embedded Automatic Fader is the possibility to display its visual representation through the Fader.Display property that works in a way very similar to the other Visual Feedbacks: this property must be associated, through the call to the Fader.Display.Create method, to an existing window that will be used as a surface for the graphic rendering; below you can see a screenshot of our Demo application that shows it:

Note that also the Fader.Display property is internally implemented through the Fader.Display COM object, so you have full customization capabilities about the display coloring; here is the set of available properties and methods:

Fader.Display.ColorSongFadingOut: the color used to render the line representing the song fading-out

Fader.Display.ColorSongFadingIn: the color used to render the line representing the song fading-in

Fader.Display.ColorLineMixPoint: the color used to render the line representing the Mix point

Fader.Display.ColorLineSongEnd: the color used to render the line representing the end of the song fading-out

Fader.Display.ColorBackground: the color used to render the Display background

Fader.Display.WidthSongLines: the width in pixels of the song lines

Fader.Display.WidthReferenceLines: the width in pixels of the reference lines

Fader.Display.SetBackPictureFromFile: sets a background picture obtained from a BMP file

Fader.Display.SetBackPictureFromHandle: sets a background picture obtained from a bitmap handle

Below you can find a graphic that gives an idea of the involved elements:

This graphic can be shown/hidden through the call to the Fader.Display.Show method.

A sample of use of the Fader object and of the Fader.Display object in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- Fader


How to use custom Stream Mixers

How to use custom Stream Mixers

Custom Stream Mixers allows mixing the output of a number of players into one single audio stream before outputting the audio stream itself to a chosen output. The graph below summarizes the available features of a custom Stream Mixer:

As you may know, a player can generate a PCM stream from a sound file or, through the interaction with Active Sound Recorder, from an input channel; as seen on the graph above, the mixing result, on which it's still possible applying further effects (for example changing the volume of the mixed stream or changing the output device), can be redirected to one or more of the following destinations:

· Directly to DirectSound and to the selected sound card.
· Through the use of an external encoder (Lame.exe for MP3, Fdkaac.exe for AAC+, OggEnc.exe for Ogg Vorbis), to a streaming server (SHOUTcast, Icecast and Windows Media Services are currently supported): in this case the control behaves as a "streaming server source".
· In combination with our Active Sound Recorder control, directly to an output file whose format can be predisposed inside Active Sound Recorder itself.

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 streaming server and, again at the same time, save what you are hearing into a file on your hard disk.

The first thing to do is to create an instance of the Stream Mixer: for this purpose you can use the StreamMixerCreate method: through this call you can pass the index of the output device that will be used in order to render the audio stream; the number and descriptions of available output devices can be obtained with a prior call to the GetOutputDevicesCount and GetOutputDeviceDesc methods; if no output device should be chosen (by passing -1 to the nOutput parameter), you could in any case output the audio stream to the Active Sound Recorder control or to a streaming server.

A successful call to the StreamMixerCreate method will return a unique identifier that will be used with other mixer-related methods calls. Once we have created an instance of the Stream Mixer and we have obtained back a unique identifier, we can start adding players to the instance of the Stream Mixer: for this purpose we need to call the StreamMixerPlayerAdd method; after this call the added player will no more send its audio stream to the output device chosen inside the InitDJSystem method but will redirect its audio stream into the Stream Mixer as seen in the graph above. A player can be removed from the Stream Mixer through the StreamMixerPlayerRemove method.

The unique identifier allows applying further effects to mixed streams, for example applying a custom DSP or modifying the Preamplifier volume: for this purpose the unique identifier can be used in place of the nPlayer parameter for all of the methods that will modify the output stream, like volume-related methods and all methods described inside the How to apply special effects to a playing sound tutorial. In the same way you have the possibility to redirect the mixed stream to a different output device through the StreamOutputDeviceSet method or to perform speakers management through the StreamOutputSpeakerSet method.

Another important feature is the possibility to create visual feedbacks that display sound levels of the stream mixer output: also in this case you simply have to use the unique identifier of the stream mixer as a replacement for the nPlayer parameter used with VUMeter, Spectrum, Oscilloscope and Waveform objects; this feature affects the VuMeterValueChange and SpectrumValueChange events as well: their nPlayer parameter will report the unique identifier of the stream mixer generating the event.

The mixed stream can be sent to a Shoutcast or Icecast server through the CastingCreateFromStreamMixer method followed by a call to the CastingStart method; casting can be stopped at any time through a call to the CastingStop method. For further details about audio stream casting take a look to the tutorial How to use the control as a source for Shoutcast/Icecast servers.

In order to save the mixed audio stream into an output file, we need to use our Active DJ Studio control in combination with our Active Sound Recorder control: the StartFromDjStudioMixer method of the recorder component will record the audio stream generated by the Stream Mixer and will encode it by using settings predisposed inside the EncodeFormats object of the recorder component itself.

Stream mixers created through the StreamMixerCreate method can be in Mono or Stereo only: in case you should need to create a multi-channel surround stream mixer you could use the StreamMixerCreateWithSurround method which allows to output mixed streams up to 8 channels: when using surround mode, the output of the stream mixer cannot be used as a source for casting sessions. When dealing with multi-channel surround stream mixers, you can add players to the instance of the Stream Mixer through the StreamMixerPlayerAddToSpeaker method which allows setting the specific speaker (channel) of the stream mixer used for outputting the player's audio stream.

IMPORTANT NOTICE ABOUT EFFECTS APPLIED TO THE OUTPUT OF THE STREAM MIXER BEING SENT TO A CASTING SERVER OR TO THE RECORDER

As mentioned before, you can apply a custom DSP or a VST effect to the output of the custom stream mixer by using the unique identifier of the custom stream mixer itself for the nPlayer parameter of the effect to apply; if you want that these effects are reflected to the stream going to the casting server or to the recorder control also, you need to set the nPriority parameter of the custom DSP or of the VST to a value higher than 0.

Samples of use of custom Stream Mixers in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- CastMixedStreams

- StreamMixer (requires the installation of Active Sound Suite)


How to play video files through DirectShow

How to play video files through DirectShow

DirectShow is a multimedia framework and API produced by Microsoft for software developers to perform various operations with media files or streams. Based on the Microsoft Windows Component Object Model (COM) framework, DirectShow provides a common interface for media across many programming languages, and is an extensible, filter-based framework that can render or record media files on demand.

IMPORTANT NOTE ABOUT DIRECTSHOW PERFORMANCES: Being based upon DirectX, DirectShow will perform better in presence of modern video cards supporting Direct3D and hardware acceleration. If the video card should not support these features, you may experience a huge CPU load during video rendering.

DirectShow divides a complex multimedia task like video playback into a sequence of fundamental processing steps known as "filters". Each filter, which represents one stage in the processing of the data, has input and/or output pins that may be used to connect the filter to other filters. The generic nature of this connection mechanism enables filters to be connected in various ways so as to implement different complex functions. To implement a specific complex task, a developer must first build a "filter graph" by creating instances of the required filters, and then connecting the filters together.

There are three main types of filters:

Source filters: These provide the source streams of data. For example, reading raw bytes from any media file.

Transform filters: These transform data that is provided from other filter's output. For example, doing a transform such as adding text on top of video or uncompressing an MPEG frame.

Renderer filters: These render the data. For example, sending audio to the sound card, drawing video on the screen or writing data to a file.

In the above example of filter graph, generated by the GraphEdt.exe application provided by Microsoft, from left to right, we can find a source filter to read an MP4 file and to split video and audio streams, decoder filters to parse and decode separated video and audio streams and, finally, rendering filters to play raw video and audio samples. Each filter has one or more pins that can be used to connect that filter to other filters. Every pin functions either as an output or input source for data to flow from one filter to another. Depending on the filter, data is either "pulled" from an input pin or "pushed" to an output pin in order to transfer data between filters. Each pin can only connect to one other pin and they have to agree on what kind of data they are sending.

By default, DirectShow includes a limited number of filters for decoding some common media file formats such as MPEG-1, MP3, Windows Media Audio, Windows Media Video, MIDI, media containers such as AVI, ASF, WAV, some splitters/demultiplexers, multiplexers, source and sink filters and some static image filters. However, DirectShow's standard format repertoire can be easily expanded by means of a variety of commercial and open source filters. Such filters enable DirectShow to support virtually any container format and any audio or video codec. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack, available in both x86 and x64 versions, and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT X86 AND X64 VERSIONS OF WINDOWS: When the container application is compiled for "Any CPU" or for "x64" and run on a x64 versions of Windows, in order to create the filters graph DirectShow automatically searches for x64 versions of the codecs; K-Lite Codec Pack comes with both x86 and x64 versions of its binaries so, when running on a x64 version of Windows, it's very important being sure that the x64 version is installed.

Active DJ Studio, through the embedded VideoPlayer COM object and the related VideoPlayer property, simplifies developers life by leveraging DirectShow technology in order to render video streams to a graphic surface and to manage contents of audio streams separately, allowing the possibility to apply most of audio features (special effects, output redirection, visual feedbacks, etc.) available for regular audio files.

IMPORTANT NOTE ABOUT CODECS AND FILTERS: By default, DirectShow includes a limited number of filters for decoding some common media file formats such as MPEG-1, MP3, Windows Media Audio, Windows Media Video, MIDI, media containers such as AVI, ASF, WAV, some splitters/demultiplexers, multiplexers, source and sink filters and some static image filters. However, DirectShow's standard format repertoire can be easily expanded by means of a variety of commercial and open source third-party filters. Such filters enable DirectShow to support virtually any container format and any audio or video codec. This obviously means that, when Active DJ Studio loads a video clip, most of the involved binary code is embedded inside external and third-party components: as you may understand, MultiMedia Soft cannot guarantee that filters provided by Microsoft or by third-party companies will always behave as expected: they could contain bugs or memory leaks and, in these cases, there is no workaround that MultiMedia Soft could apply in order to avoid this kind of problems; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

Before loading a video clip into a given player, we must decide how we will manage the output of the video stream and the output of the audio stream:

· Video stream output management: The video stream of video clips is rendered over a graphical surface, named "output video window", provided by an existing window, form or dialog box: you can create, position and size this output video window using the VideoPlayer.VideoWindowAdd method then you can move it through the VideoPlayer.VideoWindowMove method and hide/show it through the VideoPlayer.VideoWindowShow method. After having added the output window, you can change it through the VideoPlayer.VideoWindowChangeTarget method.

A couple of important notes:

· output video windows added when a video clip is already loaded into a player will be instanced only after loading a new video clip
· you can create more than one of these video windows through further calls to the VideoPlayer.VideoWindowAdd method: in this case the video stream will be reproduced in parallel and in perfect sync on all of the instanced video windows.
· if you simply need to playback the audio stream of the video clip, you don't need to create an output video window: if no output video window is found at playback time, the component will remove the video stream from the filter graph, allowing to save some CPU time
· if you simply want to render the video stream inside a floating window, the component can redirect the video stream to the "Active Movie" window provided by DirectShow: in this case you simply need to make a call to the VideoPlayer.VideoStreamSendToActiveMovieWin method without making any previous call to the VideoPlayer.VideoWindowAdd method.
· if you want to render the video clip in full screen mode, refer to the How to render video clips in full screen tutorial.

As you may know, Active DJ Studio gives the possibility to play more media files at the same time through the use of different players instanced by the InitDJSystem method: in case you should have the need to mix/blend the video output stream of two video clips inside the same output window, with full control over alpha channel transparency and positioning, refer to the How to use the video mixer tutorial.

· Audio stream output management: DirectShow sends the audio stream to the system default DirectSound device as seen inside the filter graph above by instancing the "Default DirectSound Device" audio renderer filter; Active DJ Studio replaces the default audio renderer filter with its own renderer filter allowing a better control over audio stream playback; there are three main modes for audio management that can be set through the VideoPlayer.AudioRendererModeSet method:

· Custom audio management: this is the default one and allows applying most of audio features (special effects, output redirection, visual feedbacks, support for ASIO devices, etc.) available for regular audio files by using exactly same methods like StreamVolumeLevelSet, StreamOutputDeviceSet, etc.; the unique drawback of this feature is that it will cost some more CPU (around 5-10%) in order to be achieved.
· DirectSound standard management: respect to the default DirectShow implementation, this management allows redirecting the audio output to a specific DirectSound device through the VideoPlayer.AudioRendererDsDeviceSet method and to control volume and balance of the audio stream. Available DirectSound output devices registered as DirectShow audio renderers can be enumerated through the VideoPlayer.AudioRendererDsDeviceGetCount and VideoPlayer.AudioRendererDsDeviceGetDesc methods.
· Null rendering: in cases where only the video stream is needed, allows removing the audio stream from the filter graph and to save some CPU time.

IMPORTANT NOTE ABOUT AUDIO AND VIDEO SYNC: As mentioned above, in order to allow applying special effects to the audio stream of video clips, Active DJ Studio implements its own audio renderer which is different respect to the one used by other players like "Windows Media Player™": by default the audio stream has a 200 milliseconds delay respect to the video stream because this works better when dealing with the majority of audio drivers and is not much noticeable on modern PCs having LCD monitors instead of CRT monitors; in case this should be noticeable on your side, you could use the VideoPlayer.AudioRendererDelaySet method in order to remove/reduce this delay: this method accepts delays in the range from -200 to +500 (expressed in milliseconds); in case the video stream should be rendered in advance respect to the audio stream, a negative delay (for example -150) could remove the gap.

With certain "poor quality" sound card drivers the usage of a negative delay could cause sound stuttering so, as a general rule, due to the fact that depending upon the target machine the audio delay may have different behaviour, it's always suggested providing a setting, driven through a slider control, that would allow fine-tuning this delay on customers machines.

As a further note, when the InitDriversType method has been called with a parameter different from the default DRIVER_TYPE_DIRECT_SOUND, when dealing specifically with DirectSound devices a further improvement could be obtained by reducing the size of the DirectSound buffer through the BufferLength property from the default 500 ms to a value around 170 ms: this would reduce latency caused by the filling of DirectSound buffers and could impact on the audio delay.

As a final note, in case suggestions above shouldn't be enough, the best way to have the audio always in sync would be avoiding the usage of the default audio renderer of Active DJ Studio but using the default DirectSound audio renderer: as seen inside the VideoPlayerSimple sample, installed with our setup package, the audio renderer can be changed through the VideoPlayer.AudioRendererModeSet method by setting the value of the nMode parameter to AUDIO_RENDERER_MODE_CUSTOM_2 or to AUDIO_RENDERER_MODE_DS_STANDARD. In this cases, depending upon the chosen mode, you would obviously loose some of the audio related features.

A video clip can be loaded into an instanced player using the VideoPlayer.Load, VideoPlayer.LoadForTempoChange or VideoPlayer.LoadForEAX methods; depending upon the codec and the duration of the video clip to load, due to the fact that the loading is performed inside the main application's thread, the call to this method could cause a temporary freeze of the container application user interface: in order to avoid this issue, the use of the VideoPlayer.LoadSync, VideoPlayer.LoadSyncForTempoChange or VideoPlayer.LoadSyncForEAX methods should be preferred; when using "Sync" methods, it's recommended triggering the SoundSyncLoaded event before making further calls for starting playback or for obtaining information about the loaded video.

After loading the video clip, you can start its playback using the VideoPlayer.Play method. As for audio streams, you have various methods for controlling playback like VideoPlayer.Pause, VideoPlayer.Resume and VideoPlayer.Stop.

With certain codecs, and only if VideoPlayer.IsSeekable returns "true", there is the possibility to change the current playback position through the VideoPlayer.Seek method; you can also forward and rewind the playback position of a predefined amount through the VideoPlayer.Forward and VideoPlayer.Rewind methods and, when a video clip is paused or stopped, you can instruct the player to step by single frames back and forth through the VideoPlayer.SeekToPreviousFrame and VideoPlayer.SeekToNextFrame methods.

Once a video clip has been loaded, you can obtain a number of information about it:

· Duration through the VideoPlayer.DurationGet method
· Native aspect ratio through the VideoPlayer.GetAspectRatio method.
· Native dimensions in pixels through the VideoPlayer.GetNativeSize method; due to the fact that ratio of native dimensions may vary depending upon the video ratio (for example it could be 4:3 or 16:9), the control gives the possibility to keep original aspect ratio during video stream rendering through the VideoPlayer.VideoStreamKeepAspectRatio method.
· Availability of the video stream through the VideoPlayer.IsVideoStreamAvailable method.
· Availability of the audio stream through the VideoPlayer.IsAudioStreamAvailable method.
· Total number of video frames through the VideoPlayer.FramesNumberGet method.
· Average video frames rate through the VideoPlayer.FramesAverageRateGet method.
· Codec used to decode the video stream through the VideoPlayer.CodecVideoDescGet method.
· Codec used to decode the audio stream through the VideoPlayer.CodecAudioDescGet method.
· During playback, the current position through the VideoPlayer.PositionGet method.

For video formats supporting multiple audio streams, you can know if the loaded video clip has more than one audio stream inside using the VideoPlayer.AudioMultiStreamCheck method and enumerate available audio streams through the combinations of the VideoPlayer.AudioMultiStreamGetCount and VideoPlayer.AudioMultiStreamGetName method. The current audio stream can be changed using the VideoPlayer.AudioMultiStreamSelect method.

Active DJ Studio gives the possibility to grab single video frames and store them into a graphical output file (in GIF, PNG, JPEG, BMP and TIFF format) or into a memory bitmap: refer to the How to grab frames from video files tutorial for details.

Active DJ Studio gives also the possibility to extract the audio stream, in WAV PCM format, into a memory buffer or into a temporary file through the VideoPlayer.AudioTrackExtract method; the availability of the extracted audio stream, allows performing the following further operations:

· Sound waveform analysis: see the How to obtain the sound's waveform tutorial for details
· Detection of initial and final silence positions: through the SilenceDetectionOnPlayerRequest or the SilenceDetectionOnPlayer methods.
· Detection of beats per minute (BPM): through the RequestSoundBPM method.
· Direct access to the extracted audio stream through the VideoPlayer.AudioTrackGetMemoryPtr and VideoPlayer.AudioTrackGetMemorySize methods, when the audio stream is extracted into a memory buffer, or through the VideoPlayer.AudioTrackGetTempFilePathname and VideoPlayer.AudioTrackGetTempFileSize methods, when the audio stream is extracted into a temporary file.

When the video clip is no more needed, you can discard it from memory calling the VideoPlayer.Close method. As a side note, calling this method is not needed when loading a new video clip because it will be called internally by the control.

NOTE ABOUT TEMPO AND PLAYBACK RATE CHANGE: It's important to note that not all of the video codecs are able to manage playback rate change correctly: for example certain kind of AVI codecs will loose synchronism between audio and video when calling the Effects.PlaybackTempoSet or the Effects.PlaybackRateSet methods: this is not a limitation of our control but a defect of the codec when running the video at a speed different than normal. Furthermore, other video codecs are not fast enough in order to provide enough PCM sound data for tempo and/or playback rate change so you could experience "stuttering" during playback: when dealing with codecs that cause stuttering during playback it would be a better solution avoiding the use of the VideoPlayer.LoadForTempoChange method and to prefer the use of the VideoPlayer.Load method.

With regards to the filters graph created after loading the video clip, you have the possibility to enumerate all of the available filters through the VideoPlayer.FiltersInGraphGetCount and VideoPlayer.FiltersInGraphGetName methods and determine, for each of them, the class identifier through the VideoPlayer.FiltersInGraphGetClsid method and the availability of a property page through the VideoPlayer.FiltersInGraphHasPropertyPage; if the property page should be available, it could be displayed through the VideoPlayer.FiltersInGraphShowPropertyPage method: in this way you could programmatically give access to specific settings of the filter.

In case you should need to take a screenshot of what it's currently being played on a specific video window, you may use the VideoPlayer.ScreenshotSaveToFile method.

Active DJ Studio comes with a custom transform filter which allows applying adjustments to video frames when the video source decoder supports the YUY2 color space; supported adjustments are Brightness, Contrast, Saturation, Hue and Gamma Correction. Image adjustment can be enabled, through the VideoPlayer.ImageAdjustEnable method and the value of each of the available adjustments can be retrieved or modified through the VideoPlayer.ImageAdjustPropertyGet and VideoPlayer.ImageAdjustPropertySet methods.

Another feature of the just mentioned custom transform filter is the possibility to display an On-Screen-Display (also known as OSD) which allows rendering a composition of graphical objects (mainly bitmaps and text) over video clips being played. It's important to note that the OSD of the video player (differently from the one available on the VideoMixer object) will be always sized accordingly to the native dimensions of the video clip being played so, when resizing the output window or going full screen, the OSD will be automatically scaled to best fit the area of the output window and the size of contained graphical objects will be scaled as well.

The OSD can be enabled/disabled through the VideoPlayer.OSDEnable method: when the OSD is disabled it doesn't appear on the screen. You can know if the OSD is enabled or disabled through the VideoPlayer.OSDIsEnabled method.

In order to avoid covering the video clips being played, through the VideoPlayer.OSDKeyColorSet method you can define a key color that will be always rendered as totally transparent on the OSD; for example, you could create a bitmap with a black background like the one below:

By setting the key color to "black", the bitmap would be rendered on the video frames as seen on the screenshot below:

Graphical objects (also known as "items") that can be added to compose the OSD are:

· Picture files: you can add a picture file through the VideoPlayer.OSDItemPictureFileAdd method and to change the picture through the VideoPlayer.OSDItemPictureFileChange method.
· Picture files stored in memory: you can add a picture file stored inside a memory buffer through the VideoPlayer.OSDItemPictureMemoryAdd method and to change the picture through the VideoPlayer.OSDItemPictureMemoryChange method.
· Bitmaps: you can add a bitmap stored in memory, accessible through its HBITMAP handle, through the VideoPlayer.OSDItemBitmapAdd method and to change the bitmap through the VideoPlayer.OSDItemBitmapChangemethod.
· Strings of text: you can add a string of text through the VideoPlayer.OSDItemTextAdd method and to change the string characters through the VideoPlayer.OSDItemTextChange method. With mentioned methods you can also define both color and font for each single string of text.
· Outlined strings of text: you can add an outlined string of text through the VideoPlayer.OSDItemOutlineTextAdd method and to change the string characters through the VideoPlayer.OSDItemOutlineTextChange method. With mentioned methods you can also define both color and font for each single string of text.
· Rectangles: you can add a rectangle through the VideoPlayer.OSDItemRectangleAdd method and to change its size and color through the VideoPlayer.OSDItemRectangleChange method.

You have no limit on the number of items you can add to the OSD but, keep in mind, the bigger the number of objects, the higher will be the CPU load if you should animate the OSD contents, for example for scrolling a text item.

After adding a picture item from a file or from a memory buffer or from a HBITMAP handle, there is the possibility to obtain back the handle (HBITMAP) to a memory bitmap, eventually resized to custom dimensions, through the VideoPlayer.OSDItemBitmapGet method.

Each item has the following set of properties:

· Position: the VideoPlayer.OSDItemMove and the VideoPlayer.OSDItemScrollByPixels methods can move the position of each item: this allows "animating" the OSD, for example for scrolling the item horizontally or vertically. After every position change, you can know if the item is still visible on the video rendering window through the VideoPlayer.OSDItemIsOnVisibleArea method.The rectangle surrounding the item, with coordinates and size expressed in percentage of the video clip dimensions, used by a specific item can be obtained through the VideoPlayer.OSDItemRectGet method; this is quite useful for items containing a string of text whose total size, in terms of width and height, depends upon the chosen font size.
· Z-Order: the VideoPlayer.OSDItemZOrderSet method determines which item will appear on top of the other.
· Visibility: the VideoPlayer.OSDItemShow method shows/hides the item.
· Transparency: the VideoPlayer.OSDItemAlphaSet allows changing the alpha channel transparency of the item so it will not totally cover what's behind its position.

Each item can be removed at any time from the list of items through the VideoPlayer.OSDItemRemove method.

If available graphical features of the OSD shouldn't be enough for you, don't forget that you could make a custom graphical rendering inside a memory bitmap through Windows GDI or GDI+ API and then you could display the resulting bitmap, through its HBITMAP handle, in one single shot through the VideoPlayer.OSDItemBitmapAdd method and to update it in real time through the VideoPlayer.OSDItemBitmapChange method.

Examples of use of the VideoPlayer object in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- AsioVideoPlayer

- VideoMixer

- VideoPlayerSimple

- VideoPlayerAdvanced (contains an example of usage of image adjustments and of the On Screen Display)

- VideoPlayerMultipleOutout

- VideoWaveform


How to render video clips in full screen

How to render video clips in full screen

Inside the How to play video files through DirectShow tutorial we have seen how to load and play a video clip with a video player embedded inside Active DJ Studio: now we will see how to allow rendering video clips in full screen on a single monitor system or in a multi-monitor system.

Although DirectShow comes with a dedicate API for rendering in full screen the video renderer filter through the put_FullScreenMode method of the IVideoWindow interface, it has been found that using this approach may give several problems on Windows Vista and higher versions and would limit the possibility to go in full screen to one single monitor only so it has been decided to follow a custom solution.

The custom solution requires the container application to provide one or more borderless forms, one for each of the monitors to use, that will be used as a target window for rendering the video frames in full screen: the resizing of the form, in order to occupy the full surface of the monitor, will be managed by the component directly.

The main benefit of this custom approach is the possibility to go in full screen not only on one single monitor but in more than one monitor at the same time: the configuration of monitors to use depends upon the needs of the developer.

As a further benefit, this solution allows managing the way the full screen form will be closed by adding specific code into the container form itself: for example you could hide the full screen form through the “ESC” button on the keyboard or by double-clicking the video in full screen with the mouse. You may also add a context menu to activate when the right mouse button is pressed on the video surface.

Multi-monitor management and positioning can be activated and configured in several ways, for example through the "Display" applet of the Windows control panel or, if provided, through a specific application developed by the video card manufacturer as in the case of NVIDIA video cards whose latest driver installs the "NVIDIA contro panel". As you can see on the screenshots below, a dual monitor configuration can be managed by enabling the secondary monitor to extend the Windows desktop on its surface and by positioning the secondary monitor on the left or on the right or on any other position respect to the primary monitor:

in the sample above the primary monitor has a size of 1920×1200 pixels while the secondary monitor has a size of 1280x1024 pixels; while the primary monitor will always keep its coordinates (0, 0), the positioning of the secondary monitor will determine its screen coordinates; on the picture below, corresponding to the central picture of the screenshot above, you can see that the horizontal coordinate of the secondary monitor assumes a negative value; on the picture below, corresponding to the central picture of the screenshot above, you can see that the horizontal coordinate of the secondary monitor assumes a negative value.

After having configured the multi-monitor system as described above, Active DJ Studio allows retrieving the multi-monitor configuration with a set of dedicated methods:

· The number of configured monitors that could be used for going full screen through the VideoPlayer.FullscreenMonitorCountGet method
· The friendly name assigned to each monitor by the system through the VideoPlayer.FullscreenMonitorNameGet method
· The positioning, expressed in screen coordinates, and the size, expressed in pixels, of each monitor through the VideoPlayer.FullscreenMonitorPositionGet method

As mentioned at the beginning of this tutorial, the container application needs to provide one or more borderless forms, one for each of the monitors to use, that will be used as a target window for rendering the video frames in full screen: the container application doesn't have to mind about the positioning and size of these borderless forms because this will be managed automatically and internally by the component.

After having enumerated the available monitors you can predispose each of them for going full screen: through the VideoPlayer.FullscreenMonitorPredispose method you can tell to the component which of the borderless forms instanced by the container application will be used for rendering the video clip in full screen; note that the call to this method will not immediately start the full screen rendering: for this purpose you will have to call the VideoPlayer.FullscreenMonitorActivate method at a later time and the same method could be also used to exit the full screen mode. You can programmatically know if a specific monitor is currently rendering a video clip in full screen through the VideoPlayer.FullscreenMonitorIsActivated method.

Once you won't need anymore using a specific monitor for full screen rendering, you could remove it from the list of predisposed monitors and save some resource through the VideoPlayer.FullscreenMonitorRemove method.

During the life of the container application, the monitor configuration could be manually changed, for example by moving the secondary screen to a different position respect to the primary monitor or by disabling the desktop's extension on the secondary monitor: the component can detect when the configuration of system monitors changes and inform the container application of the change through the DisplayConfigurationChanged event: when this situation happens, the rendering of the video clip could result frozen so the following operations will be needed:

· closing the video clip through the VideoPlayer.Close method
· if one or more monitors were already rendering in full screen, deactivating the full screen mode for each of them through the VideoPlayer.FullscreenMonitorActivate method
· removing all of the predisposed monitors through the VideoPlayer.FullscreenMonitorRemove method
· predisposing again the needed monitors through the VideoPlayer.FullscreenMonitorPredispose method
· reloading the video clip (for example through the VideoPlayer.Load method) in order to create an updated filters graph that will take count of the new monitors.

An example of use of full screen and multi-monitor management in Visual Basic 6 and Visual C++ 6 can be found inside the VideoPlayerAdvanced sample installed with the product's setup package; this sample shows also how the container application can allocate and provide the borderless forms used for going full screen and how to manage an eventual change of the monitors configuration.


How to grab frames from video files

How to grab frames from video files

Inside the How to play video files through DirectShow tutorial we have seen how to load and play a video clip with a video player embedded inside Active DJ Studio and we have also seen how to extract the audio track from the same video clip: now we will see how to extract single or multiple video frames and how to store them inside a picture file on the hard disk or inside a memory bitmap.

After having loaded the video clip, through one of the provided loading methods like VideoPlayer.Load, we need to initialize the frame grabber internal to a certain player through a call to the VideoPlayer.FrameGrabberInit method. At this point we must decide what we want to obtain:

· If we need to store grabbed frames into picture files, we will have to use the VideoPlayer.FrameGrabberExecToFile method.
· If we need to store grabbed frames into memory bitmaps (accessible through their HBITMAP handle) we will have to use the VideoPlayer.FrameGrabberExecToMemory method.

In both cases we have to set a range within the video clip where grabbing will occur; we certainly need to set a starting position (nStartPosition parameter) and then we need to set the final position where grabbing will end: for this purpose we have two options:

· we can grab a range expressed in milliseconds: this is obtained by setting the nStopType parameter to VIDEOGRABBER_STOP_POSITION and by setting the nEndPosition parameter to the position in milliseconds where we want to terminate the grabbing session; for example, if we would like to grab all of the frames contained in the range between 10 and 15 seconds of the video clip, we would set the nStartPosition parameter to 10000 and the nEndPosition parameter to 15000; in case we should need to grab all of the frames till the end of the video clip, we would have to set the nEndPosition parameter to -1.
· we can grab a range expressed in number of frames: this is obtained by setting the nStopType parameter to VIDEOGRABBER_STOP_FRAMES_NUM and by setting the nNumberOfFrames parameter to the number of frames we want to grab starting from the initial position; for example, if we would like to grab one single frame positioned at 10 seconds of the video clip, we would have to set the nStartPosition parameter to 10000 and the nNumberOfFrames parameter to 1 while, if we would like to grab the first 10 frames, again starting from the same position, we would set the nNumberOfFrames parameter to 10; in case we should need to grab all of the frames till the end of the video clip, we would have to set the nNumberOfFrames parameter to -1.

When the grabbing is started using the VideoPlayer.FrameGrabberExecToFile method we can also specify the graphical format of the pictures files created during the grabbing session; supported formats are the following: BMP, JPEG, PNG, GIF, TIFF and TIFF Multipage: when using "TIFF Multipage" all of the grabbed frames are obviously stored inside a single file.

After completing the grabbing session, we can check results through the following methods:

· we can know if the grabbing session stored frames in picture files or in memory bitmaps through the return value of the VideoPlayer.FrameGrabberResultsGetAvailableType method.
· If the return value should be TYPE_OF_GRABBED_FRAME_FILES, this would mean that grabbed frames are now stored inside graphical picture files which can be enumerated through the combination of the VideoPlayer.FrameGrabberResultsGetFilesCount and VideoPlayer.FrameGrabberResultsGetFilePathname methods.
· If the return value should be TYPE_OF_GRABBED_FRAME_BITMAPS, this would mean that grabbed frames are now stored inside memory bitmaps (HBITMAP) which can be enumerated through the combination of the VideoPlayer.FrameGrabberResultsGetBitmapsCount and VideoPlayer.FrameGrabberResultsGetBitmap methods.
· In both cases, for each grabbed frame we can obtain the color of a specific pixel at given coordinates through the use of the VideoPlayer.FrameGrabberResultsGetPixelColor method.

The component gives also the possibility to resize output pictures to custom dimensions respect to the original dimensions of the video frames through the VideoPlayer.FrameGrabberOutputResizeSet method.

In case you should simply need to take a screenshot of what it's currently being played on a specific video window, you may use the VideoPlayer.ScreenshotSaveToFile method.

An example of use of the frame grabber in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- VideoFrameGrabber


How to use the video mixer

How to use the video mixer

As explained inside the How to play video files through DirectShow tutorial, Active DJ Studio allows rendering video clips inside output video windows so each player can have one or more output video windows added for this specific purpose; through a specific filter named VMR-9, introduced with version 9 of DirectX, DirectShow gives the possibility to render two or more video clips inside the same output video window at the same time and Active DJ Studio, through the embedded VideoMixer COM object and the related VideoMixer property, leverages the VMR-9 filter in order to provide mixing/blending capabilities to loaded video clips.

A VideoMixer object can be created and sized through the VideoMixer.Create method on a given output window: this method will return a unique identifier that will be used in every other call related to this specific VideoMixer object. Only one instance of the video mixer can be created during the life of the container application.

Once the VideoMixer object has been created, you can attach instanced players to the video mixer through the VideoPlayer.AttachToVideoMixer method so, each time a video clip is loaded inside a player through a video loading method (like VideoPlayer.Load and VideoPlayer.LoadSync methods), the video stream output will be automatically redirected to the VideoMixer output window: it's important to note that, if you should have already added a video output window to a specific player through a previous call to the VideoPlayer.VideoWindowAdd method, you could obtain a preview window of the same video clip, perfectly in sync with the one being rendered on the video mixer output window. A specific player can be detached from a VideoMixer at any time through the VideoPlayer.DetachFromVideoMixer method.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to methods like VideoPlayer.Load could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

As for the VideoPlayer object, the VideoMixer object allows resizing its output window through the VideoMixer.Move method and to hide/show the output window through the VideoMixer.Show method. Contents of the VideoMixer can be discarded through the VideoMixer.Reset method and the VideoMixer object itself can be totally destroyed through the VideoMixer.Destroy method: after this call its unique identifier becomes invalid and no other operations will be available for this specific VideoMixer.

By default the background color of the VideoMixer, visible when no clip is in playback, is set to black but you can change this color through the VideoMixer.BackgroundColorSet method.

When two or more video clips are being rendered on a video mixer, you can set the Z-Order, determining which player will appear on top of the other, through the VideoMixer.PlayerZOrderSet method: players with a lower Z-Order value will stay on top respect to other players having a higher Z-Order value; for example, a player with Z-Order 0 will stay on top of any other player but, in case two players should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one. If a player is currently playing a video clip inside the VideoMixer, by loading a new video clip inside another player you would certainly like to avoid covering the playing one: for this reason it's always suggested that you assign a higher Z-Order to the player loading a new video clip and to assign Z-Order 0 only when you really want a specific player to stay on top of others.

Now we know how to determine players Z-Order but we still need to know how to smoothly fade-out a playing video clip and fade-in a new video clip loaded inside a second player: fade-in/fade-out of video streams can be controlled through the VideoMixer.PlayerAlphaSet method, allowing to change the alpha channel transparency of a specific player. In order to better understand how to put things together, imagine the following scenario:

1. The control allocates, through the InitDJSystem, two players (named PlayerA and PlayerB).

2. PlayerA is attached to the VideoMixer through a call to VideoPlayer.AttachToVideoMixer method.

3. PlayerB is attached to the VideoMixer through a call to VideoPlayer.AttachToVideoMixer method.

4. PlayerA is placed on top of the Z-Order through a call to the VideoMixer.PlayerZOrderSet method while PlayerB is placed on bottom of the Z-Order by setting any value higher than 0.

5. PlayerA loads a video clip through the VideoPlayer.Load method and starts playback through the VideoPlayer.Play method.

6. After a while, PlayerB loads a video clip through the VideoPlayer.Load method and starts playback through the VideoPlayer.Play method: having a higher Z-Order respect to PlayerA, it will not cover the video clip played by PlayerA itself.

7. When we need to fade-out PlayerA, using a slider or an automated procedure controlled by a timer, we smoothly increase its alpha channel transparency through the VideoMixer.PlayerAlphaSet method: during this transparency sliding, we will start seeing in transparency what is played by PlayerB and, when the transparency sliding will reach maximum transparency, we will only see what is played by PlayerB.

8. We can now loop, by inverting PlayerA and PlayerB, to point 4.

This is only an example of possible uses of Z-Order and alpha channel transparency combination but you could adapt this procedure to your specific needs without issues of sort: for example, instead of calling the VideoPlayer.Load method for both players and using timers for sliding the alpha channel transparency, you could use the video mixer in combination with the Automatic Fader and, eventually, with playlists management; at this point you could for example apply the alpha channel transparency in combination with automatic volume modifications notified through the FadingVolumeChanged event. A possible implementation of this approach is briefly explained inside the tutorial How to combine the video mixer and the automatic fader.

Another feature allowed by the VideoMixer object, is the possibility to modify the rectangle enclosing the video stream rendering of a specific player: this rectangle is known as "normalized rectangle" and its coordinates are expressed in percentage respect to actual size of the VideoMixer output window: this allows keeping the same aspect ratio when the VideoMixer output window is resized during playback. The VideoMixer.PlayerNormalizedRectSet method allow modifying the normalized rectangle for a specific player and the VideoMixer.PlayerNormalizedRectSetIdeal allows setting a normalized rectangle that will best fit into the VideoMixer the original dimensions of the loaded video clip so, if for example the video clip is in 16:9, it will maintain its original aspect ratio.

An interesting feature of normalized rectangles is the possibility to create the so called "Picture-In-Picture" effect by using a player to render its video clip on the full VideoMixer output window and another player to render its video clip inside a smaller rectangle inside the same VideoMixer output window.

Another feature of the VideoMixer object is the possibility to display an On-Screen-Display (also known as OSD) which allows rendering a composition of graphical objects (mainly bitmaps and text) over video clips being played.

IMPORTANT NOTE ABOUT OSD BEHAVIOUR: We have already seen the OSD feature available for the VideoPlayer object but with the VideoMixer object the approach is a bit different; the OSD of the VideoPlayer object is implemented through a custom transform filter which is placed "upstream" respect to the video rendering window inside the DirectShow filters graph so graphical items of the OSD are rendered directly inside video frames: as you will understand, in case the output rendering window should be resized, graphical items will be scaled accordingly because they have already been merged into the frame; differently from the described case, the OSD of the VideoMixer object is implemented directly on the output window of the VMR-9 video renderer so, when resizing this output window, the OSD will be automatically scaled to best fit the area of the window but the size of contained graphical items won't be scaled and will keep their original dimensions.

The OSD can be enabled/disabled through the VideoMixer.OSDEnable method: when the OSD is disabled it doesn't appear on the screen. You can know if the OSD is enabled or disabled through the VideoMixer.OSDIsEnabled method. As for video clips, also the rectangle of the OSD can be normalized, in this case through the VideoMixer.OSDNormalizedRectSet method.

In order to avoid covering the video clips being played, through the VideoMixer.OSDKeyColorSet method you can define a key color that will be always rendered as totally transparent on the OSD; for example, you could create a bitmap with a black background like the one below:

By setting the key color to "black", the bitmap would be rendered on the video mixer as seen on the screenshot below:

Graphical objects (also known as "items") that can be added to compose the OSD are:

· Picture files: you can add a picture file through the VideoMixer.OSDItemPictureFileAdd method and to change the picture through the VideoMixer.OSDItemPictureFileChange method.
· Picture files stored in memory: you can add a picture file stored inside a memory buffer through the VideoMixer.OSDItemPictureMemoryAdd method and to change the picture through the VideoMixer.OSDItemPictureMemoryChange method.
· Bitmaps: you can add a bitmap stored in memory, accessible through its HBITMAP handle, through the VideoMixer.OSDItemBitmapAdd method and to change the bitmap through the VideoMixer.OSDItemBitmapChange method.
· Strings of text: you can add a string of text through the VideoMixer.OSDItemTextAdd method and to change the string characters through the VideoMixer.OSDItemTextChange method. With mentioned methods you can also define both color and font for each single string of text.
· Outlined strings of text: you can add an outlined string of text through the VideoMixer.OSDItemOutlineTextAdd method and to change the string characters through the VideoMixer.OSDItemOutlineTextChange method. With mentioned methods you can also define both color and font for each single string of text.
· Rectangles: you can add a rectangle through the VideoMixer.OSDItemRectangleAdd method and to change its size and color through the VideoMixer.OSDItemRectangleChange method.

You have no limit on the number of items you can add to the OSD but, keep in mind, the bigger the number of objects, the higher will be the CPU load if you should animate the OSD contents, for example for scrolling a text item.

After adding a picture item from a file or from a memory buffer or from a HBITMAP handle, there is the possibility to obtain back the handle (HBITMAP) to a memory bitmap, eventually resized to custom dimensions, through the VideoMixer.OSDItemBitmapGet method.

Each item has the following set of properties:

· Position: the VideoMixer.OSDItemMove and the VideoMixer.OSDItemScrollByPixels methods can move the position of each item: this allows "animating" the OSD, for example for scrolling the item horizontally or vertically. After every position change, you can know if the item is still visible on the VideoMixer area through the VideoMixer.OSDItemIsOnVisibleArea method. The possibility to move an item automatically can be achieved through the VideoMixer.OSDItemMovementSet method. You can also obtain the normalized rectangle, with coordinates and size expressed in percentage, used by a specific item through the VideoMixer.OSDItemNormalizedRectGet method; this is quite useful for items containing a string of text whose total size, in terms of width and height, depends upon the chosen font size.
· Z-Order: the VideoMixer.OSDItemZOrderSet method determines which item will appear on top of the other.
· Visibility: the VideoMixer.OSDItemShow method shows/hides the item.
· Transparency: the VideoMixer.OSDItemAlphaSet allows changing the alpha channel transparency of the item so it will not totally cover what's behind its position.

Each item can be removed at any time from the list of items through the VideoMixer.OSDItemRemove method.

If available graphical features of the OSD shouldn't be enough for you, don't forget that you could make a custom graphical rendering inside a memory bitmap through Windows GDI or GDI+ API and then you could display the resulting bitmap, through its HBITMAP handle, in one single shot through the VideoMixer.OSDItemBitmapAdd method and to update it in real time through the VideoMixer.OSDItemBitmapChange method.

A last feature of the OSD is the capability to display a background picture through the VideoMixer.OSDBackgroundPictureFileSet method or a memory bitmap through the VideoMixer.OSDBackgroundBitmapSet method: the picture file or memory bitmap will be always rendered under any other item added to the OSD.

IMPORTANT NOTE ABOUT RUNNING THE WINDOWS TASK MANAGER AND SCREENSAVERS: When the video mixer is running, it would be convenient to avoid the usage of the "Ctrl+Alt+Del" keyboard combination in order to open the Windows task manager because this could cause a temporary disconnection of the video renderer: when you need opening the Windows task manager, while the video mixer is running, you should prefer the usage of the "Ctrl+Shift+Esc" keyboard combination.

For the same reason, while the video mixer is running, it's highly recommended to avoid the usage of a screensaver.

In case you should need to take a screenshot of what it's currently being played on the window of a specific video mixer, you may use the VideoMixer.ScreenshotSaveToFile method.

A sample of use of the VideoMixer object in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- VideoMixer


How to combine the video mixer and the automatic fader

How to combine the video mixer and the automatic fader

Inside the previous tutorial How to use the video mixer we have seen how two video players can mix the output of their respective video streams in one single window and inside the tutorial How to use the Automatic Fader we have seen how two players can fade two audio streams on the same speakers of a specific sound card: now we will see how these two features could be combined together in order to create a video mixer that will support the fading of both audio and video streams at the same time.

The easiest approach for implementing this feature is probably linking the volume level of the player fading-out, on the top of the Z-order (meaning that it will by default cover the video stream of the player fading-in), with the alpha channel transparency of its video stream: while the volume on this player is fading down, we raise the transparency level of the related video stream so the video stream of the player fading-in, which is at the bottom of the Z-Order, appears through until the video stream of the player fading-out totally disappears when its volume level reaches level 0.

Let's see in detail how we could proceed; first of all we need to initialize the control by instancing two players and initialize and instruct the automatic fader in order to manage one single playlist whose items will be played by the two players: for video clips, both players are set to work with the AUDIO_RENDERER_MODE_CUSTOM_2 audio rendering mode, allowing a better synchronization between audio and video stream.

Visual Basic 6

' init the control

Amp3dj1.InitDJSystem 2, Me.hWnd, 0, 0, 0, 0

' initialize the fader which will use this single playlist split for player 1 and player 2

Amp3dj1.Fader.PlayListUseSingle Player_1

Amp3dj1.Fader.Init FADE_SINGLE_PLAYLIST, Player_1, Player_2

' set the audio rendering mode

Amp3dj1.VideoPlayer.AudioRendererModeSet Player_1, AUDIO_RENDERER_MODE_CUSTOM_2

Amp3dj1.VideoPlayer.AudioRendererModeSet Player_2, AUDIO_RENDERER_MODE_CUSTOM_2

Visual C++

// init the control

Amp3dj1.InitDJSystem(2,(long)this->m_hWnd, 0, 0, 0, 0);

// initialize the fader which will use this single playlist split for player 1 and player 2

Amp3dj1.GetFader().PlayListUseSingle (Player_1);

Amp3dj1.GetFader().Init (FADE_SINGLE_PLAYLIST, Player_1, Player_2);

// set the audio rendering mode

Amp3dj1.GetVideoPlayer().AudioRendererModeSet (Player_1, AUDIO_RENDERER_MODE_CUSTOM_2);

Amp3dj1.GetVideoPlayer().AudioRendererModeSet (Player_2, AUDIO_RENDERER_MODE_CUSTOM_2);

For Visual Basic 6 it's recommended adding the code above into the Form_Load handler of the container form while for Visual C++ it's recommended adding the code below into the OnInitDialog (WM_INITDIALOG Windows message) handler of the container dialog box.

Now we can continue by creating the video mixer into a secondary form, whose client area will be totally covered by the video mixer surface, and attach the two players:

Visual Basic 6

' set scale mode to pixels

Me.ScaleMode = 3

FormMixer.ScaleMode = 3

' create the video mixer object into a secondary form (FormMixer) and get back its unique identifier

m_nMixerUniqueID = Amp3dj1.VideoMixer.Create(FormMixer.hWnd, 0, 0, FormMixer.ScaleWidth, FormMixer.ScaleHeight, RGB(0, 0, 0))

' attach the 2 instanced players to the VideoMixer object

Amp3dj1.VideoPlayer.AttachToVideoMixer Player_1, m_nMixerUniqueID

Amp3dj1.VideoPlayer.AttachToVideoMixer Player_2, m_nMixerUniqueID

' initialize a variable that will store the index of the player currently fading-out

m_nPlayerFadingOut = -1

Visual C++

// create the video mixer object and get back its unique identifier

CRect rect;

pMixerDlg->GetClientRect(rect);

m_nMixerUniqueID = Amp3dj1.GetVideoMixer().Create ((long)pMixerDlg->m_hWnd, 0, rect.Width(), rect.Height(), RGB(0, 0, 0));

// attach the 2 instanced players to the VideoMixer object

Amp3dj1.GetVideoPlayer().AttachToVideoMixer(Player_1, m_nMixerUniqueID);

Amp3dj1.GetVideoPlayer().AttachToVideoMixer(Player_2, m_nMixerUniqueID);

// initialize a variable that will store the index of the player currently fading-out

m_nPlayerFadingOut = -1;

we have also initialized a variable, named m_nPlayerFadingOut, that will store the index of the player currently fading-out; this will be useful later to determine the player that will need its alpha channel transparency to be modified. You may notice the absence of the video preview window for the involved video players: the presence of the preview windows requires an amount of CPU which is probably not justified for this specific situation where all should be automated so omitting its creation may be a good idea.

Now we could proceed with loading a playlist but we still need to decide if we want to work with standard playlist formats, like M3U, PLS and WPL, which don't contain any automation information (so we will totally rely upon settings of the automatic fader) or if we prefer working with the PDJ playlist format which allows creating very customized automations. The difference here is quite important because, differently from audio clips whose duration can be determined on the fly, with video clips we cannot automatically obtain the duration because building filters graph through DirectShow is a lengthy operation that would require a huge amount of time when dealing with long playlists. As a general rule, if the playlist is in PDJ format and contains fading automation, we can load the playlist using the automation mode while in all other cases we should load it in speed or full mode

Visual Basic 6

' check the format to load

If bFormatIsPDJ = True Then

   Amp3dj1.PlayListLoad(Player_1, strPathname, PLAYLIST_AUTOMATION_MODE)

else

   ' dealing with video clips whose duration is unknown until effective loading, it's better to

   ' disable the automatic check that verifies if loaded files are long enough to fit the fader settings

   ' this is only a sample application without strong error checking so use this setting carefully :-)

   Amp3dj1.Fader.CheckItemsDurationOnStart = False

   Amp3dj1.PlayListLoad(Player_1, strPathname, PLAYLIST_SPEED_MODE)

end if

' start fading

Amp3dj1.Fader.StartManualFading

Visual C++

// check the format to load

if (bFormatsIsPDJ)

   Amp3dj1.PlayListLoad(Player_1, strPathname, PLAYLIST_AUTOMATION_MODE);

else

{

   // dealing with video clips whose duration is unknown until effective loading, it's better to

   // disable the automatic check that verifies if loaded files are long enough to fit the fader settings

   // this is only a sample application without strong error checking so use this setting carefully :-)

   Amp3dj1.GetFader().SetCheckItemsDurationOnStart (FALSE);

   Amp3dj1.PlayListLoad(Player_1, strPathname, PLAYLIST_SPEED_MODE);

}

// start fading

Amp3dj1.GetFader().StartManualFading();

As seen above, once loaded the automatic fader can be started through the Fader.StartManualFading method; at this point the multimedia engine automatically checks if the loaded playlist contains at least two songs whose duration is long enough to apply the fader's timings and settings: if this check should fail, the call to the Fader.StartManualFading method would return an error code.

When dealing with playlists in PDJ format, containing volume fading automation, this wouldn't be an issue because the playlist is tailored to allow a total automation but when dealing with other playlist formats, which don't contain any kind of information about embedded video clips, the first fading would obviously fail: for this reason if we should be sure that all video clips are compatible with fader's settings, it could be useful disabling this automatic check by setting the Fader.CheckItemsDurationOnStart property to "False".

The automatic fader has now been started so it immediately begins loading into the involved players the sequence of playlist's video clips: it must be remarked that, when dealing with video clips, due to the filters graph building by DirectShow, the loading could be a bit more "heavy" respect to audio clips so you will have to keep count of some small delay during the loading.

The automatic fader already knows how to load and start video clips and also knows how to fade the respective audio stream but it still doesn't know how to manage the fading of the video streams into the stream mixer's window so, for achieving this purpose, we still need to add some coding.

As mentioned before, a possible solution would be linking the volume level of the player fading-out, on the top of the Z-order (meaning that it will by default cover the video stream of the player fading-in), to the alpha channel transparency of its video stream: while the volume on this player is fading down, we raise the transparency level of the related video stream so the video stream of the player fading-in, which is at the bottom of the Z-Order, appears through until the video stream of the player fading-out totally disappears when its volume level reaches level 0. The best approach is obviously synchronizing with events generated by the automatic fader as seen below:

Visual Basic 6

Private Sub Amp3dj1_SoundLoaded(ByVal nPlayer As Integer, ByVal nItemIndex As Integer)

   ' this is the next player to fade-in so put it at the bottom of the Z-Order

   Amp3dj1.VideoMixer.PlayerZOrderSet m_nMixerUniqueID, nPlayer, 100

   ... do other stuffs

End Sub

Private Sub Amp3dj1_FadeOutStarted(ByVal nPlayer As Integer)

   ' keep count of the player fading out because we will apply transparency on its video stream

   m_nPlayerFadingOut = nPlayer

End Sub

Private Sub Amp3dj1_FadeOutCompleted(ByVal nPlayer As Integer)

   ' the player is no more fading

   m_nPlayerFadingOut = -1

End Sub

Private Sub Amp3dj1_FadeInCompleted(ByVal nPlayer As Integer)

   ' fade in has been completed so put it at the top of the Z-Order

   Amp3dj1.VideoMixer.PlayerZOrderSet m_nMixerUniqueID, nPlayer, 0

End Sub

Private Sub Amp3dj1_FadingVolumeChanged(ByVal nPlayer As Integer, ByVal fVolume As Single)

   ' check if the player is fading-out

   If Amp3dj1.GetPlayerStatus(nPlayer) = SOUND_PLAYING And m_nPlayerFadingOut = nPlayer Then

       ' raise the transparent factor on the player fading out

       Amp3dj1.VideoMixer.PlayerAlphaSet m_nMixerUniqueID, nPlayer, 100 - fVolume

   End If

End Sub

Visual C++

// handler of the SoundLoaded event

void CVideoMixerWithFaderPrjDlg::OnSoundLoaded(short nPlayer, short nItemIndex)

{

   // this is the next player to fade-in so put it at the bottom of the Z-Order

   Amp3dj1.GetVideoMixer().PlayerZOrderSet (m_nMixerUniqueID, nPlayer, 100);

   ... do other stuffs

}

// handler of the FadeOutStarted event

void CVideoMixerWithFaderPrjDlg::OnFadeOutStarted(short nPlayer)

{

   // keep count of the player fading out because we will apply transparency on its video stream

   m_nPlayerFadingOut = nPlayer;

}

// handler of the FadeOutCompleted event

void CVideoMixerWithFaderPrjDlg::OnFadeOutCompleted(short nPlayer)

{

   // the player is no more fading

   m_nPlayerFadingOut = -1;

}

// handler of the FadeInCompleted event

void CVideoMixerWithFaderPrjDlg::OnFadeInCompleted(short nPlayer)

{

   // fade in has been completed so put the player at the top of the Z-Order

   Amp3dj1.GetVideoMixer().PlayerZOrderSet (m_nMixerUniqueID, nPlayer, 0);

}

// handler of the FadingVolumeChanged event

void CVideoMixerWithFaderPrjDlg::OnFadingVolumeChanged(short nPlayer, float fVolume)

{

// check if the player is fading-out

   if (Amp3dj1.GetPlayerStatus(nPlayer) == SOUND_PLAYING && m_nPlayerFadingOut == nPlayer)

// raise the transparent factor on the player fading out

       Amp3dj1.GetVideoMixer().PlayerAlphaSet (m_nMixerUniqueID, nPlayer, int (100 - fVolume));

}

This is one of the possible approaches but you could obviously implement a totally different way to manage the Z-Order and the alpha channel transparency. As a final note, please, keep count that code snippets above don't contain strong error checking: in a production environment it's recommended to add some check on values returned by various methods calls.

A sample of use of the VideoMixer object in conjunction with the Fader object in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- VideoMixerWithFader


How to deal with MIDI

How to deal with MIDI protocol

MIDI (Musical Instrument Digital Interface) is an industry-standard protocol, first defined in 1982, that enables electronic musical instruments (like synthesizers and drum machines), computers and other electronic equipment (like MIDI controllers, sound cards and samplers) to communicate and synchronize with each other. MIDI's primary functions include communicating event messages about musical notation, pitch, velocity, control signals for parameters (such as volume, vibrato, panning, cues, and clock signals) between two devices in order to complete a signal chain and produce audible sound from a sound source. As an electronic protocol, it is notable for its widespread adoption throughout the music industry.

MIDI synthesizers use wavetables to define the base samples that are used to render MIDI files. MIDI files in themselves don't contain any sounds, rather they contain only instructions to render them, and consequently rely on wavetables to render such sounds correctly. For this purposes there is the need to rely on SoundFonts files (usually identified through their ".SF2" extension) which contain base samples in PCM format (similar to WAV files) that are mapped to sections on a musical keyboard. A SoundFont bank also contains other music synthesis parameters such as loops, vibrato effect, and velocity sensitive volume changing.

When dealing with MIDI streams, in order to have a better response time and granularity for MIDI events, it's recommended to keep latency as short as possible (see the How to deal with latency tutorial for details) and to keep a small time for updating the DirectSound buffer: usually by setting a value of 10 milliseconds for the BufferUpdateTime property gives good results.

Active DJ Studio, through the MIDI property which encapsulates functionalities of the MIDI COM object, can manage different aspects of MIDI protocol:

· Loading and playback of MIDI files
· Creation of an empty playback MIDI stream on which MIDI events can be applied
· Acquisition of MIDI events from a MIDI input device
· Management of MIDI SoundFonts
· Usage of the virtual piano keyboard

Loading and playback of MIDI files

MIDI files can be loaded inside a player instanced by the control through one of the LoadSound based methods and, as seen for any other audio format, can be played through the PlaySound method; once a sound file is loaded, you can check if the loaded sound is a MIDI stream by checking if the value returned by the GetFileType method is SOUNDTYPE_MIDI.

It's important to note that, without SoundFonts installed inside the system, there is no possibility to hear sound coming out from speakers of your PC, also if a MIDI file has been loaded correctly; see the Management of MIDI SoundFonts section below for details about SoundFonts management.

Duration of MIDI files and position detection/modification during playback can be retrieved using regular methods like SoundDurationGet, SoundPositionGet and SeekSound but, due to the fact that MIDI files positioning can be measured in "MIDI ticks" as well, there is the possibility to use MIDI specific alternatives like MIDI.SoundDurationGet, MIDI.SoundPositionGet and MIDI.SeekToPosition.

Another feature common with other audio formats, but with MIDI specific capability to be expressed in MIDI ticks, are triggers so you could use the TriggersAdd and TriggersSetPos methods but also the MIDI.TriggerAdd and MIDI.TriggerSetPos methods in case you should setting the trigger position at a specific MIDI tick.

MIDI files are much smaller than recorded audio waveforms because the file stores instructions (also known as events) on how to recreate the sound based on synthesis with a MIDI synthesizer rather than an exact waveform to be reproduced: typical events used for playback purposes are music notes.

During playback of MIDI files, you can be notified of each specific MIDI event occurring by enabling their real-time detection through the MIDI.StreamEventsEnableNotifications method: after enabling detection, the container application can be notified about occurring MIDI events through the MidiStreamEventNotification event.

Without the need to start playback, you can enumerate all of the events stored inside the MIDI file through the MIDI.StreamEventsEnum method (or through the MIDI.StreamEventsEnumFromRange method if you only need to parse a smaller portion of the MIDI file) and you can get information about each of the detected events through the MIDI.StreamEventsEnumItemGet method.

The current value of a MIDI event can be obtained through the MIDI.StreamEventValueGet method: the only exception is related to music notes because more than one could be applied at the same time.

MIDI files can also contain other information not directly related to playback of music notes:

· Meta tags: Each MIDI track (you can get the number of tracks through the MIDI.TrackCountGet method) can contain meta tags in textual form: these tags can be enumerated through the MIDI.TrackTagsEnum method and related information of each meta tag can be retrieved through the MIDI.TrackTagsItemGet method.

· Markers: may contain lyric text, copyright text, time signatures and so on; markers detection can be performed in real-time during playback by enabling their notification through the MIDI.MarkersEnableNotifications method so, when a marker is encountered, the MidiMarkerNotification event is fired. Markers detection can be also performed before playback by enumerating them through the MIDI.MarkersEnum method and by getting information for each of the through the MIDI.MarkersEnumItemGet method.

Tempo management during playback of MIDI files is available through the MIDI.TempoPercGet and MIDI.TempoPercSet methods and also BPM (Beats per MInute) management is available through the MIDI.BpmGet and MIDI.BpmSet methods.

Volume playback for each MIDI track can be retrieved or modified through the MIDI.TrackVolumeGet and MIDI.TrackVolumeSet methods.

Creation of an empty playback MIDI stream on which MIDI events can be applied

In some case it may be needed to have the possibility to play MIDI notes without the need to previously load a MIDI file; for this purpose you can create and immediately put in playback mode an empty MIDI stream through the MIDI.StreamStart method. This MIDI stream can be stopped and destroyed from memory through the MIDI.StreamStop method.

Once the MIDI stream is started, you have the possibility to apply single MIDI events through the MIDI.StreamEventApply method or, in one single shot, a list of MIDI events through the MIDI.StreamEventsListApply method. The list of MIDI events to apply in one single shot can be edited using a set of dedicated methods:

· MIDI.StreamEventsListItemAdd adds a new MIDI event to the list and returns back a unique identifier for the MIDI event: this unique identifier allows discriminating MIDI events from each other
· MIDI.StreamEventsListItemModify allows modifying a specific MIDI event already added to the list
· MIDI.StreamEventsListItemRemove allows removing an event from the list or to clear all contents from the list
· MIDI.StreamEventsListItemGet allows retrieving information about a specific MIDI event already added to the list
· MIDI.StreamEventsListItemCountGet allows retrieving the number of MIDI events added to the list
· MIDI.StreamEventsListItemUniqueIdGet given a zero-based index allows retrieving the unique identifier of the corresponding MIDI event

The list stays available in memory also after having called the Midi.StreamEventsListApply method so it can be applied more than once.

MIDI events are sometime available also in raw format inside a memory buffer: in this case you can apply raw MIDI data through the MIDI.StreamEventsRawApply method.

All of the MIDI events related methods described above can be used during playback of MIDI files as well.

Acquisition of MIDI events from a MIDI input device

MIDI input devices installed inside the system can be enumerated through the MIDI.InputDevicesEnum method. After completing the enumeration, the number of installed MIDI input devices can be retrieved through the MIDI.InputDevicesCountGet method and information about each device can be obtained through the MIDI.InputDevicesInfoGet method.

When you need to get MIDI events from one of the listed MIDI devices, you need to start the device using one of the methods below:

· MIDI.InputDevicesStart starts the MIDI input device and allows receiving raw MIDI events inside a memory buffer received by a predisposed callback function
· MIDI.InputDevicesStartOnPlayer starts the MIDI input device and sends incoming raw MIDI events directly to the given player, allowing a direct playback of notes coming from the device

In both cases input from the MIDI device can be stopped through the MIDI.InputDevicesStop method.

Management of MIDI SoundFonts

As mentioned above, the availability of SoundFonts (identified through their extension ".SF2") is mandatory in order to perform playback of MIDI files or of MIDI events. By default the component will try to see if Creative SoundFonts (CT2MGM.SF2, CT4MGM.SF2, CT8MGM.SF2 and 28MBGM.SF2, ) are available inside the Windows\System32 folder: if one of them should be available, it will be automatically loaded so MIDI playback will be immediately possible.

In order to see if a default SoundFont is available you could call the MIDI.SoundFontDefaultGet method and check if the returned string contains the pathname of a SF2 file. This default can be changed at any time through the MIDI.SoundFontDefaultSet method.

The default SoundFont affects all MIDI streams loaded from a MIDI file or created from scratch through the MIDI.StreamStart method. If you should need to set a specific SoundFont for a certain player instanced by the component, you should initialize a SF2 file through one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods and, through the returned unique identifier, assign the SoundFont to the player through the MIDI.SoundFontApply method.

When a SoundFont has been initialized, you can retrieve information about it, such as its friendly name, through the MIDI.SoundFontInfoStringGet and MIDI.SoundFontInfoNumGet methods and, when the SoundFont is no more needed, you can discard it from memory through the MIDI.SoundFontFree method.

Each SoundFont can contain up to 128 presets: you can obtain information about each single preset, for example its friendly description, through the MIDI.SoundFontPresetDescGet method.

In case you should need to apply to a certain player multiple SoundFonts in one single shot, you could create a list of SoundFonts to apply through the MIDI.SoundFontListApply method. This list can be edited through the following methods:

· MIDI.SoundFontListItemAdd adds a new SoundFont to the list: the SoundFont must have been previously initialized through the MIDI.SoundFontInit method.
· MIDI.SoundFontListItemRemove allows removing a SoundFont from the list
· MIDI.SoundFontListItemCountGet allows retrieving the number of SoundFont added to the list
· MIDI.SoundFontListItemUniqueIdGet given a zero-based index allows retrieving the unique identifier of the corresponding SoundFont

Finally you can enumerate SoundFonts applied to a MIDI stream through the MIDI.SoundFontsInStreamEnum method and to obtain information about each of them through the MIDI.SoundFontsInStreamItemGet method.

In order to avoid CPU spikes during playback of MIDI streams you can load presets of the sound font using the MIDI.SoundFontLoad method or pre-load samples of the MIDI file using the MIDI.StreamPreloadSamples method.

Usage of the virtual piano keyboard

Active DJ Studio implements also a graphical gadget called "virtual piano keyboard" which allows playing notes by pressing the mouse over the available keys or to display notes being played by an external MIDI physical keyboard connected to the system.

The virtual piano keyboard can be displayed with three different orientations as seen on the screenshots below

Horizontal

Vertical left

Vertical right

and can also have a variable number of keys with a maximum of 128; below you will find the keyboard as seen when launching the sample MidiSynthesizer and pressing a key.

The virtual piano keyboard can be instanced on the user interface of your application through the MIDI.KeyboardCreate method; as for all of the other windows control, the virtual piano keyboard can be moved and resized (MIDI.KeyboardMove method), shown or hidden (MIDI.KeyboardShow method), refreshed (MIDI.KeyboardRefresh method) or destroyed (MIDI.KeyboardDestroy method).

Once instanced, the user can start playing notes by clicking keys through the left button of the mouse (but also through his fingers in case of availability of a touch screen) or by calling the MIDI.KeyboardNote method. The container application can be informed when a specific key is pressed or released through the MidiKeyboardNotification event.

In case you should simply need to display on the virtual piano keyboard that a note was played through an external MIDI input device connected to the system, the MIDI.KeyboardNote method allows simulating a key pressure without generating a clone of the same note: the purpose of its bSimulated parameter is exactly this. This feature is quite easy to implement through the following procedure:

· After having enumerated MIDI input devices through the MIDI.InputDevicesEnum method, start getting MIDI data from the external MIDI input device through the MIDI.InputDevicesStartOnPlayer method
· Enable notifications of MIDI notes events (MIDI_EVENT_NOTE) through the MIDI.StreamEventsEnableNotifications method
· When the MidiStreamEventNotification event is generated, check if its nMidiEvent parameter is set to MIDI_EVENT_NOTE: if it should, call the MIDI.KeyboardNote method passing the note to play (and related velocity) and setting the bSimulated parameter to BOOL_TRUE

The range of available keys can be modified at any time through the MIDI.KeyboardRangeSet method and its graphical settings can be retrieved and modified through the MIDI.KeyboardGraphicalSettingsGet and MIDI.KeyboardGraphicalSettingsSet methods.

Samples of management of MIDI protocol in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- MidiPlayer

- MidiSynthesizer


How to manage Volume Automation

How to manage Volume Automation

Volume automation allows having the volume change at given points, so that it can be softer at one point and louder at another. You can use automation for things like fade-outs and fade-ins, for controlling spikes in volume, and so on.

In the graphic above a volume automation sample is shown: please, note that the graphic above is simply provided for educational purposes and doesn't rely on a graphic feature available inside Active DJ Studio.

In the sample above, 4 automation points have been defined and each of them will affect how volume is applied to the sound under editing; the first two points set the start of a sliding procedure that will bring sound's volume to a softer level, the last two points sets the start of a sliding procedure that will bring sound's volume to its original value. A defined set of volume automation points is usually defined as Volume Automation Procedure.

Active DJ Studio can manage Volume Automation in 2 different ways:

Volume automation for single players: through the VolumeAutomation property, each allocated player (virtual deck) can have a separate volume automation procedure. The defined procedure will be applied to any song loaded inside the player and will stay alive, if not reset/modified through code, for the remaining life of the involved player.

Volume automation for playlists: a new XML-based playlist format has been defined (PDJ) which allows not only the definition of a set of sound files to play in sequence but also the definition of mixing automation facilities including volume automation procedures and cue points.

Volume automation for single players

Volume automation is implemented through a set of methods and properties of the VolumeAutomation property that implements the VolumeAutomation COM object. Through the VolumeAutomation property you can:

· Add/remove volume points through the VolumeAutomation.PointAdd and VolumeAutomation.PointRemove methods.
· Enumerate existing volume points through the VolumeAutomation.PointGetCount and VolumeAutomation.PointGetName methods.
· Save the current automation procedure into a XML-based "VDJ" file on disk through the VolumeAutomation.Save method and to retrieve and apply the same file at a later time through the VolumeAutomation.Load method. If the VDJ file should have been saved with the same pathname of an existing sound file, when loading the sound file the related VDJ file would be searched and, if available, loaded automatically: if for example the loaded sound file should be named MySong.mp3, the corresponding searched VDJ file would be named MySong.vdj
· Enable/disable specific points through the VolumeAutomation.PointEnable method and to know the enabled state of a specific point through the VolumeAutomation.PointIsEnabled method.
· Modify/retrieve position and parameters of a specific point through the VolumeAutomation.PointGetParams and VolumeAutomation.PointSetParams methods.
· Identify the next volume point that will be executed during a playback session through the VolumeAutomation.PointGetNext method,
· Check if the volume automation procedure is currently sliding playback volume through the VolumeAutomation.IsSliding method.
· Reset the current volume automation procedure through the VolumeAutomation.Reset method.

Modifications to an existing volume automation won't be immediately applied if loaded sound should be already playing and will take effect only after completing/stopping and restarting the playback session.

Each volume point inside the volume automation procedure is made up of 2 elements:

· position: defines the position, expressed in the unit set into the VolumeAutomation.PositionUnit property (milliseconds, seconds or percentage), on which a different volume will be applied to the player.
· volume. defines the initial volume level, expressed in the unit set into the VolumeAutomation.ScaleType property (linear or logarithmic), applied starting from the defined position.

In order to be effective, a volume automation procedure should have at least 4 defined volume points (2 for defining the fade-in sequence and 2 for defining the fade-out sequence): the volume level set into a specific volume point reaches the volume level set into the next volume point through an automatic volume sliding: for each volume point you can define how the sliding will be performed in order to reach the volume level set into the next volume point: this is usually defined as "volume curve".

As mentioned above, a volume automation procedure can be saved inside a XML-based "VDJ" file; below you can see an example of VDJ file containing 4 volume points: this simple volume automation procedure will do the following:

· sets an initial volume point, named "start" at 0% of the sound's duration with volume level set to 0% (no audible sound)
· during playback, the first volume point will reach the second one, named "start full" and positioned at 5% of the sound's duration, through a custom curve having a set of control points: the final volume level will be 100% (full volume)
· the second volume point will reach the third volume point, named "end" and positioned at 95% of the sound's duration, without applying any volume change because the volume level between the second and third point is identical
· the third volume point will reach the fourth one, named "end full" and positioned at 99% of the sound's duration, through a custom curve having a set of control points: the final volume level will be 0% (no audible sound)

<?xml version="1.0" ?>

<VolumeAutomation>

   <VolumePoints>

       <VolumePoint name="start" VolumeLevel="0.000000" PosPerc="0.000000" CurveType="5" LeftX="3" LeftY="97" RightX="97" RightY="3" />

       <VolumePoint name="start full" VolumeLevel="100.000000" PosPerc="5.000000" CurveType="0" />

       <VolumePoint name="end" VolumeLevel="100.000000" PosPerc="95.000000" CurveType="5" LeftX="3" LeftY="3" RightX="97" RightY="97" />

       <VolumePoint name="end full" VolumeLevel="0.000000" PosPerc="99.000000" CurveType="0" />

   </VolumePoints>

</VolumeAutomation>

The main key is VolumeAutomation which contains the VolumePoints sub-key.

The VolumePoints sub-key contains a set of volume points, each one defined by the VolumePoint sub-key. Each VolumePoint sub-key contains the following attributes:

• name attribute: Friendly name of the volume point.

• VolumeLevel attribute: Volume level, expressed in percentage, applied from this point. If the original level of the volume point should have been set in dB, during a save operation performed through the VolumeAutomation.Save method it would be automatically converted to percentage.

• PosSec attribute: Position, expressed in seconds where the volume will be applied. This attribute can be replaced by PosMs if milliseconds are preferred or by PosPerc if percentage is preferred.

• CurveType attribute: Defines the type of curve applied to the volume in order to reach the volume level of the next volume point. Can assume the following values:

Value | Meaning
0 | No curve is applied: volume will be changed immediately and will be kept till next volume point.
1 | Linear curve
2 | Exponential curve
3 | Cosine curve
4 | Smooth curve
5 | Custom Bézier curve. If this value has been defined, the following attributes will allow defining control points positions for the Bézier curve: • LeftX attribute: Horizontal position, expressed in percentage, of the left control point. • LeftY attribute: Vertical position, expressed in percentage, of the left control point. • RightX attribute: Horizontal position, expressed in percentage, of the right control point. • RightY attribute: Vertical position, expressed in percentage, of the right control point.

As you can see from graphs above, there are many embedded options for specifying a volume curve and the latest one is certainly the option that allows everyone finding the optimal curve for any specific need: custom curves can be designed directly inside the user interface of the container application through the VolumeAutomation.CurveDesigner property which implements the CurveDesignerMan class: this specific object manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic above). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

During execution of a volume automation procedure, the container application can be notified when a volume point has been reached through the VolumeAutomationPointReached event.

VDJ format is also used by our Active Sound Editor component.

A samples of volume automation management in Visual C++ 6 and Visual Basic 6 can be found inside the following sample installed with the product's setup package:

- VolumeAutomatiom

Volume automation for playlists

Traditional playlist formats (M3U, PLS, WPL, etc.) are composed of file paths that point to individual titles stored inside a local sound file; furthermore, till version 4.0 of Active DJ Studio, the programmable embedded fader allowed using playlists in order to mix contained titles using fixed fade-in and fade-out procedures based upon linear volume curves.

The new PDJ format, a XML-based list of files, allows adding more information about the way contained titles will be mixed through the use of two players; each title inside the playlist can have dedicated information about the way the mixing will be performed and about the type and duration of volume curves applied for fade-in and for fade-out operations. As a secondary feature, each playlist's item can have a set of related Cue Points.

If a PDJ playlist file already exists on your PC, you can use the PlayListLoad method but, in order to let the control recognize the PDJ format as a valid one, you need to set the nMode parameter to PLAYLIST_AUTOMATION_MODE; a call to this method won't return control to the container application until the playlist has been loaded completely so, if the playlist should be very long, it could block your user interface for a while; for this reason there is the possibility to call the PlayListLoadSync method which will perform playlist analysis and loading in a separate thread: the container application is informed about the loading advancement through the PlayListLoadStart, PlayListLoadPerc and PlayListLoadDone events; also in this case you will have to call the PlayListLoadSync method with the nMode parameter set to PLAYLIST_AUTOMATION_MODE.

In order to create a PDJ playlist from scratch, you need to call the PlayListCreateAutomation method.

Mixing and volume automation features of the PDJ format are managed at runtime through the embedded Fader which requires that all of the following conditions are met:

1. The PDJ playlist needs to be loaded into a player through the PlayListLoad method having its parameter nMode set to PLAYLIST_AUTOMATION_MODE or, in alternative, it must be created from scratch using the PlayListCreateAutomation method.

2. The embedded Fader must be initialized, through its Fader.Init method, in order to use the specific player on which the PDJ playlist has been loaded/created.

3. The Fader.PlayListUseSingle method must be called with its nIndexPlayer parameter having the zero-based index of the specific player on which the PDJ playlist has been loaded/created.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

IMPORTANT NOTE ABOUT USAGE OF VIDEO CLIPS INSIDE A PDJ PLAYLIST: When using video files in conjunction with the embedded fader and volume automation, it's recommended to set the audio rendering mode of each involved player to AUDIO_RENDERER_MODE_CUSTOM_2 through the VideoPlayer.AudioRendererModeSet method.

A PDJ playlist, loaded from disk or created from scratch, can be modified through the following methods:

PlayListAddItem to add one or more new songs to the playlist

PlayListAddItemEx to add a new song or the contents of another playlist or the contents of a directory to the playlist

PlayListAddItemWithTag to add a new song to the playlist with an associated tag string: this tag string will be reported by the PlaylistSoundLoaded event when the item is loaded into the player at runtime.

PlayListItemVolAutomPointAdd to add a new volume automation point to an existing item

PlayListItemVolAutomSetMixPos to modify mixing positions of an existing item

PlayListItemVolAutomPointRemove to remove a volume automation point from an existing item

PlayListItemCuePointAdd to add a new cue point to an existing item

PlayListItemCuePointRemove to remove a cue point from an existing item

PlayListRemoveItem to remove a song from the playlist

PlayListMoveItem to change the position of a song

PlayListGetCount to retrieve the number of songs currently in the playlist

PlayListGetItemString to retrieve information about a chosen song

PlayListSetLoop to make the playlist loop when it has been executed completely

PlayListSetShuffle to set a random playing order of the playlist songs

Once the playlist has been filled with all the needed items, volume automation points and cue points, you can save it on your PC using the PlayListSaveAutomation method. The PlayListSave method could be used as well but it will only save the list of stored songs without any information about mixing positions, volume automation and cue points.

The playlist can be executed using the Fader.StartManualFading method-

Below you can see an example of PDJ file containing 3 songs (items):

<?xml version="1.0"?>

<FaderPlayList>

<PlayListItems>

 <Item pathname="C:\sounds\drumtrik01_120bpm.wav" Title="First song name" DurationSec="16.00" StartPosSec="2.0" MixPosSec="12.0" EndPosSec="16.0" >

   <VolumePoints>

     <VolumePoint name="start fade-in" VolumeLevelLinear="0.0" PosSec="2.0" CurveType="5"

                LeftX="11" LeftY="3" RightX="93" RightY="43" />

     <VolumePoint name="end fade-in" VolumeLevelLinear="100.0" PosSec="5.5" CurveType="0" />

     <VolumePoint name="start fade-out" VolumeLevelLinear="100.0" PosSec="11.9" CurveType="5"

                LeftX="83" LeftY="13" RightX="32" RightY="41" />

     <VolumePoint name="end fade-out" VolumeLevelLinear="0.0" PosSec="15.9" CurveType="0" />

   </VolumePoints>

   <CuePoints>

     <CuePoint name="Silence end" PosMs="1000" />

     <CuePoint name="Fading point" PosMs="12000" />

     <CuePoint name="Silence start" PosMs="15900" />

   </CuePoints>

 </Item>

 <Item pathname="C:\sounds\drumtrik17_86bpm.wav" Title="Second song name" DurationSec="22.325" StartPosSec="3.0" MixPosSec="19.0" EndPosSec="22.0" >

   <VolumePoints>

     <VolumePoint name="start fade-in" VolumeLevelLinear="0.0" PosSec="3.1" CurveType="2" />

     <VolumePoint name="end fade-in" VolumeLevelLinear="100.0" PosSec="6.5" CurveType="0" />

     <VolumePoint name="start fade-out" VolumeLevelLinear="100.0" PosSec="19.0" CurveType="2" />

     <VolumePoint name="end fade-out" VolumeLevelLinear="0.0" PosSec="21.9" CurveType="0" />

   </VolumePoints>

   <CuePoints>

     <CuePoint name="Silence end" PosMs="1200" />

     <CuePoint name="Fading point" PosMs="19000" />

     <CuePoint name="Silence start" PosMs="21000" />

   </CuePoints>

 </Item>

 <Item pathname="C:\sounds\drumtrik14_132bpm.wav" Title="Third song name" DurationSec="14.545" StartPosSec="0.0" MixPosSec="12.0" EndPosSec="14.0" >

   <VolumePoints>

     <VolumePoint name="start fade-in" VolumeLevelLinear="0.0" PosSec="0.0" CurveType="2" />

     <VolumePoint name="end fade-in" VolumeLevelLinear="100.0" PosSec="3.5" CurveType="0" />

     <VolumePoint name="start fade-out" VolumeLevelLinear="100.0" PosSec="12.0" CurveType="2" />

     <VolumePoint name="end fade-out" VolumeLevelLinear="0.0" PosSec="14.0" CurveType="0" />

   </VolumePoints>

   <CuePoints>

     <CuePoint name="Silence end" PosMs="200" />

     <CuePoint name="Fading point" PosMs="12000" />

     <CuePoint name="Silence start" PosMs="14000" />

   </CuePoints>

 </Item>

</PlayListItems>

</FaderPlayList>

The main key is FaderPlayList which contains the PlayListItems sub-key.

The PlayListItems sub-key contains a set of items, each one defined by the Item sub-key. Each Item sub-key contains the following attributes and sub-keys:

• pathname attribute: The absolute pathname of the sound file to play

• Title attribute: Optional string of text containing the title or a description of the sound file to play

• DecryptKey attribute: Optional decryption key for sound files encrypted through the CryptSound™ application

• DurationSec attribute: Duration of the song expressed in seconds. This attribute can be replaced by DurationMs if milliseconds are preferred as scale unit.

• StartPosSec attribute: Position, expressed in seconds, where the song will begin to play. This attribute can be replaced by StartPosMs if milliseconds are preferred or by StartPosPerc if percentage is preferred. If these attributes should be set to a negative value, the effective position will be calculated by subtracting the absolute value of the attribute from the total duration of the sound file.

• MixPosSec attribute: Position, expressed in seconds, where the mixing with the next song will begin. This attribute can be replaced by MixPosMs if milliseconds are preferred or by MixPosPerc if percentage is preferred. If these attributes should be set to a negative value, the effective position will be calculated by subtracting the absolute value of the attribute from the total duration of the sound file.

• EndPosSec attribute: Position, expressed in seconds, where the song will be stopped. This attribute can be replaced by EndPosMs if milliseconds are preferred or by EndPosPerc if percentage is preferred. If these attributes should be set to a negative value, the effective position will be calculated by subtracting the absolute value of the attribute from the total duration of the sound file.

• VolumePoints sub-key: contains the volume automation procedure applied to the current item (see below).

• CuePoints sub-key: contains cue points applied to the current item (see below).

The VolumePoints sub-key contains a set of volume points (at least 4 volume points should be available, 2 for defining the fade-in sequence and 2 for defining the fade-out sequence), each one defined by the VolumePoint sub-key. Each VolumePoint sub-key contains the following attributes:

• name attribute: Friendly name of the volume point.

• VolumeLevelLinear attribute: Volume level, expressed in percentage, applied from this point. This attribute can be replaced by VolumeLevelLog if dB are preferred.

• PosSec attribute: Position, expressed in seconds where the volume will be applied. This attribute can be replaced by PosMs if milliseconds are preferred or by PosPerc if percentage is preferred. These attributes cannot assume negative values.

• CurveType attribute: Defines the type of curve applied to the volume in order to reach the volume level of the next volume point. Can assume the following values:

Value | Meaning
0 | No curve is applied: volume will be changed immediately and will be kept till next volume point.
1 | Linear curve
2 | Exponential curve
3 | Cosine curve
4 | Smooth curve
5 | Custom Bézier curve. If this value has been defined, the following attributes will allow defining control points positions for the Bézier curve: • LeftX attribute: Horizontal position, expressed in percentage, of the left control point. • LeftY attribute: Vertical position, expressed in percentage, of the left control point. • RightX attribute: Horizontal position, expressed in percentage, of the right control point. • RightY attribute: Vertical position, expressed in percentage, of the right control point.

The CuePoints sub-key contains a set of cue points, each one defined by the CuePoint sub-key. Each CuePoint sub-key contains the following attributes:

• name attribute: Friendly name of the cue point.

• PosSec attribute: Position, expressed in seconds where the cue point will generate a CuePointReached event. This attribute can be replaced by PosMs if milliseconds are preferred.

IMPORTANT NOTE ABOUT SYSTEM LOCALES: many attributes inside the PDJ format can have floating point values: as you may know the decimal separator can assume different values (colon or dot) depending upon the locale set into the target system. Active DJ Studio will internally convert the decimal separator used inside the attribute to the correct character set into the system locale so you won't have to worry about locale differences when redistributing a PDJ file.


How to create custom volume curves

How to create custom volume curves

Inside the How to manage Volume Automation tutorial we have seen that we can apply the following predefined volume curves when performing fade-in/fade-out operations on a playback session:

Inside this tutorial we will see how to manage the latest one (VOLUME_CURVE_CUSTOM) which allows designing, through a customizable user interface control, the shape of the volume curve.

Custom volume curves are based upon Cubic Bézier curves as seen on the image below:

P0 and P3 represent the 2 points delimiting the line while P1 and P2 represent the "control points" whose positioning will determine the smoothing of the curve; by moving points P1 and P2 we can control how the shape of the curve will be modified; in the sample below respect to the previous sample, only point P2 has been moved and, as you can see, the shape of the curve has been slightly changed.

The graphics above is identical to the one implemented by the CurveDesigner object accessible through the VolumeAutomation.CurveDesigner property. The curve designer renders its graphic output over a graphical surface provided by an existing window, form or dialog box: you can create, position and size this graphical surface using the VolumeAutomation.CurveDesigner.Create method.

As most Windows controls with an user interface, the curve designer can be:

· shown or hidden through the VolumeAutomation.CurveDesigner.Show method
· moved or resized through the VolumeAutomation.CurveDesigner.Move method
· refreshed through the VolumeAutomation.CurveDesigner.Refresh method
· destroyed through the VolumeAutomation.CurveDesigner.Destroy method

The default appearance of the curve designer representing a fade-in curve is the following:

while the default appearance of the curve designer representing a fade-out curve is the following:

As you can see, by default customizable curves will be initially represented having a linear evolution with the Y axis representing the volume level and the X axis representing the evolving time. Control points (P1 and P2) are represented by two cyan circles.

The graphical appearance of this control is fully customizable and you can modify colors used to render the various elements: for this purpose you can retrieve the current graphical settings calling the VolumeAutomation.CurveDesigner.GetGraphicalSettings method and then modify them calling the VolumeAutomation.CurveDesigner.SetGraphicalSettings method: both methods receive a reference to the CURVE_DESIGNER_SETTINGS data structure. You have also the possibility to display a background image using the VolumeAutomation.CurveDesigner.SetBackPictureFromFile and VolumeAutomation.CurveDesigner.SetBackPictureFromHandle methods.

Once the curve designer is instanced on the container form, you can move the control points (represented by cyan circles on the graphics displayed above) using the left button of the mouse (through drag & drop) or, programmatically, through the VolumeAutomation.CurveDesigner.SetPoints method. In either cases you can know the actual position of both control points through the VolumeAutomation.CurveDesigner.GetPoints method. Each time a control point is moved, the control will fire a VolumeCurveDesignerChanged event.

The VolumeCurveDesignerChanged event is fired each time a control point has been moved.

As a further feature, the curve designer can display other standard curves, as seen on the graphics at the beginning of this tutorial, through the VolumeAutomation.CurveDesigner.DisplayCurveType method.

A sample of usage of the CurveDesigner object in Visual C++ 6 and Visual Basic 6 can be found inside the following sample installed with the product's setup package:

- VolumeAutomatiom


How to use the embedded Visual Feedbacks

How to use the embedded Visual Feedbacks

This version of the control comes with four embedded Visual Feedbacks, internally implemented as COM objects: this object oriented approach allows to access each of the Visual Feedbacks as a control's property. The available feedbacks are the following:

VU-Meter

Spectrum

Oscilloscope

Waveform display

These Visual Feedbacks, through the call to the respective Create methods, need to be associated to an existing window that will be used as a surface for the graphic rendering; for this purpose we suggest the use of a PictureBox control with "Flat" appearance. Note that you can have separate Visual Feedbacks for each of the allocated players.

VU-Meter

Implemented through the VUMeter object and accessible through the VUMeter property, must be created through a call to the VUMeter.Create method and can be shown/hidden at any time through the VUMeter.Show method. This object exposes the following properties and methods that allow the customisation of the graphic rendering:

BandType: determines if the VU Meter will be a mix of the Left and Right channel or if each channel will have a dedicated "band" (default).

HasPeaks: determines the "peaks" visibility.

ColorBands: determines the "bands" color.

ColorPeaks: determines the "peaks" color.

ColorBackground: determines the color of the background area.

ZoomPerc: determines the height zoom percentage of bands.

SetBackPictureFromFile: sets a background picture obtained from a BMP file

SetBackPictureFromHandle: sets a background picture obtained from a bitmap handle

below you can see a sample of the embedded VU-Meter:

If you shouldn't like the graphic representation of the embedded VU-Meter, note that you can implement your own VU-Meter graphics, driven by the values received through the VUMeterValueChange event.

Through the VuMeter.KeepCountOfVolume method, you can decide if displayed and reported volume levels must be affected by changes into the player volume performed through the StreamVolumeLevelSet method or during volume sliding.

Spectrum

Implemented through the Spectrum object and accessible through the Spectrum property, must be created through a call to the Spectrum.Create method and can be shown/hidden at any time through the Spectrum.Show method. This object exposes the following properties and methods that allow the customisation of the graphic rendering:

BandWidth: determines the width in screen pixels of the "bands".

HasPeaks: determines the "peaks" visibility.

ColorBands: determines the "bands" color.

ColorPeaks: determines the "peaks" color.

ColorBackground: determines the color of the background area.

ZoomPerc: determines the height zoom percentage of bands.

SetBackPictureFromFile: sets a background picture obtained from a BMP file

SetBackPictureFromHandle: sets a background picture obtained from a bitmap handle

below you can see a sample of the embedded Spectrum and, on the right, a zoomed detail of the Spectrum "bands":

If you shouldn't like the graphic representation of the embedded Spectrum, note that you can implement your own Spectrum graphics, driven by the values obtained through the Spectrum.GetTable method which can be called after receiving the SpectrumValueChange event.

A graphically enhanced version of the spectrum analyzer can be obtained by leveraging the SpectrumEnh object: see the related tutorial for details.

Oscilloscope

Implemented through the Oscilloscope object and accessible through the Oscilloscope property, must be created through a call to the Oscilloscope.Create method and can be shown/hidden at any time through the Oscilloscope.Show method. This object exposes the following properties and methods that allow the customisation of the graphic rendering:

LineWidth: determines the "line" color.

ColorLine: determines the "line" color.

ColorBackground: determines the color of the background area.

Type: determines the type of drawing used to render the line.

ZoomPerc: determines the height zoom percentage of the line.

SetBackPictureFromFile: sets a background picture obtained from a BMP file

SetBackPictureFromHandle: sets a background picture obtained from a bitmap handle

below you can see a sample of the embedded Oscilloscope:

Waveform display

Implemented through the Waveform object and accessible through the Waveform property, must be created through a call to the Waveform.Create method and can be shown/hidden at any time through the Waveform.Show method. This object exposes the following properties and methods that allow the customisation of the graphic rendering:

Resolution: determines how frequently vertical lines are drawn on the screen (by default every 30 milliseconds).

ColorLine: determines the "lines" color.

ColorBackground: determines the color of the background area.

ZoomPerc: determines the zoom percentage of the lines drawn.

SetBackPictureFromFile: sets a background picture obtained from a BMP file

SetBackPictureFromHandle: sets a background picture obtained from a bitmap handle

below you can see a sample of the embedded Waveform display:

A sample that summarizes the use of Visual Feedbacks in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- Feedbacks


How to use the Enhanced Spectrum Analyzer

How to use the Enhanced Spectrum Analyzer

In addition to embedded visual feedbacks described inside the How to use the embedded Visual Feedbacks tutorial, the component allows performing sound analysis during playback through the usage of an enhanced FTT-based spectrum analyzer.

The enhanced spectrum analyzer can represent a FFT graph as seen inside the image below:

The FFT graph works by taking a small sample of audio and plotting a graph of frequency (on the x-axis expressed in Hz) versus intensity of the signal (on the y-axis expressed in dB). The graph features two different plots if the audio is stereo, otherwise just the one plot will be displayed.

In alternative enhanced spectrum analyzer can represent a TFFT graph, also known as "spectral view", as seen on the image below:

The TFFT graph works by plotting the intensity of the frequency spectrum of the audio across time, and represents intensity through color; during playback the signal intensity is rendered along the x-axis while the y-axis is used for frequency (expressed in Hz) and depicts the spectrum of the audio at any one point in time: for every point along the x-axis an intensity calculation is done and a dB figure is calculated: the lower the intensity, the darker the color; the higher the intensity, the brightest the color.

The enhanced spectrum analyzer can be accessed through the SpectrumEnh property which implements the SpectrumEnh COM object; an enhanced spectrum analyzer can be instanced for each of the players allocated through the InitDJSystem method by calling the SpectrumEnh.Create method: as seen for other embedded visual feedbacks, the graphic rendering is performed on the surface of a hosting window.

The spectrum analyzer can be hidden or shown through the SpectrumEnh.Show method and the hosting window can be eventually changed through the SpectrumEnh.SetHWND method.

The graphical rendering of this tool is fully customizable and you can modify colors used to render the various elements and hide/show all of the elements of the spectrum representation; for this purpose you can gain access to the various settings through the following set of data structures using the provided methods:

· general settings are managed through the SPECTR_ENH_GENERAL_SETTINGS data structure accessible through the combination of the SpectrumEnh.SettingsGeneralGet and SpectrumEnh.SettingsGeneralSet methods.
· rulers rendering settings are managed through the SPECTR_ENH_RULERS_SETTINGS data structure accessible through the combination of the SpectrumEnh.SettingsRulersGet and SpectrumEnh.SettingsRulersSet methods.
· waveform rendering settings are managed through the SPECTR_ENH_WAVE_SETTINGS data structure accessible through the combination of the SpectrumEnh.SettingsWaveGet and SpectrumEnh.SettingsWaveSet methods.

A background picture can be added as well through the SpectrumEnh.SetBackPictureFromFile and SpectrumEnh.SetBackPictureFromHandle methods:

Samples of use of the SpectrumEnh object in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- SpectrumEnhanced


How to perform custom feedbacks rendering using graphic bars

How to perform custom feedbacks rendering using graphic bars

Active DJ Studio comes with some new graphical feature implemented through the GraphicBarsManager property: one of these features is the capability to display graphic bars in both horizontal and vertical orientations; these bars work as child controls of the container form (with their own HWND window handle) so the first thing to do is to create one or more instance of the control through a call to the GraphicBarsManager.Create method; as all of the other windows control, the graphic bars can be moved and resized (GraphicBarsManager.Move method), shown or hidden (GraphicBarsManager.Show method), refreshed (GraphicBarsManager.Refresh method) or destroyed (GraphicBarsManager.Destroy method).

Graphic bars can be used for the following purposes:

· VU-Meter bars rendering

· Spectrum bars rendering

· Progress bars rendering

Exactly as for regular Progress bar controls, graphic bars have a range, defined through the GraphicBarsManager.GetRange and GraphicBarsManager.SetRange methods, and a value defined through the GraphicBarsManager.GetValue and GraphicBarsManager.SetValue methods.

Graphical settings related to a specific graphic bar can be retrieved and modified through the GraphicBarsManager.GetGraphicalSettings and GraphicBarsManager.SetGraphicalSettings methods: both of them receive in input a GRAPHIC_BAR_SETTINGS data structure which can manage the following settings:

· Orientation through the nOrientation property.

· Colors through the colorStart, colorEnd and colorBackground properties: you can define two colors used for rendering the current value so the graphic bar can display either a gradient color or a solid color.

· 3D appearance through the bAppearance3d property

· Smoothing through the bSmoothing property; graphic bars can be led-based but they can also appear smoothed as seen on the images below:

· Automatic drop through the bAutomaticDrop property; this feature allows decreasing the displayed value to 0 with a certain delay as seen on certain hardware based VU-meters when no input sound is available.

· Gradient shape through the nShape property; you can define how the gradient limits are rendered as seen on the samples below:

When using the control inside a web page, where managing data structures is not an easy task, you can access single parameters of the GRAPHIC_BAR_SETTINGS data structure using the GraphicBarsManager.GetGraphicalSettingsParam and GraphicBarsManager.SetGraphicalSettingsParam methods.

When using the graphic bar for rendering a VU-Meter bar, you will have to set the range of the graphic bar from 0 to 32767 (using the GraphicBarsManager.SetRange method) and use values sent by the VUMeterValueChange event when calling the GraphicBarsManager.SetValue method.

When using the graphic bar for rendering a Spectrum bar, you will have to set the range of the graphic bar from 0 to 100 (using the GraphicBarsManager.SetRange method) and, after receiving the SpectrumValueChange event, make a call to the Spectrum.GetTable method in order to obtain the 64 values of the spectrum's table: at this point, depending upon the number of instanced spectrum bars, call the GraphicBarsManager.SetValue method for each of them passing the related value contained inside the spectrum table.

Samples of use of the GraphicBarsManager object in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- Feedbacks

- TestEqualizer

- TestVideoPlayer


How to obtain the sound's waveform

How to obtain the sound's waveform

After loading a sound inside a player, through one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory or LoadTrackFromCd methods, the Waveform object allows generating a bitmap of the sound's waveform: this bitmap can represent the sound in its full length or, in alternative, one or more portions (also known as "views") of the same sound.

In order to generate one or more bitmaps of the loaded sound, the control needs to analyse the sound's contents: this task is performed through a call to the Waveform.AnalyzeFullSound method. The analysis can be more or less accurate depending upon the resolution passed to the nResolution parameter; higher resolutions will allow a better quality because more peaks will be detected: as a side effect, higher resolutions will require more memory and will generate larger bitmaps. The analysis can be aborted at any time through a call to the Waveform.AnalyzeAbort method.

After calling this method, the control will allow the container application to stay up-to-date about the analysis advancement through the following events:

· WaveAnalysisStart: fired when the sound's analysis begins.
· WaveAnalysisPerc: fired several times during the analysis in order to inform the container application about the percentage of advancement.
· WaveAnalysisDone: fired when the sound's analysis is completed: after catching this event, it will be possible requesting to the control the creation of the waveform's bitmap through a call to the Waveform.BitmapViewSaveToFile or Waveform.BitmapViewSaveTomemory methods. It's important to note that this event will report the exact number of peaks detected inside the loaded sound and the exact duration in milliseconds of each peak. When generating the bitmap for the full sound's waveform, the reported number of peaks will be exactly equal to the width in pixels of the bitmap. In case you should create a view of a given sound's range, you could obtain the number of pixels needed to display the waveform's view through a call to the Waveform.BitmapViewGetWidth method.

After having analyzed a certain song, in order to save CPU time when you will load and analyze again the same song, you have the possibility to store analyzed waveform's peaks into a file using the Waveform.PeaksSave method and to retrieve them at a later time using the Waveform.PeaksLoad method: WaveAnalysisStart and WaveAnalysisDone events will be generated in this case also.

The generated waveform's bitmap will be represented using the Waveform.ColorLine and Waveform.ColorBackground colors. You can also decide if the peaks of the waveform should be drawn with a color which is half the intensity of the color set through the Waveform.ColorLine property by setting the Waveform.UseHalfColorForPeaks property.

Below you can see five bitmaps generated using the same sound (whose duration is around 2.4 seconds length) but with five different resolutions (just for your information the song used for generating these bitmaps is available on this link); all these bitmaps have been created using the same height of 100 pixels:

Resolution passed to AnalyzeFullSound method | Generated bitmap
WAVEFORM_RES_MAXIMUM |
WAVEFORM_RES_VERY_HIGH |
WAVEFORM_RES_HIGH |
WAVEFORM_RES_MIDDLE |
WAVEFORM_RES_LOW |

As mentioned before, you can also generate a "view" of a defined portion of the loaded sound: on the bitmap below you can see the original song in its full length (with WAVEFORM_RES_MAXIMUM resolution)

and below you can see the view of the same song for the range between 500 and 1500 milliseconds

On the samples above we have used a very small song limited to 2.4 seconds: in case you should be in need of displaying the full waveform of a longer song on a space much smaller than the total number of required pixels, the Waveform.BitmapViewSaveToFile and Waveform.BitmapViewSaveToMemory methods will shrink the waveform in order to fit exactly inside the available space; in the example below you can see a 3 minutes song fitting inside a 455 pixels wide bitmap: the original full length bitmap, using the WAVEFORM_RES_MAXIMUM resolution, would require a width of 243,683 pixels.

VERY IMPORTANT: When using high resolutions and big sound files, keep count that the Windows operating system has limits on the size of bitmaps creation; this means that it would be better avoiding the creation of very large bitmaps: in this case it would be a better approach splitting the total song's bitmap into several smaller bitmaps, for example creating bitmaps whose width in pixels doesn't exceed the current screen width.

After catching the WaveAnalysisDone event, it will be also possible rendering the waveform directly inside a graphical device context (through its handle or HDC) using the Waveform.BitmapViewDrawToHdc method; this may be quite useful if you should need to perform real-time rendering of the waveform on the screen. Although this could be also used for creating a scrolling waveform during playback, we suggest checking the How to scroll the sound's waveform during playback tutorial for further details about managing a scrolling waveform.

In case you should need to perform your own graphic rendering of waveform's peaks, after the analysis you could obtain peak values for the full file or for a portion of the same through the Waveform.PeaksBufferGet method.

When dealing with video clips, after having loaded the video clip into a certain player, you can extract its audio track through the VideoPlayer.AudioTrackExtract method and, after completing the extraction, you can proceed to the sound waveform analysis as described for regular sound files.

Samples of waveform management in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- BeatsDetection

- Waveform

- WaveformScroll

For further details about using the embedded Waveform refer to the Waveform object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.


How to scroll the sound's waveform during playback

How to scroll the sound's waveform during playback

Many multimedia applications allow displaying a waveform scroller whose purpose is to scroll the waveform during playback and to keep the current position centered on the scrolling waveform, with a vertical line that indicates the effective playback position; the screenshot below shows a song's waveform when playback position is 0, meaning that the sound is stopped or paused:

the screenshot below shows a song's waveform when playback position is 5 seconds:

Active DJ Studio allows implementing a scrolling waveform through the embedded WaveformScroller object accessible through the WaveformScroller property.

In order to create a scrolling waveform we need to call the WaveformScroller.Create method and then we need to set how many milliseconds of waveform will be displayed inside the waveform's view: by default this value is set to 10 seconds (5 seconds on the right of the vertical line and 5 seconds on the left of the vertical line) but it can be modified at any time through the WaveformScroller.SetViewLength method.

Graphical settings related to a specific waveform scroller can be retrieved and modified through the WaveformScroller.SettingsGet and WaveformScroller.SettingsSet methods: both of them receive in input a WSCROLLER_SETTINGS data structure. You can also set a background picture to be displayed under the waveform through the WaveformScroller.SetBackPictureFromFile and WaveformScroller.SetBackPictureFromHandle methods.

At this point, after loading a sound inside a player, through one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory or LoadTrackFromCd methods, we need to analyze the sound's waveform through the Waveform object so we need to perform a call to the Waveform.AnalyzeFullSound method. The analysis can be more or less accurate depending upon the resolution passed to the nResolution parameter; higher resolutions will allow a better quality because more peaks will be detected: as a side effect, higher resolutions will require more memory; further details about sound's waveform analysis can be found inside the How to obtain the sound's waveform tutorial.

Once the waveform analysis has been completed and the WaveAnalysisDone event has been received, the WaveformScroller object will automatically display the waveform of the sound with the current playback position centered and displayed by a vertical line, exactly as seen on the screenshot above. In case playback should be started through the PlaySound method or in case the current playback position should be moved through the SeekSound or ForwardSound or RewindSound methods, the waveform scroller would automatically update the waveform view to keep the current position updated.

The waveform scroller can also display custom vertical lines added to the waveform's view through the Waveform.BitmapViewVerticalLineAdd method. Below an example of two vertical lines, rendered in red color, when the current center position of the bitmap view is set to 5000 ms.

Below the same exact red lines when the current center position has been moved to 6000 ms.

The waveform scroller supports direct mouse interaction: through the left button of your mouse you can modify the current position by pressing the left button, moving the mouse horizontally and finally by releasing the button when the needed playback position is reached. During playback, pressing the left mouse button will also put the player in paused state; by releasing the mouse playback will be automatically resumed.

When playback position is moved through the mouse, the control fires the WaveScrollerManualScroll event that notifies the container application about the new position. As a further feature, any mouse event generated on the waveform scroller, for example when the right mouse button is clicked, will be notified to the container application through the WaveformScrollerMouseNotification event.

By default, during the waveform scrolling the sound is muted: you can modify this behaviour through the WaveformScroller.PlaybackOnScrollEnable method: when playback is enabled, the control will render audio data at the same rate of the scrolling speed.

Examples of usage of the waveform scroller can be seen inside the DjStudioDemo and WaveformScroll samples.


How to mix your songs

How to mix your songs

When using more than one player inside the same application, it can be useful, in order to have a good mixing experience, to have the possibility to change the Tempo or Playback rate of a certain song; for this purpose this control provides a set of methods that will help you achieving this task.

First of all you need to load the song using the LoadSound method: once the song has been loaded you can change the following parameters:

· Volume: the StreamVolumeLevelSet method changes the sound volume of a specific player. The current volume can be obtained through the StreamVolumeLevelGet method.
· Volume sliding: the StreamVolumeSlide and StreamVolumeSlideEx methods allow sliding the sound volume of a specific player in a given amount of time. Also in this case the current volume can be obtained through the StreamVolumeLevelGet method and you can know if a sliding is occurring through the StreamVolumeIsSliding method.
· Tempo: the Effects.PlaybackTempoSet method changes the sound to play at faster or slower speed than original, without affecting the sound pitch. The actual tempo percentage can be retrieved using the Effects.PlaybackTempoGet method.
· Playback rate: the Effects.PlaybackRateSet method changes both the sound tempo and pitch, as if an LP disc was played at wrong RPM rate. The actual playback rate percentage can be retrieved using the Effects.PlaybackRateGet method.
· Pitch: the Effects.PlaybackPitchSet method changes the sound pitch or key, without affecting the sound tempo or speed. The actual pitch can be retrieved using the Effects.PlaybackPitchGet method.

Note that changing Tempo and Playback rate, the overall song duration will result altered: you will be notified of this alteration through the SoundDurationChanged event. The SoundDurationGet and SoundDurationStringGet methods may keep count of the duration change by setting the bKeepCountOfRateChange parameter to "BOOL_TRUE".

If you want to create a fader to perform fade-in/fade-out automatically, take a look to the How to use the Automatic Fader section.

A sample that shows the mentioned features in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- TestPlayers


How to use the control as a source for streaming servers like SHOUTcast

How to use the control as a source for streaming servers like SHOUTcast

Return to chapter overview

Active DJ Studio can work as a source client for the following streaming servers:

· SHOUTcast (versions 1 and 2), developed by Nullsoft, is a freeware server for streaming media. The most common use of SHOUTcast is for creating or listening to Internet audio broadcasts. SHOUTcast makes it possible to inexpensively set up an Internet broadcasting station, so hobbyists and large radio network owners alike can use it to set up their own broadcasting network for a fraction of the cost of a traditional AM broadcasting or FM radio station: Active DJ Studio can work as a source client for SHOUTcast servers through the use of an external encoder: currently supported formats are:

- MP3 through the Lame.exe external encoder

- AAC+ through the Fdkaac.exe external encoder

- Ogg Vorbis through the OggEnc.exe external encoder.

· Icecast, developed and maintained by the Xiph.org Foundation, is an open-source server streaming media project and is very similar to the already mentioned SHOUTcast; also in this case, Active DJ Studio can work as a source client for Icecast servers through the use of an external encoder: currently supported formats are:

- MP3 through the Lame.exe external encoder

- AAC+ through the Fdkaac.exe external encoder

- Ogg Vorbis through the OggEnc.exe external encoder.

· Windows Media Services (WMS) is a streaming media server, developed from Microsoft, that allows an administrator to generate streaming media through entities named "publishing points". Active DJ Studio can work as a source client for WMS by leveraging Windows Media components, installed in Windows, that will act as an external encoder and send the audio stream in WMA (Windows Media Audio) format to a given publishing point. Related to WMA format, Active DJ Studio can also send its audio output directly to a network port, allowing other clients to connect to the IP address and port combination of the PC running Active DJ Studio in order to get audio data without the interaction of a server.

If you take a look to the graph above, you will see that there are two ways to send an audio stream to a streaming server:

· Through the output of a custom Stream Mixer
· Through the output of a player directly
· Through the output of a WASAPI loopback device (Windows Vista and later versions only)

Below you will find information about the way to achieve both of them with SHOUTcast/Icecast servers or with WMS servers and, as a further information, how to stream in WMA format directly to the network.

· Sending streaming media to SHOUTcast and Icecast servers

· Through a custom Stream Mixer: in this case the stream mixer will send mixed streams to the external encoder and then to the server; for this purpose you need to create the casting session through a call to the CastingCreateFromStreamMixer method. For further information about the use of custom Stream Mixers refer to the tutorial How to use custom Stream Mixers.
· Through a player directly: in this case the player will send the previously loaded sound (for example through the LoadSound method) to the external encoder and then to the server; for this purpose you need to create the casting session through a call to the CastingCreateFromPlayer method. With this method you can only cast sound files and not Internet streams so it won't be possible casting sounds loaded through the LoadInternetStream method; in order to cast streams loaded from an Internet server you will have to rely upon a custom stream mixer and upon the CastingCreateFromStreamMixer method described above.
· Through the output of a WASAPI loopback device (Windows Vista and later versions only): in this case any sound being played through a render audio endpoint device, also by external applications like Windows Media Player, is sent to the external encoder and then to the server; for this purpose you need to create the casting session through a call to the CastingCreateFromWasapiLoopback method. For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

All of the mentioned methods, if successful, will return a unique identifier that will be used in order to take further actions on the casting session; the connection to the server is established through a call to the CastingStart method and interrupted through a call to the CastingStop method. While a casting session is connected to the server, you can set the title of the casting session through the CastingSetTitle method and to obtain statistics, in XML format, about the casting session through the CastingGetXmlStatistics method.

When dealing with a SHOUTcast version 2 server it's also possible sending metadata to the server through the usage of the CastingSendMetaData and CastingSendMetaDataString methods.

The container application can be maintained up-to-date about the casting session through a dedicated set of events:

· If the casting session has been initiated by a custom Stream Mixer, the call to the CastingStart method will generate the CastingStreamMixerStart event while the call to the CastingStop method will generate the CastingStreamMixerStop event.
· If the casting session has been initiated by one of the available players, the call to the CastingStart method will generate the CastingPlayerStart event while the call to the CastingStop method or the completion of the transmission of the loaded file will generate the CastingPlayerDone event. During the transmission of the loaded file the container application can be informed about its advancement through the CastingPlayerPerc event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the CastingStart method will generate the CastingWasapiLoopbackStart event while the call to the CastingStop method will generate the CastingWasapiLoopbackStop event.

You can know if a casting session is active through the CastingIsActive method.

· Sending streaming media to WMS servers

· Through a custom Stream Mixer: in this case the stream mixer will send mixed streams to the external encoder and then to the server; for this purpose you need to create the casting session through a call to CastingWmaPubPointOpenForStreamMixer method for WMS servers. For further information about the use of custom Stream Mixers refer to the tutorial How to use custom Stream Mixers.
· Through a player directly: in this case the player will send the previously loaded sound (for example through the LoadSound method) to the external encoder and then to the server; for this purpose you need to create the casting session through a call to the CastingWmaPubPointOpenForPlayer method for WMS servers. With this method you can only cast sound files and not Internet streams so it won't be possible casting sounds loaded through the LoadInternetStream method.
· Through the output of a WASAPI loopback device (Windows Vista and later versions only): in this case any sound being played through a render audio endpoint device, also by external applications like Windows Media Player, is sent to the external encoder and then to the server; for this purpose you need to create the casting session through a call to the CastingWmaPubPointOpenFromWasapiLoopback method for WMS servers. For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

All of the mentioned methods, if successful, will return a unique identifier that will be used in order to take further actions on the casting session; when called, you will need passing them the "bitrate" used to stream audio: you can enumerate available bitrates through the WmaBitrateCount and WmaBitrateGet methods. The connection to the server is established through a call to the CastingStart method and interrupted through a call to the CastingStop method.

The container application can be maintained up-to-date about the casting session through a dedicated set of events:

· If the casting session has been initiated by a custom Stream Mixer, the call to the CastingStart method will generate the CastingStreamMixerStart event while the call to the CastingStop method will generate the CastingStreamMixerStop event.
· If the casting session has been initiated by one of the available players, the call to the CastingStart method will generate the CastingPlayerStart event while the call to the CastingStop method or the completion of the transmission of the loaded file will generate the CastingPlayerDone event. During the transmission of the loaded file the container application can be informed about its advancement through the CastingPlayerPerc event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the CastingStart method will generate the CastingWasapiLoopbackStart event while the call to the CastingStop method will generate the CastingWasapiLoopbackStop event.

While a casting session is active and connected to the server, you can set WMA tags through the CastingWmaSetTag method. You can know if a casting session is active through the CastingIsActive method.

· Streaming in WMA format to the network

· Through a custom Stream Mixer: in this case the stream mixer will send mixed streams to the external encoder and then to to a given network port; for this purpose you need to create the casting session through a call to CastingWmaNetworkOpenForStreamMixer method. For further information about the use of custom Stream Mixers refer to the tutorial How to use custom Stream Mixers.
· Through a player directly: in this case the player will send the previously loaded sound (for example through the LoadSound method) to the external encoder and then to a given network port; for this purpose you need to create the casting session through a call to the CastingWmaNetworkOpenForPlayer method. With this method you can only cast sound files and not Internet streams so it won't be possible casting sounds loaded through the LoadInternetStream method; in order to cast streams loaded from an Internet server you will have to rely upon a custom stream mixer and upon the CastingWmaNetworkOpenForStreamMixer method described above.
· Through the output of a WASAPI loopback device (Windows Vista and later versions only): in this case any sound being played through a render audio endpoint device, also by external applications like Windows Media Player, is sent to the external encoder and then to a given network port; for this purpose you need to create the casting session through a call to CastingWmaNetworkOpenFromWasapiLoopback method. For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

All of the mentioned methods, if successful, will return a unique identifier that will be used in order to take further actions on the casting session; when called, you will need passing them the "bitrate" used to stream audio: you can enumerate available bitrates through the WmaBitrateCount and WmaBitrateGet methods. The connection to the server is established through a call to the CastingStart method and interrupted through a call to the CastingStop method.

The container application can be maintained up-to-date about the casting session through a dedicated set of events:

· If the casting session has been initiated by a custom Stream Mixer, the call to the CastingStart method will generate the CastingStreamMixerStart event while the call to the CastingStop method will generate the CastingStreamMixerStop event.
· If the casting session has been initiated by one of the available players, the call to the CastingStart method will generate the CastingPlayerStart event while the call to the CastingStop method or the completion of the transmission of the loaded file will generate the CastingPlayerDone event. During the transmission of the loaded file the container application can be informed about its advancement through the CastingPlayerPerc event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the CastingStart method will generate the CastingWasapiLoopbackStart event while the call to the CastingStop method will generate the CastingWasapiLoopbackStop event.

While a casting session is connected to the server, you can set WMA tags through the CastingWmaSetTag method and to get some information, like the number of connected clients and the network port used for streaming, through the CastingWmaGetInfo method. You can enumerate IP addresses, connected to your casting session, through the CastingWmaConnectedIPGetCount and CastingWmaConnectedIPGetDesc methods.

While a casting session is active and connected to the server, you can set WMA tags through the CastingWmaSetTag method. You can know if a casting session is active through the CastingIsActive method. Each time a client is connected/disconnected, the container application receives a WmaNetworkClientConnect event with a flag that specifies if there was a connection or disconnection and with the IP address of the client machine originating the request.

IMPORTANT NOTICE ABOUT FIREWALL PRESENCE

If the computer that is hosting the server, or the computer that is hosting the container application, has an active firewall or is behind a router, there are settings that must be configured in order to allow data communication. Refer to your firewall and/or router documentation in order to know which settings must be changed.

Samples of casting in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- Casting

- CastMixedStreams

- CastWasapiLoopback

- StreamMixer (requires the installation of Active Sound Suite)

- WasapiStreamMixer (requires the installation of Active Sound Suite)


How to create and use an Equalizer

How to create and use an Equalizer

Active DJ Studio comes with an embedded equalizer which allows setting up a pool of equalizer bands; each equalizer band works on a different frequency and the current available range of frequencies is from 1 to 16000 Hz.

Each equalizer band is always identified by its frequency expressed in Hertz: it's not possible defining more than one band having the same frequency. Note that a band's frequency cannot exceed one-third of the frequency of the sound under editing so, if you have loaded a sound with a frequency of 44100 Hz, the maximum allowed band's frequency will be 14700 Hz (14700 * 3 = 44100); in order to reach a band's frequency of 16000 Hz, you must load sounds whose frequency is at least 48000 Hz.

The first step for creating an equalizer band and for adding it to the control's equalizer is to call the Effects.EqualizerBandAdd method. Each band can be removed at a later time using the Effects.EqualizerBandRemove method and its settings can be retrieved through the Effects.EqualizerBandParamsGet method and modified through the Effects.EqualizerBandGainSet and Effects.EqualizerBandParamsSet methods.

Existing bands can be enumerated using the Effects.EqualizerBandCountGet and Effects.EqualizerBandFrequencyGet methods.

Once the equalizer has been defined, there is the possibility to store its bands and their respective settings into a destination file through the Effects.EqualizerSaveToFile method and retrieved at a later time through the Effects.EqualizerLoadFromFile method.

Equalizer settings are stored into a XML based file (usually with .EDJ extension) and has a structure like the sample below:

<?xml version="1.0" ?>

<Equalizer>

 <Bands>

     <Band FreqInHz="80" BandWidth="12" GainIndB="-5.200000">0</Band>

     <Band FreqInHz="170" BandWidth="12" GainIndB="3.750000">1</Band>

     <Band FreqInHz="310" BandWidth="12" GainIndB="0.000000">2</Band>

     <Band FreqInHz="600" BandWidth="12" GainIndB="-4.500000">3</Band>

     <Band FreqInHz="1000" BandWidth="12" GainIndB="-3.000000">4</Band>

     <Band FreqInHz="3000" BandWidth="12" GainIndB="1.125000">5</Band>

     <Band FreqInHz="6000" BandWidth="12" GainIndB="5.250000">6</Band>

     <Band FreqInHz="12000" BandWidth="12" GainIndB="6.750000">7</Band>

     <Band FreqInHz="14000" BandWidth="12" GainIndB="-3.120000">8</Band>

 </Bands>

</Equalizer>

As you can see each band has a progressive number (in the case above from 0 to 8) and is identified by the frequency stored inside the FreqInHz attribute (expressed in Hertz) while its parameters are defined inside the BandWidth (expressed in semi-tones) and GainIndB (expressed in dB) attributes.

EDJ format is also used by our Active Sound Editor component.

A further feature for setting up the equalizer is to load bands containing presets as defined by WinAmp™ using the Effects.EqualizerLoadPresets method.

The equalizer can be enabled or disabled, without changing parameters of various bands, through the Effects.EqualizerEnable method and the gain of available bands can be reset to 0 dB using the Effects.EqualizerReset method.

Active DJ Studio supports automatic equalization of loaded sound files: for each sound file you have the possibility to create a specific EDJ file containing optimal equalization settings for the sound file to load; automatic equalization can be enabled through the EnableAutoEqualiz property and obtained by adding a .EDJ sound inside the same folder containing the loaded sound: if for example the loaded sound file should be named MySong.mp3, the corresponding EDJ file should be named MySong.mp3.edj : when the control will find this specific file inside the same folder of the loaded sound it will automatically create and apply the requested bands of the equalizer and will also fire an EqualizerLoaded event.

The creation and use of equalizer bands requires DirectX version 8 or higher to be installed on the target system: you can verify the availability of this DirectX version calling the IsDirectX8Avail method.

Samples of use of Equalizers in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- TestEqualizer

- TestPlayers

- TestVideoPlayer

- SpecialEffects


How to apply special effects to a playing sound

How to apply special effects to a playing sound

This control supports the following kinds of special effects:

Custom DSP effects

Preamplifier

Filters

Channels remapping, swapping and mixing

Misc effects

Vocal remover

Normalization

DC Offset removal

Multiplex management

VST effects

DirectX Media Object effects

Equalizer

Reverse playback

EAX effects

Custom DSP effects

The purpose of custom DSP effects is to give the developer the possibility to apply custom DSP algorithms to the sound under playback. Check the How to manage custom DSP effects tutorial for further details.

Preamplifier

Pre-amplification of the loaded sound can be enabled or disabled through the Effects.PreAmplifierEnable method.

For stereo and mono sounds the current pre-amplification value can be obtained through the Effects.PreAmplifierValueGet method and changed through the Effects.PreAmplifierValueSet method.

For multi-channel songs like 5.1 or 7.1 the current pre-amplification value assigned to each speaker can be obtained through the Effects.PreAmplifierSpeakerValueGet method and changed through the Effects.PreAmplifierSpeakerValueSet method.

Filters

You can apply or remove a filter (low pass, high pass, band pass or stop band) through the Effects,FilterApply and Effects.FilterReset methods.

Channels remapping, swapping and mixing

You can remap channels of a stereo or multi-channel sound through the Effects.ChannelsRemapApply method: remapping includes the possibility to swap and/or reposition specific channels and also to mix specific channels together. Channels remapping can be reset through the Effects.ChannelsRemapReset method.

Misc effects

You can apply or remove the following types of multi-channel capable effects:

· "AutoWah" effect through the Effects.AutoWahApply and Effects.AutoWahReset methods
· "Chorus" effect through the Effects.ChorusApply and Effects.ChorusReset methods
· "Compressor" effect through the Effects.CompressorApply and Effects.CompressorReset methods
· "Distortion" effect through the Effects.DistortionApply and Effects.DistortionReset methods
· "Echo" effect through the Effects.EchoApply and Effects.EchoReset methods
· "Freeverb reverberation" effect through the Effects.FreeverbApply and Effects.FreeverbReset methods
· "Phaser" effect through the Effects.PhaserApply and Effects.PhaserReset methods
· "Bass boost "effect through the Effects.BassBoostApply and Effects.BassBoostReset methods

Vocal remover

You can apply or remove the vocal remover filter through the Effects.F ilterVocalRemoverApply and Effects.FilterVocalRemoverReset methods.

Normalization

You can apply or remove normalization to a playing sound through the Effects.NormalizationEnable method.

DC Offset removal

You can enable or disable DC Offset removal to a playing sound through the Effects.DcOffsetRemovalEnable method.

Multiplex management

Multiplex, also known as "MPX", is a type of Karaoke software that has specially formatted left and right channels to make multiplex features available: you can enable MPX management through the Effects.MPXEnable and control the vocal attenuation through the Effects.MPXSetVocalAttenuation method.

VST effects

Steinberg''s Virtual Studio Technology (VST) is an interface for integrating software audio synthesizer and effect plugins with audio editors and hard-disk recording systems. VST and similar technologies use Digital Signal Processing (DSP) to simulate traditional recording studio hardware with software. Thousands of plugins exist and VST is supported by a large number of audio applications. Check the How to manage VST effects tutorial for further details.

DirectX Media Object effects

DirectX Media Objects (also known as DMO) are components that can be inserted in a media stream to manipulate the data in some way. In audio, DMOs are generally used to create special effects.

The use of DMO requires DirectX version 8 or higher: you can check if your system has the required DirectX version installed using the IsDirectX8Avai l method.

The following standard effects are installed with the operating system:

Chorus

Compression

Distortion

Echo

Environmental reverberation (I3DL2)

Flange

Gargle

Parametric equalizer

Waves reverberation (music reverb based on the Waves MaxxVerb technology, licensed to Microsoft)

These effects can be used with any sound format supported by our control and come with their own default settings: you can retrieve the current settings using the Effects.DirectXEffectParamsGet and you can change them using the Effects.DirectXEffectParamsSet . Once the effect parameters have been setup, you can apply/remove an effect using the Effects.DirectXEffectApply method; in case you should need to apply more effects at the same time, and you should need to apply them in a specific order, you could add them to the chain of effects with a specific priority.

Note that more than one DMO effect can be applied on a playing sound.

Equalizer

Sound equalization is obtained through the DMO effect "Parametric equalizer". Check the How to create and use an Equalizer tutorial for further details.

Reverse playback

Reverse playback can be enabled or disabled through the Effects.SoundDirectionEnable method: during playback you can modify the sound's playback direction through the Effects.SoundDirectionSet method and obtain the current direction through the Effects.SoundDirectionGet method.

EAX effects

EAX environmental effects, available only on Windows XP, can be applied to a given output device (sound card) in order to enhance your music listening experience: not all of the commercial sound cards implement EAX and not all of the sound cards implementing EAX reach the same quality you can have with Creative sound cards. You can check if an output device supports EAX through a call to the IsEAXAvailableOnOutputDevice method.

EAX parameters (volume, decay and damping) applied to a given output device can be obtained through the GetEAXEffect method and changed through the SetEAXEffect and SetEAXEffectPresets methods. Differently from DMO effects, which are applied directly to an existing player, EAX parameters are applied to a given output device: this means that EAX settings will automatically affect all of the players associated to an EAX compatible output device.

At runtime it's easy to know if a given player is associated to an EAX compatible output device through the IsEAXAvailable method and obtain/modify the EAX wet/dry mix ratio for that specific player through the GetEAXEffectWetDryMix and SetEAXEffectWetDryMix methods.

It's important to note that EAX effects can be applied only to sounds loaded through the LoadSoundForEAX method: this method will load a given song in Mono and will not allow further Tempo, Playback rate and Pitch changes.

EAX supported effects are the following:

None (removes the current EAX effect, if any)

Generic

Padded cell

Room

Bathroom

Living room

Stone room

Auditorium

Concert hall

Cave

Arena

Hangar

Carpeted hallway

Hallway

Stone corridor

Alley

Forest

City

Mountains

Quarry

Plain

Parking lot

Sewer pipe

Underwater

Drugged

Dizzy

Psychotic

It's important to note that EAX effects are mutually exclusive: you cannot have more than one EAX effect applied on an output device.

Samples of use of the mentioned special effects in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- SpecialEffects

- VstEffects

- CustomDSP

- CustomDSPWithUI

- TestEqualizer

- TestVideoPlayer


How to manage custom DSP effects

How to manage custom DSP effects

The purpose of custom DSP effects, implemented through a set of methods of the CustomDSP COM object, is to give the developer the possibility to apply DSP algorithms to the sound under playback: the concept of DSP effects is quite similar to the concept of Steinberg's Virtual Studio Technology (VST) effects but with some simplification and with more expansion possibilities.

As for VST effects, the main purpose of custom DSP effects is to take a stream of audio data, apply a process to the audio and return the result to the container application: as a secondary purpose, custom DSP effects can be used to perform sound analysis in real time, allowing for example the display of visual feedbacks or separation of stereo audio channels into different output files.

The core functionality of DSP effects is the callback function: this function is called by the DSP system and receives a buffer, containing sound samples, a parameter which tells the size in bytes of the buffer and a third parameter that allows passing to the callback a user-defined value. Samples inside the buffer can be in the following formats:

· If loaded sound file is 8 bits per sample, each sample is represented by a signed integer on 1 byte whose value could be in the range from -127 to 127
· If loaded sound file is 16 bits per sample, each sample is represented by a signed integer on 2 bytes whose value can be in the range from -32768 to 32767
· Whichever the resolution of the loaded sound file, after a call to the CustomDSP.UseFloatSamples method each sample is represented by a floating point on 4 bytes whose value can be in the range from -1.0 to 1.0; values are not automatically capped so you could also get values outside of this range

In all cases described above, for stereo files the sequence of samples will be left channel first followed by right channel. See below a C++ sample of a callback that, after a call to the CustomDSP.UseFloatSamples method, will process a stereo file in order to swap the left channel with the right channel:

void WINAPI fnSwapStereoChannels (void *bufferSamples, DWORD bufferSamplesLength, DWORD dwUserData)

{

// cast the buffer to floating point

float *buffTemp = (float *) bufferSamples;

// calculate total number of samples passed to the callback

DWORD nTotalSamples = bufferSamplesLength / sizeof (float);

// loop through the buffer

DWORD index;

for (index = 0; index < nTotalSamples; index +=2)

{

// swap left channel sample with right channel sample

float fSample = buffTemp[index];

buffTemp[index] = buffTemp[index+1];

buffTemp[index+1] = fSample;

}

}

In case you should apply more than one custom DSP at the same time, it's important to remember that the type used for managing samples must always match: it's not allowed applying custom DSPs using floating point samples and custom DSPs using integer samples at the same time.

There are two types of custom DSP effects:

· Internal DSP effects

The code of these effects is inserted directly inside the code of the container application: usually the DSP code will be limited to a callback function containing the DSP algorithm and to some variable that will store parameters used by the DSP algorithm itself.

In order to initialize an internal DSP effect, you need to create a unique identifier for the internal DSP effect: this task can be achieved through a call to the CustomDSP.InternalLoad method: the return value of this call will be a 32 bits value that will identify the internal DSP effect.

At this point you need to set the callback function that will apply the DSP algorithm to incoming sound data: for this purpose you need to create a specific callback function inside your code and then to pass this function to Active DJ Studio calling the CustomDSP.InternalSetFunction method. It's important to remember that the algorithm of the DSP effect inside the callback function must be as quick as possible and should never call functions or APIs that could require user's interaction like message boxes and similar.

VERY IMPORTANT WARNING for VB6 users

The Microsoft Visual Basic 6 IDE (Integrated Development Environment) is not safe when dealing with callbacks and secondary threads and could sometime cause unpredictable GPFs or dead-lock situations so it's highly recommended to avoid executing internal DSP code from the VB6 IDE directly or you may experience a crash of VB6 itself. In order to test the code of the DSP, please, compile the EXE of the application and launch the EXE from outside of VB6.

· External DSP effects

The code of external DSP effects is inserted inside external dynamic-link library (DLL) files which need to export one or more pre-defined functions.

In order to initialize an external DSP effect, you need to create a unique identifier for the external DSP effect: this task can be achieved through a call to the CustomDSP.ExternalLoad method which will receive the filename or the absolute pathname of the external DLL file and will return a 32 bits value that will identify the external DSP effect: this method can be considered a specialized version of the LoadLibrary Windows API.

Once we have successfully loaded the external DSP and obtained its unique identifier, we can gain access to its exported functions through the CustomDSP.ExternalSetFunction method which can be considered a specialized version of the GetProcAddress Windows API.

Functions exported by the dynamic-link library (DLL) containing the DSP effect should be one or more of the following:

· The callback function used to apply the DSP algorithm to incoming sound data: the presence of this function should be considered as mandatory. The callback function is called internally after invoking the CustomDSP.Enable method: it's important to note that the code of the callback function must be as quick as possible and should never call functions or APIs that could require user's interaction like message boxes and similar.

· Two function used to obtain and set parameters used by the algorithm of the external DSP effect. Calls to these functions at runtime are wrapped within calls to the CustomDSP.ExternalGetParameters and CustomDSP.ExternalSetParameters methods. As you may understand, each DSP effect will come with its own set of parameters so they will need to be defined by the DSP developer himself and made public in order to be managed by our container application: just to make a comparison with the Microsoft's SDK, the developer that will write a DSP effect will have to deliver a sort of ".h" include file containing the definition of all of the needed data structures allowing their use from within the container application.

· The function used to send custom commands to the external DSP. This is an optional function and its call at runtime is wrapped within a call to the CustomDSP.ExternalSendCommand method. This function allows the container application sending pre-defined custom commands to the DSP effect in form of a string of characters: as you may understand this gives great flexibility and allows the developer of the DSP effect to define a "dialect" of custom commands. There is no limitation to the way these custom commands could be defined or used: they could be seen as a sort of "command line" where you could define your own set of options and parameters or as a XML formatted string containing both commands and parameters: parsing contents of these commands will be obviously responsibility of the external custom DSP effect. After receiving a custom command, the DSP effect will have the possibility to immediately reply through the return value of the CustomDSP.ExternalSendCommand method or, in case of a lengthy operation managed inside a secondary thread, at a later time through the use of the PostMessage Windows API, sending a user-defined message to the window (HWND) of the container form or dialog box.

· The function used to display or hide the editor (user interface) of the external DSP: editors can be useful in order to display custom user interfaces which allows modifying the algorithm parameters through user's interaction: its presence can be certainly considered as optional. The call to this function at runtime is wrapped within a call to the CustomDSP.ExternalEditorShow method.

· The function used to obtain information about the editor (if available) of the external DSP. The call to this function at runtime is wrapped within a call to the CustomDSP.ExternalEditorGetInfo method. Typical editor's parameters could be its visibility state, its coordinates and dimensions respect to the client area of the parent window but also colors for customizing the appearance of the editor.

It's certainly worth to mention that an external dynamic-link library (DLL) could contain more than one DSP effect: in this case, for each of the available DSP effects you will have to call the CustomDSP.ExternalLoad method (this will obviously generate a specific unique identifier) and the CustomDSP.ExternalSetFunction method for setting the specific callback function.

During playback both internal and external custom DSP effects can be enabled/disabled through the CustomDSP.Enable method: through this method you can not only create a chain of DSP effects but, through its nPriority parameter, you can establish which DSP effect will be processed first.

IMPORTANT NOTICE ABOUT EFFECTS APPLIED TO THE OUTPUT OF A STREAM MIXER BEING SENT TO A CASTING SERVER OR TO THE RECORDER

DSP effects can be applied to the output of a custom stream mixer by using the unique identifier of the custom stream mixer itself for the nPlayer parameter of the effect to apply; if you want that these effects are reflected to the stream going to the casting server or to the recorder control also, you need to set the nPriority parameter of the DSP to a value higher than 0.

Both internal and external custom DSP effects can be discarded from memory using the CustomDSP.Free method.

In order to have a better understanding about the use and implementation of custom DSP effects, you will find some sample of usage of these internal and external DSP effects inside the CustomDSP and CustomDSPWithUI samples installed by the product's setup package. You will also find two projects, written in Visual C++ 6, that demonstrate the implementation of two external custom DSP effects, one containing an editor (named MyCustomDspWithUI) that will implement a simple "Bass Boost" effect and one without any editor (named MyCustomDsp) that will implement two different effects: a simple "Reverb" effect and a simple "Balance" effect.


How to manage VST effects

How to manage VST effects

Steinberg's Virtual Studio Technology (VST) is an interface for integrating software audio synthesizer and effect plugins with audio editors and hard-disk recording systems. VST and similar technologies use Digital Signal Processing (DSP) to simulate traditional recording studio hardware with software. Thousands of plugins exist and VST is supported by a large number of audio applications. The technology can be licensed from its creator, Steinberg.

Active DJ Studio allows managing two kinds of VST plugins up to the VST 2.4 implementation:

· VST effects: this kind of plugins allows processing the audio input, for example for creating a reverb effect, and/or performing analysis of the audio input, for example for creating custom visual feedbacks.
· VST Instruments: this kind of plugins allows generating audio without the need to load it from a sound file: they are generally either virtual synthesizers or samplers

Both kinds of VST plugins are available inside external dynamic-link library (DLL) files.

The first step for integrating a VST plugin is to load it into the control through the VST.EffectLoad method (for VST effects) or through the VST.InstrumentLoad method (for VST instruments). Both mentioned methods receive the filename or the absolute pathname of the external DLL file containing the VST plugin and returns a 32 bits unique identifier that identifies the loaded VST plugin from now on: from a programming perspective, calling this method is quite similar to calling the LoadLibrary Windows API.

Once we have successfully loaded the VST plugin and obtained its unique identifier, we can gain access to other VST related features.

· Generic information about the VST plugin can be obtained through the VST.GetInfo and VST.GetInfoString methods.
· Discriminate if a VST plugin is an effect or an instrument through the VST.GetType method.
· Available programs implemented inside the VST plugin can be enumerated through the VST.ProgramsGetCount method and respective programs names can be obtained/modified through the VST.ProgramNameGet and VST.ProgramNameSet methods.
· The current program can be obtained through the VST.ProgramGetCurrent method and selected through the VST.ProgramSetCurrent method.
· For each program there is the possibility to enumerate the number of available parameters through the VST.ProgramParamsGetCount method and to obtain generic information for each of them through the VST.ProgramParamGetInfo method.
· Each parameter has a default value that can be obtained calling the VST.ProgramParamGetDefaultValue method. The current value can be obtained through the VST.ProgramParamGetValue method and modified through the VST.ProgramParamSetValue method.
· Most VST effects come with their own user interface, also known as "editor": you can know if a loaded VST effect has its own editor through the VST.EditorGetInfo method.
· If an editor is available, you can integrate it and show/hide it on your application's user interface through the VST.EditorShow method and move it through the VST.EditorMove method.

When a parameter has been modified through the editor, the container application is notified through the VstParamChangedValue event.

When the editor's user interface is resized, the container application is notified through the VstEditorResized event.

During playback VST effects can be enabled/disabled through the VST.EffectEnable method: through this method you can not only create a chain of VST effects but, through its nPriority parameter, you can establish which VST effect will be processed first.

IMPORTANT NOTICE ABOUT EFFECTS APPLIED TO THE OUTPUT OF A STREAM MIXER BEING SENT TO A CASTING SERVER OR TO THE RECORDER

VST effects can be applied to the output of a custom stream mixer by using the unique identifier of the custom stream mixer itself for the nPlayer parameter of the effect to apply; if you want that these effects are reflected to the stream going to the casting server or to the recorder control also, you need to set the nPriority parameter of the VST to a value higher than 0.

Differently from VST effects, which process the audio generated by a player taking audio from an external source like an audio file, VST instruments cannot be chained because they are audio source themselves so each of them needs a separate player. You can mix more VST instruments into a single audio stream by creating a custom stream mixer and attaching each separate VST instrument to the mixer.

For VST instruments there is the possibility to apply MIDI events through the VST.InstrumentEventApply method or raw MIDI events through the VST.InstrumentEventRawApply method.

Once the VST plugin is no more needed, it can be discarded from memory using the VST.EffectFree method (for VST effects) or through the VST.InstrumentFree method (for VST instruments).

A sample of use of the VST object in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- VstEffects


How to detect beats positions and BPM

How to detect beats positions and BPM

Active DJ Studio supports both "Beats detection" (BD) analysis and "Beats Per Minute" (BPM) analysis.

· "Beats detection" (BD) analysis can be performed in two ways:

· Offline: in this case beats detection analysis is performed through a call to the BeatsDetectRequest method while the sound to analyze is not in playback status: beats detection is performed in a separate thread and the container application is informed about results being available through the BeatsAvailableOffline event. At this point you can enumerate available beats positions through the BeatsDetectGetBeatsCount method and to obtain each of them through the BeatsDetectGetBeatPos method. By default beats position analysis will scan the overall sound: a smaller range to analyze can be set through the BeatsDetectSetRange method.

· Real-time: in this case beats detection is enabled by a call to the BeatsDetectEnableRT method and performed while the sound is in playback status: a BeatDetectedRealTime event is fired each time the control detects a beat during playback.

In both cases, parameters applied to beats detection analysis can be obtained/changed through the BeatsDetectGetParams and BeatsDetectSetParams methods.

· "Beats Per Minute detection" (BPM) is enabled by default and automatically calculated each time a new sound is loaded: the BPMAvailable event will pass detected BPM to the container application.

Automatic BPM detection can been disabled/enabled through a call to the SetAutomaticBPM method: when disabled you can manually request BPM detection through the RequestSoundBPM method: also in this case the BPMAvailable event will pass detected BPM to the container application.

Both beats position detection and BPM detection won't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

A sample of use of the "Beats detection" (BD) analysis in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- BeatsDetection

A sample of use of the "Beats Per Minute detection" (BPM) analysis in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- TestPlayers


How to add Triggers and Cue Points to a player

How to add Triggers and Cue Points to a player

An useful feature for DJ applications is the ability to setup Triggers and/or Cue points that will generate one or more events when a predefined position is reached: the main difference between a trigger and a cue point is the fact that a trigger is identified though a unique identification number (for example 0, 1, 2, 1000, 2000, etc.) while a cue point is identified by a mnemonic string of characters containing a custom name (for example "intro start", "mainpart start", "refrain start", etc.): obviously you are free to define your own set of triggers and of cue points identifiers.

You can add as many Triggers and Cue Points you need to a given player using a set of predefined methods.

· Triggers

A new trigger can be added through the TriggersAdd method or the TriggersAddPerc method and removed at a later time using the TriggersRemove method.

Each time you create a trigger using the TriggersAdd or TriggersAddPerc methods, you must provide a unique identification number that will be used in order to identify the trigger at a later time: each time a trigger is reached during playback, a TriggerReached event will be generated and you will be able to discriminate the specific trigger through its nTriggerID parameter: this parameter will match exactly the unique identification number assigned to the trigger when added through the TriggersAdd or TriggersAddPerc methods.

The total number of existing triggers can be obtained using the TriggersGetCount method; you can obtain/modify the position for an existing trigger, expressed in ScaleUnits, through the TriggersGetPos and TriggersSetPos methods or, if you are working with positions in floating point percentage, through the TriggersGetPosPerc and TriggersSetPosPerc methods.

Each single trigger can be enabled/disabled through the TriggersEnable method and its enabled/disabled state can be obtained through the TriggersIsEnabled method.

· Cue Points

A new cue point can be added through the CuePointsAdd method and removed at a later time using the CuePointsRemove method.

Each time you create a cue point using the CuePointsAdd method, you must provide a mnemonic string of characters containing a custom name that will be used in order to identify the cue point at a later time: each time a cue point is reached during playback, a CuePointReached event is generated allowing to discriminate the specific cue point through its strCuePointName parameter: this parameter will match exactly the custom name assigned to the cue point when added through the CuePointsAdd method.

The total number of existing cue points can be obtained using the CuePointsGetCount method; you can obtain/modify the position for an existing cue point, expressed in milliseconds, through the CuePointsGetPos and CuePointsSetPos methods. The name of each cue point can be be obtained through the CuePointsGetName method.

Each single cue point can be enabled/disabled through the CuePointsEnable method and its enabled/disabled state can be obtained through the CuePointsIsEnabled method.

A further feature available for cue points is the capability to save them inside a XML-based file through the CuePointsSaveToFile method and to retrieve them at a later time using the CuePointsLoadFromFile method: last but not least, each time a new sound is loaded, the control will automatically search for a XML file containing cue points for that specific file: if for example the loaded sound file should be named MySong.mp3, the corresponding XML file containing cue points should be named MySong.cue: when the control will find this specific XML file inside the same folder of the loaded sound it will automatically create the list of cue points.

The XML file, which should always have extension .cue, has a structure like the sample below:

<?xml version="1.0" ?>

<CuePoints>

 <CuePoint PosMs="1000" name="Silence end" />

 <CuePoint PosMs="4200" name="Fading point" />

 <CuePoint PosMs="18000" name="Silence start" />

</CuePoints>

As you can see, each cue point is identified by the name attribute and has a position expressed in milliseconds set into the PosMs attribute.

A CuePointsLoaded event is fired each time a file containing cue points is loaded into the player, automatically or through a call to the CuePointsLoadFromFile method.

Cue points can be also managed when dealing with playlists formatted in PDJ format containing volume automation features; for details about using Volume Automation refer to the How to manage Volume Automation tutorial.

IMPORTANT NOTE ABOUT POSITIONING OF TRIGGERS AND CUE POINTS: Positioning of triggers and cue points, added through the TriggersAdd and CuePointsAdd methods whose position is expressed in milliseconds, is always referred to the original duration of the loaded sound, meaning that their position won't be automatically moved when tempo and/or playback rate changes and will always refer to the position inside the song as it should be played at its original speed. This means that if you should improve tempo percentage through the Effects.PlaybackTempoSet method, determining a shorter duration of the song, the cue point or trigger could be never reached if the updated song duration should be shorter respect to the position were the cue point or trigger was originally set. The only entity that could avoid this issue would be triggers added through the TriggersAddPerc method which, being based upon a positioning expressed in percentage, won't be affected by changes of the song's duration.

As a final note, positioning expressed in percentage is not supported for cue points. In case you should need to have cue points that would automatically update their positioning after using the the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods, you would have to apply a proportion that would allow repositioning the cue point through the CuePointsSetPos method; see the VB6 example below where tempo is updated after moving a slider control:

Private Sub sliderTempo_Change()

   ' change tempo using value set into the slider control: this will change the duration of the loaded sound

   Amp3dj1.Effects.PlaybackTempoSet Player_1, sldTempo.Value

   ' obtain updated duration after tempo change

   Dim nUpdatedDuration As Double

   Amp3dj1.SoundDurationGet(0, nUpdatedDuration, BOOL_TRUE)

   ' obtain original duration as available before applying tempo change

   Dim nOriginalDuration As Long

   Amp3dj1.SoundDurationGet(0, nOriginalDuration, BOOL_FALSE)

   ' imagine that our cue points was originally positioned at an offset of 5 seconds (5000 ms) from the end of the file

   Dim nOffsetOriginalSpeed As Long

   nOffsetOriginalSpeed = 5000

   ' recalculate the offset through a proportion

   Dim nOffsetUpdatedSpeed As Long

   nOffsetUpdatedSpeed = (nOffsetOriginalSpeed * nUpdatedDuration) / nOriginalDuration

   ' reposition the cue point based upon the updated song duration and offset

   Amp3dj1.CuePointsSetPos 0, "CuePoint name", nUpdatedDuration - nOffsetUpdatedSpeed

End Sub

During playback, Triggers and Cue Points will not generate the related events TriggersReached and CuePointReached if the current playback position should be moved, through a call to the SeekSound or ForwardSound methods, to a position exceeding the one of the trigger/cue point itself.

A sample of use of Triggers in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- Triggers

A sample of use of Cue Points in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- CuePoints


How to retrieve information about loaded songs

How to retrieve information about loaded songs

Active DJ Studio can easily retrieve information about the song contents.

If you work with single song files you can:

· Load a song file through the LoadSound method.
· Retrieve the sound duration through the SoundDurationGet and/or SoundDurationStringGet methods.
· Detect the initial and final silent portions; see the How to detect silent portions of sound files tutorial for details.
· Force the control to retrieve information below, that could require some more CPU tick, using the ReadSoundInfo method
· Retrieve the song bitrate through the GetFrequency method
· Retrieve the number of channels of the loaded song through the GetChannels method.
· If the loaded song is in MP3 format, use one of the following methods in order to get detailed information:

GetMp3StreamTypeLevel

GetMp3StreamTypeLayer

GetMp3StreamTypeBitRate

GetMp3StreamTypeMode

GetMp3Frames

If you work with playlists you can:

· Create and fill a playlist (see How to create and manage a playlist).
· Use the PlayListGetItemString in order to receive one or more strings containing the needed information.

Sound files in WAV format may contain information stored inside "chunks": Audio DJ Studio can retrieve contents of BEXT and CART chunks in the following way:

· Load a WAV file through the LoadSound method.
· Force the control to perform a deeper analysis using the ReadSoundInfo method
· Check if the loaded WAV file contains CART and/or BEXT chunks through the IsWavChunkAvailable method.
· Obtain single fields of the chunks using one of the following methods:

* GetWavChunkStringInfo for string fields

* GetWavChunkNumericInfo for numeric fields

* GetWavChunkBinaryInfo for binary fields

Tags contents can be obtained through a set of dedicated methods: see the How to read TAG information in sound files and How to retrieve basic TAG information from the sound loaded into a player tutorials for details.


How to read TAG information in sound files

How to read TAG information in sound files

The majority of audio formats allows the insertion of metadata, also known as "tags", which helps describing the content of the audio file by inserting information such as the title, artist, album, track number and other information about the audio file to be stored in the file itself.

The TagsReader COM object of Active DJ Studio allows reading the most common tag formats (in case you should need both reading and writing you may consider using our Active Sound Editor component): this can be accomplished by analyzing the audio file loaded inside an editing session, through the TagsReader.ALL_AnalyzeSoundOnPlayer method, or by accessing a sound file directly on the local disk through the TagsReader.ALL_AnalyzeSoundFile method.

Both methods return a combination of flags which allow determining the specific tag formats embedded inside the audio file; certain audio formats allow embedding more than one tag format; for example, the MP3 format could contain ID3V1, ID3V2 and LYRICS3 formats: the combination of flags allows discriminating which of them are effectively available inside the audio file and to manage them separately; if the returned value should be 0, this would mean that no known tag format is embedded inside the audio file. A small example can be see inside the following code snippets:

Visual Basic 6

' perform tags analysis

Dim nTagFormat As enumTagAvailable

nTagFormat = Amp3dj1.TagsReader.ALL_AnalyzeSoundOnPlayer(0)

If nTagFormat = TAG_FLAG_NONE Then

   ' no tag detected

   Exit Sub

End If

' check tags availability: we use bitwise operators because more than one type of tag format could be available

If nTagFormat And TAG_FLAG_ID3V1 Then

   ...

do something with ID3V1

   ...

End If

If nTagFormat And TAG_FLAG_ID3V2 Then

   ...

do something with ID3V2

   ...

End If

If nTagFormat And TAG_FLAG_WMA Then

   ...

do something with WMA

   ...

End If

If nTagFormat And TAG_FLAG_MP4 Then

   ...

do something with MP4

   ...

End If

Visual C++

// perform tags analysis

long nTagFormat = Amp3dj1.GetTagsReader().ALL_AnalyzeSoundOnPlayer(0);

if (nTagFormat == TAG_FLAG_NONE)

   // no tag detected

   return;

// check tags availability: we use bitwise operators because more than one type of tag format could be available

if (nTagFormat & TAG_FLAG_ID3V1)

{

   ...

   do something with ID3V1

   ...

}

if (nTagFormat & TAG_FLAG_ID3V2)

{

   ...

   do something with ID3V2

   ...

}

if (nTagFormat & TAG_FLAG_WMA)

{

   ...

   do something with WMA

   ...

}

if (nTagFormat & TAG_FLAG_MP4)

{

   ...

   do something with MP4

   ...

}

Some of the tag fields, such as artist, title and album, are common to all of the tag formats so Active DJ Studio exposes a set of methods that allows accessing these common frames without the need to know the specific format of the audio file being edited: TagsReader.ALL_CommonFrameGet method allows reading these common frames.

IMPORTANT NOTE:When using the TagsReader.ALL_AnalyzeSoundOnPlayer and TagsReader.ALL_AnalyzeSoundFile methods, subsequent calls to other methods of the TagsReader COM object will be related to that specific analysis.

If for example you have an instance of Active DJ Studio with 2 players, named Player_A and Player_B respectively and you want to obtain the title of the loaded song, after the following call

Dim nTagFormat As enumTagAvailable

nTagFormat = Amp3dj1.TagsReader.ALL_AnalyzeSoundOnPlayer(Player_A)

Dim strTitle as String

strTitle = Amp3dj1.TagsReader.ALL_CommonFrameGet (TAG_FIELD_TITLE)

the returned title will be about the sound file loaded inside Player_A while after the following call

nTagFormat = Amp3dj1.TagsReader.ALL_AnalyzeSoundOnPlayer(Player_B)

strTitle = Amp3dj1.TagsReader.ALL_CommonFrameGet (TAG_FIELD_TITLE)

the returned title will be about the sound file loaded inside Player_B. This means that, in order to read further information about tags stored inside Player_A, for example the author's name, you will have to perform a new analysis of the sound loaded in Player_A as seen below:

Dim strAuthor as String

nTagFormat = Amp3dj1.TagsReader.ALL_AnalyzeSoundOnPlayer(Player_A)

strAuthor = Amp3dj1.TagsReader.ALL_CommonFrameGet (TAG_FIELD_ARTIST)

When dealing with specific audio formats, Active DJ Studio allows reading the following kind of tags:

· ID3V1
· ID3V2
· LYRICS3
· WMA
· OGG Vorbis
· MP4
· APE
· FLAC
· WAV Chunks

ID3V1

The ID3V1 tag, intended for usage with MP3 files, occupies 128 bytes beginning with the string TAG and is placed at the end of the file. This tag allows 30 bytes each for the title, artist, album, and a "comment", four bytes for the year, and a byte to identify the genre of the song from a predefined list of 80 values (Winamp later extended this list to 148 values).

One improvement to ID3V1 uses the last two bytes of the comment field to store the track number. Such tags are referred to as ID3V1.1.

A full description of this tagging format can be found on this link.

You can know if the ID3V1 tag is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_ID3V1 this would mean that the ID3V1 tag is available.

ID3V1 fields can be read through the TagsReader.ID3V1_FieldGet method.

ID3V2

ID3V2 is a tagging system that lets you put enriching and relevant information about your audio files within them. ID3V2 is a chunk of data prepended to the binary audio data. Each ID3V2 tag holds one or more smaller chunks of information, called frames. These frames can contain any kind of information and data you could think of such as title, album, performer, website, lyrics, equalizer presets, pictures etc.

A full description of this tagging format can be found on this link.

Active DJ Studio supports 3 different versions of ID3V2:

· ID3V2.2
· ID3V2.3
· ID3V2.4

All of them are currently supported in read mode only. This system allows the use of UNICODE characters in UTF-16 format and, when dealing with version ID3V2.4, in UTF-8 format as well.

You can know if the ID3V2 tag is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_ID3V2 this would mean that the ID3V2 tag is available.

The list of supported ID3V2 frames, with related identifiers and methods to access stored information, can be found on the table below:

Supported frame types | Frame identifiers | Multiple | Related methods
Text-based frames | TIT1, TIT2, TIT3, TALB, TOAL, TRCK, TPOS, TSST, TSRC, TPE1, TPE2, TPE3, TPE4, TOPE, TEXT, TOLY, TCOM, TMCL, TIPL, TENC, TBPM, TLEN, TKEY, TLAN, TCON, TFLT, TMED, TMOO, TCOP, TPRO, TPUB, TOWN, TRSN, TRSO, TOFN, TDLY, TDEN, TDOR, TDRC, TDRL, TDTG, TSSE, TSOA, TSOP, TSOT | No | TagsReader.ID3V2_TextFrameGet
User text frames | TXXX | Yes | TagsReader.ID3V2_UserTextFrameDescriptionGet TagsReader.ID3V2_UserTextFrameGet
URL-based frames | WCOM, WCOP, WOAF, WOAR, WOAS, WORS, WPAY, WPUB | No | TagsReader.ID3V2_URLFrameGet
User URL frames | WXXX | Yes | TagsReader.ID3V2_UserURLFrameDescriptionGet TagsReader.ID3V2_UserURLFrameGet
Comment frames | COMM | Yes | TagsReader.ID3V2_CommentFrameGet TagsReader.ID3V2_CommentFrameInfoGet
Commercial frames | COMR | Yes | TagsReader.ID3V2_CommercialFrameInfoGet TagsReader.ID3V2_CommercialFramePictureBitmapGet TagsReader.ID3V2_CommercialFramePictureFileGet TagsReader.ID3V2_CommercialFramePictureMemoryFileGet TagsReader.ID3V2_CommercialFramePictureSizeGet TagsReader.ID3V2_CommercialFrameReceivedAsGet
Event timings (cue points) frame | ETCO | No | TagsReader.ID3V2_EventTimingsFrameEventCountGet TagsReader.ID3V2_EventTimingsFrameEventInfoGet
General objects frames | GEOB | Yes | TagsReader.ID3V2_GeneralObjectFrameFileGet TagsReader.ID3V2_GeneralObjectFrameInfoGet TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet TagsReader.ID3V2_GeneralObjectFrameSizeGet
Music CD identifier frames | MCDI | No | TagsReader.ID3V2_MusicCdIdentifierFrameGet TagsReader.ID3V2_MusicCdIdentifierFrameSizeGet
Ownership frame | OWNE | No | TagsReader.ID3V2_OwnershipFrameInfoGet
Picture frames | APIC | Yes | TagsReader.ID3V2_PictureFrameBitmapGet TagsReader.ID3V2_PictureFrameFileGet TagsReader.ID3V2_PictureFrameInfoGet TagsReader.ID3V2_PictureFrameMemoryFileGet TagsReader.ID3V2_PictureFrameSizeGet TagsReader.ID3V2_PictureFrameTypeGet
Play counter frame | PCNT | No | TagsReader.ID3V2_PlayCounterFrameCountGet
Popularimiter frame | POPM | Yes | TagsReader.ID3V2_PopularimeterFrameCounterGet TagsReader.ID3V2_PopularimeterFrameEmailGet TagsReader.ID3V2_PopularimeterFrameRatingGet
Private frame | PRIV | Yes | TagsReader.ID3V2_PrivateFrameFileGet TagsReader.ID3V2_PrivateFrameMemoryFileGet TagsReader.ID3V2_PrivateFrameOwnerGet TagsReader.ID3V2_PrivateFrameSizeGet
Synchronized lyrics frames | SYLT | Yes | TagsReader.ID3V2_SynchLyricsFrameGet TagsReader.ID3V2_SynchLyricsFrameInfoGet TagsReader.ID3V2_SynchLyricsFrameInfoNumGet
Terms of use frames | USER | Yes | TagsReader.ID3V2_TermsOfUseFrameGet TagsReader.ID3V2_TermsOfUseFrameLanguageGet
Unsynchronized lyrics frames | USLT | Yes | TagsReader.ID3V2_UnsynchLyricsFrameGet TagsReader.ID3V2_UnsynchLyricsFrameInfoGet

Support for other frames not available in the list above may be added in future versions of the component so, in case you should need the support of a specific frame, feel free to contact our technical support team.

The "Multiple" column specifies if more than one frame, having the same identifier, can be available inside the tag; in order to know how many frames are available for a specific identifier, you should use the ID3V2_FrameCountGet method. If for example you should need enumerating pictures stored inside the tag, you could do something similar:

Visual Basic 6

' perform tags analysis

Dim nTagFormat As enumTagAvailable

nTagFormat = Amp3dj1.TagsReader.ALL_AnalyzeSoundOnPlayer(0)

If nTagFormat And TAG_FLAG_ID3V2 Then

   ' check the availability of embedded pictures through the search of "APIC" frames

   Dim nAvailablePictures as Long

   nAvailablePictures = Amp3dj1.TagsReader.ID3V2_FrameCountGet("APIC")

   ' output each picture's description

   Dim nIndex as Long

   For nIndex = 0 to nAvailablePictures - 1

      Debug.Print Amp3dj1.TagsReader.ID3V2_PictureFrameInfoGet (nIndex, ID3V2_FRAME_INFO_DESCRIPTION)

   Next nIndex

End If

Visual C++

// perform tags analysis

long nTagFormat = Amp3dj1.GetTagsReader().ALL_AnalyzeSoundOnPlayer(0);

if(nTagFormat & TAG_FLAG_ID3V2)

{

   // check the availability of embedded pictures through the search of "APIC" frames

   long nAvailablePictures = Amp3dj1.GetTagsReader().ID3V2_FrameCountGet(_T("APIC"));

   // output each picture's description

   for (long nIndex = 0; nIndex < nAvailablePictures; nIndex++)

      TRACE (Amp3dj1.GetTagsReader().ID3V2_PictureFrameInfoGet (nIndex, ID3V2_FRAME_INFO_DESCRIPTION) + _T("\r\n"));

}

Identifiers of frames available inside the ID3V2 tag can be enumerated using the combination of the TagsReader.ID3V2_UniqueFramesCountGet and TagsReader.ID3V2_UniqueFramesIdGet methods.

LYRICS3

The Lyrics3 v2.00 tag resides between the audio and the ID3V1 tag, which must be present. The tag uses only text for everything from content to size descriptors, which are represented as numerical strings.

A full description of this tagging format can be found on this link.

You can know if the Lyrics3 tag is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_LYRICS3 this would mean that the Lyrics3 tag is available.

Text fields of the Lyrics3 tag can be read through the TagsReader.LYRICS3_TextFieldGet method.

The lyrics text can be read through the TagsReader.LYRICS3_LyricsGet method.

The link to the image field can be read through the TagsReader.LYRICS3_ImageLinkGet method.

WMA

You can know if the WMA tag is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_WMA this would mean that the WMA tag is available.

The list of supported WMA frames, with related identifiers and methods to access stored information, can be found on the table below:

Supported frame types | Frame identifiers | Multiple | Related methods
Text-based frames | You can use predefined identifiers or, in alternative, your own custom ones: a list of predefined identifiers can be found inside the Windows Media Format SDK. | No | TagsReader.WMA_TextFrameGet
Picture frames | WM/Picture | Yes | TagsReader.WMA_PictureFrameBitmapGet TagsReader.WMA_PictureFrameCountGet TagsReader.WMA_PictureFrameFileGet TagsReader.WMA_PictureFrameInfoGet TagsReader.WMA_PictureFrameMemoryFileGet TagsReader.WMA_PictureFrameSizeGet TagsReader.WMA_PictureFrameTypeGet

The "Multiple" column specifies that there may be more than one picture frame available inside the tag; you can know how many picture frames are available through the TagsReader.WMA_PictureFrameCountGet method.

Identifiers of frames available inside the WMA tag can be enumerated using the combination of the TagsReader.WMA_UniqueFramesCountGet and TagsReader.WMA_UniqueFramesIdGet methods.

OGG Vorbis

Vorbis metadata, called Vorbis comments, supports metadata tags similar to those implemented in the ID3 standard for MP3. All strings are encoded as UTF-8. Music tags are typically implemented as strings of the form "[TAG]=[VALUE]", for instance, "ARTIST=The big band". The tags are case-insensitive, thus typing "ARTIST=The big band" would be the same as "artist=The big band".

You can know if the OGG Vorbis tag is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_OGG this would mean that the OGG Vorbis tag is available.

Predefined text frames can be read through the TagsReader.OGG_TextFrameGet method.

User defined text frames can be read through the TagsReader.OGG_UserFrameGet method.

Identifiers of frames available inside the OGG tag can be enumerated using the combination of the TagsReader.OGG_UniqueFramesCountGet and TagsReader.OGG_UniqueFramesIdGet methods.

MP4

There is no official MPEG standard on how to embed metadata tags in MP4 files. Apple iTunes therefore started to use their own solution in order to be able to store metadata tags. Those iTunes tags quickly became the de-facto standard for metadata tags within MP4 files. Metadata tags within MP4 files are stored within so-called "boxes" (also known as "atoms").

You can know if the MP4 tag is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_MP4 this would mean that the MP4 tag is available.

The list of supported MP4 frames, with related identifiers and methods to access stored information, can be found on the table below:

Supported frame types | Frame identifiers | Multiple | Related methods
Text-based frames | ©alb, ©ART, ©aut, aART, tmpo, catg, dsk, disk, ©cmt, ©wrt, cpil, ©day, ©cpy, ©day, ©des, ©inf, ©dir, ©dis, ©too, ©grp, keyw, ©lyr, ©nam, ©url, ©ope, ©fmt, ©src, ©prf, rate, ©prd, ©wrn | No | TagsReader.MP4_TextFrameGet
Picture frames |  | Yes | TagsReader.MP4_PictureFrameBitmapGet TagsReader.MP4_PictureFrameCountGet TagsReader.MP4_PictureFrameFileGet TagsReader.MP4_PictureFrameMemoryFileGet TagsReader.MP4_PictureFrameMimeGet TagsReader.MP4_PictureFrameSizeGet

The "Multiple" column specifies that there may be more than one picture frame available inside the tag; you can know how many picture frames are available through the TagsReader.MP4_PictureFrameCountGet method.

Identifiers of frames available inside the WMA tag can be enumerated using the combination of the TagsReader.MP4_UniqueFramesCountGet and TagsReader.MP4_UniqueFramesIdGet methods.

APE

APE tags are closer to Vorbis comments than ID3 tags. Like Vorbis comments, they are unstructured key/value pairs.

You can know if the APE tag is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_APE this would mean that the APE tag is available.

Predefined text frames can be read through the TagsReader.APE_TextFieldGet method.

User defined text frames can be read through the TagsReader.APE_UserFieldGet method.

Identifiers of frames available inside the APE tag can be enumerated using the combination of the TagsReader.APE_UniqueFramesCountGet and TagsReader.APE_UniqueFramesIdGet methods.

FLAC

FLAC has it's own native tagging system which is mostly identical to that of OGG Vorbis described above, indeed they are sometime called alternately "FLAC tags" and "Vorbis comments". Respect to the Vorbis tagging system, FLAC allows embedding pictures as well as seen for the ID3V2, WMA and MP4 formats.

You can know if the FLAC tag is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_FLAC this would mean that the FLAC tag is available.

The list of supported FLAC frames can be found on the table below:

Supported frame types | Multiple | Related methods
Text-based frames | No | TagsReader.FLAC_TextFrameGet
Picture frames | Yes | TagsReader.FLAC_PictureFrameBitmapGet TagsReader.FLAC_PictureFrameCountGet TagsReader.FLAC_PictureFrameFileGet TagsReader.FLAC_PictureFrameInfoGet TagsReader.FLAC_PictureFrameMemoryFileGet TagsReader.FLAC_PictureFrameSizeGet TagsReader.FLAC_PictureFrameTypeGet

The "Multiple" column specifies that there may be more than one picture frame available inside the tag; you can know how many picture frames are available through the TagsReader.FLAC_PictureFrameCountGet method.

Identifiers of frames available inside the FLAC tag can be enumerated using the combination of the TagsReader.FLAC_UniqueFramesCountGet and TagsReader.FLAC_UniqueFramesIdGet methods.

WAV Chunks

WAV files are based upon the RIFF format which consists entirely of "chunks"; some of these chunks allows storing metadata; Active DJ Studio supports reading the following types of chunks:

· CART
· BEXT
· DISP
· LIST INFO

You can know if any of the chunks above are available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the combination of any of the following flags, this would mean that the chunks are available: TAG_FLAG_WAV_CART, TAG_FLAG_WAV_BEXT, TAG_FLAG_WAV_DISP and TAG_FLAG_WAV_LIST_INFO.

CART Chunk

The CART chunk contains fields and attributes that a large number of broadcast systems use to describe an audio file. Its full specifications can be found inside the CartChunk.org web site.

You can know if the CART chunk is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_WAV_CART this would mean that the CART chunk is available.

Text fields can be read through the TagsReader.WAV_CartChunkTextFieldGet method.

Time markers can be read through the TagsReader.WAV_CartChunkTimeMarkerFieldGet method.

BEXT Chunk

The BEXT chunk (“Broadcast Audio Extension”) adds to the RIFF format extra parameters needed for the exchange of material between broadcasters.

You can know if the BEXT chunk is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_WAV_BEXT this would mean that the BEXT chunk is available.

Text fields can be read through the TagsReader.WAV_BextChunkTextFieldGet method.

Binary fields can be read through the TagsReader.WAV_BextChunkBinaryFieldGet method.

DISP Chunk

The DISP chunk allows entering a text string to display on the user interface when the WAV file is loaded.

You can know if the DISP chunk is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_WAV_DISP this would mean that the DISP chunk is available.

The text field can be read through the TagsReader.WAV_DisplayChunkTextGet method.

LIST INFO Chunk

The LIST chunk can contain a list of frames (sub-chunks) of type INFO, each of them containing a different text string. As for other kinds of chunks, each INFO frame is defined by a four characters identifier (FOURCC). Some identifier has already been standardized by the EXIF 2.3 specification (for esample 'IART' for 'Artist', 'ICMT' for 'Comments' or 'ICOP' for 'Copyright'), but the user may create new custom ones.

You can know if the LIST INFO chunk is available by checking the value returned by the TagsReader.ALL_AnalyzeSoundOnPlayer or TagsReader.ALL_AnalyzeSoundFile methods: if it should contain the flag TAG_FLAG_WAV_LIST_INFO this would mean that the LIST INFO chunk is available.

Identifiers of INFO frames available inside the LIST chunk can be enumerated using the combination of the TagsReader.WAV_ListInfoChunkUniqueFramesCountGet and TagsReader.WAV_ListInfoChunkUniqueFramesIdGet methods.

Single INFO frames can be read through the TagsReader.WAV_ListInfoChunkFrameGet method.

Samples of usage of tags editing through the TagsReader object in Visual C++ and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- TagsReader


How to retrieve basic TAG information from the sound loaded into a player

How to retrieve basic TAG information from the sound loaded into a player

 Return to chapter overview

This tutorial refers to a set of methods which, although still of some usage, are now mostly superseded by methods described inside the How to read TAG information in sound files tutorial.

Many formats add some information, also known as Tags, to the song binary in order to allow an immediate 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 inside the tag

GetTagString retrieves a string inside the tag

Note that, in order to speed up the sound file loading, tag information is not available immediately after the call of the LoadSound method: once the sound is loaded, you can force the control to read tag information using the ReadSoundInfo method.

If the GetFileTagField method succeeds in retrieving the artist name and the title of the song, you can try requesting the related lyrics text through the SoundLyricsRequest method: this request will try to connect to the MultiMedia Soft server in order to check for availability of the requested lyrics text: when the request has been completed and after receiving the SoundLyricsAvailable event with a positive result, you can retrieve the lyrics text through the SoundLyricsGet method.

In a similar way, after having obtained information about the artist name and the title of the album, there is the possibility to obtain the cover art of the related Audio CD (see the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial for details) and then to directly navigate to the purchase page of the specific Audio CD on the Amazon store through the CdNavigateToPurchasePage method.

If dealing with playlists, you can use the PlayListGetItemString method in order to receive a string containing the needed information.

A sample of access to tag information in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- SoundInfo


How to deal with latency

How to deal with latency

By default this control creates a DirectSound buffer that will host 500 milliseconds of song during the decoding/playback phase: this setting will usually work with most of the available sound card drivers but it's not optimized for the latest sound card drivers available on the market that can deal with smaller buffers without breaking-up the song during playback: the smaller the DirectSound buffer, the smaller will result the latency time when applying new equalizer values, when seeking to a new song position or when changing other stuffs like Volume, Tempo and Playback Rate.

In order to change the default DirectSound buffer size, you can use the BufferLength property: its value, expressed in milliseconds, can be in the range 100 - 5000: higher or lower values will be automatically cut to the nearest supported value.

Usually the latest sound card drivers will allow the use of a 150-200 milliseconds buffer size, but how can you determine which value will give you the smaller latency without breaking-up the playing song?

· First of all you need to tell the control to perform, when initialized at Runtime, a check of the sound card drivers latency: in order to perform this check you need to set at Design-time the CheckOutputDevicesLatency property to TRUE: changes to this property made at Runtime will be simply ignored. Note that this setting will require the InitDJSystem method a longer time to execute.
· At this point you can call the GetOutputDeviceLatency method on one of the available output devices in order to know its latency (expressed in milliseconds) and the GetOutputDeviceMinBufferLength method in order to know which is the minimal supported size of the DirectSound buffer (expressed in milliseconds); note that, in some case, it could happen that the reported minimal size will not work as expected when set into the BufferLength property: usually this behaviour is caused by an outdated sound card driver which can be usually fixed downloading a driver update from the sound card manufacturer.

When decreasing the BufferLength property you may also reduce the time used to update the DirectSound buffer: this can be done by reducing the value of the BufferUpdateTime property.

At Runtime, the BufferLength property can be changed at any time but will be effective only after loading a new song.

When dealing with custom stream mixers, the BufferLength property must be changed BEFORE creating the custom stream mixer or it will have no effect on the mixer itself.

When both ASIO and DirectSound devices are enabled through the InitDriversType method, the BufferLength property must be set before calling the InitDJSystem method or through the InitDJSystemEx method and cannot be changed at a later time without performing a previous call to ResetEngine and ResetControl methods.

It's also important to note that, if the target PC has more than one sound card, you won't have the possibility to have a different buffer length for each of them.

When dealing with emulated DirectSound drivers, for example drivers used by Windows Terminal Services and Remote Desktop Protocol (RDP), in order to avoid sound stuttering there could be the need to set a latency of 2000 ms or higher.


How to play Internet streams and radio stations

How to play Internet streams and radio stations

There are three main types of Internet stream:

· Broadcasting streams
· Sound files available on a web site
· Playlists which main contain more broadcasting streams and/or sound files

These streams cannot be loaded through the LoadSound method: for this purpose you must use the LoadInternetStream method which gives the possibility to pass a URL in place of a pathname. Let's see how to manage these different streams.

Default settings related to Internet connections, like the buffer length and eventual timeouts, can be retrieved and modified through the InternetSettingsGet and InternetSettingsSet methods.

Broadcasting streams

Internet radio is a broadcasting service which transmits one or more sound streams via the Internet: for this kind of streams, the control will connect to the remote server and will fire the following sequence of events:

· StreamConnecting to notify about the beginning of the connection to the server.
· In case the connection should fail, the StreamLoaded event would report the failure.
· In case of successful connection the DownloadBuffering event would be fired with its nState parameter set to STREAMING_BUFFERING to notify that connection with the server was established and that buffering begins. This would be followed by a number of DownloadPercentage events to notify about buffering percentage.
· Once there will be enough data to play, the control will fire the StreamLoaded event allowing the container application to start the playback session through a call to the PlaySound method. The effective URL of the broadcasting stream can be obtained through the GetLoadedSoundFile method.

Immediately after starting playback, the control will fire again the DownloadBuffering event with its nState parameter set to STREAMING_PLAYING: note that, during the playback session, the control will continue buffering data from the Internet: if for any reason, for example for a slow connection, the download should stall, the control will notify the container application firing again the DownloadBuffering event with the nState parameter set to STREAMING_BUFFERING: when there will be again enough data to play, the control will automatically resume playback notifying the container application through the DownloadBuffering event with the nState parameter set to STREAMING_PLAYING.

After a stall situation, the Internet stream provider could also close the connection: in this case the control will fire the ServerClosed event.

During playback, the server will usually send information about the radio station and about the song in playback: the control has the capability to notify in real-time the availability of this information, usually called "tags", and to retrieve the various strings composing the same tag: for this purpose the control will fire the MetaTagChanged event: at this point the container application will have the possibility to perform the following sequence of tasks:

· instruct the control to retrieve the tag contents through a call to the ReadSoundInfo method.
· verify the effective availability of the tags and the number of strings composing the tag through a call to the IsTagAvailable method.
· retrieve each of the various strings composing the tag through a call to the GetTagString method.

Sound files available on a web site

Loading a sound file from a web site is mostly identical to loading a broadcast stream with the following differences:

· The remote server will not send metadata so the control will never fire the MetaTagChanged event
· Differently from streams, that can be created in real-time, sound files have a limited size: this means that, at a certain extent, the download of the file will be completed: the control will in this case fire a DownloadComplete method allowing the container application to gain access to tags like ID3V1 which, for MP3 files, are stored on the file's bottom.

Playlists which main contain more broadcasting streams and/or sound files

Many radio stations will play a small intro before starting playback of the real broadcasting streams: some achieve this by loading a playlist (usually in ASX or PLS format) which contains the URL pointing to the intro message (usually a WMA or MP3 file stored inside the server) followed by the real URL of the broadcasting stream.

In some cases the playlist may point to other nested playlists: in this case our component will try to manage the situation by updating the playlist with new contents of the nested playlist.

When dealing with playlists, most of events fired by the component will be identical to the ones described for broadcasting streams and for sound files with the following differences:

· In case of success StreamLoaded event is immediately followed by the StreamLoadedFromInetPlaylist event which reports the URL of the loaded stream.
· In case the connection should fail the StreamLoaded event would report the failure only if all of the streams contained inside the playlist should fail while the StreamLoadedFromInetPlaylist event would be fired for each failing URL.
· ServerClosed event would be fired only when executing the latest entry inside the playlist.

A sample of access to Internet streams in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- InternetRadio


How to protect your music through encryption

How to protect your music through encryption

Protecting music from fraudulent uses and from copyright infringements is a must for many authors and distributors: currently you could already use your own or third-party encryption/decryption schemas and load decrypted song's data through the LoadSoundFromMemory method; as a second alternative, you could also compress your songs into one or more ZIP files, protected with an AES encryption key, and use Active DJ Studio in order to extract zipped songs directly into a memory buffer through the LoadSoundFromZip method (see the How to manage ZIP files tutorial for details about ZIP files management).

Active DJ Studio comes also with its own proprietary solution that allows encrypting songs, for safe redistribution purposes, using our CryptSound™ application.

Once encrypted, no available multimedia application will be able to playback these songs while applications developed using Active DJ Studio will be able to load encrypted songs through one of the following methods:

· LoadEncryptedSound: loads and decrypts an encrypted sound file from disk: all operations are performed inside the main thread.
· LoadEncryptedSoundSync: loads and decrypts an encrypted sound file from disk: all operations are performed inside a secondary thread.
· LoadEncryptedSoundFromMemory: loads and decrypts an encrypted sound file stored inside a memory buffer: all operations are performed inside the main thread.
· LoadEncryptedSoundFromMemorySync: loads and decrypts an encrypted sound file stored inside a memory buffer: all operations are performed inside a secondary thread.

For security reasons, the CryptSound™ application is currently not installed with our trial version setup package: if you need to test its encryption capabilities, please, contact us and we will ask you to upload inside our FTP server one of your songs; at this point we will send you back the encrypted song with a dedicated decryption key that will have to be passed to the LoadEncryptedSound method: as a fast testing start, we have provided a small sample also, called SecureSongs.exe, that will give you the possibility to test the encrypted song directly on your PC without the need to create a test application from scratch.

The CryptSound™ application has two working modes:

· With its own user interface

Launching the application without any command line parameter will display the user interface as shown on the screenshot below:

As you can see, this user interface is very straightforward and intuitive; the complete sequence of operations is the following:

· fill the "List of files to encrypt" list using the "Add file..." and/or "Add directory..." buttons
· remove any unwanted file selecting its pathname inside the list and pressing the "Remove file" button.
· select the destination directory for encrypted output files: if not specified, the encrypted output file will be placed inside the same folder of the input file, with the same filename and extension changed with the string contained inside the "Encrypted files extension" edit box
· optionally change the default extension for encrypted output files filling the "Encrypted files extension" edit box
· fill the "Encryption key" edit box with your own key (from 16 to 32 characters) or, in alternative, let the application generate a unique key for you pressing the "Generate new key" button
· if needed, check the "Add header containing information about the sound file" checkbox: this will allow adding a small header to each encrypted file containing a few information about file contents (duration, author, title, etc.)
· if needed, check the "Store output encrypted files ... etc." checkbox: this will allow storing each encrypted file into a separate sub-folder whose name will reflect the "genre" of the song taken from an eventual ID tag (for example "Rock", "Rock & Roll", "Country", etc.). If for example the song's genre should be "Rock & Roll", by using settings displayed on the picture above a generic "filename.mp3" song after being encrypted would be stored inside the following pathname: "C:\m_sounds\audio\encrypted\Rock & Roll\filename.bin"
· press the "Start encryption" button and wait for the "Encryption completed" message.

· From the command line for use with batch files

Launching the application from the command line requires the following syntax:

CryptSound "InputFileFullPathname" -k="EncryptionKey" [-p="PreviousEncryptionKey"] [-o="OutputFileFullPathname"] [-i] [-s]

were:

"InputFileFullPathname"

Full pathname for the input file

-k="EncryptionKey"

The key used to encrypt the file: must be from 16 to 32 characters long

-p="PreviousEncryptionKey"

(Optional parameter) Previous encryption key, allows to open and decrypt a previously encrypted file and to re-encrypt it using the new key specified inside the -k parameter

-o="OutputFileFullPathname"

(Optional parameter) Full pathname for the output file; if not specified and if the "-f" parameter has not been specified as well, the output file will be placed inside the same folder of the input file, with the same filename and the extension changed into ".bin"

-f="OutputPath"

(Optional parameter) Output folder where encrypted file will be placed; if not specified, the output file will be placed inside the same folder of the input file, with the same filename and the extension changed into ".bin". This parameter is ignored if the "-o" parameter has been specified.

-i

(Optional parameter) Allows performing analysis of the original sound file before encryption in order to add a small header to each encrypted file containing a few information about file contents; this feature is useful when adding encrypted songs to a playlist.

Supported fields are the following:

· filename
· frequency
· channels
· duration in milliseconds
· author (*)
· title (*)
· album (*)
· genre code (*)
· genre string (*)
· year (*)
· comment (*)
· track number (*)

(*) only compiled if corresponding tag field is available inside the original sound file

-g

(Optional parameter) Put the encrypted output file inside a sub-folder named as the eventual genre of the sound file (only if the "-i" option has been specified and the "-o" option is not available). This parameter is ignored if the "-i" parameter has not been specified.

-s

(Optional parameter) Silent mode

below two examples of use:

CryptSound "c:\mp3_sounds\myfile.mp3" -k="ABSF1SHR46KFL0JVH6E8JFG49KMD3H28"

The sample above will encrypt the "c:\mp3_sounds\myfile.mp3" file using the "ABSF1SHR46KFL0JVH6E8JFG49KMD3H28" encryption key and the output will be placed inside the "c:\mp3_sounds\myfile.bin" file

CryptSound "c:\mp3_sounds\myfile.mp3" -k="ABSF1SHR46KFL0JVH6E8JFG49KMD3H28" -o="c:\mp3_sounds\encrypted\myfile.zzz"

The sample above will encrypt the "c:\mp3_sounds\myfile.mp3" file using the "ABSF1SHR46KFL0JVH6E8JFG49KMD3H28" encryption key and the output will be placed inside the "c:\mp3_sounds\encrypted\myfile.zzz" file


How to export the loaded song into a WAV file

How to export the loaded song into a WAV file

If you need to perform a specific analysis of a sound loaded inside a player, the best thing to do is to have it available in uncompressed WAV format: for this purpose, the container application can choose to export the sound to a WAV file on hard-disk or in memory. It's important to note that the exported WAV file will not be resampled at all so it will have the same sample rate and number of channels of the loaded sound file; if you should need to perform a resampling you should consider using the ExportToFile method of our Active Sound Editor component in place of Active DJ Studio.

The first thing to do is calling the RequestSoundExportToWav method: this method has a strPathname parameter were you can specify the full pathname of the output disk file in WAV format or, if the parameter is left empty, the exported WAV file will be stored inside a memory buffer.

Depending upon the size of the loaded sound, the export session could result in a lengthy operation so it will be performed on a separate thread: during the export session, the container application will be notified about the exporting advancement through the following intuitive events: ExportToWavStart, ExportToWavPerc and ExportToWavStop.

As you will understand, the ExportToWavStop event will notify the container application about the exported WAV file availability and will report the effective size in bytes used to store the WAV file; if the exported WAV file has been stored on a hard-disk file, you will have the possibility to access its contents through the file access functions allowed by your development environment; if the exported WAV file has been stored in memory, you will have the possibility to copy the file contents into a buffer allocated by the container application through a call to the CopyExportedWavToMemory method: in this last case, it's important to note that after calling the CopyExportedWavToMemory method the original memory buffer, internal to the control and containing the exported WAV file, will be discarded from memory so it won't be accessible for further copies.


How to load and play sounds recorded by Active Sound Recorder

How to load and play sounds recorded by Active Sound Recorder

Return to chapter overview

Starting from version 3.0, Active DJ Studio can be integrated with an existing instance of Active Sound Recorder in order to reproduce sounds coming from one of the available input devices.

When instancing both controls inside the same form, it's highly recommended initializing Active DJ Studio first, through a call to the InitDJSystem method and then initializing Active Sound Recorder through its InitRecorder method..

This integration allows the following scenarios:

· Real-time playback of sound data coming from an input device, for example from a Microphone

In this case the recorder will not store recorded sound data and will simply pass them to the player that will have the possibility to apply DMO effects or EAX effects during playback.

In order to activate this scenario you need to keep latency at its minimum so you must enable automatic latency check setting the CheckOutputDevicesLatency property to "True": it's important to note that this setting will only work when set at design-time. After the controls' initialization, you simply have to call the PlaySoundFromRecorderEx method and proceed with further player's operations as you would do after a normal PlaySound call. This recording/playback scenario can be stopped at any time calling the StopSoundFromRecorder method.

· Load and playback of sound data coming from a completed recording session and stored inside a memory buffer or inside the hard-disk

After having completed a recording session through Active Sound Recorder, recorded sound data will remain available inside a memory buffer or, in alternative, inside a file on the hard-disk: Active DJ Studio can obtain and load recorded sound data directly from the recorder calling the LoadSoundFromRecordingSession method. After calling this method you can proceed with further player's operations as you would do after a normal LoadSound call.

· Playback of sound data still being recorded and stored inside the hard-disk

During a recording session, where Active Sound Recorder is still storing recorded sound data inside a file on the hard-disk, Active DJ Studio can obtain and load available sound data directly from the recorder calling the LoadSoundFromRecordingSession method: this functionality is not available for sounds being stored inside a memory buffer or for sounds being saved inside a file in WAV format on the hard-disk.


How to get Audio CD info using CDDB servers and Amazon catalogue

How to get Audio CD info using CDDB servers and Amazon catalogue

Return to chapter overview

There are three situations in which obtaining information about an Audio CD may be required:

· When an Audio CD is physically available inside the CD drive
· When an Audio CD is not physically available inside the CD drive but a song with relevant tag info is loaded into a player
· When an Audio CD is not physically available inside the CD drive but author's name and album's title are known

When an Audio CD is physically available inside the CD drive

In this situation there is the possibility to perform CDDB queries to FreeDb servers distributed around the world.

CDDB (which stands for Compact Disc Database) is a database for software applications to look up CD information over the Internet. This is performed by a client which calculates a (nearly) unique disc ID and then queries the database. As a result, the client is able to display the artist name, CD title, track list and some additional information.

Active Sound Recorder comes with a number of methods and properties that help the developer in getting this information from FreeDb servers: the USA server (us.freedb.org) reports that, as of January 2006, the database holds over 1,927,000 CD titles.

The first needed task, in order to retrieve CDDB information about an audio CD, is to verify the availability of an open Internet connection and then to request the list of available FreeDb servers: this operation is performed through a call to the CddbRequestServersList method: due to the fact that retrieving information from the Internet can be a lengthy operation, this call will return immediately and, when the list of servers will be available, a CddbServersListAvailable event will be raised: at this point it will be possible requesting each CDDB server's friendly name using the CddbGetServerName method. Note that if the target PC is running behind a proxy, you have the possibility to set the proxy details through the CddbSetProxyDetails method.

The second needed task is to have an audio CD inserted inside a CD drive on the target machine: this will allow calling the CddbRequestAlbumInfo method that, after calculating the audio CD's Unique Identification Number, will send a request to the FreeDb server of choice: also in this case, retrieving information from the Internet can be a lengthy operation, so this call will return immediately; when the CD album information will be available, a CddbAlbumInfoAvailable event will be raised: at this point it will be possible requesting specific album information through the CddbGetAlbumInfo method, enumerating CD tracks calling the GetCdNumTracks method and obtain the title of each single track through the CddbGetTrackTitle method.

When CD album information are requested and obtained through a call to the CddbRequestAlbumInfo method, the control automatically performs a search of the same Audio CD on the Amazon catalogue, through standard Amazon Web Services, in order to obtain cover pictures (also know as CD cover art) of the Audio CD: these pictures are usually of three different sizes: Small (thumbnail), Medium and Large. When this information is found, the control notifies the container application about their availability through the following events:

· CdCoverURLsAvailableEx: notifies that the URL pointing to a certain CD cover picture on the Amazon catalogue is available and can be obtained through a call to the GetCdCoverPictureURL method. It's important to note that if one of these pictures should be missing on the Amazon web server, a valid URL will be in any case returned.
· CdCoverPictureFileAvailableEx: notifies that the a certain CD cover picture has been downloaded from the the Amazon web site and is now available locally: the local absolute pathname of the picture can at this point be obtained through a call to the GetCdCoverPictureFile method. It's important to note that the downloaded picture files are temporarily stored inside the system defined "Temp" directory and are automatically deleted when the container application is closed.

When an Audio CD is not physically available inside the CD drive but a song with relevant tag info is loaded into a player

After having loaded a song into a player through the LoadSound or similar methods, you can call the AmazonStoreCdInfoCreate method which instructs the control to parse eventual tag information stored inside the song: if the control should succeed in obtaining the name of the author and the title of the album, by leveraging Amazon Web Services it would automatically query the Amazon catalogue in order to check if the related Audio CD is available for purchase.

If the Audio CD having the same author and title should be found inside the Amazon catalogue, it will be possible to get a number of information about this Audio CD through the following methods:

· AmazonStoreCdInfoGet allows obtaining the URL of pictures representing the CD cover, the year when the CD was published, the URL of the purchase page and the number of tracks available inside the Audio CD.
· AmazonStoreCdTrackTitleGet allows obtaining the title of each single track stored inside the Audio CD
· AmazonStoreCdCoverPictureFileGet allows obtaining the local pathname of pictures representing the CD cover: these graphic files are automatically downloaded as temporary files when the Audio CD is found inside the Amazon catalogue.
· AmazonStoreCdNavigateToUrl allows opening the system default Internet browser and navigating to the purchase URL of the Audio CD.

When an Audio CD is not physically available inside the CD drive but author's name and album's title are known.

Differently from situations described above, where the artist name and the album title are obtained through a FreeDB server or by looking into tag information stored inside the song file, in this situation the control can search information about an Audio CD by leveraging Amazon Web Services in order to query the Amazon catalogue through the CdRequestAlbumInfo method: when requested information become available, the control generates the following sequence of events:

· CddbAlbumInfoAvailable: notifies that information about the album is available and can be retrieved through the CddbGetAlbumInfo method; at the same time also the number of tracks and respective titles are retrieved and can be enumerated calling the GetCdNumTracks method (passing -1 to its nCdDriveIndex parameter) in conjunction with the CddbGetTrackTitle method.
· CdCoverURLsAvailableEx: notifies that the URL pointing to a certain CD cover picture on the Amazon catalogue is available and can be obtained through a call to the GetCdCoverPictureURL method. It's important to note that if one of these pictures should be missing on the Amazon web server, a valid URL will be in any case returned.
· CdCoverPictureFileAvailableEx: notifies that the a certain CD cover picture has been downloaded from the the Amazon catalogue and is now available locally: the local absolute pathname of the picture can at this point be obtained through a call to the GetCdCoverPictureFile method. It's important to note that the downloaded picture files are temporarily stored inside the system defined "Temp" directory and are automatically deleted when the container application is closed.

In both cases, after having obtained information about CD covers, there is the possibility to directly navigate to the purchase page of the specific Audio CD on the Amazon store through the CdNavigateToPurchasePage method.

A sample of access to CDDB resources and Amazon Web Services in Visual Basic 6 and Visual C++ 6 can be found inside the following sample installed with the product's setup package:

- SoundInfo

- CdPlayerWithCddb


How to get pictures of CD covers

Copyright © 2001-2018 MultiMedia Soft

How to get pictures of CD covers

Return to chapter overview

Pictures of Audio CD covers (also know as CD cover art) are obtained using the standard Amazon Web Services and are usually of three different sizes: Small (thumbnail), Medium and Large: see the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial for details about obtaining covers of an Audio CD.


How to manage delayed playbacks

How to manage delayed playbacks

Active DJ Studio allows setting up a list of sound files whose playback can be programmed to start after a given delay through a set of methods of the DelayedPlayback COM object.

Each sound file (item) can be added to the list of delayed playbacks in 2 different ways:

· by setting a specific amount of delay through the DelayedPlayback.ListAddItem or DelayedPlayback.ListAddItemEx methods
· by setting a specific date and time through the DelayedPlayback.ListAddItemByDate or DelayedPlayback.ListAddItemByDateEx methods

in both cases mentioned methods will return back a unique identifier that will be then used in order to access the item itself at a later stage.

Each item can be removed from the list through the DelayedPlayback.ListRemoveItem method and the whole list can be emptied through the DelayedPlayback.ListRemoveAll method.

The number of items inside the list can be enumerated through the DelayedPlayback.ListGetCount method.

If time positioning and duration of a certain item should overlap with the time positioning and duration of an existing item, you could decide if accepting or denying its insertion inside the list through the DelayedPlayback.AllowOverlapping property: if overlapping shouldn't be allowed, an ERR_DELAYED_PLAYBACK_OVERLAP error would be generated in case of overlapping. Note that, in case of overlapping, the playing song would be immediately stopped without any kind of fade-out when an overlapped song should be started.

As already mentioned, each item is identified through its unique identifier: this identifier is passed as a parameter for accessing the following item's related features:

· Get its duration through the DelayedPlayback.ItemGetDuration method
· Start an immediate playback of the item through the DelayedPlayback.ItemPlayNow method with the option to keep it or remove it from the list
· Set the effective range that will be played through the DelayedPlayback.ItemSetRange method: this range can be obtained through the DelayedPlayback.ItemGetRange method
· Change or update the item's playback delay through the DelayedPlayback.ItemResetDelay method
· Set the number of loops that will be performed on the given item through the DelayedPlayback.ItemSetLoopCount method: the number of loops can be obtained through the DelayedPlayback.ItemGetLoopCount method
· Set the fade-in and fade-out time applied to start and end of playback through the DelayedPlayback.ItemSetFadeTime method: current fade-in and fade-out time can be obtained through the DelayedPlayback.ItemGetFadeTime method

Delayed playbacks are mainly intended for usage with regular audio files so encrypted audio files and video clips are not supported directly. A possible trick for using encrypted audio files and video clips with delayed playback would be the following:

· Load the file into the player using LoadEncryptedSound or VideoPlayer.Load methods
· Call DelayedPlayback.ListAddItem passing the index of the involved player and an empty pathname: this will force the player to start playback of its actual contents.

As you may understand, with this trick there would be no possibility to add more than one single file to the list of delayed playbacks for the involved player.


How to manage lyrics coming from LRC files

How to manage lyrics coming from LRC files

LRC is a text-based file format that synchronizes song lyrics with an audio file. When an audio file is played with certain music players on a computer or on modern digital audio players, the song lyrics are displayed. The lyrics file generally has the same name as the audio file, for example MySong.mp3 and MySong.lrc.

LRC files can be in 2 different formats:

· Simple LRC format

Simple LRC format was introduced by Kuo (Djohan) Shiang-shiang's Lyrics Displayer. It was one of the first computer programs, if not the first, that attempted to simulate Karaoke performance. It usually displays a whole line of lyrics by creating a time tag for each line.

The Line Time Tags are in the format [mm:ss.xx] where mm is minutes, ss is seconds and xx is hundredths of a second.

Example:

[mm:ss.xx] lyrics line 1

[mm:ss.xx] lyrics line 2

...

[mm:ss.xx] last lyrics line

ID Tags may appear before the lyrics, although some players may not recognize or simply ignore this.

[ti:Lyrics Title ]

[ar:Lyrics Artist]

[by:Creator of the LRC file]

[re:the player or the editor that creates LRC file]

[ve:version of program]

Example with ID tags:

[ti:Let's Twist Again]

[ar:Chubby Checker oppure Beatles, The]

[au:Written by Kal Mann / Dave Appell, 1961]

[al:Hits Of The 60's - Vol. 2 – Oldies]

[00:12.00]Lyrics beginning ...

[00:15.30]Some more lyrics ... ...

· Enhanced LRC format

Enhanced LRC format is an extension of Simple LRC Format developed by the designer of A2 Media Player. It adds an extra Enhanced time tag in the format: <mm:ss.xx>.

Example of an Enhanced LRC file:

[mm:ss.xx] <mm:ss.xx> line 1 word 1 <mm:ss.xx> line 1 word 2 <mm:ss.xx> ... line 1 last word <mm:ss.xx>

[mm:ss.xx] <mm:ss.xx> line 2 word 1 <mm:ss.xx> line 2 word 2 <mm:ss.xx> ... line 2 last word <mm:ss.xx>

...

[mm:ss.xx] <mm:ss.xx> last line word 1 <mm:ss.xx> last line word 2 <mm:ss.xx> ... last line last word <mm:ss.xx>

Active DJ Studio supports both Simple and Enhanced LRC formats through a set of methods and events.

LRC files can be loaded manually, through a call to the LrcLoad method, or automatically by setting the automatic load through the LrcNotifEnableSet method: in this latest case, each time a sound is loaded into a player, the control will automatically search for a file having the same filename of the loaded sound file and extension ".LRC": if for example the loaded sound file should be named MySong.mp3, the corresponding LRC file should be named MySong.lrc; the search would be obviously limited to the same directory containing the sound file. You can know if automatic loading of LRC file is enabled through the LrcNotifEnableGet method.

Each time a LRC file has been loaded, the container application is notified through the LrcFileAvailable event which also reports if the LRC format is Enhanced.

When a LRC file is loaded, its contents are parsed and stored internally, ID Tags are separated from Line Time Tags and Line Time Tags are parsed again and separated from eventual Enhanced Time Tags: you can request each of them through the following methods:

· ID tags, if available, can be retrieved using the LrcIdTagGet method.
· Line Time Tags (identified by the [mm:ss.xx] sequence) can be enumerated using the LrcTimeTagsSimpleGetCount method; the text of each single line and its timing position, expressed in milliseconds, can be obtained through the LrcTimeTagsSimpleGetAt method.
· Enhanced Time Tags (identified by the <mm:ss.xx> sequence) can be enumerated using the LrcTimeTagsEnhGetCount method; the text of each single tag, its timing position and related duration, expressed in milliseconds, can be obtained through the LrcTimeTagsEnhGetAt method.

It's important to remark that Enhanced LRC format can contain both Line Time Tags and Enhanced Time Tags while Simple LRC format can contain Line Time Tags only.

In most cases you won't need getting contents of Line Time Tags and of Enhanced Time Tags using methods described above because, during playback of a sound whose LRC file has been loaded, Active DJ Studio will automatically generate the following set of events that will allow the container application and the playing sound to be synchronized with lyrics:

· Incoming Line Time Tags are reported by the LrcAdvanceTimeLineFull: this event reports the full line of lyrics text and is generated with a certain advance respect to the playing sound allowing to display a preview of the lyrics text that will be sing some second later.
· The same incoming Line Time Tag is reported again by the LrcRealTimeLineFull: as for the event above, this event reports the same full line of lyrics text and is generated in the exact moment (real-time) when the specific lyrics text is being sung.
· Incoming Enhanced Time Tags are reported by the LrcRealTimeLinePortion: this event reports a portion of line of lyrics and is generated in the exact moment (real-time gain) when the specific lyrics text is being sung: this event is obviously generated for Enhanced LRC format only.

The possibility to fine tune the raising of the mentioned events is guaranteed by the LrcNotifTimingsSet method: it allows to set both the advance time used to fire the LrcAdvanceTimeLineFull event and the advance time used to fire the LrcRealTimeLineFull and LrcRealTimeLinePortion events; both timings are expressed in milliseconds and, by default, the LrcAdvanceTimeLineFull event is fired with an advance of 2000 milliseconds (2 seconds) while the LrcRealTimeLineFull and LrcRealTimeLinePortion events are fired with an advance of 20 milliseconds. Current settings can be obtained through the LrcNotifTimingsGet method.


How to manage Unicode characters in filenames and tags

How to manage Unicode characters in filenames and tags

All of our ActiveX controls support loading/saving files whose filename contains Unicode characters. Sound files with tags having fields containing Unicode characters are managed as well.

If you are a Visual Basic 6 developer, you certainly know that VB6 is built internally with Unicode support but all of its custom controls are only ANSI compliant, meaning that you will get a series of "???" when inserting Unicode characters inside a label control or inside a textbox. If your application needs to display Unicode characters on user interface elements, the unique alternative is using the "Microsoft Forms 2.0" (FM20.DLL) ActiveX control which comes with a set of Unicode compliant controls.

As a second VB6 issue, the "Microsoft Common Dialog Control" (ComDlg32.ocx), used to display common dialogs for open and save operations on files, is not Unicode compliant as well and Microsoft didn't give any alternative ActiveX control for this purpose; for this reason we have added to our control a set of methods which allows selecting files containing Unicode characters:

· CommonDialogShowOpen allows browsing a file to open
· CommonDialogGetInfoFromLastOpen allows obtaining details about the filename chosen for opening through a previous call to the CommonDialogShowOpen method
· CommonDialogShowSave allows browsing a file to save
· CommonDialogGetInfoFromLastSave allows obtaining details about the filename chosen for saving through a previous call to the CommonDialogShowSave method

In order to correctly manage Unicode characters with languages like Visual C++, you must compile the container application specifically for Unicode.


How to access BASS library functionalities directly

How to access BASS library functionalities directly

For some of its many features, Active DJ Studio embeds the well known BASS library and some of its plugins which allow decoding and playing a number of different audio formats; in some case you could have the need to drive BASS directly in order to perform some particular task not available from the component itself; for achieving this possibility you would have to load and eventually free BASS or its plugins through the LoadLibrary or LoadLibraryEx and the FreeLibrary Windows API functions.

Due to the fact that BASS.DLL and some of its plugins are already embedded inside this component, you don't need to redistribute them with your application because you can get direct access to the module loaded in memory through its handle (HMODULE) returned by an internal call to the LoadLibrary Windows API: this handle, for usage with your own code, can be obtained through the BassModuleGet method.

Through this method you have the possibility to access instances already loaded in memory by the multimedia engine AdjMmsEng.dll: indeed, by knowing the HMODULE of BASS.DLL or of some of its plugins, you could get the pointer to all of the functions exported by the various BASS modules through the GetProcAddress Windows API.

For details about dynamic loading of functions exported by the various BASS modules you can refer to the official documentation of BASS.

IMPORTANT NOTE: Calls to the BASS_Init and BASS_Free functions of BASS.DLL are already managed internally by multimedia engine AdjMmsEng.dll so it's recommended avoiding their usage in order to avoid compatibility issues.

Let's see a small example in C code (Visual Basic 6 is not such friendly when dealing with function pointers loaded dynamically) where we need to access, directly from our code, the BASS_ChannelSetAttribute function exported by BASS.DLL: In order to access this functions directly from your code, you will need to declare it inside you code like this:

#include "Bass.h"

#undef BASSDEF

#define BASSDEF(f) (WINAPI *f)  // define the functions as pointers

BOOL BASSDEF (BASS_ChannelSetAttribute)(DWORD handle, DWORD attrib, float value);

the syntax above is in pure C and is the exact copy of the statements available inside the Bass.h header file. The BASSDEF macro needs to be undefined and redefined with a small variation which allows declaring the calling convention of the exported functions as WINAPI * , which means "pointer to __stdcall". For further details about dynamic loading of functions exported by the various BASS modules you can refer to the official documentation of BASS.

At this point we can proceed with the effective loading of the function pointers in this way:

HMODULE    hBass = NULL;

Amp3dj1.BassModuleGet (MODULE_BASS, &hBass);

#define LOADBASSFUNCTION(f) *((void**)&f)=GetProcAddress(HMODULE (hBass),#f)

LOADBASSFUNCTION(BASS_ChannelSetAttribute);

That's all: we can now call the BASS function directly from our code: if for example we should need to lower a stream to half its volume, we could simply use the following code:

HSTREAM   hStream = NULL;

Amp3dj1.BassStreamGet (0, &hStream);

BASS_ChannelSetAttribute (hStream, BASS_ATTRIB_VOL, 0.5f);

This brings another interesting point: on the function call above we are acting on a playback stream, identified by the hStream variable: how can we obtain that stream? This is quite simple: In case you should need to have direct access to the handle (HSTREAM) of a playback stream created through BASS after calling the LoadSound, StreamMixerCreate and similar methods, you can use the BassStreamGet method. In order to initialize this variable you could catch the SoundLoaded event or, as seen on the code snippet above, call the BassStreamGet method when needed.

A second feature brought by the BassStreamGet method is the possibility to apply custom DSP effects implemented by third-party plugins which work on playback streams of type HSTREAM: some of these plugins, such as BASS_WA, BASS_WINAMP, BASS_SFX and others, are available on the BASS web site: please, refer to the respective documentations for knowing how to use the HSTREAM playback stream with these plugins.

As mentioned before, Active DJ Studio already embeds some external BASS plugin that supports the decoding of specific audio formats like WMA, MP4, AC3 and others: from time to time someone belonging to the BASS community delivers new plugins for supporting other audio formats; also if not directly embedded inside the component, functions exported by the plugin for creating the playback audio stream can be in any case accessed by the component through a previous call to the BassPluginStreamCreateFunc method which allows loading the plugin and the specific function dynamically at runtime.

After calling the BassPluginStreamCreateFunc method, when methods beginning with the "Load".prefix (like LoadSound or LoadSoundFromMemory) are invoked, the function exported by the plugin will be automatically used for trying to load the sound file or the Internet stream.

At the moment the component supports the dynamic loading of functions for creating playback streams from the following entities:

· Sound files: the related function is usually exported by the plugin with the name BASS_xxx_StreamCreateFile where "xxx" indicates the managed audio format, for example BASS_AIX_StreamCreateFile or BASS_TTA_StreamCreateFile; the exported function must use the following C syntax:

HSTREAM BASS_xxx_StreamCreateFile (

   BOOL mem,

   const void *file,

   QWORD offset,

   QWORD length,

   DWORD flags

);

· Internet streams: the related function is usually exported by the plugin with the name BASS_xxx_StreamCreateURL where "xxx" indicates the managed audio format, for example BASS_AIX_StreamCreateURL; the exported function must use the following C syntax:

HSTREAM BASS_xxx_StreamCreateURL (

   const char *url,

   DWORD offset,

   DWORD flags,

   DOWNLOADPROC *proc,

   void *user

);

It's important to note that you don't need calling the LoadLibrary and FreeLibrary functions on the DLL of the plugin: these functions are already called internally by the component when the BassPluginStreamCreateFunc method is invoked: you simply need to provide the pathname of the plugin and the component will take care of the needed operations.


How to detect silent portions of sound files

How to detect silent portions of sound files

Active DJ Studio allows detecting silent portions of sound files in different ways:

· automatic silence detection when a sound is loaded inside a player
· manual silence detection before starting playback of a sound loaded inside a player
· manual silence detection directly on a sound file stored on disk
· realtime silence detection during playback

Let's see how the various ways differ from each other:

Automatic silence detection when a sound is loaded inside a player

In this case silent portions of a sound file, usually found at the beginning and at the end of the audio stream, are automatically detected each time a song is loaded inside a player through one of the many methods beginning with the "Load" prefix like LoadSound or LoadSoundFromMemory (with the exception of the LoadInternetStream method).

By default this feature is disabled but can be enabled through the SilenceDetectionOnPlayerLoadAutoSet method: this setting becomes effective as soon as a new sound is loaded into the given player. Silence detection is performed inside a secondary thread so silence positions are not immediately available after loading the sound: when silence positions become available the container application is notified through the SilencePositionAvailable event.

Manual silence detection before starting playback of a sound loaded inside a player

As seen on the point above, by default silence detection is disabled when loading a new sound inside a player: in this situation you can obtain silent portions at the beginning and at the end of the loaded sound in two ways:

· through the SilenceDetectionOnPlayer method: in this case silence detection is performed inside the main thread of the container application so, when the method returns control to the caller, silence positions are immediately available.
· through the SilenceDetectionOnPlayerRequest method: in this case silence detection is performed inside a secondary thread so, when the method returns control to the caller, silence positions are not immediately available; when silence positions are calculated the container application is notified through the SilencePositionAvailable event.

Manual silence detection directly on a sound file stored on disk

If you don't need to start a playback session with a specific audio file you can in any case detect the initial and final silent portions through the SilenceDetectionOnFile method: as seen for the SilenceDetectionOnPlayer method, also in this case silence detection is performed inside the main thread of the container application so, when the method returns control to the caller, silence positions are immediately available.

Realtime silence detection during playback

During a playback session there may be the need to detect when the sound level stays under a certain threshold for a given amount of time: this task can be performed by enabling the realtime silence detection system through the SilenceDetectionRealTimeEnable method. Parameters related to the silence detection processing, like the sound level threshold and the minimal duration of the silent portion, can be set through the SilenceDetectionRealTimeParamsSet method which should be invoked before enabling silence detection.

Differently from other ways described on points above, which can only detect the initial and final portions of silence on audio files whose duration is known, when realtime silence detection is enabled you can detect silent portions of songs which may be located within other audible data and, more interesting, realtime silence detection could be enabled on Internet streams loaded through the LoadInternetStream method or on audio queues created using the StreamQueueCreate method.

Each time a silent portion of song is detected, the container application is notified through the SilenceDetectionStateChange event: obviously the same event is fired again when the silent portions ends and new audible samples are met.

In order to improve the granularity of realtime silence detection is recommended setting a small update time for the playback buffer by setting the BufferUpdateTime property to a value around 10 milliseconds.


How to manage download sessions

How to manage download sessions

Inside the How to play Internet streams and radio stations tutorial we have seen that the component gives the possibility to connect to a remote server in order to start playback of a remote file through its URL: there are situations which could require downloading the full remote file locally before starting playback in order to avoid buffering issues in case of slow or intermittent connections or to allow the storage of the remote file for future uses; the downloading task can be achieved through the Downloader COM object accessible through the Downloader property.

The Downloader COM object, which is intended for download of remote files only (so downloading from broadcasting streaming servers or radio stations is not supported), can be instanced and started through the Downloader.Create method and exposes the following features:

· downloading a remote file and storing its contents inside a local file through the Downloader.SessionStartToFile method.

· downloading a remote file and storing its contents inside a local memory buffer through the Downloader.SessionStartToMemory method: the size of the buffer, whose allocation is responsibility of the container application, can be determined through the Downloader.SessionDataSizeGet method.

· downloading a remote media file and loading its contents into an instanced player directly through the Downloader.SessionStartToPlayer method. This method is equivalent to calling the Downloader.SessionStartToFile method followed by a call to the LoadSound, LoadEncryptedSound (in case of sound files encrypted through our CryptSound™ application) or VideoPlayer.Load methods. Apart from the automatic loading of the downloaded media file, the difference respect to the Downloader.SessionStartToFile method is the fact that the remote file will be stored locally inside a temporary file that will be automatically deleted when the CloseSound or VideoPlayer.Close methods are invoked or when a new media file is loaded inside the same player: this means that the container application won't have to worry about the existence of the downloaded file when no more needed.

All of the mentioned methods allow starting the downloading session and, in case of success, a session's unique identifier is returned: through this identifier you have the possibility to interrupt the same downloading session through the Downloader.SessionStop method.

A set of events is provided for keeping the container application up to date respect to the downloading session advancement:

- the DownloaderSessionStarted event reports that the downloading session is started

- the DownloaderSessionProgress event informs about the download advancement expressed in percentage

- the DownloaderSessionCompleted event reports that the downloading session is completed successfully

- the DownloaderSessionFailed event reports that the connection to the remote server or the access to the remote file failed

- the DownloaderSessionStopped event reports that the downloading session has been stopped by the user manually through a call to the Downloader.SessionStop method

When the downloading session has been started through the Downloader.SessionStartToPlayer method and the same has been reported as successful through the DownloaderSessionCompleted event, a further couple of events may be generated:

- the SoundLoaded event reports that the downloaded media file belongs to a supported format and that the automatic loading into the player has been successful: after receiving this event the downloaded file could be put in playback through the usual PlaySound or VideoPlayer.Play methods.

- the DownloaderSessionInvalidFile event reports that the remote file belongs to an unsupported format and that the automatic loading into the player failed.

When invoking the Downloader.Create method you can specify timeouts checked during the connection to the remote server and during data downloading: these timeouts can be modified at any time through the Downloader.SetTimeouts method.


How to decode media files

How to decode media files

There could be situations in which the container application needs to gain access to uncompressed PCM sound data of a media file in order to perform some specific task: for this purpose the MediaFileDecoder COM object exposes a set of methods which ease this specific task.

The first mandatory step is to initialize the decoder through the MediaFileDecoder.Initialize method: after this operation you can start decoding single media files, where the term "media file" applies to both audio and video clips, through the MediaFileDecoder.FileOpen method or, for RAW audio files, through the MediaFileDecoder.FileOpenRaw method.

Once the file has been decoded, you can know its duration in milliseconds through the MediaFileDecoder.FileDurationGet method and you can start obtaining uncompressed PCM samples; the total uncompressed size in bytes of the decoded audio track can be obtained through the MediaFileDecoder.FileLengthGet method while the size of a specific portion of the decoded audio track can be obtained through the MediaFileDecoder.FileChunkLengthGet method.

Due to the fact that uncompressed PCM samples of audio tracks may require huge sized buffers for storage, you have the possibility to read smaller portions of the uncompressed samples through the MediaFileDecoder.FileDataGet method: this method receives in input a buffer of a predetermined length which be filled accordingly with the decoded PCM samples: each call to this method will automatically increment the position internal to the decoded audio track allowing to read the full audio track without the need to reposition the reader; in most cases the buffer will be smaller respect to the total size of the decoded audio track, so you will have to perform an adequate number of calls to this method, usually inside a loop, in order to scan the entire audio track.

Let's see a couple of small pieces of code (please, note that for simplicity the code below misses error checking):

Visual Basic 6

' create the decode stream

Amp3dj1.MediaFileDecoder.FileOpen "c:\myfile.mp3"

' allocate the buffer that will receive uncompressed samples

Dim buffer(20000) As Byte

' get the total length of the uncompressed audio track: we will use it for determining the current percentage

Dim nFileLength As Long

Amp3dj1.MediaFileDecoder.FileLengthGet nFileLength

Dim nBytesRead As Long

nBytesRead = -1

Dim nTotalBytesRead As Currency

nTotalBytesRead = 0

' loop until the MediaFileDecoder.FileDataGet method find some byte

Do While nBytesRead <> 0

   ' get samples from the decode stream and put them in buffer

   Amp3dj1.MediaFileDecoder.FileDataGet VarPtr(buffer(0)), 20000, DATA_TYPE_NATIVE, nBytesRead

   ' do something with the returned buffer

   [ ... ]

   ' calculate the current percentage of advancement: may be useful to drive a progress bar

   nTotalBytesRead = nTotalBytesRead + nBytesRead

   Dim nPercentage As Long

   nPercentage = CLng((nTotalBytesRead * 100) / nFileLength)

   ' in case you want to stop/exit...

   DoEvents

Loop

Visual C++

// create the decode stream

Amp3dj1.GetMediaFileDecoder().FileOpen("c:\\myfile.mp3");

// allocate the buffer that will receive uncompressed samples

VARIANT buffer;

VariantInit(&buffer);

buffer.vt = VT_BYREF | VT_UI1;

buffer.pbVal = (BYTE*) malloc (20000);

// get the total length of the uncompressed audio track: we will use it for determining the current percentage

long        nFileLength32;

Amp3dj1.GetMediaFileDecoder().FileLengthGet (&nFileLength32);

__int64        nFileLength = nFileLength32;

__int64        nTotalBytesRead = 0;

long        nBytesRead = 0;

// loop until the MediaFileDecoder.FileDataGet method find some byte

do

{

   // get samples from the decode stream and put them in buffer

   Amp3dj1.GetMediaFileDecoder().FileDataGet (buffer, 20000, DATA_TYPE_NATIVE, &nBytesRead);

   // do something with the returned buffer

   [ ... ]

   // calculate the current percentage of advancement: may be useful to drive a progress bar

   nTotalBytesRead += nBytesRead;

   long        nPercentage = long ((nTotalBytesRead * 100) / nFileLength);

   // in case you want to stop/exit...

   theApp.YieldControl ();

}

while (nBytesRead != 0);

free (buffer.pbVal);

In the code above we have seen how to read the uncompressed PCM samples for the entire media file: there may be situations in which you could need to read only a smaller portion of the media file; in this case you can know how many bytes should be read for a specific portion of the audio track through the MediaFileDecoder.FileChunkLengthGet method and to set the initial position where the reading will start within the media file through the MediaFileDecoder.FilePositionSet method; the code above could be then adapted to check how many bytes have been read in order to exit the loop when the length in bytes returned by the MediaFileDecoder.FileChunkLengthGet method is reached.

After the decoding of the audio track, you may obtain its sample rate and number of channels through the MediaFileDecoder.FileInfoGet method: this method will also return the bit depth (also known as "encode mode") of the decoded samples.

Once the decoded stream is no more needed, you can discard it from memory and free its resources by calling the MediaFileDecoder.FileClose method.


How to generate wave tones, noises, DTMF tones and text to speech

How to generate wave tones, noises, DTMF tones and text to speech

 Return to chapter overview

Apart from playing music files, Active DJ Studio allows creating several kinds of sound:

Pure wave tones

Monaural, Binaural and multi-channel wave tones

Sliding wave tones

Noises

DTMF tones

Text to speech

Pure wave tones

A pure wave tone is typically a tone with a sinusoidal waveform having an amplitude and a frequency. The component allows creating sinusoidal, square, sawtooth and triangular waveforms in two ways:

· Through the SoundGenerator.StreamCreateTone method.

This way creates on a specific player a mono or stereo wave tone having a given duration and a fixed amplitude and frequency: after invoking this method the wave tone can be played just in the same way used for regular sound files, PlaySound method for starting playback, StopSound method for stopping playback, StreamOutputSpeakerSet method for redirecting the audio flow to a given speaker and so on.

· By creating an empty multi-channel (up to 7.1) audio stream on a specific player through the SoundGenerator.StreamCreateMultiChannelEmpty method and then by adding the pure wave tone, which is always a mono audio stream, to a specific channel of the stream through the SoundGenerator.StreamChannelAddTone method. if you should need to render the same wave tone on two speakers of the stream at the same time, you would simply need to make a further call to the SoundGenerator.StreamChannelAddTone method on a different channel of the stream. Once at least one element has been added, the multi-channel audio stream can be played just in the same way used for regular sound files.

The pure wave tone can be added to the multi-channel at a given offset and, once reproduced completely, is automatically removed from the audio stream: if you should need to repeat the wave tone, you would have to add it again to the stream with a new call to the SoundGenerator.StreamChannelAddTone method.

Differently from pure wave tones created through the SoundGenerator.StreamCreateTone method, pure wave tones added to a multi-channel audio stream can be endless, meaning that they can generate a sound flow without interruption for the whole duration of the multi-channel audio stream and can be modified during playback by changing the amplitude (through the SoundGenerator.StreamElementAmplitudeSet method) and/or the frequency (through the SoundGenerator.StreamElementToneFrequencySet method).

Monaural, Binaural and multi-channel wave tones

Pure wave tones described in the previous section can be combined together to create more complex waveforms:

· Binaural wave tones are produced when two pure wave tones, having different frequencies, combine directly in the brain of the listener by sending two different pure wave tones, having different frequencies, to two different channels of the audio stream. Also in this case a binaural wave tone can be created by creating an empty multi-channel (up to 7.1) audio stream on a specific player through the SoundGenerator.StreamCreateMultiChannelEmpty method and then by adding, in this case on different channels, two or more pure wave tones, each having its own frequency and amplitude, through separate calls to the SoundGenerator.StreamChannelAddTone method. Below a couple of code snippets which show how to create a binaural stereo waveform.

Visual Basic 6

' prepare the audio stream to compose on player 0 (44100, stereo)

ActiveDjStudio1.SoundGenerator.StreamCreateMultiChannelEmpty Player_0, 44100, 2

Dim nDummyUniqueId As Long

' add the first 3 seconds long sine tone on left channel of the stream (400 hz on channel 0)

Dim nSpeaker As Integer

nSpeaker = 0

ActiveDjStudio1.SoundGenerator.StreamChannelAddTone Player_0, SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 400, 1, 3000, 0, nDummyUniqueId

' add the second 3 seconds long sine tone on right channel of the stream (480 hz on channel 1)

ActiveDjStudio1.SoundGenerator.StreamChannelAddTone Player_0, SOUNDGEN_WAVE_TYPE_SINE, nSpeaker+1, 480, 1, 3000, 0, nDummyUniqueId

' play the stream

ActiveDjStudio1.PlaySound Player_0

Visual C++

// prepare the audio stream to compose on player 0 (44100, stereo)

m_DjStudio1.GetSoundGenerator().StreamCreateMultiChannelEmpty (Player_0, 44100, 2);

long nDummyUniqueId;

// add the first 3 seconds long sine tone on left channel of the stream (400 hz on channel 0)

int nSpeaker = 0;

m_DjStudio1.GetSoundGenerator().StreamChannelAddTone (Player_0, SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 400, 1, 3000, 0, &nDummyUniqueId);

// add the second 3 seconds long sine tone on right channel of the stream (480 hz on channel 1)

m_DjStudio1.GetSoundGenerator().StreamChannelAddTone (Player_0, SOUNDGEN_WAVE_TYPE_SINE, nSpeaker+1, 480, 1, 3000, 0, &nDummyUniqueId);

// play the stream

m_DjStudio1.PlaySound (Player_0);

· Monaural wave tones are produced when two or more pure wave tones, having different frequencies, combine digitally or naturally before the sounds reach the ears, as opposed to combining in the brain of the listener like binaural wave tones. The component allows creating composite wave tones with more than two pure wave tones combined together. In this case a monaural wave tone can be created by creating an empty multi-channel (up to 7.1) audio stream on a specific player through the SoundGenerator.StreamCreateMultiChannelEmpty method and then by adding, always on the same channel, two or more pure wave tones, each having its own frequency and amplitude, through separate calls to the SoundGenerator.StreamChannelAddTone method. Below a couple of code snippets which show how to create a monaural stereo waveform.

Visual Basic 6

' prepare the audio stream to compose on player 0 (44100, stereo)

ActiveDjStudio1.SoundGenerator.CompositeWaveTonePrepare Player_0, 44100, 2

' loop on the two channels (left and right)

Dim nSpeaker as Integer

For nSpeaker = 0 To 1

   ' add a 3 seconds long 400 hz sine tone on the current channel

   ActiveDjStudio1.SoundGenerator.StreamChannelAddTone Player_0, SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 400, 1, 3000, 0, nDummyUniqueId

   ' add a 3 seconds long 480 hz sine tone on the current channel

   ActiveDjStudio1.SoundGenerator.StreamChannelAddTone Player_0, SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 480, 1, 3000, 0, nDummyUniqueId

Next nSpeaker

' play the stream

ActiveDjStudio1.PlaySound Player_0

Visual C++

' prepare the audio stream to compose on player 0 (44100, stereo)

m_DjStudio1.GetSoundGenerator().StreamCreateMultiChannelEmpty (Player_0, 44100, 2);

// loop on the two channels (left and right)

for (int nSpeaker = 0; nSpeaker < 2; nSpeaker++)

{

   // add a 3 seconds long 400 hz sine tone on the current channel

   m_DjStudio1.GetSoundGenerator().StreamChannelAddTone (Player_0, SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 400, 1.0f, 3000, 0, &nDummyUniqueId);

   // add a 3 seconds long 480 hz sine tone on the current channel

   m_DjStudio1.GetSoundGenerator().StreamChannelAddTone (Player_0, SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 480, 1.0f, 3000, 0, &nDummyUniqueId);

}

// play the stream

m_DjStudio1.PlaySound (Player_0);

In both cases, as seen for pure wave tones, after one or more tones have been added to the multi-channel audio stream, this can be played just in the same way used for regular sound files: PlaySound method for starting playback, StopSound method for stopping playback.

Each wave tone can be added to the multi-channel at a given offset and, once reproduced completely, is automatically removed from the audio stream: if you should need to repeat these composite wave tones, you would have to add them again to the stream with new calls to the SoundGenerator.StreamChannelAddTone method.

Also in this case pure wave tones added to a multi-channel audio stream can be endless, meaning that they can generate a sound flow without interruption for the whole duration of the multi-channel audio stream and can be modified during playback by changing the amplitude (through the SoundGenerator.StreamElementAmplitudeSet method) and/or the frequency (through the SoundGenerator.StreamElementToneFrequencySet method).

Sliding wave tones

Sliding wave tones are obtained by dynamically modifying, during a given interval, the frequency and/or the amplitude of a pure wave tone. The component allows creating sinusoidal, square and sawtooth waveforms in two ways:

· Through the SoundGenerator.StreamCreateSlidingTone method.

This way creates on a specific player a mono or stereo sliding wave tone having a given duration and a starting and ending amplitude and/or frequency: after invoking this method the sliding wave tone can be played just in the same way used for regular sound files, PlaySound method for starting playback, StopSound method for stopping playback, StreamOutputSpeakerSet method for redirecting the audio flow to a given speaker and so on.

· By creating an empty multi-channel (up to 7.1) audio stream on a specific player through the SoundGenerator.StreamCreateMultiChannelEmpty method and then by adding the sliding wave tone, which is always a mono audio stream, to a specific channel of the stream through the SoundGenerator.StreamChannelAddSlidingTone method. if you should need to render the same sliding wave tone on two speakers of the stream at the same time, you would simply need to make a further call to the SoundGenerator.StreamChannelAddSlidingTone method on a different channel of the stream. Once at least one element has been added, the multi-channel audio stream can be played just in the same way used for regular sound files.

Also in this case each sliding wave tone can be added to the multi-channel at a given offset and, once reproduced completely, is automatically removed from the audio stream: if you should need to repeat the same sliding wave tone, you would have to add it again to the stream with new calls to the SoundGenerator.StreamChannelAddSlidingTone method.

Noises

Noises are obtained by generating a random signal with a constant power spectral density. The component allows creating white, pink and brown noises in two ways:

· Through the SoundGenerator.StreamCreateNoise method.

This way creates on a specific player a mono or stereo noise having a given duration and a fixed amplitude: after invoking this method the noise can be played just in the same way used for regular sound files, PlaySound method for starting playback, StopSound method for stopping playback, StreamOutputSpeakerSet method for redirecting the audio flow to a given speaker and so on.

· By creating an empty multi-channel (up to 7.1) audio stream on a specific player through the SoundGenerator.StreamCreateMultiChannelEmpty method and then by adding the noise, which is always a mono audio stream, to a specific channel of the stream through the SoundGenerator.StreamChannelAddNoise method. if you should need to render the same noise on two speakers of the stream at the same time, you would simply need to make a further call to the SoundGenerator.StreamChannelAddNoise method on a different channel of the stream. Once at least one element has been added, the multi-channel audio stream can be played just in the same way used for regular sound files.

The noise can be added to the multi-channel at a given offset and, once reproduced completely, is automatically removed from the audio stream: if you should need to repeat the noise, you would have to add it again to the stream with a new call to the SoundGenerator.StreamChannelAddNoise method.

Differently from noises created through the SoundGenerator.StreamCreateNoise method, noises added to a multi-channel audio stream can be endless, meaning that they can generate a sound flow without interruption for the whole duration of the multi-channel audio stream and can be modified during playback by changing the amplitude through the SoundGenerator.StreamElementAmplitudeSet method.

DTMF tones

DTMF (Dual Tone Multi Frequency) tones are used for telecommunication signaling over analog telephone lines in the voice-frequency band between telephone handsets and other communications devices and the switching center. The component allows creating DTMF tones in two ways:

· Through the SoundGenerator.StreamCreateDtmfString method.

This way creates on a specific player a mono or stereo audio stream having a duration which depends upon the number of characters to convert to DTMF tones and a fixed amplitude: after invoking this method, DTMF tones can be played just in the same way used for regular sound files, PlaySound method for starting playback, StopSound method for stopping playback, StreamOutputSpeakerSet method for redirecting the audio flow to a given speaker and so on.

· By creating an empty multi-channel (up to 7.1) audio stream on a specific player through the SoundGenerator.StreamCreateMultiChannelEmpty method and then by adding the audio stream generated through the conversion of a string of characters to DTMF tones, which is always a mono audio stream, to a specific channel of the stream through the SoundGenerator.StreamChannelAddDtmfString method. if you should need to render the same DTMF tones on two speakers of the stream at the same time, you would simply need to make a further call to the SoundGenerator.StreamChannelAddDtmfString method on a different channel of the stream. Once at least one element has been added, the multi-channel audio stream can be played just in the same way used for regular sound files.

The mono stream containing DTMF tones can be added to the multi-channel at a given offset and, once reproduced completely, is automatically removed from the audio stream: if you should need to repeat the stream, you would have to add it again to the stream with a new call to the SoundGenerator.StreamChannelAddDtmfString method.

Text to speech

Text to speech is the artificial production of human speech and is obtained by leveraging the Microsoft's Speech API installed on Windows systems. Text is converted into an audio stream containing spoken voice through the usage of voices installed inside the system; the total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method while attributes of each single voice can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method.

As seen for previous items, the component allows creating text to speech in two ways:

· Through the SoundGenerator.StreamCreateSpeechFromFile or through the SoundGenerator.StreamCreateSpeechFromString method.

This way creates on a specific player a mono or stereo audio stream having a duration which depends upon the number of text's words to convert and a fixed amplitude: after invoking this method, the generated audio stream can be played just in the same way used for regular sound files, PlaySound method for starting playback, StopSound method for stopping playback, StreamOutputSpeakerSet method for redirecting the audio flow to a given speaker and so on.

· By creating an empty multi-channel (up to 7.1) audio stream on a specific player through the SoundGenerator.StreamCreateMultiChannelEmpty method and then by adding the audio stream generated through the conversion of words of text, which is always a mono audio stream, to a specific channel of the stream through the SoundGenerator.StreamChannelAddSpeechFromFile method or through the SoundGenerator.StreamChannelAddSpeechFromString method; if you should need to render the same text on two speakers of the stream at the same time, you would simply need to make a further call to the mentioned methods on a different channel of the stream. Once at least one element has been added, the multi-channel audio stream can be played just in the same way used for regular sound files.

The mono stream containing the speech can be added to the multi-channel at a given offset and, once reproduced completely, is automatically removed from the audio stream: if you should need to repeat the stream, you would have to add it again to the stream with a new call to the SoundGenerator.StreamChannelAddSpeechFromFile method or through the SoundGenerator.StreamChannelAddSpeechFromString method.

A sample of generation of a multi-channel audio stream in Visual Basic 6 and Visual C++ can be found inside the following sample installed with the product's setup package:

- SoundGenerator


How to compose a sound

How to compose a sound

Active DJ Studio allows composing new sound and/or music files by mixing together audio data incoming from several sources; an important concept about this feature is the fact that all sound items composing the session are layered, meaning that they can be added, removed and modified before rendering the final mix.

Main sources of audio data can be the following:

· Sound files stored inside disk files or inside memory buffers: these sound files can be in several audio formats as seen inside the LoadSound and LoadSoundFromRawFile methods
· The Microsoft Speech API which allows creating audio data from a string of text or from a text file through synthesized voices

The sound composer can create mono, stereo and multi-channel (up to 7.1) sessions and allows, for each item added to the session, to define the destination channel and the offset in milliseconds respect to the beginning of the final audio stream.

The main actor in sound composition is the internal sound composer object, implemented through the SoundComposerMan class and exposed through the SoundComposer property; there are three main steps needed to perform a sound composition:

· Initializing the sound composer's session by defining the characteristics of the audio stream that will be composed, mainly sample rate and number of audio channels, through the SoundComposer.SessionCreate method.

· Once the session has been initialized, we can start adding items through a set of methods that will be mentioned on the next paragraph; each item added to the session is identified through a unique identifier: this unique identifier can be used in case you should need to perform some modification to the item itself, for example changing its amplitude, its offset, its channel and so on.

· At this point, when all of the needed items have been added and placed on the selected offsets and audio channels, before starting playback there is the possibility to save the current session into a XML file on disk (with the only exception of memory-based items) through the SoundComposer.SessionSave method, allowing to eventually reload the same session at a later time through the SoundComposer.SessionLoad method.

· We can now start rendering the audio stream through the PlaySound method. It's important to note that the sound composer will output a continuous audio stream and, by default, when playback of the last item inside the session has been completed, the involved player will stay in "playback status" until the StopSound method is invoked. You may change this behaviour by invoking the SoundComposer.SessionAutomaticStopWhenDoneSet method with its bAutomaticStop parameter set to "true": in this situation the audio stream will be automatically stopped when playback of the last item inside the session has been completed and the SoundDone event will be raised.

· When the session is started, you can still add new items to the sound composer, keeping in mind that, in this case, the offset of the item will be related to the current playback position.

· When playback of an item is started, the container application is notified through the SoundComposerItemStart event. You may also check if a given item is in playback state through the SoundComposer.ItemIsPlaying method and obtain its current playback position through the SoundComposer.ItemPlaybackPositionGet method.

· When playback of an item has been performed completely, the item is automatically removed from the session and its resources deallocated, including the unique identifier which from now on becomes invalid. In this case the container application is notified through the SoundComposerItemDone event.

· In order to totally remove a sound composer session and discard all of the previously added items, you would need to call the CloseSound method.

As mentioned on the second point above, new items can be added to the sound composer session through a set of specific methods which vary depending upon the specific type of item:

Audio files

Audio generated from Microsoft Speech API

After adding an item to the session, you can still perform changes to the item or eventually obtaining related information by leveraging the following set of methods:

- SoundComposer.ItemAmplitudeGet to obtain the amplitude of the item

- SoundComposer.ItemAmplitudeSet to modify the amplitude of the item

- SoundComposer.ItemChannelGet to obtain the channel of of the audio stream that will reproduce the item

- SoundComposer.ItemChannelSet to modify the channel of of the audio stream that will reproduce the item

- SoundComposer.ItemRemove to remove the item from the sound composition

- SoundComposer.ItemInfoGet to obtain the duration, expressed in milliseconds, of the item and the number of audio channel on the original sound file

- SoundComposer.ItemOffsetGet to obtain the offset, expressed in milliseconds, of the item respect to the beginning of the audio stream

- SoundComposer.ItemOffsetSet to modify the offset, expressed in milliseconds, of the item respect to the beginning of the audio stream

- SoundComposer.ItemTypeGet to obtain the item's type

- SoundComposer.ItemFriendlyNameGet to obtain the friendly name of the item

- SoundComposer.ItemFriendlyNameSet to modify the friendly name of the item

Other methods, specific to each type of item, are described inside sections below.

Adding audio files

The sound composer allows adding sound files stored in different audio formats and media:

· Sound files stored on the local disk through the SoundComposer.ItemSoundFileAdd method or through the SoundComposer.ItemSoundFileRawAdd method: accepted audio formats are the same supported by the LoadSound and LoadSoundFromRawFile methods.
· Sound files stored inside a memory buffer through the SoundComposer.ItemSoundFileMemoryAdd method or through the SoundComposer.ItemSoundFileMemoryRawAdd method: accepted audio formats are the same supported by the LoadSoundFromMemory and LoadSoundFromRawMemory methods; as mentioned before, memory-based items are ignored and discarded when the SoundComposer.SessionSave method is invoked.

Once the sound file has been added to the session, you can modify some of its settings through the following set of methods:

- SoundComposer.ItemSoundFileLoadRangeGet to obtain the loading range of the item

- SoundComposer.ItemSoundFileVolumeSmoothingGet to obtain the eventual volume smoothing of the item

- SoundComposer.ItemSoundFileVolumeSmoothingSet to obtain the eventual volume smoothing of the item

As you can see there is a consistent number of methods that can be used to modify how a specific sound file will be mixed to the audio stream.

In case you should need to add a new sound file item or speech item at the exact end of an existing item, you may append the new sound file by invoking the SoundComposer.ItemAppendNext method immediately before invoking the SoundComposer.ItemSoundFileAdd method (or the other methods for adding files in raw format or memory-based files).

The SoundComposer.ItemAppendNext method receives the unique identifier of the already existing item allowing the next call to the SoundComposer.ItemSoundFileAdd method to calculate the exact offset to place the new item inside the audio stream.

When the SoundComposer.ItemAppendNext method is invoked successfully, the next sound file will be appended to the given existing item on the same audio channel of the sound composer and with the same "downmix to mono" setting. After the new item has been appended, the "append mode" is automatically reset.

Let's see a small code snippet where we create a session having a stereo audio stream; on this stream we will perform the following actions:

· add two stereo sound files (myfile1.mp3 and myfile2.wma) to the session
· the loading range of both sound files is limited to 30 seconds starting from second 10 of each sound file
· the first file is loaded at offset 0 on the final audio stream
· the second file is loaded at offset 28000 (28 seconds) on the final audio stream
· a fade-in of 2 seconds is applied at the beginning of each sound file
· a fade-out of 3 seconds is applied at the end of each sound file

as you may see, the two sound file will overlap for a small chunk of 2 seconds, during fade-in/fade-out, on the final audio stream:

Visual Basic.NET

' create the audio stream on a specific player (44100, stereo)

Amp3dj1.SoundComposer.SessionCreate (Player_1, 44100, 2)

' add the two sound files by limiting their loading range from second 10 to second 40 (30 seconds)

Dim nUniqueIdFile1 As Int32 = 0

Dim nUniqueIdFile2 As Int32 = 0

Amp3dj1.SoundComposer.ItemSoundFileAdd (Player_1, "First sound", 0, _

                 "c:\myfolder\myfile1.mp3", False, 0, 10000, 40000, nUniqueIdFile1)

Amp3dj1.SoundComposer.ItemSoundFileAdd (Player_1, "Second sound", 0, _

                 "c:\myfolder\myfile2.wma", False, 28000, 10000, 40000, nUniqueIdFile2)

' add a 2 seconds fade-in and a 3 seconds fade-out to the two sound files

Amp3dj1.SoundComposer.ItemSoundFileVolumeSmoothingSet (Player_1, nUniqueIdFile1, 2000, 3000)

Amp3dj1.SoundComposer.ItemSoundFileVolumeSmoothingSet (Player_1, nUniqueIdFile2, 2000, 3000)

' start playback of the final audio stream

Amp3dj1.PlaySound (Player_1)

Visual C#

// create the audio stream on a specific player (44100, stereo)

Amp3dj1.SoundComposer.SessionCreate (Player_1, 44100, 2);

// add the two sound files by limiting their loading range from second 10 to second 40 (30 seconds)

Int32 nUniqueIdFile1 = 0;

Int32 nUniqueIdFile2 = 0;

Amp3dj1.SoundComposer.ItemSoundFileAdd (Player_1, "First sound", 0,

                 @"c:\myfolder\myfile1.mp3", false, 0, 10000, 40000, ref nUniqueIdFile1);

Amp3dj1.SoundComposer.ItemSoundFileAdd (Player_1, "Second sound", 0,

                 @"c:\myfolder\myfile2.wma", false, 28000, 10000, 40000, ref nUniqueIdFile2);

// add a 2 seconds fade-in and a 3 seconds fade-out to the two sound files

Amp3dj1.SoundComposer.ItemSoundFileVolumeSmoothingSet (Player_1, nUniqueIdFile1, 2000, 3000);

Amp3dj1.SoundComposer.ItemSoundFileVolumeSmoothingSet (Player_1, nUniqueIdFile2, 2000, 3000);

// start playback of the final audio stream

Amp3dj1.PlaySound (Player_1);

Now let's see another small code snippet where we create a session having again a stereo audio stream; on this stream we will perform the following actions:

· add a sound file (myfile1.mp3) to the session
· append a new sound file (myfile2.mp3) to the previous file (myfile1.mp3) by separating them with 2 seconds of silence

Visual Basic.NET

' create the audio stream on a specific player (44100, stereo)

Amp3dj1.SoundComposer.SessionCreate (Player_1, 44100, 2)

Dim nUniqueIdFile1 As Int32 = 0

Dim nUniqueIdFile2 As Int32 = 0

' add the first sound files

Amp3dj1.SoundComposer.ItemSoundFileAdd (Player_1, "First sound", 0, _

                 "c:\myfolder\myfile1.mp3", False, 0, 0, -1, nUniqueIdFile1)

' predispose the next item to be appended and leave 2 seconds of silence in between

Amp3dj1.SoundComposer.ItemAppendNext (Player_1, nUniqueIdFile1l, 2000)

' append the second item to the previous one

Amp3dj1.SoundComposer.ItemSoundFileAdd (Player_1, "Second sound", 0, _

                 "c:\myfolder\myfile2.wma", False, 0, 0, -1, nUniqueIdFile2)

' start playback of the final audio stream

Amp3dj1.PlaySound (Player_1)

Visual C#

// create the audio stream on a specific player (44100, stereo)

Amp3dj1.SoundComposer.SessionCreate (Player_1, 44100, 2);

// add the two sound files and obtain respective unique identifiers

Int32 nUniqueIdFile1 = 0;

Int32 nUniqueIdFile2 = 0;

Amp3dj1.SoundComposer.ItemSoundFileAdd (Player_1, "First sound", 0,

                 @"c:\myfolder\myfile1.mp3", false, 0, 0, -1, ref nUniqueIdFile1);

// predispose the next item to be appended and leave 2 seconds of silence in between

Amp3dj1.SoundComposer.ItemAppendNext (Player_1, nUniqueIdFile1, 2000);

// append the second item to the previous one

Amp3dj1.SoundComposer.ItemSoundFileAdd (Player_1, "Second sound", 0,

                 @"c:\myfolder\myfile2.wma", false, 0, 0, -1, ref nUniqueIdFile2);

// start playback of the final audio stream

Amp3dj1.PlaySound (Player_1);

Adding audio generated from Microsoft Speech API

Text to speech is the artificial production of human speech and is obtained by leveraging the Microsoft's Speech API installed on Windows systems. Text is converted into an audio stream containing spoken voice through the usage of voices installed inside the system: you can enumerate installed voices through the combination of the SoundGenerator.SpeechVoicesNumGet and SoundGenerator.SpeechVoiceAttributeGet methods; the sound composer can generate audio streams starting from a string of text, through the SoundComposer.ItemSpeechFromStringAdd method, or from a file containing text, through the SoundComposer.ItemSpeechFromFileAdd method; in both cases the provided text may eventually contain XML markups: see the MSDN documentation for a tutorial about XML markup syntax.

Once the text to speech has been added to the session, you can modify some of its settings through the following set of methods:

- SoundComposer.ItemSpeechFileSet to modify the file containing the string of the text to speech (only if the item was added through the SoundComposer.ItemSpeechFromFileAdd method)

- SoundComposer.ItemSpeechStringSet to modify the string of the text to speech (only if the item was added through the SoundComposer.ItemSpeechFromStringAdd method)

- SoundComposer.ItemContentGet to obtain the current string of text to speech or the pathname of the file containing the text to speech

- SoundComposer.ItemSpeechVoiceGet to obtain the speaking voice

- SoundComposer.ItemSpeechVoiceSet to modify the speaking voice

In case you should need to add a new speech item at the exact end of an existing item, which could be a sound file or another speech item, you may append the new item by invoking the SoundComposer.ItemAppendNext method immediately before invoking the SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd methods.

The SoundComposer.ItemAppendNext method receives the unique identifier of the already existing item allowing the next call to the SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd methods to calculate the exact offset to place the new item inside the audio stream.

When the SoundComposer.ItemAppendNext method is invoked successfully, the speech item or sound file will be appended to the given existing item on the same audio channel of the sound composer and with the same "downmix to mono" setting. After the new item has been appended, the "append mode" is automatically reset.

Let's see a small code snippet where we create a session having a stereo audio stream; on this stream we will add two mono streams, one for each channel, containing speech generated from a string of text (in order to keep the code simpler we have used a unique identifier variable for each item, in a real situation you may want to use separate unique identifier variables for each item):

Visual Basic.NET

' create the audio stream on a specific player (44100, stereo)

Amp3dj1.SoundComposer.SessionCreate (Player_1, 44100, 2)

Dim nDummyUniqueId As Int32 = 0

Dim nChannel As Integer = 0

' add the string of text on the two channels of the audio stream (channel 0 and 1)

Amp3dj1.SoundComposer.ItemSpeechFromStringAdd (Player_1, "", nChannel, _

                 "This is a string of text to speech", 0, True, 1, 0, nDummyUniqueId)

Amp3dj1.SoundComposer.ItemSpeechFromStringAdd (Player_1, "", nChannel+1, _

                 "This is a string of text to speech", 0, True, 1, 0, nDummyUniqueId)

' start playback of the final audio stream

Amp3dj1.PlaySound (Player_1)

Visual C#

// create the audio stream on a specific player (44100, stereo)

Amp3dj1.SoundComposer.SessionCreate (Player_1, 44100, 2);

Int32 nDummyUniqueId = 0;

int nChannel = 0;

// add the string of text on the two channels of the audio stream (channel 0 and 1)

Amp3dj1.SoundComposer.ItemSpeechFromStringAdd (Player_1, "", nChannel,

                 "This is a string of text to speech", 0, True, 1, 0, ref nDummyUniqueId);

Amp3dj1.SoundComposer.ItemSpeechFromStringAdd (Player_1, "", nChannel+1,

                 "This is a string of text to speech", 0, True, 1, 0, ref nDummyUniqueId);

// start playback of the final audio stream

Amp3dj1.PlaySound (Player_1);

A sample of usage of the sound composer object in Visual Basic 6 can be found inside the following sample installed with the product's setup package:

- SoundComposer


How to manage ZIP files

How to manage ZIP files

ZIP is an archive file format that supports lossless data compression. A ".ZIP" file may contain one or more files or directories that may have been compressed. Audio Sound Recorder API for .NET comes with embedded support for this format and, apart from being able to manage general compression and decompression of files, allows storing recording sessions inside ZIP files that may be optionally protected with AES encryption.

ZIP files can be managed through the ZIP COM object accessible through the ZIP property; existing ZIP files can be opened with the ZIP.Open method: this method allows specifying a password that could be used for accessing entries protected through the legacy ZIP 2.0 encryption or through the latest AES encryption: you can know if a ZIP file is protected through the ZIP.IsProtected method.

You may also create a brand new ZIP file from scratch using the ZIP.Create method: also in this case you would have the option to protect your new ZIP file through encryption.

Once opened or created, existing entries of the ZIP file can be enumerated through the combination of the ZIP.EntriesCountGet and ZIP.EntryNameGet methods and extracted on the local disk through the ZIP.EntryExtractToFile method or inside a memory buffer through the ZIP.EntryExtractToMemory method: in this latest case, you can know how much room is needed for allocating the buffer through the ZIP.EntryUncompressedSizeGet method. It's important to note that, in order to load a sound file contained inside the ZIP file, the component doesn't need to extract it: the LoadSoundFromZip, LoadSoundFastFromZip and LoadSoundSyncFromZip methods can extract and automatically load the sound file from the ZIP file into a given player.

New entries can be added by storing local disk files through the ZIP.EntryAdd method or by storing contents of a memory buffer through the ZIP.EntryAddFromMemory method.

During lengthy operations for both compression and decompression, the container application is notified through the ZipOperationStart event followed by a number of ZipOperationPerc events and finally by the ZipOperationDone event.

Existing entries can be removed through the ZIP.EntryRemove method.

Once ZIP management is completed, you can save your modifications through the ZIP.Save method and close the ZIP management session through the ZIP.Close method.

Samples of use of the ZIP object in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- ZipPlayer


How to use Mnemonic Constants

How to use Mnemonic Constants

The use of Mnemonic Constants improves the readability of your code. This version of the control implements a new internal design to expose these public enumerated types. You will see them in the drop downs on property sheets and in Microsoft's Intellisense feature.

The only environment where this is not the case is Microsoft Visual C++ environment (due to the manner in which the environment communicates with the control).

The following is the full list of enumerated types with their associated properties:

Enumerated type | Corresponding properties or parameters
enumErrorCodes | LastError
enumDriverTypes | nDriverType parameter of the InitDriversType method
enumStates | return value of GetPlayerStatus method
enumTagVersions | return value of GetMp3TagVersion method
enumScaleUnits | ScaleUnits
enumFileTypes | return value of GetFileType method and nFormat parameter of the LoadInternetStreamWithFormat method
enumGranulType | ForwRewGranularityType property
enumTagTypes | nTagType parameter of the IsTagAvailable and GetTagString methods
enumTagFields | nField parameter of the GetFileTagField method
enumPlayListModes | nMode parameter of the PlayListLoad method
enumPlayListFormats | nFormat parameter of the PlayListSave method
enumPlayListFieldsForDj | nString parameter of the PlayListGetItemString method
enumBoolean | Several methods use this boolean value.
enumOscillType | Oscilloscope.Type
enumVuBandsMode | VUMeter.BandType
enumWaveformUpdateRes | Waveform.UpdateResolution
enumFadeOutModes | Fader.FadeOutMode
enumFadeTypes | nFadeType parameter of the Fader.Init method
enumCdActions | nAction parameter of the PerformActionOnCd method
enumCdStates | Return value of GetCdStatus method and nCdStatus parameter of the CdPlayerStatusChanged event
enumCdIdCodes | nIdentType parameter of the GetCdIdentification method
enumVolumeScales | nScaleType parameter of the StreamVolumeLevelGet, StreamVolumeLevelSet, PlayListSaveAutomation, ASIO.DeviceChannelVolumeGet, ASIO.DeviceChannelVolumeSet, ASIO.DeviceMasterVolumeGet, ASIO.DeviceMasterVolumeSet, PlayListItemVolAutomPointAdd, Fader.FadeInTargetVolumeGet, Fader.FadeInTargetVolumeSet, CoreAudioDevices.ChannelVolumeGet, CoreAudioDevices.ChannelVolumeSet, CoreAudioDevices.MasterVolumeGet, CoreAudioDevices.MasterVolumeSet methods. VolumeAutomation.ScaleType property.
enumDirectXEffects | Effects.DirectXEffectApply, Effects.DirectXEffectIsApplied, Effects.DirectXEffectParamsSet and Effects.DirectXEffectParamsGet methods
enumEaxEffects | GetEaxEffect, SetEaxEffect and SetEaxEffectPresets methods
enumEventStreaming | nState parameter of DownloadBuffering event
enumEventLoadStreamResults | nResult parameter of StreamLoaded event
enumWaveformResolutions | nResolution parameter of the Waveform.AnalyzeFullSound method
enumWaveformTypes | nWaveformType parameter of the Waveform.BitmapViewSaveToFile and Waveform.BitmapViewSaveToMemory methods
enumSpeakersConfig | GetOutputSpeakersConfig and SetOutputSpeakersConfig methods
enumSpeakers | nSpeaker parameter of the StreamOutputSpeakerSet, Effects.PreAmplifierSpeakerValueGet and Effects.PreAmplifierSpeakerValueSet methods, return value of the StreamOutputSpeakerGet and method
enumCddbAlbumInfo | nInfo parameter of the CddbGetAlbumInfo method
enumCdCoverSizes | nCoverSize parameter of the GetCdCoverPictureURL, GetCdCoverPictureFile and AmazonStoreCdCoverPictureFileGet methods and of the CdCoverPictureFileAvailable event
enumPlayListItemType | nItemType parameter of the PlayListAddItemEx method
enumDspExternalFunctions | nFunctionType parameter of the CustomDSP.ExternalSetFunction method
enumVstInfo | nInfo parameter of the VST.GetInfoString method
enumVstParamInfo | nInfo parameter of the VST.ProgramParamGetInfo method
enumEqualizerPresets | nPreset parameter of the EqualizerLoadPresets method
enumGraphicBarOrientations | nOrientation member of the GRAPHIC_BAR_SETTINGS data structure
enumGraphicBarShapes | nShape member of the GRAPHIC_BAR_SETTINGS data structure
enumSoundDirections | Return value of the SoundDirectionGet method and nDirection parameter of the SoundDirectionSet method
enumRAWEncodeModes | nEncodeMode parameter of the LoadSoundFromRawFile, LoadSoundFromRawMemory, MediaFileDecoder.FileInfoGet, MediaFileDecoder.FileOpenRaw, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd, SoundComposer.ItemSoundFileRawInfoGet methods
enumLrcFileIdTags | nTagType parameter of the LrcIdTagGet method
enumEncodingFormats | nEncodeFormat parameter of the CastingCreateFromStreamMixer and CastingCreateFromPlayer methods
enumCastEncodeModes | nEncodeMode parameter of the CastingCreateFromStreamMixer and CastingCreateFromPlayer methods
enumAudioRendererModes | nMode parameter of the VideoPlayer.AudioRendererModeSet method and return value of theVideoPlayer.AudioRendererModeGet method.
enumMemoryMediaFormats | nMediaFormat parameter of the VideoPlayer.LoadFromMemory, VideoPlayer.LoadFromMemoryForEAX, VideoPlayer.LoadFromMemoryForTempoChange, VideoPlayer.LoadFromMemorySync, VideoPlayer.LoadFromMemorySyncForEAX and VideoPlayer.LoadFromMemorySyncForTempoChange methods.
enumTextAlignment | nAlignment parameter of the VideoMixer.OSDItemTextAdd and VideoMixer.OSDItemTextChange methods
enumRectAlignment | nAlignment parameter of the VideoMixer.OSDItemChangeAlignment method
enumDriverTypes | nDriverType parameter of the InitDriversType method and return value of the GetOutputDeviceDriverType method
enumAsioChannelModes | nChannelMode parameter of the ASIO.DeviceStart method
enumVolumeAutomationPosUnits | nPosUnit parameter of the PlayListSaveAutomation method, nPositionUnit parameter of the PlayListItemVolAutomPointAdd and PlayListItemCuePointAdd methods. VolumeAutomation.PositionUnit property
enumVolumeCurves | nCurveType parameter of the PlayListItemVolAutomPointAdd, VolumeAutomation.PointAdd, VolumeAutomation.PointGetParams, VolumeAutomation.PointSetParams, VolumeAutomation.PointAdd, VolumeAutomation.CurveDesigner.DisplayCurveType, StreamVolumeSlide, StreamVolumeSlideEx, StreamVolumeSmoothingSet and StreamVolumeSmoothingSetEx methods
enumWavChunkStringInfo | nInfoField parameter of the GetWavChunkStringInfo method
enumWavChunkNumericInfo | nInfoField parameter of the GetWavChunkNumericInfo method
enumWavChunkBinaryInfo | nInfoField parameter of the GetWavChunkBinaryInfo method
enumFilterNames | nFilterName parameter of the FilterApply method
enumFilterTypes | nFilterType parameter of the FilterApply method
enumCommonDialogInfo | nInfo parameter of the CommonDialogGetInfoFromLastOpen and CommonDialogGetInfoFromLastSave methods.
enumGraphicFormats | nFormat parameter of the Waveform.BitmapViewSaveToFile and VideoPlayer.FrameGrabberExecToFile methods
enumWaveformStereoModes | nWaveformStereoMode parameter of the Waveform.BitmapViewDrawToHdc method
enumWaveformLineModes | nMode parameter of the Waveform.BitmapViewVerticalLineAdd method
enumMp3BitrateTypes | Return value of the GetMp3BitrateType method
enumVideoGrabberStopTypes | nStopType parameter of the VideoPlayer.FrameGrabberExecToFile and VideoPlayer.FrameGrabberExecToMemory methods
enumFramesSet | Return value of the VideoPlayer.FrameGrabberResultsGetAvailableType method
enumTagAvailable | Return value of TagsEditor.ALL_AnalyzeSoundOnPlayer and TagsEditor.ALL_AnalyzeSoundFile methods
enumTagFields | nField parameter of the TagsEditor.ALL_CommonFrameGet, TagsEditor.ID3V1_FieldGet, TagsEditor.APE_TextFieldGet, TagsEditor.LYRICS3_TextFieldGet methods
enumMp4Frames | nFrameId parameter of the TagsEditor.MP4_TextFrameGet method
enumOggFrames | nFrameId parameter of the TagsEditor.OGG_TextFrameGet method
enumId3v2FrameInfo | nInfo parameter of the TagsEditor.ID3V2_PictureFrameInfoGet, TagsEditor.ID3V2_CommentFrameInfoGet, TagsEditor.ID3V2_SynchLyricsFrameInfoGet, TagsEditor.ID3V2_GeneralObjectFrameInfoGet, TagsEditor.ID3V2_UnsynchLyricsFrameInfoGet, TagsEditor.FLAC_PictureFrameInfoGet, TagsEditor.WMA_PictureFrameInfoGet methods
enumId3v2PictureType | nPictureType parameter of the TagsEditor.ID3V2_PictureFrameTypeGet, TagsEditor.WMA_PictureFrameTypeGet, TagsEditor.FLAC_PictureFrameTypeGet methods
enumId3v2ReceivedAsType | nReceivedAs parameter of the TagsEditor.ID3V2_CommercialFrameReceivedAsGet method
enumId3v2CommercialInfo | nInfo parameter of the TagsEditor.ID3V2_CommercialFrameInfoGet method
enumId3v2SyncLyricsType | nLyricsType parameter of the TagsEditor.ID3V2_SynchLyricsFrameInfoNumGet method
enumId3v2TimeStampFormats | nTimeStampFormat parameter of the TagsEditor.ID3V2_SynchLyricsFrameInfoNumGet, TagsEditor.ID3V2_EventTimingsFrameEventCountGet methods
enumId3v2OwnershipInfo | nInfo parameter of the TagsEditor.ID3V2_OwnershipFrameInfoGet method
enumId3v2EventTimingTypes | nEventTimingType parameter of the TagsEditor.ID3V2_EventTimingsFrameEventInfoGet method
enumBextChunkField | nFieldId parameter of the TagsEditor.WAV_BextChunkTextFieldGet method
enumBextChunkBinaryField | nFieldId parameter of the TagsEditor.WAV_BextChunkBinaryFieldGet method
enumCartChunkTextField | nFieldId parameter of the TagsEditor.WAV_CartChunkTextFieldGet method
enumCartChunkTimeMarkerField | nFieldId parameter of the TagsEditor.WAV_CartChunkTimeMarkerFieldGet method
enumCoreAudioDeviceStates | nStateMask parameter of the CoreAudioDevices.Enum method
enumCoreAudioDataFlows | nDataFlow parameter of most methods of the CoreAudioDevices COM object
enumCoreAudioDeviceNames | nTypeOfName parameter of the CoreAudioDevices.DescGet method
enumCoreAudioRoles | nRole parameter of the CoreAudioDevices.DefaultGet method
enumCoreAudioDeviceStates | nStatus parameter of the CoreAudioDevices.StatusGet method
enumCoreAudioCaptureParts | nPartId parameter of the CoreAudioDevices.CapturePartChannelCountGet, CoreAudioDevices.CapturePartChannelVolumeGet and CoreAudioDevices.CapturePartChannelVolumeSet methods
enumCoreAudioRenderParts | nPartId parameter of the CoreAudioDevices.RenderPartChannelCountGet, CoreAudioDevices.RenderPartChannelVolumeGet. CoreAudioDevices.RenderPartChannelVolumeSet, CoreAudioDevices.RenderPartMuteGet and CoreAudioDevices.RenderPartMuteSet methods
enumAmazonStoreInfo | nInfo parameter of the AmazonStoreCdInfoGet method
enumMidiPositionUnits | nPositionUnit parameter of the MIDI.SeekToPosition, MIDI:MarkersEnumItemGet, MIDI.StreamEventsEnumFromRange, MIDI.StreamEventsEnumItemGet, MIDI.TriggerAdd, MIDI.TriggerSetPos methods.
enumMidiMarkerNotifications | nMarkerType parameter of the MidiMarkerNotification event and of the MIDI.MarkersEnableNotifications, MIDI.MarkersEnum and MIDI:MarkersEnumItemGet methods.
enumStreamMidiEvents | nMidiEvent parameter of the MidiStreamEventNotification event and of the MIDI.StreamEventApply, MIDI:StreamEventValueGet, MIDI.StreamEventsEnableNotifications, MIDI.StreamEventsEnum, MIDI.StreamEventsEnumFromRange, MIDI:StreamEventsEnumItemGet, MIDI.StreamEventsListItemAdd, MIDI.StreamEventsListItemModify, MIDI.StreamEventsListItemGet methods.
enumMidiKeyboardOrientations | nOrientation parameter of the MIDI.KeyboardCreate method
enumMidiSoundFontStringInfo | nInfo parameter of the MIDI.SoundFontInfoStringGet method
enumMidiSoundFontNumInfo | nInfo parameter of the MIDI.SoundFontInfoNumGet method
enumVstType | nType parameter of the VST.GetType method
enumWasapiDeviceTypes | nDeviceType parameter of the WASAPI.AttachInputDeviceToPlayer, WASAPI.DeviceCoreAudioIndexGet, WASAPI.DeviceGetCount, WASAPI.DeviceGetDesc, WASAPI.DeviceIsFormatSupported, WASAPI.DeviceIsStarted, WASAPI.DeviceLatencyGet, WASAPI.DeviceMuteGet, WASAPI.DeviceMuteSet, WASAPI.DeviceSharedFormatGet, WASAPI.DeviceStartExcusive, WASAPI.DeviceStartShared, WASAPI.DeviceStop, WASAPI.DeviceVolumeGet, WASAPI.DeviceVolumeSet methods
enumWasapiChannelModes | nChannelMode parameter of the WASAPI.DeviceStartShared method
enumCoreAudioDeviceTypes | nDeviceType parameter of the CoreAudioDevices.TypeGet method
enumOSDAutoMoveDirection | nDirection parameter of the VideoMixer.OSDItemMovementSet method
enumWaveformStereoModes | nStereoVisualizationMode parameter of the WSCROLLER_SETTINGS structure
enumWaveScrollerAutoUpdate | nUpdateSpeed parameter of the WSCROLLER_SETTINGS structure
enumBitmapModes | nMode parameter of the WaveformScroller.SetBackPictureFromFile and WaveformScroller.SetBackPictureFromHandle methods
enumVideoImageAdjustProps | nProperty parameter of the VideoPlayer.ImageAdjustPropertyGet, VideoPlayer.ImageAdjustPropertySet and VideoPlayer.ImageAdjustPropertyRangeGet methods
enumGraphicItemMaskValues | nGraphicItemsMask field of the WSCROLLER_SETTINGS data structure
enumWaveformLineDashStyles | nPositionLineDashStyle field of the WSCROLLER_SETTINGS data structure
enumLineCaps | nPositionLineHighCap and nPositionLineLowCap fields of the WSCROLLER_SETTINGS data structure
enumLineDashCaps | nPositionLineDashCap field of the WSCROLLER_SETTINGS data structure
enumBassModules | nModule parameter of the BassModuleGet method
enumBassPluginStreamCreateFuncs | nType parameter of the BassPluginStreamCreateFunc method
enumComponentTypes | nComponentType parameter of the MixerVolumeSet, MixerVolumeGet, MixerMuteSet and MixerMuteGet methods
enumInternetSetting | nSetting parameter of the InternetSettingsGet and InternetSettingsSet methods
enumMediaTypes | nMediaType parameter of the Downloader.SessionStartToPlayer method
enumDataTypes | nDataType parameter of the MediaFileDecoder.FileDataGet method
enumDecodePositionUnit | nPositionUnit parameter of the MediaFileDecoder.FilePositionGet and MediaFileDecoder.FilePositionSet methods
enumPlayerEvents | nEvent parameter of the CallbackForPlayersEventsSet method
enumCdDrivesEvents | nEvent parameter of the CallbackForCdDrivesEventsSet method
enumCoreAudioEvents | nEvent parameter of the CallbackForCoreAudioEventsSet method
enumSapiVoiceAttributes | nAttribute parameter of the SoundGenerator.SpeechVoiceAttributeGet method
enumSoundGenWaveTypes | nWaveType parameter of the SoundGenerator.StreamCreateTone, SoundGenerator.StreamChannelAddTone and SoundGenerator.StreamElementToneTypeGet methods
enumSoundGenNoiseTypes | nNoiseType parameter of the SoundGenerator.StreamCreateNoise, SoundGenerator.StreamChannelAddNoise and SoundGenerator.StreamElementToneNoiseGet methods
enumSoundGenSlidingWaveTypes | nWaveType parameter of the SoundGenerator.StreamCreateSlidingTone, SoundGenerator.StreamChannelAddSlidingTone and SoundGenerator.StreamElementSlidingToneTypeGet methods
enumSoundGeneratorTypes | nType parameter of the SoundGenerator.StreamElementTypeGet method
enumSpectrumEnhTypes | nGraphType field of the SPECTR_ENH_GENERAL_SETTINGS data structure
enumSpectrumEnhWindowTypes | nFFTWindowType field of the SPECTR_ENH_GENERAL_SETTINGS data structure
enumZipEncryptionTypes | nEncryptionType parameter of the ZIP.Create method
enumPlayerSoundComposerTypes | nType parameter of the SoundComposer.ItemTypeGet method

The following examples, under different development environments, show how to use Mnemonic Constants in your code. These examples assume that one instance of the control, named MyPlayer, exists on a form or dialog box. The purpose of this sample code is to check if a certain player is in paused state.

Microsoft Visual C++ (4.0, 5.0, 6.0 and .NET)

Microsoft Visual Basic 5 and 6

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual C++ (4.0, 5.0, 6.0 and .NET)

Because of the different behaviour of these environments, you need to include the module AdjMmsEngDef.h in order to use predefined Mnemonic Constants: This module can be found inside the product Include directory (default C:\Program Files\Active DJ Studio\include).

You can test a certain player (0 in this sample) for the "paused" state using the following line of code:

if (MyControl.GetPlayerStatus (0) == SOUND_PAUSED)

 // do something

 .....

else

 // do something else

 .....

The GetPlayerStatus method is defined by the control wrapper class CAmp3dj contained inside the amp3dj.cpp and amp3dj.h files: these wrapper files are automatically generated when you insert the control inside your project. So, in order to access this function, you will have to insert the following line of code somewhere in your code.

#include "amp3dj.h"

The mnemonic constant SOUND_PAUSED can be found inside the AdjMmsEngDef.h module file. So, in order to access this value, you will have to insert the following line of code somewhere in your code.

#include "AdjMmsEngDef.h"

Microsoft Visual Basic 5 and 6

In this environment you can use that IntelliSense features that make it easy to assign the intended value to the method parameter.

After typing the code...

If MyControl.GetPlayerStatus (0)

press the "=" key on your keyboard. IntelliSense displays the listbox of the possible values that can used to check the player status:

Select the SOUND_PAUSED value to complete the line of code as follows:

If MyControl.GetPlayerStatus (0) = SOUND_PAUSED Then

 ' do something

 .....

Else

 ' do something else

 .....

End If

Microsoft Visual Basic.NET

In this environment it is also easy to use that IntelliSense features that make it easy to assign the intended value to the method parameter.

After typing the code...

If MyControl.GetPlayerStatus (0)

press the "=" key on your keyboard. IntelliSense displays the listbox of the possible values that can be assigned to the method parameter.

Select the AMP3DJLib.enumStates.SOUND_PAUSED value so the complete line of code will be:

If MyControl.GetPlayerStatus(0) = AMP3DJLib.enumStates.SOUND_PAUSED Then

   ' do something

Else

   ' do something else

End If

Microsoft Visual C#.NET

This environment requires a couple of additional lines of code to make use of Intellisense. First, the following code must be inserted at the beginning of the form management file:

using AMP3DJLib;

After typing the code...

if (MyControl.GetPlayerStatus (0) == enumStates

press the "." key on your keyboard. Note that to use Intellisense, you must add enumStates after the equal sign in order to trigger the enumStates enumerated type. After typing a period, Intellisense is activated.

if (MyControl.GetPlayerStatus (0) == enumStates.

Select the SOUND_PAUSED value so the complete line of code will be:

if (MyControl.GetPlayerStatus (0) == enumStates.SOUND_PAUSED)

   // do something

   ....

else

   // do something else

   ....


ASIO property (RO)

ASIO property (RO)

 Return to chapter overview
Type | CASIO for Visual C++ AMP3DJLib.ASIO for Visual Basic This property is Read-only
Syntax | object.ASIO [=AMP3DJLib.ASIO]
Remarks | The object used to manage ASIO drivers This property encapsulates the functionality of the ASIO object and the IASIO COM interface. Further information about the use of ASIO drivers can be found inside the How to manage ASIO drivers tutorial.


BufferLength property

BufferLength property

Type

integer for Visual Basic

short for Visual C++

Remarks

The size, expressed in milliseconds, of the DirectSound buffer used for song playback.

The supported range for this property, whose default value is 500, is between 100 and 5000: higher or lower values will be automatically cut to the nearest supported value.

Decreasing the size of the DirectSound buffer will result in a smaller latency time: for details about latency, take a look to the How to deal with latency section.


BufferUpdateTime property

BufferUpdateTime property

Type

integer for Visual Basic

short for Visual C++

Remarks

The update time, expressed in milliseconds, of the DirectSound buffer used for song playback.

The supported range for this property, whose default value is 100, is between 5 and 100: higher or lower values will be automatically cut to the nearest supported value.

Decreasing the update time allows using a smaller DirectSound buffer set through the BufferLength property and also allows a better granularity in managing MIDI events but, obviously, will require a bit more CPU.


CheckOutputDevicesLatency property

CheckOutputDevicesLatency property

Type

Boolean for Visual Basic

BOOL for Visual C++

Remarks

Boolean value that determines if the control will have to perform a calculation of the sound card drivers latency time. For details about latency, take a look to the How to deal with latency section.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
FALSE (default) | 0 | The sound card drivers latency time won't be calculated
TRUE | 1 | The sound card drivers latency time will be calculated: this will require the InitDJSystem method a longer time to execute.

NOTE: This property can be set at Design-time only: changes made at Runtime will be simply ignored.


CoreAudioDevices property (RO)

CoreAudioDevices property (RO)

 Return to chapter overview

Type

CCoreAudioDevices for Visual C++

AMP3DJLib.CoreAudio for Visual Basic

This property is Read-only

Syntax

object.CoreAudioDevices [=AMP3DJLib.CoreAudioDevices]

Remarks

The object used to manage specific functionalities of audio devices inside Windows Vista and later versions.

This property encapsulates the functionality of the CoreAudioDevices object and the ICoreAudioDevices COM interface.

Further information about the management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.


CustomDSP property (RO)

CustomDSP property (RO)

Return to chapter overview
Type | CCustomDSP for Visual C++ AMP3DJLib.CustomDSP for Visual Basic This property is Read-only
Syntax | object.CustomDSP [=AMP3DJLib.CustomDSP]
Remarks | The object used to manage custom DSPs. This property encapsulates the functionality of the CustomDSP object and the ICustomDSP COM interface. Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.


DelayedPlayback property (RO)

DelayedPlayback property (RO)

Return to chapter overview

Type

CDelayedPlayback for Visual C++

AMP3DJLib.DelayedPlayback for Visual Basic

This property is Read-only

Syntax

object.DelayedPlayback [=AMP3DJLib.DelayedPlayback]

Remarks

The object used for managing delayed playbacks.

This property encapsulates the functionality of the DelayedPlayback object and the IDelayedPlayback COM interface.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.


Downloader property (RO)

Downloader property (RO)

Return to chapter overview

Type

CDownloader for Visual C++

AMP3DJLib.Downloader for Visual Basic

This property is Read-only

Syntax

object.Downloader [=AMP3DJLib.Downloader]

Remarks

The object used for managing download sessions.

This property encapsulates the functionality of the Downloader object and the IDownloaderDj COM interface.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.


Effects property (RO)

Effects property (RO)

 Return to chapter overview
Type | CEffectsDj for Visual C++ AMP3DJLib.Effects for Visual Basic This property is Read-only
Syntax | object.Effects [=AMP3DJLib.Effects]
Remarks | The object used to manage special effects to apply to loaded sounds. This property encapsulates the functionality of the Effects object and the IEffectsDj COM interface. See the How to apply special effects to a playing sound section for further details.


EnableAutoEqualiz property

EnableAutoEqualiz property

Type

Boolean for Visual Basic

BOOL for Visual C++

Remarks

Boolean value that enables/disables automatic equalization of loaded sounds.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
FALSE (default) | 0 | Automatic equalization is disabled
TRUE | 1 | Automatic equalization is enabled

Automatic equalization can be obtained by adding a .EDJ sound inside the same folder containing the loaded sound: if for example the loaded file should be named MySong.mp3, the corresponding EDJ file should be named MySong.mp3.edj: when the control will find this specific file inside the same folder of the loaded sound it will automatically create and apply the requested bands of the equalizer.

For further details about defining the equalizer settings and about the EDJ format refer to the How to create and use an Equalizer section.


EnableMixingFeatures property

EnableMixingFeatures property

Type

Boolean for Visual Basic

BOOL for Visual C++

Remarks

Boolean value that enables/disables applying mixing related settings to loaded sounds.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
FALSE | 0 | Mixing related settings are disabled allowing a faster loading of the sound. In this situation it won't be possible calling the following methods and features: Effects.PlaybackTempoSet, Effects.PlaybackRateSet and Effects.PlaybackPitchSet, BPM detection, beats position detection, equalizers, DMO effects, EAX effects, VST effects, custom DSP effects and silence detection will be unavailable also.
TRUE (default) | 1 | Mixing related settings are enabled


EnableSpeakers property

EnableSpeakers property

Type

Boolean for Visual Basic

BOOL for Visual C++

Remarks

Boolean value that enables/disables speakers assignment.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
FALSE (default) | 0 | Speakers assignment disabled
TRUE | 1 | Speakers assignment enabled

NOTE 1: This property can be set at Design-time only: changes made at Runtime will be simply ignored.

NOTE 2: This property has no effect under Windows Vista and newer versions where speakers management can be only enabled/disabled through the Windows Control Panel.

For further details about speakers management, take a look to the How to work with multiple output devices and speakers section.


Fader property (RO)

Fader property (RO)

Return to chapter overview
Type | CFader for Visual C++ AMP3DJLib.Fader for Visual Basic This property is Read-only
Syntax | object.Fader [=AMP3DJLib.Fader]
Remarks | The embedded Automatic Fader object. This property encapsulates the functionality of the Fader object and the IFader COM interface. For details about using the Automatic Fader refer to the How to use the Automatic Fader section


GraphicBarsManager property (RO)

GraphicBarsManager property (RO)

Return to chapter overview

Type

CGraphicBarsManager for Visual C++

AMP3DJLib.GraphicBarsManager for Visual Basic

This property is Read-only

Syntax

object.GraphicBarsManager [=AMP3DJLib.GraphicBarsManager]

Remarks

The Graphic Bars Manager object is used to create custom graphic bars like VU-Meter bars, Spectrum bars and Progress bars.

This property encapsulates the functionality of the GraphicBarsManager object and the IGraphicBarsManager COM interface.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.


LastError property (RO)

LastError property (RO)

Return to chapter overview

Type

enumErrorCodes for Visual Basic

long for Visual C++

This property is Read-only

Remarks

Each call to one of the control's methods could generate an error: in case the called method should return an unexpected value, this property could give more details about the error nature. In case the called method should success, this property would assume the value NOERROR (0).

Here follows a list of the available error codes that could be returned by the component's methods calls (note that the table below refers to our internal multimedia engine so many of the available codes could be not directly related to Active DJ Studio):

Mnemonic value | Numeric value | Meaning
ERR_NOERROR | 0 | No error was generated by the latest method call
ERR_INVALID_PLAYER | -1 | Invalid player
ERR_NOT_ENOUGH_MEMORY | -2 | Not enough memory
ERR_VALUE_OUT_OF_RANGE | -3 | The value of one of the parameters passed to the method was out of the available range of values
ERR_INVALID_WINDOW | -4 | The provided HWND handle doesn't belong to a valid window
ERR_INVALID_DS_CARD | -5 | The sound card chosen as the output device is not a compatible sound card
ERR_INVALID_FILE | -6 | Invalid sound file
ERR_INVALID_PLAYLIST_FILE | -7 | Invalid playlist file
ERR_CANNOT_CREATE_FILE | -8 | A file creation failed (probably attempting to save a playlist file)
ERR_INVALID_SOURCE_POS | -9 | The source position of a playlist item is invalid (out of range)
ERR_INVALID_DEST_POS | -10 | The destination position of a playlist item is invalid (out of range)
ERR_INVALID_MIXER | -11 | The selected mixer index is out of range
ERR_FX_EFFECT_UNAVAILABLE | -12 | The selected special effect is not available (probably the passed value was out of range)
ERR_BUFFERING | -13 | Error during Internet stream buffering
ERR_ALREADY_INITIALIZED | -14 | The control has already been initialized
ERR_INTERNET_UNAVAILABLE | -15 | No Internet connection cannot be established
ERR_TIMEOUT | -16 | Connection timeout
ERR_EAX_UNAVAILABLE | -17 | The EAX effects are not available on the current sound card
ERR_DMOFX_UNAVAILABLE | -18 | DirectX effects not available
ERR_DIRECTX_OLDER | -19 | The DirectX version is older than version 8
ERR_SOUND_NOT_LOADED | -20 | The last operation failed because no sound was loaded
ERR_INVALID_FORMAT | -21 | The last operation failed because not available for the loaded file format
ERR_INVALID_DRIVER | -22 | The sound card chosen as the output device doesn't have a valid driver
ERR_CANNOT_LOAD_FOR_MIXING | -23 | The given song cannot be used for mixing purposes
ERR_NOT_LOADED_FOR_MIXING | -24 | Unsupported
ERR_CHANGING_TEMPO | -25 | The Tempo change failed
ERR_CHANGING_RATE | -26 | The Playback rate change failed
ERR_CHANGING_PITCH | -27 | The Pitch change failed
ERR_EQUALIZER_BAND_UNAVAILABLE | -28 | The given equalizer band is not available
ERR_FEEDBACK_ALREADY_AVAILABLE | -29 | The visual feedback you are trying to create already exists
ERR_FEEDBACK_NOT_CREATED | -30 | You are trying to use a visual feedback that still doesn't exists
ERR_CANNOT_FADE_ON_SAME_PLAYER | -31 | It's not possible to perform a fade-in/fade-out using a single player
ERR_FADER_NOT_READY | -32 | The fader is not ready: check the Fader.Init method for details
ERR_TRIGGER_ALREADY_EXISTS | -33 | A trigger with the given identification number already exists
ERR_TRIGGER_NOT_FOUND | -34 | The selected trigger doesn't exist
ERR_INVALID_CD_DRIVE | -35 | The specified CD drive is invalid
ERR_CD_DRIVE_NOT_READY | -36 | The specified CD drive is not ready
ERR_CD_INVALID_TRACK | -37 | The specified CD audio track is invalid
ERR_CD_INVALID_ACTION | -38 | The requested CD action is invalid
ERR_CD_INVALID_IDENTIF_CODE | -39 | The requested CD identification code is invalid
ERR_CD_IDENTIF_UNAVAIL | -40 | The requested CD identification is not available
ERR_CD_TRACK_NOAUDIO | -41 | The specified CD track is not an audio track
ERR_CD_DRIVE_BUSY | -42 | The specified CD drive is busy loading another audio track
ERR_CANNOT_FADE_PLAYER_A | -43 | Cannot fade on player A (probably because no playlist has been loaded)
ERR_CANNOT_FADE_PLAYER_B | -44 | Cannot fade on player B (probably because no playlist has been loaded)
ERR_CANNOT_FADE_SMALL_SONGS | -45 | Cannot use the given playlist for fading because all of the contained songs duration is shorter than the overall fading time
ERR_FADER_BOTH_PLAYING | -46 | Cannot fade two players that are already playing: at least one of them must be paused or stopped.
ERR_CANNOT_LOAD_FOR_FADING | -47 | Cannot fade songs whose duration is shorter than the overall fading time
ERR_INFO_UNAVAILABLE | -48 | The requested information is currently unavailable
ERR_NOT_INITIALIZED | -49 | The component is still not initialized
ERR_INVALID_INPUT_DEVICE | -50 | The input device is not valid
ERR_INVALID_INPUT_CHANNEL | -51 | The input channel is not valid
ERR_INVALID_RECORDER | -52 | Invalid recorder
ERR_INVALID_INPUT_FORMAT | -53 | The input format is not valid
ERR_OPENING_REC_SILENCE_LOGFILE | -54 | Error opening Sound Activation System silence log file
ERR_CD_COVER_URL_NOT_AVAILABLE | -55 | URL for CD cover picture not available
ERR_CD_COVER_FILE_NOT_AVAILABLE | -56 | CD cover picture file not available
ERR_CDDB_QUERY_FAILED | -57 | Query to CDDB server failed
ERR_CDDB_INFO_NOT_AVAIL | -58 | Information about CD not available on the CDDB server
ERR_CDDB_DATA_NOT_AVAIL | -59 | Information about CD not available locally
ERR_CDDB_SERVERS_NOT_AVAIL | -60 | CDDB server not available
ERR_CDDB_CONNECTION_FAILURE | -61 | Connection to CDDB server failed
ERR_CD_MCI_ERROR | -62 | MCI error accessing CD drive
ERR_INTERNET_NOT_CONNECTED | -63 | Internet connection not available
ERR_RECORDER_BUSY | -64 | The recorder is busy
ERR_SOUND_WAVEFORM_NOT_ANALYSED | -65 | Sound waveform still not analyzed
ERR_SPEAKERS_DISABLED | -66 | Speakers assignment disabled
ERR_SPEAKER_REAR_UNSUPPORTED | -67 | The current output device doesn't support Rear speakers
ERR_SPEAKER_CENTER_LFE_UNSUPPORTED | -68 | The current output device doesn't support Center speakers
ERR_SPEAKER_REAR_CENTER_UNSUPPORTED | -69 | The current output device doesn't support Rear Center speakers
ERR_SPEAKER_NEEDS_MONO | -70 | Cannot assign a stereo sound to a mono speaker
ERR_INVALID_SPEAKERS_CONFIG | -71 | The provided speakers configuration is invalid
ERR_SOUND_WAV_NOT_IN_MEMORY | -72 | The sound exported in memory in WAV format is not available
ERR_RECORDER_EMPTY | -73 | The recorder didn't performed any previous recording session in memory
ERR_REVERSED_SOUND_NOT_AVAIL | -74 | Reversed sound not available
ERR_INVALID_EQUALIZER_FILE | -75 | Invalid equalizer file
ERR_EQUALIZER_BAND_NOT_AVAIL | -76 | Equalizer band not available
ERR_ACM_CODEC_FORMAT_UNSUPPORTED | -77 | Unsupported ACM codec format
ERR_ACM_CODEC_CANCEL | -78 | The Cancel button was pressed after a selection of an ACM codec
ERR_WAV_DATA_NOT_ENOUGH_ROOM | -79 | Not enough room for containing WAV data
ERR_INVALID_POSITION | -80 | Invalid position
ERR_NO_SELECTION_AVAIL | -81 | No selection available
ERR_INVALID_EXPORT_SETTINGS | -82 | Invalid export settings
ERR_ENCODER_NOT_AVAILABLE | -83 | Encoder application not available inside the system or, in alternative, parameters passed to the encoder were invalid.
ERR_ENCODER_ERROR | -84 | Encoder failed to start
ERR_CANNOT_MIX_REMOTE_URL | -85 | Cannot mix sound coming from remote URL
ERR_FTP_CONNECTION_FAILED | -86 | FTP connection failed
ERR_FTP_DIRECTORY_NOT_FOUND | -87 | FTP remote directory not found
ERR_FTP_UPLOAD_FAILURE | -88 | FTP upload failure
ERR_FTP_UPLOAD_CANCELED | -89 | FTP upload canceled by the user
ERR_SOCKET_NOT_AVAILABLE | -90 | FTP upload impossible because the Windows sockets cannot be initialized
ERR_DSP_INVALID_DLL | -91 | This is not a valid DLL for custom DSP management
ERR_DSP_FUNCTION_NOT_AVAIL | -92 | The custom DSP doesn't contain the requested function
ERR_DSP_INVALID_ID | -93 | Invalid custom DSP identifier
ERR_DSP_FAILURE | -94 | Custom DSP failure
ERR_DSP_IS_NOT_EXTERNAL | -95 | The identifier is not related to an external custom DSP
ERR_REVERSE_NOT_AVAILABLE | -96 | Reversed sound is not available
ERR_MEMORY_REC_SESSION | -97 | Recording session is being performed in memory and in an output file
ERR_UNAVAIL_EDITION | -98 | Deprecated
ERROR_TOO_MANY_PLAYERS | -99 | The current product edition cannot create other players (*)
ERR_GENERIC | -100 | An unknown error occurred
ERR_VST_FILE_NOT_FOUND | -101 | The DLL containing the VST effect was not found
ERR_VST_INVALID_ID | -102 | Invalid VST identifier
ERR_VST_FAILURE | -103 | VST effect failure
ERR_VST_NOT_LOADED | -104 | The VST effect still needs to be loaded
ERR_VST_NOT_COMPATIBLE | -105 | The VST effect is not compatible with the current implementation of the control
ERR_VST_NO_EDITOR_AVAIL | -106 | The VST effect doesn't contain an editor
ERR_VST_EDITOR_IS_VISIBLE | -107 | The editor of the VST effect is visible
ERR_VST_INVALID_PROGRAM | -108 | The VST effect doesn't contain the given program
ERR_INVALID_EDITOR | -109 | Invalid editor
ERR_EDITOR_BUSY | -110 | The sound editor is busy
ERR_EDITOR_EMPTY | -111 | The sound editor doesn't contain any sound
ERR_ALREADY_EXISTS | -112 | The given item already exists
ERR_NOT_FOUND | -113 | Item not found
ERR_PLAYER_BUSY | -114 | Player is busy
ERR_DELAYED_PLAYBACK_OVERLAP | -115 | Delayed playback overlaps an existing one
ERR_NO_UNDO_AVAILABLE | -116 | Undo is not available
ERR_RAW_PCM_WITHOUT_HEADER | -117 | The sound file is a headerless RAW PCM
ERR_INCOHERENT_REC_SESSION | -118 | Incoherent recording session
ERR_INVALID_FILTER_NAME | -119 | Invalid filter name
ERR_INVALID_FILTER_TYPE | -120 | Invalid filter type
ERR_INVALID_WINDOW_TYPE | -121 | Invalid window type
ERR_CANNOT_ADD_PLAYER_TO_MIXER | -122 | Cannot add player to mixer
ERR_OUTPUT_NOT_FOR_MIXING | -123 | Output not set to mixing mode
ERR_INVALID_CASTING_ID | -124 | Invalid casting identifier
ERR_INVALID_ENCODE_MODE | -125 | Invalid encode mode
ERR_INVALID_SERVER_ADDRESS | -126 | Invalid server address
ERR_CONNECTION_FAILED | -127 | Connection failed
ERR_INVALID_PASSWORD | -128 | Invalid password
ERR_CASTING_ALREADY_STARTED | -129 | Casting session already started
ERR_CONNECTION_DIED | -130 | Casting connection died
ERR_INVALID_STREAN_MIXER | -131 | Invalid stream mixer
ERR_ASIO_INVALID_DEVICE | -132 | Invalid ASIO device
ERR_ASIO_INVALID_CHANNEL | -133 | Invalid ASIO channel
ERR_ASIO_CPANEL_NOT_AVAILABLE | -134 | ASIO control panel not available
ERR_ASIO_SYSTEM_NOT_INITIALIZED | -135 | ASIO system not initialized
ERR_ASIO_DEVICE_NOT_INITIALIZED | -136 | ASIO device not initialized
ERR_ASIO_CANNOT_START_DEVICE | -137 | Cannot start ASIO device
ERR_ASIO_INPUT_CHAN_BUSY | -138 | ASIO input channel is busy
ERR_INVALID_DEVICE | -139 | Invalid device
ERR_CANNOT_CREATE_DS_BUFFER | -140 | Cannot create DirectSound buffer
ERR_INVALID_DRIVER_TYPE | -141 | Invalid driver type
ERR_ASIO_DEVICE_ALREADY_STARTED | -142 | ASIO device already started
ERR_NOT_IMPLEMENTED | -143 | Feature not implemented
ERR_CANNOT_INIT_GDIPLUS | -144 | Cannot initialize GDI+
ERR_INVALID_ENCR_KEY | -145 | Invalid encryption key
ERR_NOT_QUEUED_SOUND | -146 | The chosen player is not streaming from a sound queue
ERR_MISSING_NOISE_PROFILE | -147 | Noise profile is missing
ERR_INVALID_BITRATE | -148 | Invalid bitrate
ERR_AUDIO_RENDERERS_ENUM_FAILED | -149 | Enumeration of audio renderers failed
ERR_NO_AUDIO_RENDERERS | -150 | No audio renderers available
ERR_INVALID_VIDEO_MIXER_ID | -151 | The unique identifier of the video mixer is invalid
ERR_PLAYER_NOT_ON_MIXER | -152 | The chosen player is not attached to a video mixer
ERR_FONT_NOT_GDIPLUS_COMPATIBLE | -153 | The chosen font is not compatible with GDI+
ERR_PL_NOT_AUTOMATION_MODE | -154 | Playlist is not set to work in automation mode
ERR_INVALID_PLATFORM | -155 | The command cannot be executed on platforms different from x86
ERR_NOT_MULTISTREAM | -156 | The audio of the video clip is not multistream
ERR_INVALID_FRAME_ID | -157 | Invalid frame identifier
ERR_CANNOT_CREATE_BITMAP | -158 | Cannot create bitmap
ERR_STRING_TOO_SHORT | -159 | The string is too short
ERR_STRING_TOO_LONG | -160 | The string is too long
ERR_INVALID_RECORDING_MODE | -161 | Invalid recording mode
ERR_INVALID_OUTPUT_FORMAT | -162 | Invalid output format
ERR_SOUND_NOT_STEREO | -163 | The loaded sound is not stereo
ERR_INVALID_STATE | -164 | Invalid state for performing the requested operation
ERR_FFDSHOW_NOT_AVAILABLE | -165 | FFDSHOW is not installed inside the system
ERR_SOUND_NOT_MONO | -166 | The loaded sound is not mono
ERR_OUTPUT_FORMAT_NOT_STEREO | -167 | The format of the output file is not stereo
ERR_INVALID_CURVE_DESIGNER_ID | -168 | Invalid identifier for the curve designer
ERR_FULLSCREEN_NOT_PREDISPOSED | -169 | Fullscreen not predisposed for the given monitor
ERR_NOT_MIDI | -170 | Not a MIDI file
ERR_INVALID_MIDI_SOUNDFONT_ID | -171 | Invalid MIDI soundfont identifier
ERR_INVALID_MIDI_PARAM | -172 | Invalid MIDI parameter
ERR_LIST_EMPTY | -173 | The requested list (for example a list of MIDI events) is empty
ERR_INVALID_MIDI_EVENT_ID | -174 | Invalid MIDI event identifier
ERR_NO_DEFAULT_SOUNDFONT | -175 | No default soundfont available
ERR_INVALID_KEYBOARD | -176 | Invalid keyboard
ERR_MIDI_DEVICE_ALREADY_STARTED | -177 | MIDI device already started
ERR_MIDI_DEVICE_NOT_STARTED | -178 | MIDI device not started
ERR_INVALID_RANGE | -179 | Invalid range
ERR_WASAPI_SYSTEM_NOT_INITIALIZED | -180 | WASAPI system not initialized
ERR_WASAPI_DEVICE_NOT_STARTED | -181 | WASAPI device not started
ERR_WASAPI_CANNOT_START_DEVICE | -182 | Cannot start WASAPI device
ERR_WASAPI_DEVICE_ALREADY_STARTED | -183 | WASAPI device already started
ERR_WASAPI_DEVICE_BUSY | -184 | WASAPI device busy
ERR_WASAPI_VOLUME_UNAVAIL | -185 | WASAPI volume not available or not accessible
ERR_UNSUPPORTED_AUDIO_FORMAT | -186 | The audio format is not supported
ERR_ASIO_DEVICE_NOT_STARTED | -187 | The ASIO device has not been started
ERR_CODEC_NOT_AVAILABLE | -188 | The add-on needed to decode the samples is not available
ERR_INVALID_FUNC | -189 | Invalid function
ERR_INVALID_PLUGIN | -190 | Invalid plugin
ERR_DOWNLOADER_REMOTE_FILE_FAILURE | -191 | Downloader remote file error
ERR_DOWNLOADER_LOCAL_FILE_FAILURE | -192 | Downloader local file error
ERR_DOWNLOADER_INVALID_SERVICE | -193 | Downloader invalid service
ERR_DOWNLOADER_INVALID_PARAM | -194 | Downloader invalid parameter
ERR_DOWNLOADER_INVALID_MEMORY | -195 | Downloader invalid memory buffer
ERR_DOWNLOADER_CONNECTION_TIMEOUT | -196 | Downloader connection timeout
ERR_DOWNLOADER_DATA_TIMEOUT | -197 | Downloader data timeout
ERR_DOWNLOADER_URL_NOT_FOUND | -198 | Downloader URL not found
ERR_DOWNLOADER_FILE_NOT_FOUND | -199 | Downloader remote file not found
ERR_SOUNDGEN_CHANNEL_EMPTY | -200 | The specified channel of the sound generator is empty
ERR_SOUNDGEN_INVALID_TYPE | -201 | The sound generator doesn't support the specified type
ERR_SOUNDCOMPOSER_EMPTY | -202 | The sound composer is empty
ERR_SAPI_VOICE_CANNOT_CREATE | -203 | Cannot create Speech API voice
ERR_SAPI_STREAM_CANNOT_CREATE | -204 | Cannot create Speech API audio stream
ERR_SAPI_VOICE_INVALID_OUTPUT | -205 | The output specified for the Speech API stream is invalid
ERR_SAPI_VOICE_CANNOT_SPEAK | -206 | Speech API voice unable to speech
ERR_SAPI_VOICE_CANNOT_ENUM | -207 | Cannot enumerate Speech API voices
ERR_SAPI_VOICE_CANNOT_SET | -208 | Cannot set Speech API voice
ERR_SOUNDCOMPOSER_INVALID_CHANNEL | -209 | The specified channel of the sound composer is invalid
ERR_INVALID_CHANNEL_PAIR | -210 | Invalid channels pair
ERR_LICENSE_PROTECTED | -211 | The sound file is protected through DRM (Digital Right Management)
ERR_ZIP_CLOSED | -212 | The ZIP session is closed
ERR_INVALID_ZIP_ENCR_TYPE | -213 | Invalid encryption type for creating the ZIP file
ERR_SOUNDCOMPOSER_NOT_READY | -214 | The sound composer session is not ready
ERR_SOUNDCOMPOSER_INVALID_ITEM | -215 | The new item is not suitable for the sound composer


MediaFileDecoder property (RO)

MediaFileDecoder property (RO)

Return to chapter overview
Type | CMediaFileDecoder for Visual C++ AMP3DJLib.MediaFileDecoder for Visual Basic This property is Read-only
Syntax | object.Downloader [=AMP3DJLib.MediaFileDecoder]
Remarks | The object used for managing decoding of media files in various formats. This property encapsulates the functionality of the MediaFileDecoder object and the IMediaFileDecoder COM interface. For details about management of media files decoding, refer to the How to decode media files tutorial.


MIDI property (RO)

MIDI property (RO)

 Return to chapter overview
Type | CMIDI for Visual C++ AMP3DJLib.MIDI for Visual Basic This property is Read-only
Syntax | object.MIDI [=AMP3DJLib.MIDI]
Remarks | The object used to manage MIDI protocol. This property encapsulates the functionality of the MIDI object and the IMIDI COM interface. Further information about management of MIDI protocol can be found inside the How to deal with MIDI protocol tutorial.


Oscilloscope property (RO)

Oscilloscope property (RO)

Return to chapter overview
Type | COscilloscope for Visual C++ AMP3DJLib.Oscilloscope for Visual Basic This property is Read-only
Syntax | object.Oscilloscope [=AMP3DJLib.Oscilloscope]
Remarks | The embedded Oscilloscope object (Visual Feedback). This property encapsulates the functionality of the Oscilloscope object and the IOscilloscope COM interface. For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


ScaleUnits property

ScaleUnits property

Type

enumScaleUnits for Visual Basic

short for Visual C++

Remarks

The unit used to seek into the loaded sound when dealing with the SeekSound, PlaySoundRange and PlaySoundRangeLoop methods.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_MILLISECONDS | 0 | Milliseconds
SCALE_SECONDS | 1 | Seconds
SCALE_MINUTES | 2 | Minutes
SCALE_HOURS | 3 | Hours
SCALE_PERCENTAGE | 4 | Percentage (expressed with values from 0 to 100)


SoundComposer property (RO)

SoundComposer property (RO)

Return to chapter overview
Type | CSoundComposer for Visual C++ AMP3DJLib.SoundComposer for Visual Basic This property is Read-only
Syntax | object.SoundComposer [=AMP3DJLib.SoundComposer]
Remarks | The embedded sound composer. This property encapsulates the functionality of the SoundComposer object and the ISoundComposer COM interface. For further details about sound composing see the How to compose a sound tutorial.


SoundGenerator property (RO)

SoundGenerator property (RO)

Return to chapter overview

Type

CSoundGenerator for Visual C++

AMP3DJLib.SoundGenerator for Visual Basic

This property is Read-only

Syntax

object.SoundGenerator [=AMP3DJLib.SoundGenerator]

Remarks

The embedded sound generator object.

This property encapsulates the functionality of the SoundGenerator object and the ISoundGenerator COM interface.

For details about using the sound generator refer to the How to generate wave tones, noises, DTMF tones and text to speech tutorial.


SoundsDirectory property

Copyright © 2001-2018 MultiMedia Soft

SoundsDirectory property

Return to chapter overview
Type | String for Visual Basic LPCTSTR for Visual C++
Remarks | The string containing the directory path from which the LoadSound method will take, by default, the sound files.


Spectrum property (RO)

Spectrum property (RO)

Return to chapter overview
Type | CSpectrum for Visual C++ AMP3DJLib.Spectrum for Visual Basic This property is Read-only
Syntax | object.Spectrum [=AMP3DJLib.Spectrum]
Remarks | The embedded Spectrum object (Visual Feedback). This property encapsulates the functionality of the Spectrum object and the ISpectrum COM interface. For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


SpectrumEnh property (RO)

SpectrumEnh property (RO)

Return to chapter overview

Type

CSpectrumEnhDJ for Visual C++

AMP3DJLib.SpectrumEnhDJ for Visual Basic

This property is Read-only

Syntax

object.SpectrumEnh [=AMP3DJLib.SpectrumEnhDJ]

Remarks

The embedded Enhanced Spectrum Analyzer object (Visual Feedback).

This property encapsulates the functionality of the SpectrumEnh object and the ISpectrumEnhDJ COM interface.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


TagsReader property (RO)

TagsReader property (RO)

Return to chapter overview
Type | CTagsReader for Visual C++ ACTIVESOUNDEDITORLib.TagsReader for Visual Basic This property is Read-only
Syntax | object.WaveformAnalyzer [=ACTIVESOUNDEDITORLib.TagsReader]
Remarks | The embedded reader of tag information. This property encapsulates the functionality of the TagsReader object and the ITagsReader COM interface. For details about the reading of tags see the How to read TAG information in sound files tutorial.


VideoMixer property (RO)

VideoMixer property (RO)

 Return to chapter overview
Type | CVideoMixer for Visual C++ AMP3DJLib.VideoMixer for Visual Basic This property is Read-only
Syntax | object.VideoMixer [=AMP3DJLib.VideoMixer]
Remarks | The embedded video mixer. This property encapsulates the functionality of the VideoMixer object and the IVideoMixer COM interface. For details about video mixing refer to the How to use the video mixer tutorial.


VideoPlayer property (RO)

VideoPlayer property (RO)

Return to chapter overview

Type

CVideoPlayer for Visual C++

AMP3DJLib.VideoPlayer for Visual Basic

This property is Read-only

Syntax

object.VideoPlayer [=AMP3DJLib.VideoPlayer]

Remarks

The embedded player of video files.

This property encapsulates the functionality of the VideoPlayer object and the IVideoPlayer COM interface.

For details about video clips rendering refer to the How to play video files through DirectShow section.


VolumeAutomation property (RO)

VolumeAutomation property (RO)

 Return to chapter overview

Type

CVolumeAutomation for Visual C++

AMP3DJLib.VolumeAutomation for Visual Basic

This property is Read-only

Syntax

object.VolumeAutomation [=AMP3DJLib.VolumeAutomation]

Remarks

The object used to manage Volume Automation.

This property encapsulates the functionality of the VolumeAutomation object and the IVolumeAutomation COM interface.

Further information about the use of volume automation can be found inside the How to manage Volume Automation tutorial.


VST property (RO)

VST property (RO)

Return to chapter overview
Type | CVST for Visual C++ AMP3DJLib.VST for Visual Basic This property is Read-only
Syntax | object.VST [=AMP3DJLib.VST]
Remarks | The object used to manage VST effects. This property encapsulates the functionality of the VST object and the IVST COM interface. For further details about managing a VST effect refer to the How to manage VST effects tutorial.


VUMeter property (RO)

VUMeter property (RO)

Return to chapter overview
Type | CVUMeter for Visual C++ AMP3DJLib.VUMeter for Visual Basic This property is Read-only
Syntax | object.VUMeter [=AMP3DJLib.VUMeter]
Remarks | The embedded VU-Meter object (Visual Feedback). This property encapsulates the functionality of the VUMeter object and the IVUMeter COM interface. For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


WASAPI property (RO)

WASAPI property (RO)

 Return to chapter overview

Type

CWASAPI for Visual C++

AMP3DJLib.WASAPI for Visual Basic

This property is Read-only

Syntax

object.WASAPI [=AMP3DJLib.WASAPI]

Remarks

The object used to manage audio flow through WASAPI.

This property encapsulates the functionality of the WASAPI object and the IWASAPI COM interface..

Further information about WASAPI can be found inside the How to manage audio flow through WASAPI tutorial.


Waveform property (RO)

Waveform property (RO)

Return to chapter overview
Type | CWaveform for Visual C++ AMP3DJLib.Waveform for Visual Basic This property is Read-only
Syntax | object.Waveform [=AMP3DJLib.Waveform]
Remarks | The embedded Waveform display object (Visual Feedback). This property encapsulates the functionality of the Waveform object and the IWaveform COM interface. For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


WaveformScroller property (RO)

WaveformScroller property (RO)

Return to chapter overview

Type

CWaveformScroller for Visual C++

AMP3DJLib.WaveformScroller for Visual Basic

This property is Read-only

Syntax

object.WaveformScroller [=AMP3DJLib.WaveformScroller]

Remarks

The embedded Waveform scroller display object.

This property encapsulates the functionality of the WaveformScroller object and the IWaveformScroller COM interface.

For details about creating and using a WaveformScroller refer to the How to scroll the sound's waveform during playback tutorial.


ZIP property (RO)

ZIP property (RO)

Return to chapter overview
Type | CZIP for Visual C++ AMP3DJLib.ZIP for Visual Basic This property is Read-only
Syntax | object.ZIP [=AMP3DJLib.ZIP]
Remarks | The object used to manage ZIP files. This property encapsulates the functionality of the ZIP object. Further details about using ZIP management are available inside the How to manage ZIP files tutorial.


AboutBox method

AboutBox method

Remarks

Displays information about the control.

Syntax

[Visual Basic]

control.AboutBox (

)

[C++]

void control.AboutBox (

);


AudioExtensionAdd method

AudioExtensionAdd method

Remarks

Adds a file extension to the list of file extensions considered as belonging to audio formats.

Certain video formats, like WMV, MP4 and DIVX, can be loaded by the control as audio tracks (causing the video stream to be ignored), through the LoadSound method or as video clips (having both audio and video streams) through the VideoPlayer.Load method; when files of these formats are inserted inside a playlist file, the control will consider them as video clips by default so will try to load them through DirectShow: through this method you can instruct the playlist manager to consider these formats as being simple audio tracks instead of video clips so only the audio stream will be managed and the video stream ignored.

Syntax

[Visual Basic]

control.AudioExtensionAdd (

strExtension as String

)

[C++]

void control.AudioExtensionAdd (

LPCTSTR strExtension

);

Parameter | Description
strExtension | String containing the file extension, for example WMV or MP4.

Return value

None


BassModuleGet method

BassModuleGet method

Remarks

Obtains the handle of the instance of one of the BASS related modules loaded in memory. This method should be called only after having initialized the component through the InitDJSystem or InitDJSystemEx method.

This component already initializes and exploits the most important decoding and playback features implemented by the BASS module; in some case you could have the need to drive BASS directly in order to perform some particular task not available from the component itself; for achieving this possibility you would have to load and eventually free BASS or its plugins through the LoadLibrary or LoadLibraryEx and the FreeLibrary Windows API functions.

Through this method you have the possibility to access instances already loaded in memory by the multimedia engine AdjMmsEng.dll: indeed, by knowing the HMODULE of BASS.DLL or of some of its plugins, you could get the pointer to all of the functions exported by the various BASS modules through the GetProcAddress Windows API.

IMPORTANT NOTE: Calls to the BASS_Init and BASS_Free functions of BASS.DLL are already managed internally by multimedia engine AdjMmsEng.dll so it's recommended avoiding their usage in order to avoid compatibility issues.

In case you should need to have direct access to the handle (HSTREAM) of a playback stream created through BASS after calling the LoadSound, StreamMixerCreate and similar methods, please, refer to the BassStreamGet method.

For further details about accessing BASS and its plugins directly from your code you can refer to the tutorial How to access BASS library functionalities directly.

Syntax

[Visual Basic]

control.BassModuleGet (

nModule as enumBassModules,

ByRef hModule as Long

) as enumErrorCodes

[C++]

short control.BassModuleGet (

short nModule,

long *hModule

);

Parameter

Description

nModule

Number representing the instance of the BASS module whose handle is needed.

Supported values are the following:

Mnemonic constant | Value | Meaning
MODULE_BASS | 0 | Main BASS module BASS.DLL
MODULE_BASS_FX | 1 | BASS_FX.DLL plugin
MODULE_BASS_CD | 2 | BASSCD.DLL plugin
MODULE_BASS_ENC | 3 | BASSENC.DLL plugin
MODULE_BASS_MIX | 4 | BASSMIX.DLL plugin
MODULE_BASS_WMA | 5 | BASSWMA.DLL plugin
MODULE_BASS_MIDI | 6 | BASSMIDI.DLL plugin
MODULE_BASS_VST | 7 | BASS_VST.DLL plugin
MODULE_BASS_FLAC | 8 | BASSFLAC.DLL plugin
MODULE_BASS_AAC | 9 | BASS_AAC.DLL plugin
MODULE_BASS_AC3 | 10 | BASS_AC3.DLL plugin
MODULE_BASS_WAVPACK | 11 | BASSWV.DLL plugin
MODULE_BASS_ALAC | 12 | BASS_ALAC.DLL plugin
MODULE_BASS_APE | 13 | BASS_APE.DLL plugin
MODULE_BASS_MPC | 14 | BASS_MPC.DLL plugin
MODULE_BASS_SPX | 15 | BASS_SPX.DLL plugin
MODULE_BASS_WASAPI | 17 | BASSWASAPI.DLL plugin
MODULE_BASS_OPUS | 18 | BASSOPUS.DLL plugin

hModule

Reference that, on return from the method call, will contain the handle to the BASS module (HMODULE) as returned by the LoadLibraryEx Windows API function called internally by the multimedia engine AdjMmsEng.dll of the component.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


BassPluginStreamCreateFunc method

BassPluginStreamCreateFunc method

Remarks

Imports a specific function for creating a playback stream of type HSTREAM from a BASS plugin implementing the decoding of an audio format not already covered by the multimedia engine.

Audio formats not included inside the multimedia engine but implemented inside existing BASS plugins are the following:

· OptimFrog through the Bass_OFR.dll plugin
· TTA through the Bass_TTA.dll plugin
· ADX through the Bass_ADX.dll plugin
· AIX through the Bass_AIX.dll plugin

Other formats may be added in the future. Check the www.un4seen.com website for downloading the mentioned plugins or for checking the availability of new ones.

For further details about accessing BASS and its plugins directly from your code you can refer to the tutorial How to access BASS library functionalities directly.

Syntax

[Visual Basic]

control.BassPluginStreamCreateFunc (

strPluginPathname as String,

strFuncName as String,

nType as enumBassPluginStreamCreateFuncs

) as enumErrorCodes

[C++]

short control.BassPluginStreamCreateFunc (

BSTR strPluginPathname,

BSTR strFuncName,

short nType

);

Parameter

Description

strPluginPathname

String containing the absolute or relative pathname of the BASS plugin. For example "Bass_AIX.dll".

If the string specifies a full path, the function searches only that path for the module.

If the string specifies a relative path or a module name without a path, the function uses the standard search strategy adopted by the LoadLibraryEx Windows API to find the module.

strFuncName

String containing the exact name of the function to import. For example "BASS_AIX_StreamCreateFile" or "BASS_AIX_StreamCreateURL".

nType

Type of function.

Supported values are the following:

Mnemonic constant | Value | Meaning
BASS_PLUGIN_STREAM_CREATE_FILE | 0 | Function for creating a playback stream from a sound file. This function is usually exported by the plugin with the name BASS_xxx_StreamCreateFile where "xxx" indicates the managed audio format, for example BASS_AIX_StreamCreateFile or BASS_TTA_StreamCreateFile; the exported function must use the following C syntax: HSTREAM BASS_xxx_StreamCreateFile ( BOOL mem, const void *file, QWORD offset, QWORD length, DWORD flags ); See the BASS documentation for details about the parameters in use.
BASS_PLUGIN_STREAM_CREATE_URL | 1 | Function for creating a playback stream from an Internet URL. This function is usually exported by the plugin with the name BASS_xxx_StreamCreateURL where "xxx" indicates the managed audio format, for example BASS_AIX_StreamCreateURL; the exported function must use the following C syntax: HSTREAM BASS_xxx_StreamCreateURL ( const char *url, DWORD offset, DWORD flags, DOWNLOADPROC *proc, void *user ); See the BASS documentation for details about the parameters in use.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


BassStreamGet method

BassStreamGet method

Remarks

Obtains the handle to the playback stream (HSTREAM) created by BASS after calling one of the many methods having the "Load" prefix (like LoadSound and LoadSoundFromMemory) or through the StreamMixerCreate method,

The obtained handle allows calling functions of BASS.DLL directly or to apply to the playback stream some special effect exported by BASS plugins, for example BASS_SFX, BASS_WM, etc., not included inside the multimedia engine AdjMmsEng.dll.

See the BassModuleGet method for details about the direct usage of functions exported by the BASS.DLL library and by the other BASS plugins included inside the multimedia engine AdjMmsEng.dll.

For further details about accessing BASS and its plugins directly from your code you can refer to the tutorial How to access BASS library functionalities directly.

Syntax

[Visual Basic]

control.BassStreamGet (

nPlayer as Integer,

ByRef hStream as Long

) as enumErrorCodes

[C++]

short control.BassStreamGet (

short nPlayer,

long *hStream

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
hStream | Reference that, on return from the method call, will contain the handle (HSTREAM) to the playback stream.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CallbackForCdDrivesEventsSet method

CallbackForCdDrivesEventsSet method

Remarks

Sets a callback for receiving notification of events generated by CD drives, allowing to synchronize CD drives with the container application; the usage of this callback can be an alternative to the usage of regular events.

Syntax

[Visual Basic]

control.CallbackForCdDrivesEventsSet (

pCallback as Long

) as enumErrorCodes

[C++]

short control.CallbackForCdDrivesEventsSet (

long pCallback

);

Parameter

Description

pCallback

Pointer to the callback function that will receive CD drives related events. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

A callback function is defined like this:

[Visual Basic ]

Public Sub MyCdDriveCallback (

ByVal nEvent As enumCdDrivesEvents,

ByVal nCdDrive As Long,

ByVal nData1 As Long,

ByVal nData2 As Long,

ByVal nData3 As Long

)

[Visual C++]

void FAR PASCAL MyCdDriveCallback (

long nEvent,

long nCdDrive,

long nData1,

long nData2,

long nData3

);

where

nEvent

Event reported by the CD drive.

Supported values are the following:

Mnemonic constant

Value

Meaning with data parameters

EV_CD_READ_TRACK_START

0

Alternative to the CdReadTrackStart event.

Involved data parameters:

nData1: Number representing the one-based index of the CD audio track that is being loaded.

EV_CD_READ_TRACK_PERC

1

Alternative to the CdReadTrackPercentage event.

Involved data parameters:

nData1: Number representing the one-based index of the CD audio track that is being loaded.

nData2: Number representing the CD track loading advancement percentage.

EV_CD_READ_TRACK_STOP

2

Alternative to the CdReadTrackStop event.

Involved data parameters:

nData1: Number representing the one-based index of the CD audio track that is being loaded.

EV_CD_STATUS_CHANGED

3

Alternative to the CdPlayerStatusChanged event.

Involved data parameters:

nData1: Number representing the CD drive status. See the CdPlayerStatusChanged event for supported values.

EV_CDDB_SERVERS_AVAIL

4

Alternative to the CddbServersListAvailable event.

Involved data parameters:

nData1: The number of CDDB servers found. If this parameter value is 0, this means that an error occurred during the connection to the CDDB site.

EV_CDDB_ALBUM_INFO_AVAIL

5

Alternative to the CddbAlbumInfoAvailable event.

Involved data parameters:

nData1: Boolean value that specifies if the CDDB information was retrieved successfully. See the CddbAlbumInfoAvailable event for supported values.

EV_CD_COVER_URLS_AVAIL

6

Alternative to the CdCoverURLsAvailableEx event.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. See the CdCoverURLsAvailableEx event for supported values.

EV_CD_COVER_SMALL_FILE_AVAIL

7

Alternative to the CdCoverPictureFileAvailableEx event having the nSize parameter set to CD_COVER_SIZE_SMALL.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. See the CdCoverPictureFileAvailableEx event for supported values.

EV_CD_COVER_MEDIUM_FILE_AVAIL

8

Alternative to the CdCoverPictureFileAvailableEx event having the nSize parameter set to CD_COVER_SIZE_MEDIUM.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. See the CdCoverPictureFileAvailableEx event for supported values.

EV_CD_COVER_LARGE_FILE_AVAIL

9

Alternative to the CdCoverPictureFileAvailableEx event having the nSize parameter set to CD_COVER_SIZE_LARGE.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. See the CdCoverPictureFileAvailableEx event for supported values.

nCdDrive

Zero-based index of the CD drive reporting the event

nData1

First 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

nData2

Second 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

nData3

Third 32 bits integer value containing event specific data; currently unused, reserved for future developments.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CallbackForCoreAudioEventsSet method

CallbackForCoreAudioEventsSet method

Remarks

Sets a callback for receiving notification of events generated by CoreAudio devices, allowing to synchronize these devices with the container application; the usage of this callback can be an alternative to the usage of regular events.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

control.CallbackForCoreAudioEventsSet (

pCallback as Long

) as enumErrorCodes

[C++]

short control.CallbackForCoreAudioEventsSet (

long pCallback

);

Parameter

Description

pCallback

Pointer to the callback function that will receive CoreAudio devices related events. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

A callback function is defined like this:

[Visual Basic ]

Public Sub MyCdDriveCallback (

ByVal nEvent As enumCoreAudioEvents,

ByVal nData1 As Long,

ByVal nData2 As Long,

ByVal nData3 As Long

)

[Visual C++]

void FAR PASCAL MyCdDriveCallback (

long nEvent,

long nData1,

long nData2,

long nData3

);

where

nEvent

Event reported by the CoreAudio device.

Supported values are the following:

Mnemonic constant | Value | Meaning with data parameters
EV_COREAUDIO_DEVICE_STATE_CHANGED | 0 | Alternative to the CoreAudioDeviceStateChange event. Involved data parameters: nData1: See the nDeviceIndex parameter of the CoreAudioDeviceStateChange event. nData2: See the nDataFlow parameter of the CoreAudioDeviceStateChange event. nData3: See the nNewState parameter of the CoreAudioDeviceStateChange event.
EV_COREAUDIO_DEVICE_ADDED | 1 | Alternative to the CoreAudioDeviceAdded event. Involved data parameters: none.
EV_COREAUDIO_DEVICE_REMOVED | 2 | Alternative to the CoreAudioDeviceRemoved event. Involved data parameters: none.
EV_COREAUDIO_DEVICE_DEFAULT_CHANGE | 3 | Alternative to the CoreAudioDeviceDefaultChange event. Involved data parameters: nData1: See the nDeviceIndex parameter of the CoreAudioDeviceDefaultChange event. nData2: See the nDataFlow parameter of the CoreAudioDeviceDefaultChange event. nData3: See the nRole parameter of the CoreAudioDeviceDefaultChange event.
EV_COREAUDIO_DEVICE_VOLUME_CHANGE | 4 | Alternative to the CoreAudioDeviceVolumeChange event. Involved data parameters: nData1: See the nDeviceIndex parameter of the CoreAudioDeviceVolumeChange event. nData2: See the nDataFlow parameter of the CoreAudioDeviceVolumeChange event.
EV_COREAUDIO_DEVICE_VUMETER_CHANGE | 5 | Alternative to the CoreAudioDeviceVuMeterChange event. Involved data parameters: nData1: See the nDeviceIndex parameter of the CoreAudioDeviceVuMeterChange event. nData2: See the nDataFlow parameter of the CoreAudioDeviceVuMeterChange event.

nData1

First 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

nData2

Second 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

nData3

Third 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CallbackForPlayersEventsSet method

CallbackForPlayersEventsSet method

Remarks

Sets a callback for receiving notification of events generated by instanced players, allowing to synchronize players themselves with the container application; the usage of this callback can be an alternative to the usage of regular events.

Syntax

[Visual Basic]

control.CallbackForPlayersEventsSet (

pCallback as Long

) as enumErrorCodes

[C++]

short control.CallbackForPlayersEventsSet (

long pCallback

);

Parameter

Description

pCallback

Pointer to the callback function that will receive player related events. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

A callback function is defined like this:

[Visual Basic ]

Public Sub MyPlayerCallback (

ByVal nEvent As enumPlayerEvents,

ByVal nPlayer As Integer,

ByVal nData1 As Long,

ByVal nData2 As Long,

ByVal fData3 As Single,

ByVal pBufferUnicode As Long,

ByVal nBufferLength As Long

)

[Visual C++]

void FAR PASCAL MyPlayerCallback (

long nEvent,

short nPlayer,

long nData1,

long nData2,

float fData3,

char *pBufferUnicode,

long nBufferLength

);

where

nEvent

Event reported by the player.

Supported values are the following:

Mnemonic constant

Value

Meaning with data parameters

EV_SOUND_DONE

0

Alternative to the SoundDone event.

Involved data parameters: none.

EV_SOUND_PLAYING

1

Alternative to the SoundPlaying event.

Involved data parameters: none.

EV_SOUND_PAUSED

2

Alternative to the SoundPaused event.

Involved data parameters: none.

EV_SOUND_STOPPED

3

Alternative to the SoundStopped event.

Involved data parameters: none.

EV_SOUND_LOADED

4

Alternative to the SoundLoaded event.

Involved data parameters:

nData1: Number representing the zero-based index of the song in the player playlist; if the song is not inserted into a playlist it's always set to 0.

EV_SOUND_SYNC_LOADED

5

Alternative to the SoundSyncLoaded event.

Involved data parameters:

nData1: The result of the loading operation. See the LastError property for details about the returned result code.

EV_META_CHANGED

6

Alternative to the MetaTagChanged event.

Involved data parameters: none.

EV_DOWNLOAD_COMPLETE

7

Alternative to the DownloadComplete event.

Involved data parameters: none.

EV_DOWNLOAD_BUFFERING

8

Alternative to the DownloadBuffering event.

Involved data parameters:

nData1: The buffering status.

EV_DOWNLOAD_PERC

9

Alternative to the DownloadPercentage event.

Involved data parameters:

nData1: Number representing the download percentage.

EV_STREAM_CONNECTING

10

Alternative to the StreamConnecting event.

Involved data parameters: none.

EV_STREAM_LOADED

11

Alternative to the StreamLoaded event.

Involved data parameters:

nData1: The stream loading result.

EV_STREAM_LOADED_FROM_INET_PLS

12

Alternative to the StreamLoadedFromInetPlaylist event.

Involved data parameters:

nData1: The stream loading result.

nData2: The zero-based index of the item.

pBufferUnicode: String containing the URL of the Internet stream.

EV_PLAYLIST_DONE

13

Alternative to the PlayListDone event.

Involved data parameters: none.

EV_PLAYLIST_SOUND_LOADED

14

Alternative to the PlaylistSoundLoaded event.

Involved data parameters:

nData1: Number representing the zero-based index of the song in the player playlist; if the song is not inserted into a playlist it's always set to 0.

pBufferUnicode: String containing a custom tag associated to this item.

EV_PLAYLIST_SOUND_LOAD_FAILED

15

Alternative to the PlayListSoundLoadFailure event.

Involved data parameters:

nData1: Number representing the zero-based index of the song in the player playlist; if the song is not inserted into a playlist it's always set to 0.

EV_PLAYLIST_STREAM_LOADED

16

Alternative to the PlayListStreamLoaded event.

Involved data parameters:

nData1: The zero based-index of the loaded item: in case of failure in loading the stream taken from the playlist this parameter would be set to -1.

EV_SOUND_CLOSED

17

Alternative to the SoundClosed event.

Involved data parameters: none.

EV_SERVER_CLOSED

18

Alternative to the ServerClosed event.

Involved data parameters: none.

EV_DURATION_CHANGED

19

Alternative to the SoundDurationChanged event.

Involved data parameters:

fData3: The updated sound duration expressed in seconds.

EV_VUMETER

20

Alternative to the VUMeterValueChange event.

Involved data parameters:

nData1: Number representing the peak value for the left channel: can assume values from 0 (no sound) to 32767 (max volume).

nData2: Number representing the peak value for the right channel: can assume values from 0 (no sound) to 32767 (max volume).

EV_SPECTRUM_CHANGE

21

Alternative to the SpectrumValueChange event.

Involved data parameters: none.

EV_BPM_AVAILABLE

22

Alternative to the BPMAvailable event.

Involved data parameters:

fData3: The detected song BPM.

EV_FADING_VOLUME_CHANGED

23

Alternative to the FadingVolumeChanged event.

Involved data parameters:

fData3: The player's current volume.

EV_FADING_POINT_REACHED

24

Alternative to the FadingPointReached event.

Involved data parameters: none.

EV_FADEIN_STARTED

25

Alternative to the FadeInStarted event.

Involved data parameters: none.

EV_FADEIN_COMPLETED

26

Alternative to the FadeInCompleted event.

Involved data parameters: none.

EV_FADEOUT_STARTED

27

Alternative to the FadeOutStarted event.

Involved data parameters: none.

EV_FADEOUT_COMPLETED

28

Alternative to the FadeOutCompleted event.

Involved data parameters: none.

EV_TRIGGER_REACHED

29

Alternative to the TriggerReached event.

Involved data parameters:

nData1: Number representing the trigger identifier.

EV_SILENCE_AVAIL

30

Alternative to the SilencePositionAvailable event.

Involved data parameters:

nData1: Number representing the position in milliseconds where the sound level is higher than the initial threshold. If no sound has been detected, due to the threshold level being higher respect to existing sound, this parameter is set to -1.

nData2: Number representing the position in milliseconds where the sound level is lower than the final threshold. If no sound has been detected, due to the threshold level being higher respect to existing sound, this parameter is set to -1.

EV_WAVE_ANALYSIS_START

31

Alternative to the WaveAnalysisStart event.

Involved data parameters: none.

EV_WAVE_ANALYSIS_PERC

32

Alternative to the WaveAnalysisPerc event.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current sound analysis.

EV_WAVE_ANALYSIS_DONE

33

Alternative to the WaveAnalysisDone event.

Involved data parameters:

nData1: Number representing the amount of peaks detected during the sound's analysis.

fData3: Floating point number representing the duration in milliseconds of each detected peak.

EV_RANGE_LOOP_DONE

34

Alternative to the RangeLoopDone event.

Involved data parameters:

nData1: Number representing the amount of loops that must be still performed.

EV_WAV_EXPORT_START

35

Alternative to the ExportToWavStart event.

Involved data parameters: none.

EV_WAV_EXPORT_PERC

36

Alternative to the ExportToWavPerc event.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current exporting session.

EV_WAV_EXPORT_COMPLETE

37

Alternative to the ExportToWavStop event.

Involved data parameters:

nData1: Number representing the total size, expressed in bytes, of the exported WAV file..

EV_EQUALIZER_LOADED

38

Alternative to the EqualizerLoaded event.

Involved data parameters: none.

EV_CUE_POINTS_LOADED

39

Alternative to the CuePointsLoaded event.

Involved data parameters: none.

EV_BEATS_AVAILABLE

40

Alternative to the BeatsAvailableOffline event.

Involved data parameters:

nData1: Number of beats detected.

EV_BEAT_DETECTED

41

Alternative to the BeatDetectedRealTime event.

Involved data parameters:

nData1: Beat's position expressed in milliseconds.

EV_PLAYLIST_LOAD_STARTED

42

Alternative to the PlayListLoadStart event.

Involved data parameters: none.

EV_PLAYLIST_LOAD_PERC

43

Alternative to the PlayListLoadPerc event.

Involved data parameters:

nData1: Number representing the percentage of advancement for the loading session.

EV_PLAYLIST_LOAD_DONE

44

Alternative to the PlayListLoadDone event.

Involved data parameters: none.

EV_CUE_POINT_REACHED

45

Alternative to the CuePointReached event.

Involved data parameters:

nData1: Number representing the position, expressed in milliseconds, of the cue point.

pBufferUnicode: String containing the unique name of the cue point as defined when the cue point was added through the CuePointsAdd method.

EV_VOLUME_POINT_REACHED

46

Alternative to the VolumeAutomationPointReached event.

Involved data parameters:

fData3: Number representing the position of the volume point expressed in the same unit set into the VolumeAutomation.PositionUnit property.

pBufferUnicode: String containing the friendly name of the volume point as defined when the volume point was added through the VolumeAutomation.PointAdd method.

EV_VOLUME_AUTOMATION_LOADED

47

Alternative to the VolumeAutomationLoaded event.

Involved data parameters: none.

EV_LYRICS_AVAIL

48

Alternative to the SoundLyricsAvailable event.

Involved data parameters:

nData1: The result of the lyrics search operation. See the LastError property for details about the returned result code. If the result is enumErrorCodes.ERR_NOERROR, lyrics text can be retrieved through the SoundLyricsGet method.

EV_SOUND_STALLED

49

Alternative to the StreamQueueStalled event.

Involved data parameters: none.

EV_AUDIO_EXTRACT_START

50

Alternative to the AudioExtractFromVideoStart event.

Involved data parameters: none.

EV_AUDIO_EXTRACT_PERC

51

Alternative to the AudioExtractFromVideoPerc event.

Involved data parameters:

nData1: Number representing the current percentage of the audio extraction.

EV_AUDIO_EXTRACT_DONE

52

Alternative to the AudioExtractFromVideoDone event.

Involved data parameters:

nData1: Boolean flag that warns when the extracted audio track, that was originally requested to be stored in memory, has been put into a temporary file due to missing memory space. If the original request was to store the extracted audio track inside a temporary file, this flag can be ignored.

nData2: Result of the audio extraction: see the LastError property for details about the specific error code.

EV_VOLUME_SLIDE_COMPLETED

53

Alternative to the VolumeSlideCompleted event.

Involved data parameters: none.

EV_PLAYER_DISCONNECTED

54

Alternative to the PlayerDisconnected event.

Involved data parameters: none.

EV_OUTPUT_DEVICE_CHANGED

55

Alternative to the OutputDeviceChanged event.

Involved data parameters:

nData1: Number representing the zero-based index of the new output device for the given player.

EV_SILENCE_DETECTION

56

Alternative to the SilenceDetectionStateChange event.

Involved data parameters:

nData1: Boolean value specifying detection of silent data or of audible data.

nData2: Number representing the position inside the sound stream, expressed in milliseconds, where the silence threshold was crossed.

nPlayer

Zero-based index of the player reporting the event

nData1

First 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

nData2

Second 32 bits integer value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

fData3

Third floating point value containing event specific data; its value and meaning depends upon the specific event received: see the table above for possible values.

pBufferUnicode

Pointer to the buffer; its value and meaning depends upon the specific event received: see the table above for possible values.

nBufferLength

The length in characters of the buffer above

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CommonDialogGetInfoFromLastOpen method

CommonDialogGetInfoFromLastOpen method

Remarks

Obtains further information about the file chosen through a previous call to the CommonDialogShowOpen method.

For further information about dealing with Unicode characters, check the How to manage Unicode characters in filenames and tags tutorial.

Syntax

[Visual Basic]

control.CommonDialogGetInfoFromLastOpen (

nInfo as enumCommonDialogInfo

) as String

[C++]

LPCTSTR control.CommonDialogGetInfoFromLastOpen (

short nInfo

);

Parameter

Description

nInfo

Number representing the information to obtain.

Supported values are the following:

Mnemonic constant | Value | Meaning
COMMON_DLG_FULLPATHNAME | 0 | String representing the absolute pathname (path + filename) of the chosen file; this value is identical to the one returned by the CommonDialogShowOpen method Example "C:\myfolder\myfile.mp3".
COMMON_DLG_PATH | 1 | String representing the absolute path where the file is located (without the filename). Example "C:\myfolder\".
COMMON_DLG_FILENAME | 2 | String representing the filename of the chosen file. Example "myfile.mp3".
COMMON_DLG_FILENAME_NOEXT | 3 | String representing the filename of the chosen file without the extension. Example "myfile".
COMMON_DLG_EXT | 4 | String representing the extension of the chosen file. Example "mp3".

Return value

Value | Meaning
Empty string | Information not available or an error occurred.
Valid string | The requested information.


CommonDialogGetInfoFromLastSave method

CommonDialogGetInfoFromLastSave method

Remarks

Obtains further information about the file chosen through a previous call to the CommonDialogShowSave method.

For further information about dealing with Unicode characters, check the How to manage Unicode characters in filenames and tags tutorial.

Syntax

[Visual Basic]

control.CommonDialogGetInfoFromLastSave (

nInfo as enumCommonDialogInfo

) as String

[C++]

LPCTSTR control.CommonDialogGetInfoFromLastSave (

short nInfo

);

Parameter

Description

nInfo

Number representing the information to obtain.

Supported values are the following:

Mnemonic constant | Value | Meaning
COMMON_DLG_FULLPATHNAME | 0 | String representing the absolute pathname (path + filename) of the chosen file; this value is identical to the one returned by the CommonDialogShowOpen method Example "C:\myfolder\myfile.mp3".
COMMON_DLG_PATH | 1 | String representing the absolute path where the file is located (without the filename). Example "C:\myfolder\".
COMMON_DLG_FILENAME | 2 | String representing the filename of the chosen file. Example "myfile.mp3".
COMMON_DLG_FILENAME_NOEXT | 3 | String representing the filename of the chosen file without the extension. Example "myfile".
COMMON_DLG_EXT | 4 | String representing the extension of the chosen file. Example "mp3".

Return value

Value | Meaning
Empty string | Information not available or an error occurred.
Valid string | The requested information.


CommonDialogShowOpen method

CommonDialogShowOpen method

Remarks

Displays the standard dialog box used to select a file for opening. This method allows accessing filenames containing Unicode characters from development environments whose common dialog components don't manage Unicode natively like the "Microsoft Common Dialog Control" (ComDlg32.ocx) used by Visual Basic 6.

After choosing an input file, you can access more detailed information about it through the CommonDialogGetInfoFromLastOpen method.

For further information about dealing with Unicode characters, check the How to manage Unicode characters in filenames and tags tutorial.

Syntax

[Visual Basic]

control.CommonDialogShowOpen (

strDialogTitle as string,

strInitialDirectory as string,

strFilter as string,

nFilterIndex as integer

) as String

[C++]

LPCTSTR control.CommonDialogShowOpen (

BSTR strDialogTitle,

BSTR strInitialDirectory,

BSTR strFilter,

short *nFilterIndex

);

Parameter | Description
strDialogTitle | String representing the caption text of the dialog box.
strInitialDirectory | String representing the path of the directory where the browsing starts from.
strFilter | String representing the filter that let users limit which filenames appear for selection.
nFilterIndex | Reference that, on return from the method call, will contain the 1-based index of the filter selected by the user.

Return value

Value | Meaning
Empty string | The user pressed the Cancel button or didn't selected any file.
Valid string | The absolute pathname of the chosen file.


CommonDialogShowSave method

CommonDialogShowSave method

Remarks

Displays the standard dialog box used to select a file for saving. This method allows accessing filenames containing Unicode characters from development environments whose common dialog components don't manage Unicode natively like the "Microsoft Common Dialog Control" (ComDlg32.ocx) used by Visual Basic 6.

After choosing a destination file, you can access more detailed information about it through the CommonDialogGetInfoFromLastSave method.

For further information about dealing with Unicode characters, check the How to manage Unicode characters in filenames and tags tutorial.

Syntax

[Visual Basic]

control.CommonDialogShowSave (

strDialogTitle as string,

strInitialDirectory as string,

strFilter as string,

nFilterIndex as integer

) as String

[C++]

LPCTSTR control.CommonDialogShowSave (

BSTR strDialogTitle,

BSTR strInitialDirectory,

BSTR strFilter,

short *nFilterIndex

);

Parameter | Description
strDialogTitle | String representing the caption text of the dialog box.
strInitialDirectory | String representing the path of the directory where the browsing starts from.
strFilter | String representing the filter that let users limit which filenames appear for selection.
nFilterIndex | Reference that, on return from the method call, will contain the 1-based index of the filter selected by the user.

Return value

Value | Meaning
Empty string | The user pressed the Cancel button or didn't selected any file.
Valid string | The absolute pathname of the chosen file.


DirectShowAutoLoadEnable method

DirectShowAutoLoadEnable method

Remarks

Enables/disables, for the given player, the automatic loading through installed DirectShow codecs of audio and video tracks not supported natively by the LoadSound method.

Syntax

[Visual Basic]

control.DirectShowAutoLoadEnable (

nPlayer as Integer

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.DirectShowAutoLoadEnable (

short nPlayer

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value that instructs the player to enable/disable the use DirectShow when the LoadSound method is invoked for audio/video format not supported natively.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | DirectShow usage is disabled
BOOL_TRUE | 1 | DirectShow usage is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


ForceSpeakersAssignment method

ForceSpeakersAssignment method

Remarks

Forces the speakers assignment on the given output device (sound card): some specific output device (for example the Maya EX7 sound card) will always return 2 speakers also if it supports up to 8 mono speakers: in this case the container application can force the speakers assignment anyway.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.ForceSpeakersAssignment (

nIndex as Integer

) as enumErrorCodes

[C++]

short control.ForceSpeakersAssignment (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the involved output device.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


FromMsToFormattedTime method

FromMsToFormattedTime method

Remarks

Given an amount of time, expressed in milliseconds, retrieves a string containing the formatted time using the following format [hh:mm:ss:ms(3)] in which hh is for hours, mm is for minutes, ss is for seconds and ms(3) are three characters representing the milliseconds.

For example "04:34:200" indicates a time of 0 hours, 4 minutes, 34 seconds and 200 milliseconds.

Syntax

[Visual Basic]

control.FromMsToFormattedTime (

nTimeInMs as Double,

bShowHour as enumBoolean,

bShowMs as enumBoolean,

strHourSeparator as String,

strMsSeparator as String,

nNumberOfMsDigits as Integer

) as String

[C++]

LPCTSTR control.FromMsToFormattedTime (

double nTimeinMs,

short bShowHour,

short bShowMs,

BSTR strHourSeparator,

BSTR strMsSeparator,

short nNumberOfMsDigits

);

Parameter

Description

nfTimeInMs

Time, expressed in milliseconds, to convert to a formatted string

bShowHour

Boolean value that specifies the player to avoid displaying the 'hour' position field.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't show hour value
BOOL_TRUE | 1 | Shows hour value

bShowMs

Boolean value that specifies the player to avoid displaying the 'milliseconds' position field.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't show milliseconds value
BOOL_TRUE | 1 | Shows milliseconds value

strHourSeparator

Character used to separate hours, minutes and seconds, typically this should be set to ":"

strMsSeparator

Character used to separate seconds and milliseconds, typically this should be set to "."

nNumberOfMsDigits

Number of characters used to represent milliseconds digits, can be in the range from 1 to 3; values outside this range will be automatically set to 3.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The formatted time


GetControlVersion method

GetControlVersion method

Remarks

Retrieves the version of the control.

Syntax

[Visual Basic]

control.GetControlVersion (

) as String

[C++]

LPCTSTR control.GetControlVersion (

);

Return value

String containing the control's version.


GetEngineVersion method

GetEngineVersion method

Remarks

Retrieves the version of the multimedia engine.

Syntax

[Visual Basic]

control.GetEngineVersion (

) as String

[C++]

LPCTSTR control.GetEngineVersion (

);

Return value

String containing the version of the multimedia engine.


GetFileTagField method

GetFileTagField method

Remarks

Retrieves content of a given specified tag field for the loaded sound.

The availability of this information requires a prior call to the ReadSoundInfo method.

Details about the use of Tags can be found inside the How to read TAG information in sound files and How to retrieve basic TAG information from the sound loaded into a player tutorials.

Syntax

[Visual Basic]

control.GetFileTagField (

nPlayer as Integer,

nField as enumTagFields

) as String

[C++]

LPCTSTR control.GetFileTagField (

short nPlayer,

short nField

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player whose information must be retrieved

iField

Number representing the zero-based index of the field that must be retrieved.

Supported values are the following:

Mnemonic constant | Value | Meaning
TAG_FIELD_TITLE | 0 | Title
TAG_FIELD_ARTIST | 1 | Artist
TAG_FIELD_ALBUM | 2 | Album
TAG_FIELD_YEAR | 3 | Year
TAG_FIELD_COMMENT | 4 | Comment
TAG_FIELD_TRACK | 5 | Track number
TAG_FIELD_GENRE_CODE | 6 | Genre code
TAG_FIELD_GENRE_STRING | 7 | Genre
TAG_FIELD_COMPOSER | 8 | Composer
TAG_FIELD_COPYRIGHT | 9 | Copyright
TAG_FIELD_SUBTITLE | 10 | Subtitle
TAG_FIELD_ALBUMARTIST | 11 | Album artist

Return value

Value | Meaning
Empty string | The information was not available or an error occurred (see the LastError property for further error details)
Valid string | The content of the requested tag field


GetHwnd method

GetHwnd method

Remarks

Retrieves the window handle (HWND) of the control. This method is useful when using the control in scripting languages like JavaScript where the HWND of the control is not directly accessible.

Syntax

[Visual Basic]

control.GetHwnd (

) as Long

[C++]

long control.GetHwnd (

);

Return value

Number representing the window handle (HWND) of the control.


GetMaxAvailablePlayers method

GetMaxAvailablePlayers method

Remarks

Retrieves the maximum number of players that can be allocated by the control.

Syntax

[Visual Basic]

control.GetMaxAvailablePlayers (

) as Integer

[C++]

short control.GetMaxAvailablePlayers (

);

Return value

Number representing the maximum number of players.


GetMp3CurrentFrame method

GetMp3CurrentFrame method

Remarks

Gets the MP3 frame that is currently being played.

Syntax

[Visual Basic]

control.GetMp3CurrentFrame (

nPlayer as Integer

) as Long

[C++]

long control.GetMp3CurrentFrame (

short nPlayer

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The frame being played


GetMp3Frames method

GetMp3Frames method

Remarks

Retrieves the number of frames for the song currently loaded into the specified player.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetMp3Frames (

nPlayer as Integer

) as Long

[C++]

long control.GetMp3Frames (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | The number of frames


GetMp3StreamTypeBitRate method

GetMp3StreamTypeBitRate method

Remarks

Retrieves the Bitrate (number of bits per second) for the song currently loaded into the specified player.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetMp3StreamTypeBitRate (

nPlayer as Integer

) as Long

[C++]

long control.GetMp3StreamTypeBitRate (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | The song bitrate


GetMp3StreamTypeLayer method

GetMp3StreamTypeLayer method

Remarks

Retrieves the MPEG layer for the song currently loaded into the specified player.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetMp3StreamTypeLayer (

nPlayer as Integer

) as Long

[C++]

long control.GetMp3StreamTypeLayer (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
1 | MPEG layer 1
2 | MPEG layer 2
3 | MPEG layer 3
Negative value | An error occurred (see the LastError property for further error details)


GetMp3StreamTypeLevel method

GetMp3StreamTypeLevel method

Remarks

Retrieves the MPEG level for the song currently loaded into the specified player.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetMp3StreamTypeLevel (

nPlayer as Integer

) as Long

[C++]

long control.GetMp3StreamTypeLevel (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
0 | MPEG 2.5
1 | MPEG 1
2 | MPEG 2
Negative value | An error occurred (see the LastError property for further error details)


GetMp3StreamTypeMode method

GetMp3StreamTypeMode method

Remarks

Retrieves the MPEG mode for the song currently loaded into the specified player.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetMp3StreamTypeMode (

nPlayer as Integer

) as Long

[C++]

long control.GetMp3StreamTypeMode (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
0 | Stereo
1 | Joint-stereo
2 | Dual-channel
3 | Single-channel
Negative value | An error occurred (see the LastError property for further error details)


GetMp3Tag2Data method

GetMp3Tag2Data method

Remarks

Retrieves the full binary contents of the ID3V2 tag for a MP3 sound. The overall tag size can be obtained through a call to the GetMp3Tag2Size method.

Details about the use of Tags and a sample of use of this method can be found on the How to read TAG information in sound files and How to retrieve basic TAG information from the sound loaded into a player tutorials.

Syntax

[Visual Basic]

control.GetMp3Tag2Data (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.GetMp3Tag2Data (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
pBuffer | Variant parameter containing the pointer to a pre-allocated destination buffer that will receive the ID3V2 data. Allocating/freeing this buffer is responsibility of the container application.
nBufferLen | Length in bytes of the destination buffer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful


GetMp3Tag2Size method

GetMp3Tag2Size method

Remarks

Retrieves the size of the ID3V2 tag (if any) for a MP3 song. The full tag binary contents can be obtained through a call to the GetMp3Tag2Data method.

Details about the use of Tags and a sample of use of this method can be found on the How to read TAG information in sound files and How to retrieve basic TAG information from the sound loaded into a player tutorials.

Syntax

[Visual Basic]

control.GetMp3Tag2Size (

nPlayer as Integer

) as Long

[C++]

long control.GetMp3Tag2Size (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
0 | No ID3V2 tag available
> 0 | The ID3V2 tag size


GetMp3TagVersion method

GetMp3TagVersion method

Remarks

Retrieves the version of MP3 tag(s) in the loaded sound: note that in the same sound can be present both tag versions 1.x (ID3V1) and 2.x (ID3V2). Further information about tags management can be found inside the How to read TAG information in sound files and How to retrieve basic TAG information from the sound loaded into a player tutorials.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetMp3TagVersion (

nPlayer as Integer

) as enumTagVersions

[C++]

short control.GetMp3TagVersion (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Mnemonic constant | Value | Meaning
ERR_xxx | Negative | The loaded sound is not in MP3 format or an error occurred (see the LastError property for further error details)
TAGVER_NONE | 0 | No tag available
TAGVER_1 | 1 | Tag ID3V1 is available
TAGVER_11 | 2 | Tag ID3V1.1 is available
TAGVER_2 | 3 | Tag ID3V2 is available
TAGVER_1_2 | 4 | Both tags ID3V1 and ID3V2 are available
TAGVER_11_2 | 5 | Both tags ID3V1.1 and ID3V2 are available


GetTagString method

GetTagString method

Remarks

Retrieves a tag string from the loaded sound. The availability of Tag strings and their total number can be checked using the IsTagAvailable method.

Due to their format, this method cannot be used with ID3V1 and ID3V2 Tags.

The availability of this information requires a prior call to the ReadSoundInfo method.

Details about the use of Tags and a sample of use of this method can be found on the How to read TAG information in sound files and How to retrieve basic TAG information from the sound loaded into a player tutorials.

Syntax

[Visual Basic]

control.GetTagString (

nPlayer as Integer,

nTagType as enumTagTypes,

nStringIndex as Integer

) as String

[C++]

LPCTSTR control.GetTagString (

short nPlayer,

short nTagType,

short nStringIndex

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTagType

The type of Tag whose string must be retrieved.

Supported values are the following:

Mnemonic constant | Value | Meaning
TAGTYPE_ICY | 2 | ICY Shoutcast tag
TAGTYPE_METADATA | 3 | Shoutcast metadata
TAGTYPE_OGG | 4 | OGG Vorbis tag
TAGTYPE_WMA | 5 | Window Media Audio tag
TAGTYPE_MP4 | 6 | MP4 tag
TAGTYPE_APE | 7 | APE tag
TAGTYPE_MIDI | 8 | MIDI tag

nStringIndex

The zero-based index of the string to obtain: the total number of available strings can be retrieved using the IsTagAvailable method.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The requested string


GetWavChunkBinaryInfo method

GetWavChunkBinaryInfo method

Remarks

Obtains binary contents a specific binary field of the WAV chunk available inside the loaded file. You can know if a certain chunk is available through the IsWavChunkAvailable method.

Syntax

[Visual Basic]

control.GetWavChunkBinaryInfo (

nPlayer as Integer,

nInfoField as enumWavChunkBinaryInfo,

pBuffer as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.GetWavChunkBinaryInfo (

short nPlayer,

short nInfoField,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nInfoField

Identifier of the needed field.

Supported values are the following:

Mnemonic value | Value | Meaning
WAV_CHUNK_CART_BIN_Reserved | 0 | Reserved for future expansion (CART chunk only)
WAV_CHUNK_BEXT_BIN_UMID_0 | 1 | Binary bytes of SMPTE UMID (BEXT chunk only)
WAV_CHUNK_BEXT_BIN_Reserved | 2 | Reserved for future expansion (BEXT chunk only)

pBuffer

Variant parameter containing the pointer to a pre-allocated destination buffer that will receive binary data. Allocating/freeing this buffer is responsibility of the container application.

nBufferLen

Length in bytes of the destination buffer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful


GetWavChunkNumericInfo method

GetWavChunkNumericInfo method

Remarks

Obtains a specific numeric value from a field of the WAV chunk available inside the loaded file. You can know if a certain chunk is available through the IsWavChunkAvailable method.

Syntax

[Visual Basic]

control.GetWavChunkNumericInfo (

nPlayer as Integer,

nInfoField as enumWavChunkNumericInfo

) as Long

[C++]

long control.GetWavChunkNumericInfo (

short nPlayer,

short nInfoField

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nInfoField

Identifier of the needed field.

Supported values are the following:

Mnemonic value | Value | Meaning
WAV_CHUNK_CART_NUM_LevelReference | 0 | Sample value for 0 dB reference (CART chunk only)
WAV_CHUNK_CART_NUM_PostTimer_Value_0 | 1 | Time marker after head value (CART chunk only)
WAV_CHUNK_CART_NUM_PostTimer_Value_1 | 2 | Time marker after head value (CART chunk only)
WAV_CHUNK_CART_NUM_PostTimer_Value_2 | 3 | Time marker after head value (CART chunk only)
WAV_CHUNK_CART_NUM_PostTimer_Value_3 | 4 | Time marker after head value (CART chunk only)
WAV_CHUNK_CART_NUM_PostTimer_Value_4 | 5 | Time marker after head value (CART chunk only)
WAV_CHUNK_CART_NUM_PostTimer_Value_5 | 6 | Time marker after head value (CART chunk only)
WAV_CHUNK_CART_NUM_PostTimer_Value_6 | 7 | Time marker after head value (CART chunk only)
WAV_CHUNK_CART_NUM_PostTimer_Value_7 | 8 | Time marker after head value (CART chunk only)
WAV_CHUNK_BEXT_NUM_TimeReferenceLow | 9 | First sample count since midnight low word (BEXT chunk only)
WAV_CHUNK_BEXT_NUM_TimeReferenceHigh | 10 | First sample count since midnight, high word (BEXT chunk only)
WAV_CHUNK_BEXT_NUM_Version | 11 | Version of the BWF; unsigned binary number (BEXT chunk only)

Return value

The value of the requested field


GetWavChunkStringInfo method

GetWavChunkStringInfo method

Remarks

Obtains a specific string value from a field of the WAV chunk available inside the loaded file. You can know if a certain chunk is available through the IsWavChunkAvailable method.

Syntax

[Visual Basic]

control.GetWavChunkStringInfo (

nPlayer as Integer,

nInfoField as enumWavChunkStringInfo

) as String

[C++]

LPCTSTR control.GetWavChunkStringInfo (

short nPlayer,

short nInfoField

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nInfoField

Identifier of the needed field.

Supported values are the following:

Mnemonic value | Value | Meaning
WAV_CHUNK_CART_STR_Version | 0 | Version of the data structure (CART chunk only)
WAV_CHUNK_CART_STR_Title | 1 | Title of cart audio sequence (CART chunk only)
WAV_CHUNK_CART_STR_Artist | 2 | Artist or creator name (CART chunk only)
WAV_CHUNK_CART_STR_CutID | 3 | Cut number identification (CART chunk only)
WAV_CHUNK_CART_STR_ClientID | 4 | Client identification (CART chunk only)
WAV_CHUNK_CART_STR_Category | 5 | Category ID, PSA, NEWS, etc. (CART chunk only)
WAV_CHUNK_CART_STR_Classification | 6 | Classification or auxiliary key (CART chunk only)
WAV_CHUNK_CART_STR_OutCue | 7 | Out cue text (CART chunk only)
WAV_CHUNK_CART_STR_StartDate | 8 | Start date YYYY-MM-DD (CART chunk only)
WAV_CHUNK_CART_STR_StartTime | 9 | Start time hh:mm:ss (CART chunk only)
WAV_CHUNK_CART_STR_EndDate | 10 | End date YYYY-MM-DD (CART chunk only)
WAV_CHUNK_CART_STR_EndTime | 11 | End time hh:mm:ss (CART chunk only)
WAV_CHUNK_CART_STR_ProducerAppID | 12 | Name of vendor or application (CART chunk only)
WAV_CHUNK_CART_STR_ProducerAppVersion | 13 | Version of producer application (CART chunk only)
WAV_CHUNK_CART_STR_UserDef | 14 | User defined text (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_0 | 15 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_1 | 16 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_2 | 17 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_3 | 18 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_4 | 19 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_5 | 20 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_6 | 21 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_7 | 22 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_URL | 23 | Uniform resource locator (CART chunk only)
WAV_CHUNK_CART_STR_TagText | 24 | Tag text (CART chunk only)
WAV_CHUNK_BEXT_STR_Description | 25 | Description of the sound sequence (BEXT chunk only)
WAV_CHUNK_BEXT_STR_Originator | 26 | Name of the originator (BEXT chunk only)
WAV_CHUNK_BEXT_STR_OriginatorReference | 27 | Reference of the originator (BEXT chunk only)
WAV_CHUNK_BEXT_STR_OriginationDate | 28 | Originator date yyyy-mm-dd (BEXT chunk only)
WAV_CHUNK_BEXT_STR_OriginationTime | 29 | Originator time hh-mm-ss (BEXT chunk only)
WAV_CHUNK_BEXT_STR_CodHistory | 30 | Coding history (BEXT chunk only)

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The requested string

Syntax

[Visual Basic]

control.GetWavChunkStringInfo (

nPlayer as Integer,

nInfoField as enumWavChunkStringInfo

) as Integer

[C++]

short control.GetWavChunkStringInfo (

short nPlayer,

short nInfoField

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nInfoField

Identifier of the needed field.

Supported values are the following:

Mnemonic value | Value | Meaning
WAV_CHUNK_CART_STR_Version | 0 | Version of the data structure (CART chunk only)
WAV_CHUNK_CART_STR_Title | 1 | Title of cart audio sequence (CART chunk only)
WAV_CHUNK_CART_STR_Artist | 2 | Artist or creator name (CART chunk only)
WAV_CHUNK_CART_STR_CutID | 3 | Cut number identification (CART chunk only)
WAV_CHUNK_CART_STR_ClientID | 4 | Client identification (CART chunk only)
WAV_CHUNK_CART_STR_Category | 5 | Category ID, PSA, NEWS, etc. (CART chunk only)
WAV_CHUNK_CART_STR_Classification | 6 | Classification or auxiliary key (CART chunk only)
WAV_CHUNK_CART_STR_OutCue | 7 | Out cue text (CART chunk only)
WAV_CHUNK_CART_STR_StartDate | 8 | Start date YYYY-MM-DD (CART chunk only)
WAV_CHUNK_CART_STR_StartTime | 9 | Start time hh:mm:ss (CART chunk only)
WAV_CHUNK_CART_STR_EndDate | 10 | End date YYYY-MM-DD (CART chunk only)
WAV_CHUNK_CART_STR_EndTime | 11 | End time hh:mm:ss (CART chunk only)
WAV_CHUNK_CART_STR_ProducerAppID | 12 | Name of vendor or application (CART chunk only)
WAV_CHUNK_CART_STR_ProducerAppVersion | 13 | Version of producer application (CART chunk only)
WAV_CHUNK_CART_STR_UserDef | 14 | User defined text (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_0 | 15 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_1 | 16 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_2 | 17 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_3 | 18 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_4 | 19 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_5 | 20 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_6 | 21 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_PostTimer_Fourcc_7 | 22 | Time marker after head FOURCC usage ID (CART chunk only)
WAV_CHUNK_CART_STR_URL | 23 | Uniform resource locator (CART chunk only)
WAV_CHUNK_CART_STR_TagText | 24 | Tag text (CART chunk only)
WAV_CHUNK_BEXT_STR_Description | 25 | Description of the sound sequence (BEXT chunk only)
WAV_CHUNK_BEXT_STR_Originator | 26 | Name of the originator (BEXT chunk only)
WAV_CHUNK_BEXT_STR_OriginatorReference | 27 | Reference of the originator (BEXT chunk only)
WAV_CHUNK_BEXT_STR_OriginationDate | 28 | Originator date yyyy-mm-dd (BEXT chunk only)
WAV_CHUNK_BEXT_STR_OriginationTime | 29 | Originator time hh-mm-ss (BEXT chunk only)
WAV_CHUNK_BEXT_STR_CodHistory | 30 | Coding history (BEXT chunk only)

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The requested string


GetWmaCodecString method

GetWmaCodecString method

Remarks

If the loaded sound has been encoded in WMA format, retrieves a string containing the friendly name of the WMA codec used for encoding the file.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetWmaCodecString (

nPlayer as Integer

) as String

[C++]

LPCTSTR control.GetWmaCodecString (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The requested string


HwMixingEnable method

HwMixingEnable method

Remarks

Enables/disables Hardware mixing for playback of the sound loaded into the given player.

If supported by the selected output device, DirectSound tries making use of hardware acceleration in order to improve performances and decrease CPU usage: with this method you can tell DirectSound to avoid using hardware acceleration. You can know if the output device, selected for the given player, supports Hardware acceleration through a call to the HwMixingIsSupported method.

Syntax

[Visual Basic]

control.HwMixingEnable (

nPlayer as Integer

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.HwMixingEnable (

short nPlayer

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value that specifies the player to enable/disable the use of Hardware mixing.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't use Hardware mixing
BOOL_TRUE (default) | 1 | Uses Hardware mixing

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


HwMixingIsSupported method

HwMixingIsSupported method

Remarks

Determines if Hardware mixing is available on the output device selected for the given player.

Syntax

[Visual Basic]

control.HwMixingIsSupported (

nPlayer as Integer

) as boolean

[C++]

BOOL control.HwMixingIsSupported (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
FALSE | Hardware mixing is not supported
TRUE | Hardware mixing is supported


InitDJSystem method

InitDJSystem method

Remarks

Initializes the control: the call to this method (or in alternative to the IniDJSystemEx method) is always mandatory when the control is instanced inside the container form and must be performed before calling any other method that will use any player related functionality, possibly from the initialization routine of the container form or dialog: calling this method inside the constructor function of the container form will not work and could cause unpredictable results.

In case the component should be instanced in conjunction with the recorder component and/or the editor component, this method should be called before calling the initialization methods of the other components (InitRecordingSystem for the recorder component and InitEditor for the editor component).

The purpose of this initialization method is to allocate the desired number of players (*), to synchronize the control with the container form, to set the output device (sound card) for the first 4 allocated players (players exceeding the fourth one will automatically output their sound flow into the system default sound card) and, eventually, setting the DirectX buffer length in order to reduce the latency time.

Use the value returned by the GetOutputDevicesCount method in order to know how many output devices are currently installed on the system and the GetOutputDeviceDesc method in order to retrieve the friendly name of every output device.

The output device for a certain player can be changed at a later time using the StreamOutputDeviceSet method.

For further details about "multi-player" management, take a look to the How to deal with multi-player features section.

For further details about output devices management, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.InitDJSystem (

nTotalPlayers as short,

hWndParent as OLE_HANDLE,

nOutput0 as Integer,

nOutput1 as Integer,

nOutput2 as Integer,

nOutput3 as Integer

) as Integer

[C++]

short control.InitDJSystem (

short nTotalPlayers,

OLE_HANDLE hWndParent,

short nOutput0,

short nOutput1,

short nOutput2,

short nOutput3

);

Parameter

Description

nTotalPlayers

Number of players (*) that must be allocated by the control.

hWndParent

Handle of the container (parent) window: for Visual Basic is represented by the hWnd property of the container form, while for Visual C++ is represented by the call to the container dialog box GetSafeHwnd member function: the return value of this call represents a HWND so it must be cast to OLE_HANDLE to avoid compiler errors

nOutput0

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 0 (pass 0 for using the system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

Check the How to use the control in your projects section for details about obtaining output devices. If the multimedia engine shouldn't find any enabled or valid output device, the container application would be notified through the WarnNoOutputDevice event.

nOutput1

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 1 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

nOutput2

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 2 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

nOutput3

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 3 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

Examples of use of the nOutputX parameters

As mentioned inside the tutorials, you can obtain the number of sound cards installed inside the system by invoking the GetOutputDevicesCount method and storing its return value into a numeric variable named, for example, nCount.

Example 1: nCount value is 1

Suppose that you must allocate two players (0 and 1); you have only one sound card that, for exclusion, will be the default one, so you can set the following values:

nTotalPlayers = 2 (*)

hWndParent = your form or dialog box HWND

nOutput0 = 0 (use default sound card)

nOutput1 = 0 (use default sound card)

nOutput2 = 0 (value ignored)

nOutput3 = 0 (value ignored)

Example 2: nCount value is 3

Call the GetOutputDeviceDesc method nCount times (once for every sound card) using a zero-based index in order to obtain every sound card friendly name (suppose you obtain A, B and C).

Now suppose that you must allocate four players (0, 1, 2 and 3) that will redirect their output in the following way:

- player 0 and player 1 must output to the system default sound card A.

- player 2 must output to sound card C.

- player 3 must output to sound card B.

You will have to call the InitDJSystem method with the following parameters:

nTotalPlayers = 4 (*)

hWndParent = your form or dialog box HWND

nOutput0 = 0

nOutput1 = 0

nOutput2 = 2

nOutput3 = 1

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Value > 0 | The method completed successfully and this value represents the number of allocated players. In order to know if all of the instanced players have been set to operate with a valid output device, you should check the value of the LastError property: if it should have value 2 (WARNING_INVALID_DEVICE), this would mean that one or more of the nOutputX parameters where set to an invalid output device: in this case a reset of the multimedia engine (ResetEngine method) and of the control (ResetControl method) would be needed in order to set correct output devices.

(*) 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.


InitDJSystemEx method

InitDJSystemEx method

Remarks

Initializes the control: the call to this method or to the IniDJSystem method is always mandatory when the control is instanced inside the container form and must be performed before calling any other method that will use any player related functionality, possibly from the initialization routine of the container form or dialog: calling this method inside the constructor function of the container form will not work and could cause unpredictable results.

In case the component should be instanced in conjunction with the recorder component and/or the editor component, this method should be called before calling the initialization methods of the other components (InitRecordingSystem for the recorder component and InitEditor for the editor component).

The purpose of this initialization method is to allocate the desired number of players (*), to synchronize the control with the container form, to set the output device (sound card) for the first 4 allocated players (players exceeding the fourth one will automatically output their sound flow into the system default sound card) and, eventually, setting the DirectX buffer length in order to reduce the latency time.

Use the value returned by the GetOutputDevicesCount method in order to know how many output devices are currently installed on the system and the GetOutputDeviceDesc method in order to retrieve the friendly name of every output device.

The output device for a certain player can be changed at a later time using the StreamOutputDeviceSet method.

For further details about "multi-player" management, take a look to the How to deal with multi-player features section.

For further details about output devices management, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.InitDJSystemEx (

nTotalPlayers as short,

hWndParent as OLE_HANDLE,

nOutput0 as Integer,

nOutput1 as Integer,

nOutput2 as Integer,

nOutput3 as Integer,

nBufferLength as Integer

) as Integer

[C++]

short control.InitDJSystemEx (

short nTotalPlayers,

OLE_HANDLE hWndParent,

short nOutput0,

short nOutput1,

short nOutput2,

short nOutput3,

short nBufferLength

);

Parameter

Description

nTotalPlayers

Number of players (*) that must be allocated by the control.

hWndParent

Handle of the container (parent) window: for Visual Basic is represented by the hWnd property of the container form, while for Visual C++ is represented by the call to the container dialog box GetSafeHwnd member function: the return value of this call represents a HWND so it must be cast to OLE_HANDLE to avoid compiler errors

nOutput0

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 0 (pass 0 for using the system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

Check the How to use the control in your projects section for details about obtaining output devices. If the multimedia engine shouldn't find any enabled or valid output device, the container application would be notified through the WarnNoOutputDevice event.

nOutput1

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 1 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

nOutput2

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 2 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

nOutput3

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 3 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

nBufferLength

Number representing the length in milliseconds of the DirectX buffer. By default the buffer size contains 500 milliseconds: see the How to deal with latency section for further details about this parameter.

Examples of use of the nOutputX parameters

As mentioned inside the tutorials, you can obtain the number of sound cards installed inside the system by invoking the GetOutputDevicesCount method and storing its return value into a numeric variable named, for example, nCount.

Example 1: nCount value is 1

Suppose that you must allocate two players (0 and 1); you have only one sound card that, for exclusion, will be the default one, so you can set the following values:

nTotalPlayers = 2 (*)

hWndParent = your form or dialog box HWND

nOutput0 = 0 (use default sound card)

nOutput1 = 0 (use default sound card)

nOutput2 = 0 (value ignored)

nOutput3 = 0 (value ignored)

Example 2: nCount value is 3

Call the GetOutputDeviceDesc method nCount times (once for every sound card) using a zero-based index in order to obtain every sound card friendly name (suppose you obtain A, B and C).

Now suppose that you must allocate four players (0, 1, 2 and 3) that will redirect their output in the following way:

- player 0 and player 1 must output to the system default sound card A.

- player 2 must output to sound card C.

- player 3 must output to sound card B.

You will have to call the InitDJSystem method with the following parameters:

nTotalPlayers = 4 (*)

hWndParent = your form or dialog box HWND

nOutput0 = 0

nOutput1 = 0

nOutput2 = 2

nOutput3 = 1

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Value > 0 | The method completed successfully and this value represents the number of allocated players. In order to know if all of the instanced players have been set to operate with a valid output device, you should check the value of the LastError property: if it should have value 2 (WARNING_INVALID_DEVICE), this would mean that one or more of the nOutputX parameters where set to an invalid output device: in this case a reset of the multimedia engine (ResetEngine method) and of the control (ResetControl method) would be needed in order to set correct output devices.

(*) 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.


InitDriversType method

InitDriversType method

Remarks

Initializes the type of drivers (DirectSound and/or ASIO or WASAPI) for devices managed by the control. This method can be called only once and will affect any other instance of the control inside the application. If the control should be used in conjunction with the Active Sound Recorder control, this one would be affected too.

Next calls to this method will be ignored until the multimedia engine has been reset through the ResetEngine method: in this specific case the InitDriversType method must be called after the ResetEngine method but before the ResetControl method.

The call to this method must be performed before calling any other method that will access the component, possibly in the container form initialization function: calling this method inside the constructor function of the container form will not work and could cause unpredictable results.

If only DirectSound devices are needed, a call to this method can be omitted; if ASIO or WASAPI devices are needed, this method should be called before any other method of the control because it will affect output devices enumeration performed through GetOutputDevicesCount and GetOutputDeviceDesc methods.

For further information about ASIO drivers management, refer to the How to manage ASIO drivers tutorial.

For further details about the use of WASAPI see the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.InitDriversType (

nDriverType as enumDriverTypes

) as enumErrorCodes

[C++]

short control.InitDriversType (

short nDriverType

);

Parameter

Description

nDriverType

Type of drivers managed by the control.

Supported values are the following:

Mnemonic constant

Value

Meaning

DRIVER_TYPE_DIRECT_SOUND (default)

0

Only DirectSound devices are supported and ASIO devices will be ignored.

DRIVER_TYPE_ASIO

1

Only ASIO devices are supported and DirectSound devices will be ignored.

DRIVER_TYPE_BOTH_DS_FIRST

2

Both DirectSound and ASIO devices are supported, DirectSound output devices will be listed first when enumerating output devices through GetOutputDevicesCount and GetOutputDeviceDesc methods.

If a certain sound card supports both DirectSound and ASIO drivers, it will be seen as two separate sound cards; it's in any case important to know that being able to manage both DirectSound and ASIO drivers at the same time is not guaranteed to be supported by all sound cards.

IMPORTANT NOTES:

· when using this setting for playback of video clips in conjunction with a DirectSound sound card, you could hear the audio stream having a noticeable delay respect to the video stream: this can be usually reduced/eliminated by lowering the value of the BufferLength property around 150 milliseconds.
· when using this setting for playback of sound files, on DirectSound output devices you may note a certain slowness of commands like PauseSound or SeekSound: this can be reduced by lowering the value of the BufferLength property around 100-150 milliseconds.

DRIVER_TYPE_BOTH_ASIO_FIRST

3

Both DirectSound and ASIO devices are supported, ASIO devices will be listed first when enumerating output devices through GetOutputDevicesCount and GetOutputDeviceDesc methods.

If a certain sound card supports both DirectSound and ASIO drivers, it will be seen as two separate sound cards; it's in any case important to know that being able to manage both DirectSound and ASIO drivers at the same time is not guaranteed to be supported by all sound cards.

IMPORTANT NOTES:

· when using this setting for playback of video clips in conjunction with a DirectSound sound card, you could hear the audio stream having a noticeable delay respect to the video stream: this can be usually reduced/eliminated by lowering the value of the BufferLength property around 150 milliseconds.
· when using this setting for playback of sound files, on DirectSound output devices you may note a certain slowness of commands like PauseSound or SeekSound: this can be reduced by lowering the value of the BufferLength property around 100-150 milliseconds.

DRIVER_TYPE_WASAPI

4

Only WASAPI devices are supported: this setting can be only applied under Windows Vista and later versions.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


InternetSettingsGet method

InternetSettingsGet method

Remarks

Obtains Internet related settings that will affect the loading of Internet stream through the LoadInternetStream method. Current settings can be modified through the InternetSettingsSet method.

For further details about Internet streams support see the How to play Internet streams and radio stations section.

Syntax

[Visual Basic]

control.InternetSettingsGet (

nSetting as enumInternetSetting,

nSettingValue as Long

) as enumErrorCodes

[C++]

short control.InternetSettingsGet (

short nDriverType,

long *nSettingValue

);

Parameter

Description

nSetting

Setting whose value must be retrieved.

Supported values are the following:

Mnemonic constant | Value | Meaning
INET_SETTING_BUFFER_LENGTH | 0 | Length of the download buffer expressed in milliseconds
INET_SETTING_CONNECT_TIMEOUT | 1 | The time to wait for a connection expressed in milliseconds
INET_SETTING_READ_TIMEOUT | 2 | The time to wait for a server to deliver more data for an internet stream expressed in milliseconds
INET_SETTING_PREBUFF_PERC | 3 | Amount to pre-buffer when opening internet streams expressed in percentage
INET_SETTING_PREBUFF_PLAYBACK_PERC | 4 | Amount of pre-buffer before allowing playback of the Internet stream expressed in percentage
INET_SETTING_FTP_PASSIVE_MODE | 5 | Use of passive mode in FTP connections: if set to 1 passive mode is enabled, if set to 0 passive mode is disabled.

nSettingValue

Reference that, on return from the method call, will contain the value of the setting.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


InternetSettingsSet method

InternetSettingsSet method

Remarks

Modifies Internet related settings that will affect the loading of Internet stream through the LoadInternetStream method. Current settings can be obtained through the InternetSettingsGet method.

For further details about Internet streams support see the How to play Internet streams and radio stations section.

Syntax

[Visual Basic]

control.InternetSettingsSet (

nSetting as enumInternetSetting,

nSettingValue as Int32

) as enumErrorCodes

[C++]

short control.InternetSettingsSet (

enumInternetSetting nDriverType,

Int32 nSettingValue

);

Parameter

Description

nSetting

Setting whose value must be retrieved.

Supported values are the following:

Mnemonic constant | Value | Meaning
INET_SETTING_BUFFER_LENGTH | 0 | Length of the download buffer expressed in milliseconds. The default buffer length is 5000 milliseconds (5 seconds). The buffer length should be larger than the length of the playback buffer stored inside the BufferLength property, otherwise the stream is likely to stall soon after starting playback.
INET_SETTING_CONNECT_TIMEOUT | 1 | The time to wait for a connection expressed in milliseconds. The default timeout is 5000 milliseconds (5 seconds).
INET_SETTING_READ_TIMEOUT | 2 | The time to wait for a server to deliver more data for an internet stream expressed in milliseconds. The default timeout is 0, meaning that there is no timeout.
INET_SETTING_PREBUFF_PERC | 3 | Amount to pre-buffer when opening internet streams expressed in percentage. The default value is 75%.
INET_SETTING_PREBUFF_PLAYBACK_PERC | 4 | Amount of pre-buffer before allowing playback of the Internet stream expressed in percentage. The default value is 90%.
INET_SETTING_FTP_PASSIVE_MODE | 5 | Use of passive mode in FTP connections: if set to 1 passive mode is enabled, if set to 0 passive mode is disabled. By default passive mode is enabled.

nSettingValue

The new value of the setting.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


IsDirectShowLoadedFile method

IsDirectShowLoadedFile method

Remarks

Checks if the file loaded into the given player is rendered through DirectShow or natively.

Syntax

[Visual Basic]

control.IsDirectShowLoadedFile (

nPlayer as Integer

) as boolean

[C++]

BOOL control.IsDirectShowLoadedFile (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
FALSE | The loaded file is rendered natively
TRUE | The loaded file is rendered through DirectShow


IsDirectX8Avail method

IsDirectX8Avail method

Remarks

Tells if DirectX version 8 or higher is currently installed on the system. Through this method it's possible to know if we can create Equalizer bands to apply to the playing sound: see the How to create and use an equalizer section for further details.

Syntax

[Visual Basic]

control.IsDirectX8Avail (

) as boolean

[C++]

BOOL control.IsDirectX8Avail (

);

Return value

Value | Meaning
FALSE | DirectX version 8 or higher is not available
TRUE | DirectX version 8 or higher is available


IsEAXAvailable method

IsEAXAvailable method

Remarks

Checks if EAX effects are currently supported by the output device (sound card) currently selected for the given player: see the How to apply special effects to a playing sound section for further details.

Note that, although some sound card driver will tell you that it supports EAX, this doesn't guarantees that its EAX implementation quality will be the same available for Creative sound cards.

Syntax

[Visual Basic]

control.IsEAXAvailable (

nPlayer as Integer

) as boolean

[C++]

BOOL control.IsEAXAvailable (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
FALSE | EAX effects are not available on the given player
TRUE | EAX effects are available on the given player


IsEAXAvailableOnOutputDevice method

IsEAXAvailableOnOutputDevice method

Remarks

Checks if EAX effects are currently supported by the given output device (sound card): see the How to apply special effects to a playing sound section for further details.

Note that, although some sound card driver will tell you that it supports EAX, this doesn't guarantees that its EAX implementation quality will be the same available for Creative sound cards.

Syntax

[Visual Basic]

control.IsEAXAvailableOnOutputDevice (

nIndex as Integer

) as boolean

[C++]

BOOL control.IsEAXAvailableOnOutputDevice (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the output device whose friendly name must be retrieved

Return value

Value | Meaning
FALSE | EAX effects are not available on the given output device
TRUE | EAX effects are available on the given output device


IsTagAvailable method

IsTagAvailable method

Remarks

Verifies if the loaded sound contains Tag information and, in case of multi-string Tags separated by NULL characters (like OGG Vorbis), returns the number of available strings. These strings can be retrieved one by one at a later time using the GetTagString method.

Details about the use of Tags can be found inside the How to read TAG information in sound files and How to retrieve basic TAG information from the sound loaded into a player tutorials.

Syntax

[Visual Basic]

control.IsTagAvailable (

nPlayer as Integer,

nTagType as enumTagTypes

) as Integer

[C++]

short control.IsTagAvailable (

short nPlayer,

short nTagType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTagType

The type of Tag whose presence we need to check.

Supported values are the following:

Mnemonic value | Value | Meaning
TAGTYPE_ID3V1 | 0 | MP3 ID3V1 tag
TAGTYPE_ID3V2 | 1 | MP3 ID3V2 tag
TAGTYPE_ICY | 2 | ICY Shoutcast tag
TAGTYPE_METADATA | 3 | Shoutcast metadata
TAGTYPE_OGG | 4 | OGG Vorbis tag
TAGTYPE_WMA | 5 | Window Media Audio tag
TAGTYPE_MP4 | 6 | MP4 tag
TAGTYPE_APE | 7 | APE tag
TAGTYPE_MIDI | 8 | MIDI tag

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
0 | The requested Tag is not available inside the loaded sound
>= 1 | The requested Tag is available inside the loaded sound and this return value gives the number of found strings.


IsWavChunkAvailable method

IsWavChunkAvailable method

Remarks

Verifies if a specific WAV chunk is available inside the loaded file.

Single fields of the chunk can be retrieved one by one using the GetWavChunkStringInfo, GetWavChunkNumericInfo and GetWavChunkBinaryInfo methods.

Syntax

[Visual Basic]

control.IsWavChunkAvailable (

nPlayer as Integer,

strChunkId as String

) as Integer

[C++]

short control.IsWavChunkAvailable (

short nPlayer,

LPCTSTR strChunkId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strChunkId

String representing the identifier of the chunk whose presence must be verified

Supported values are the following:

String value | Meaning
CART | Check CART chunk availability
BEXT | Check BEXT chunk availability

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
0 | The requested chunk is not available inside the loaded sound
> 0 | The requested chunk is available inside the loaded sound


IsWmaAvailable method

IsWmaAvailable method

Remarks

Tells if the Microsoft Windows Media Format modules, needed for managing WMA files, are available inside the system.

Syntax

[Visual Basic]

control.IsWmaAvailable (

) as Boolean

[C++]

BOOL control.IsWmaAvailable (

);

Return value

Value | Meaning
FALSE | WMA is not available
TRUE | WMA is available


ReadSoundInfo method

ReadSoundInfo method

Remarks

Obtains information about the loaded sound and about embedded Tags. When a sound is loaded, in order to speed up its availability for playback, the only immediately available information is its duration: further information can be retrieved at a later time calling this method.

Syntax

[Visual Basic]

control.ReadSoundInfo (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.ReadSoundInfo (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


RequestSoundBPM method

RequestSoundBPM method

Remarks

Analyses the loaded song BPM (Beats Per Minute): useful when the automatic BPM detection has been disabled through a call to the SetAutomaticBPM method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

Once the BPM has been calculated, the container application will be notified about the detected BPM through the BPMAvailable event.

For further details about BPM detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.RequestSoundBPM (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.RequestSoundBPM (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


RequestSoundExportToWav method

RequestSoundExportToWav method

Remarks

Requests the exporting of the sound loaded inside the given player into a file in WAV format: the destination WAV file can be stored in memory or on disk.

During the export phase, the container application is notified about the exporting advancement through the following events: ExportToWavStart, ExportToWavPerc and ExportToWavStop.

If the ExportToWavStop event reports a success, the container application can load the exported WAV file from disk or, if the destination file has been stored in memory, can copy the full WAV buffer through the CopyExportedWavToMemory method.

For further details about exporting a sound to a file in WAV format take a look to the How to export the loaded song into a WAV file section.

Syntax

[Visual Basic]

control.RequestSoundExportToWav (

nPlayer as Integer,

strPathname as String,

nStartPosInMs as Long,

nFinalPosInMs as Long

) as enumErrorCodes

[C++]

short control.RequestSoundExportToWav (

short nPlayer,

LPCTSTR strPathname,

long nStartPosInMs,

long nFinalPosInMs

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

strPathname

Absolute pathname of the destination file in WAV format: if empty, the destination WAV file will be stored in memory. In this last case the memory buffer contents can be retrieved through the CopyExportedWavToMemory method

nStartPosInMs

Number representing the initial position, expressed in milliseconds, where the export of the loaded sound will begin. This value must be set to 0 in order to export from the sound beginning.

nFinalPosInMs

Number representing the final position, expressed in milliseconds, where the export of the loaded sound will end. This value must be set to -1 in order to export till the sound end.

The difference between nFinalPosInMs and nStartPosInMs must be at least 500 milliseconds: smaller ranges will be automatically adjusted accordingly.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


ResetControl method

ResetControl method

Remarks

Re-initialises the control after a reset of the multimedia engine: the call to this method is mandatory after a call to the ResetEngine method. The purpose of this method is mostly identical to the InitDJSystem method and shares the same parameters.

Syntax

[Visual Basic]

control.ResetControl (

nTotalPlayers as short,

hWndParent as OLE_HANDLE,

nOutput0 as Integer,

nOutput1 as Integer,

nOutput2 as Integer,

nOutput3 as Integer

)

[C++]

void control.ResetControl (

short nTotalPlayers,

OLE_HANDLE hWndParent,

short nOutput0,

short nOutput1,

short nOutput2,

short nOutput3

);

Parameter

Description

nTotalPlayers

Number of players that must be allocated by the control: if the requested number exceed the maximum allowed by the control you purchased (*) then the number will be cut to the number of available players

hWndParent

Handle of the container (parent) window: for Visual Basic is represented by the hWnd property of the container form, while for Visual C++ is represented by the call to the container dialog box GetSafeHwnd member function: the return value of this call represents a HWND so it must be cast to OLE_HANDLE to avoid compiler errors

nOutput0

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 0 (pass 0 for using the system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

Check the How to use the control in your projects section for details about obtaining output devices.

If the multimedia engine shouldn't find any enabled or valid output device, the container application would be notified through the WarnNoOutputDevice event.

nOutput1

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 1 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

nOutput2

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 2 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

This parameter is ignored when using the Light edition of the control.

nOutput3

Number representing the zero-based index of the output device (sound card) that will be used for playback by player 3 (use 0 for system default output device). If the parameter is set to -1, the specific player can be used also in absence of a sound card, for example for performing a waveform analysis.

This parameter is ignored when using the Light edition or Standard edition of the control.

Return value

None


ResetEngine method

ResetEngine method

Remarks

Resets the multimedia engine: this method can be used in order to enumerate again available sound devices which could have been plugged or unplugged into a USB port; the container application can be notified when a USB device is plugged or unplugged through the DeviceChange event (On Windows XP) or through the events CoreAudioDeviceAdded, CoreAudioDeviceRemoved and CoreAudioDeviceDefaultChange (on Windows Vista and higher versions).

Immediately after calling this method it's mandatory to make a call to the ResetControl method, on each of the instanced controls, in order to re-initialize the control(s).

By design the CoreAudioDeviceDefaultChange event is only sent to the first instance of the component: due to the fact that all instances of the component share the same instance of the multimedia engine, it's very important that ResetEngine is called only once from this specific instance of the component, as it will affect all of the other instances, and that you call ResetControl from all of the instances or you would experience the ERR_INVALID_PLAYER error on next calls to methods of the control.

In case the component should be used in conjunction with the sound recorder and/or sound editor components, you should call the ResetControl method of these components as well.

Syntax

[Visual Basic]

control.ResetEngine (

)

[C++]

void control.ResetEngine (

);


SetAutomaticBPM method

SetAutomaticBPM method

Remarks

Enable/disables the automatic BPM (Beat Per Minute) detection during the loading of a sound through one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory: the automatic BPM detection is enabled by default: disabling the automatic BPM detection will result in a faster load.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

When the automatic BPM detection is enabled, the container application will be notified about the detected BPM through the BPMAvailable event.

When the automatic BPM detection is disabled, the loaded song BPM can be requested at any time using the RequestSoundBPM method.

For further details about BPM detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.SetAutomaticBPM (

bAutomatic as enumBoolean

)

[C++]

void control.SetAutomaticBPM (

short bAutomatic

);

Parameter

Description

bAutomatic

Boolean value that specifies to execute the automatic BPM detection

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Automatic BPM detection is disabled
BOOL_TRUE | 1 | Automatic BPM detection is enabled (default)

Return value

None


SetNetAgent method

SetNetAgent method

Remarks

Sets the string identifying the net user agent when a link to a remote server is requested, for example when trying to load a stream from a ShoutCAST server or when acting as a source for a ShoutCAST server.

Syntax

[Visual Basic]

control.SetNetAgent (

strNetAgent as String

)

[C++]

void control.SetNetAgent (

LPCTSTR strNetAgent

);

Parameter | Description
strNetAgent | String containing the user agent. By default this string is set to "ADJSTUD/version" where "version" indicates the current version of the multimedia engine, i.e. "ADJSTUD/8.0.0.0"

Return value

None


SetProxyConfiguration method

SetProxyConfiguration method

Remarks

Modifies settings of an eventual proxy server for accessing the Internet.

Syntax

[Visual Basic]

control.SetProxyConfiguration (

bUseProxy as enumBoolean,

strHost as String,

nPort as Long,

strUsername as String,

strPassword as String

)

[C++]

void control.SetProxyConfiguration (

short bUseProxy,

LPCTSTR strHost,

long nPort,

LPCTSTR strUsername,

LPCTSTR strPassword

);

Parameter

Description

bUseProxy

Boolean value stating if there is the need to make use of a proxy server for accessing the Internet.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Don't use a proxy server
BOOL_TRUE | 1 | Use a proxy server

strHost

String containing the proxy host address

nPort

Number of the proxy's port

strUsername

String containing the proxy's username

strPassword

String containing the proxy's password

Return value

None


SetRewindOnEOF method

SetRewindOnEOF method

Remarks

Enable/disables the automatic rewinding to position 0 on a player that reaches the end of the loaded song playback.

Syntax

[Visual Basic]

control.SetRewindOnEOF (

bRewind as enumBoolean

)

[C++]

short control.SetRewindOnEOF (

short bRewind

);

Parameter

Description

bRewind

Boolean value that specifies if the player needs to rewind the song position after reaching the end of the song

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Automatic rewind is disabled
BOOL_TRUE | 1 | Automatic rewind is enabled (default)

Return value

None


SilenceDetectionOnFile method

SilenceDetectionOnFile method

Remarks

Performs the calculation of silent portions at the start and end of the given sound file: differently from the SilenceDetectionOnPlayerRequest and SilenceDetectionOnPlayer methods, the sound file doesn't need to be loaded inside a player.

Supported audio file formats are the same mentioned inside the documentation of the LoadSound method. Video files are not supported by this method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

control.SilenceDetectionOnFile (

strPathname as String,

nThresholdInitial as Long,

nThresholdFinal as Long,

nInitialPosition as Long,

nFinalPosition as Long,

nSoundDuration as Long

) as enumErrorCodes

[C++]

short control.SilenceDetectionOnFile (

LPCTSTR strPathname,

long nThresholdInitial,

long nThresholdFinal,

long *nInitialPosition,

long *nFinalPosition,

long *nSoundDuration

);

Parameter | Description
strPathname | Absolute pathname of the sound file to analyze.
nThresholdInitial | Number representing the silence threshold at the start of the loaded sound: can assume values from 0 (no sound) to 32767 (max volume).
nThresholdFinal | Number representing the silence threshold at the end of the loaded sound: can assume values from 0 (no sound) to 32767 (max volume).
nInitialPosition | Reference that, on return from the method call, will contain the detected position, expressed in milliseconds, where audible sound begins.
nFinalPosition | Reference that, on return from the method call, will contain the detected position, expressed in milliseconds, where audible sound ends.
nSoundDuration | Reference that, on return from the method call, will contain the duration, expressed in milliseconds, of the sound file being analyzed.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SilenceDetectionOnPlayer method

SilenceDetectionOnPlayer method

Remarks

Performs the calculation of silent portions at the start and end of the sound loaded inside the given player: useful when the automatic silence detection has been disabled through a call to the SilenceDetectionOnPlayerLoadAutoSet method.

Differently from the SilenceDetectionOnPlayerRequest method, where silence detection is performed inside a secondary thread, in this case silence detection is performed inside the main thread so, when the method returns, silence positions are immediately available and there is no need to wait for the SilencePositionAvailable event.

The possibility to detect sound silence directly on a sound file, without the need to load it inside a player, is given by the SilenceDetectionOnFile method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

control.SilenceDetectionOnPlayer (

nPlayer as Integer,

nThresholdInitial as Long,

nThresholdFinal as Long,

nInitialPosition as Long,

nFinalPosition as Long

) as enumErrorCodes

[C++]

short control.SilenceDetectionOnPlayer (

short nPlayer,

long nThresholdInitial,

long nThresholdFinal,

long *nInitialPosition,

long *nFinalPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nThresholdInitial | Number representing the silence threshold at the start of the loaded sound: can assume values from 0 (no sound) to 32767 (max volume).
nThresholdFinal | Number representing the silence threshold at the end of the loaded sound: can assume values from 0 (no sound) to 32767 (max volume).
nInitialPosition | Reference that, on return from the method call, will contain the detected position, expressed in milliseconds, where audible sound begins
nFinalPosition | Reference that, on return from the method call, will contain the detected position, expressed in milliseconds, where audible sound ends

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SilenceDetectionOnPlayerLoadAutoSet method

SilenceDetectionOnPlayerLoadAutoSet method

Remarks

Enable/disables the automatic detection of silent sound's portions during the loading of a sound through one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory: the automatic silence detection is disabled by default.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

When the automatic silence detection is enabled, the container application will be notified about initial and final positions of silent portions at the start and end of loaded songs through the SilencePositionAvailable event.

When the automatic silence detection is disabled, the loaded song silence can be requested at any time calling the SilenceDetectionOnPlayerRequest method.

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

control.SilenceDetectionOnPlayerLoadAutoSet (

bAutomatic as enumBoolean,

nThresholdInitial as Long,

nThresholdFinal as Long

)

[C++]

void control.SilenceDetectionOnPlayerLoadAutoSet (

short bAutomatic,

long nThresholdInitial,

long nThresholdFinal

);

Parameter

Description

bAutomatic

Boolean value that specifies to execute the automatic silence detection on each loaded sound.

Supported values are the following:

Value | Meaning
false | Automatic silence detection is disabled (default)
true | Automatic silence detection is enabled

nThresholdInitial

Number representing the silence threshold at the start of the loaded sound: can assume values from 0 (no sound) to 32767 (max volume).

nThresholdFinal

Number representing the silence threshold at the end of the loaded sound: can assume values from 0 (no sound) to 32767 (max volume).

Return value

None


SilenceDetectionOnPlayerRequest method

SilenceDetectionOnPlayerRequest method

Remarks

Requests the calculation of silent portions at the start and end of the sound loaded inside the given player: useful when the automatic silence detection has been disabled through a call to the SilenceDetectionOnPlayerLoadAutoSet method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

Silence detection works inside a secondary thread so, once detected, the container application will be notified about initial and final positions of silent portions at the start and end of loaded songs through the SilencePositionAvailable event. If you need to perform silence detection inside the main thread and to have silence positions immediately available after returning from the method call you can use the SilenceDetectionOnPlayer method.

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

control.SilenceDetectionOnPlayerRequest (

nPlayer as Integer,

nThresholdInitial as Long,

nThresholdFinal as Long

) as enumErrorCodes

[C++]

short control.SilenceDetectionOnPlayerRequest (

short nPlayer,

long nThresholdInitial,

long nThresholdFinal

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nThresholdInitial | Number representing the silence threshold at the start of the loaded sound: can assume values from 0 (no sound) to 32767 (max volume).
nThresholdFinal | Number representing the silence threshold at the end of the loaded sound: can assume values from 0 (no sound) to 32767 (max volume).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SilenceDetectionRealTimeEnable method

SilenceDetectionRealTimeEnable method

Remarks

Enables/disables realtime silence detection during sound playback. Parameters involved in realtime silence detection can be modified through the SilenceDetectionRealTimeParamsSet method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to "false".

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

control.SilenceDetectionRealTimeEnable (

nPlayerIndex as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.SilenceDetectionRealTimeEnable (

short nPlayerIndex,

short bEnable

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

bEnable

Boolean value that specifies if realtime silence detection must be enabled or not.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Realtime silence detection is disabled (default)
BOOL_TRUE | Realtime silence detection is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SilenceDetectionRealTimeParamsSet method

SilenceDetectionRealTimeParamsSet method

Remarks

Sets parameters of realtime silence detection which can be enabled through the SilenceDetectionRealTimeEnable method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to "false".

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

control.SilenceDetectionRealTimeParamsSet (

nPlayerIndex as Integer,

nSilenceThreshold as Long,

nSilenceMinLength as Long

) as enumErrorCodes

[C++]

short control.SilenceDetectionRealTimeParamsSet (

short nPlayerIndex,

long nSilenceThreshold,

long nSilenceMinLength

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nSilenceThreshold

Number representing the silence threshold referred to the volume level. Supported values are expressed with a linear volume in the range from 0 (no sound) to 32767 (max volume). If for example you should set a value of 800, any portion of sound having a volume level lower than 800 would be considered as silent.

In case you should need to set a threshold value expressed in dB, before setting this parameter you could convert the value in dB into a linear value through the following formula (C syntax):

ValueLinear = 32767 * pow (10, ValueInDB/20);

nSilenceMinLength

Number representing the minimal length of silence expressed in milliseconds. If for example you wish to consider as "silent" only those portions of sound whose duration is above one second, you would have to set this value to 1000.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0 | The method call was successful.


SoundLyricsGet method

SoundLyricsGet method

Remarks

Retrieves lyrics text previously requested through the SoundLyricsRequest method.

This method must be called only after receiving the SoundLyricsAvailable event and only if no error is reported by the event itself.

Syntax

[Visual Basic]

control.SoundLyricsGet (

nPlayer as Integer

) as String

[C++]

LPCTSTR control.SoundLyricsGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The string containing requested lyrics text


SoundLyricsRequest method

SoundLyricsRequest method

Remarks

Given an author and title of a song, requests a connection to the MultiMedia Soft server in order to search for the lyrics text of the song.

Once completed the SoundLyricsAvailable event will be fired and, if found, lyrics text can be retrieved through the SoundLyricsGet method.

Syntax

[Visual Basic]

control.SoundLyricsRequest (

nPlayer as Integer,

strArtist as String,

strTitle as String

) as enumErrorCodes

[C++]

short control.SoundLyricsRequest (

short nPlayer,

LPCTSTR strArtist,

LPCTSTR strTitle

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strArtist | String representing the artist name
strTitle | String representing the song title

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


VideoFiltersBlacklistDisable method

VideoFiltersBlacklistDisable method

Remarks

Disables/enables blacklisting of certain DirectShow filters during filter graph building.

When dealing with Windows 7, system default video codecs are not always compatible with certain features of our component like adding the clip to a video mixer or loading a video clip from a memory buffer: for this reason, when FFDSHOW (installed by K-Lite Codec pack) is available inside the target system and a specific FFDSHOW video decoder has been set for managing these formats, the following system codecs result blacklisted and the component uses the selected FFDSHOW alternative (for example "libavcodec"):

- "MPEG VIDEO DECODER" for MPEG1

- "Microsoft DTV-DVD Video Decoder" for MPEG2

- "Mpeg4s Decoder DMO" for MP4V

Other codecs or filters may be added in the future to this blacklist if we should find them to be incompatible with our purposes. You can add to this blacklist other filters or codecs on your own through the VideoFiltersBlacklistItemAdd method.

Inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoFiltersBlacklistDisable (

bDisable as enumBoolean

)

[C++]

void control.VideoFiltersBlacklistDisable (

short bDisable

);

Parameter

Description

bDisable

Boolean value that specifies if the blacklist must be disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Blacklist is enabled
BOOL_TRUE | 1 | Blacklist is disabled

Return value

None


VideoFiltersBlacklistItemAdd method

VideoFiltersBlacklistItemAdd method

Remarks

Adds a DirectShow filter or codec to the blacklist of filters whose usage should be rejected during the filter graph building. Blacklisted filters can be removed at any time from the black list through the VideoFiltersBlacklistItemRemove method; the black list can be reset through the VideoFiltersBlacklistReset method or disabled through the VideoFiltersBlacklistDisable method.

Inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoFiltersBlacklistItemAdd (

strCLSID as String

) as enumErrorCodes

[C++]

short control.VideoFiltersBlacklistItemAdd (

BSTR strCLSID

);

Parameter

Description

strCLSID

String containing the class identifier (CLSID) of the filter to blacklist; a CLSID is a 128 bit (large) number that represents a unique identifier for a software application or application component. This parameter must be in the format "{AE7AB96B-FF5E-4dce-801E-14DF2C4CD681}". The presence of curly brackets  inside the string is mandatory.

There are several applications which can be used to obtain the CLSID string for a specific filter: InstalledCodecs by NirSoft, GraphEditPlus by Infognition, GraphStudioNext and others.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


VideoFiltersBlacklistItemRemove method

VideoFiltersBlacklistItemRemove method

Remarks

Removes a DirectShow filter or codec from the blacklist of filters whose usage should be rejected during the filter graph building. Blacklisted filters can be added at any time to the black list through the VideoFiltersBlacklistItemAdd method.

Inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoFiltersBlacklistItemRemove (

strCLSID as String

) as enumErrorCodes

[C++]

short control.VideoFiltersBlacklistItemRemove (

BSTR strCLSID

);

Parameter | Description
strCLSID | String containing the class identifier (CLSID) of the filter to remove from the blacklist: this string must exactly match the one used to add the filter to the blacklist through the previous call to the VideoFiltersBlacklistItemAdd method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


VideoFiltersBlacklistReset method

VideoFiltersBlacklistReset method

Remarks

Resets the blacklist of filters whose usage should be rejected during the filter graph building. Blacklisted filters can be added at any time to the black list through the VideoFiltersBlacklistItemAdd method.

Inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoFiltersBlacklistReset (

) as enumErrorCodes

[C++]

short control.VideoFiltersBlacklistReset (

);

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


VideoFiltersFfdShowIsAvailable method

VideoFiltersFfdShowIsAvailable method

Remarks

Determines if FFDSHOW is installed inside the system. FFDSHOW is a media decoder and encoder mainly used for the fast and high-quality decoding of several video and audio formats through DirectShow and is usually installed by K-Lite Codec pack.

Inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoFiltersFfdShowIsAvailable (

) as boolean

[C++]

BOOL control.VideoFiltersFfdShowIsAvailable (

);

Return value

Value | Meaning
FALSE | FFDSHOW is not installed
TRUE | FFDSHOW is installed


VideoFiltersFfdShowDecoderGet method

VideoFiltersFfdShowDecoderGet method

Remarks

If FFDSHOW is installed inside the system, obtains the FFDSHOW decoder set for a certain video format. The current decoder can be changed through the VideoFiltersFfdShowDecoderSet method.

You can know if FFDSHOW is installed by querying the VideoFiltersFfdShowIsAvailable method.

Inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoFiltersFfdShowDecoderGet (

strVideoFormat as String,

nDecoder as Integer

) as enumErrorCodes

[C++]

short control.VideoFiltersFfdShowDecoderGet (

LPCTSTR strVideoFormat,

short *nDecoder

);

Parameter

Description

strVideoFormat

String representing the registry sub-key for the video format as managed by FFDSHOW inside the registry key HKEY_CURRENT_USER\Software\GNU\ffdshow, for example "mpg1" for MPEG1, "mpg2" for MPEG2, "mp4v" for MP4V, etc.,

nDecoder

Reference that, on return from the method call, will contain the current decoder selected for the given video format.

When no decoder has been set the returned value is 0; depending upon the video format in use this value may assume different meanings; for example, when dealing with MPEG1 and MPEG2 formats, the value 1 means that the selected decoder is "libavcodec" while the value 5 means that the selected decoder is "libmpeg2".

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoFiltersFfdShowDecoderSet method

VideoFiltersFfdShowDecoderSet method

Remarks

If FFDSHOW is installed inside the system, modifies the FFDSHOW decoder set for a certain video format. You can obtain the current selected decoder through the VideoFiltersFfdShowDecoderGet method.

You can know if FFDSHOW is installed by querying the VideoFiltersFfdShowIsAvailable method.

Inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoFiltersFfdShowDecoderSet (

strVideoFormat as String,

nDecoder as Integer

) as enumErrorCodes

[C++]

short control.VideoFiltersFfdShowDecoderSet (

LPCTSTR strVideoFormat,

short nDecoder

);

Parameter | Description
strVideoFormat | String representing the registry sub-key for the video format as managed by FFDSHOW inside the registry key HKEY_CURRENT_USER\Software\GNU\ffdshow, for example "mpg1" for MPEG1, "mpg2" for MPEG2, "mp4v" for MP4V, etc.,
nDecoder | The identifier of the new decoder for the given video format. You can disable using any FFDSHOW decoders for the given video format by setting this value to 0; depending upon the video format in use this value may assume different meanings; for example, when dealing with MPEG1 and MPEG2 formats, the value 1 selects the "libavcodec" decoder while the value 5 selects the "libmpeg2" decoder.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


BeatsDetectEnableRT method

BeatsDetectEnableRT method

Remarks

Enables/disables real-time detection (during playback) of beats positions. A BeatDetectedRealTime event is fired each time the control detects a beat during playback.

Parameters for beats positions analysis can be obtained/set through the BeatsDetectGetParams and BeatsDetectSetParams methods.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.BeatsDetectEnableRT (

nPlayer as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.BeatsDetectEnableRT (

short nPlayer,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value that specifies if the control must automatically detect beats positions during playback.

Supported values are the following:

Mnemonic constant | Value | Meaning
FALSE (default) | 0 | Beats detection is disabled
TRUE | 1 | Beats detection is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


BeatsDetectGetBeatPos method

BeatsDetectGetBeatPos method

Remarks

Obtains the position of a specific beat detected during a previous offline beats detection analysis performed through a previous call to the BeatsDetectRequest method.

The total number of detected beats can be obtained calling the BeatsDetectGetBeatsCount method.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.BeatsDetectGetBeatPos (

nPlayer as Integer,

nBeatIndex as Long

) as Long

[C++]

long control.BeatsDetectGetBeatPos (

short nPlayer,

long nBeatIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nBeatIndex | Zero-based index of the requested beat

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | Position of the beat expressed in milliseconds


BeatsDetectGetBeatsCount method

BeatsDetectGetBeatsCount method

Remarks

Obtains the total number of beats detected during a previous offline beats detection analysis performed through a previous call to the BeatsDetectRequest method.

Each detected position can be obtained calling the BeatsDetectGetBeatPos method.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.BeatsDetectGetBeatsCount (

nPlayer as Integer

) as Long

[C++]

long control.BeatsDetectGetBeatsCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | The number of detected beats


BeatsDetectGetParams method

BeatsDetectGetParams method

Remarks

Obtains parameters used for beats detection fine tuning

Parameters for beats positions analysis can be modified through the BeatsDetectSetParams method.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.BeatsDetectGetParams (

nPlayer as Integer,

fBandwidth as Single,

fCenterFreq as Single,

fBeatReleaseTime as Single

) as enumErrorCodes

[C++]

short control.BeatsDetectGetParams (

short nPlayer,

float *fBandwidth,

float *fCenterFreq,

float *fBeatReleaseTime

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fBandwidth | Reference that, on return from the method call, will contain a floating point value representing the current bandwidth expressed in Hertz.
fCenterFreq | Reference that, on return from the method call, will contain a floating point value representing the current center frequency expressed in Hertz
fBeatReleaseTime | Reference that, on return from the method call, will contain a floating point value representing the current beat release time expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


BeatsDetectRequest method

BeatsDetectRequest method

Remarks

Analyses a given range of the loaded sound in order to identify and store beats positions. In this case beats positions detection is performed offline, i.e. while the sound is not being played: if you should need detecting beats positions in real-time during playback, use the BeatsDetectEnableRT method.

Parameters for beats positions analysis can be obtained/set through the BeatsDetectGetParams and BeatsDetectSetParams methods and the range of sound to analyze can be set through the BeatsDetectSetRange method.

Once beats positions have been calculated, the container application will be notified through the BeatsAvailableOffline event.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.BeatsDetectRequest (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.BeatsDetectRequest (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


BeatsDetectSetParams method

BeatsDetectSetParams method

Remarks

Sets parameters used for beats detection fine tuning

Parameters for beats positions analysis can be obtained through the BeatsDetectGetParams method.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.BeatsDetectSetParams (

nPlayer as Integer,

fBandwidth as Single,

fCenterFreq as Single,

fBeatReleaseTime as Single

) as enumErrorCodes

[C++]

short control.BeatsDetectSetParams (

short nPlayer,

float fBandwidth,

float fCenterFreq,

float fBeatReleaseTime

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fBandwidth | Floating point value representing the new bandwidth expressed in Hertz.
fCenterFreq | Floating point value representing the new center frequency expressed in Hertz
fBeatReleaseTime | Floating point value representing the new current beat release time expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


BeatsDetectSetRange method

BeatsDetectSetRange method

Remarks

Sets the song's range where offline beats detection (started by a call to the BeatsDetectRequest method) will be performed.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

control.BeatsDetectSetRange (

nPlayer as Integer,

nStartPosition as Long,

nEndPosition as Long

) as enumErrorCodes

[C++]

short control.BeatsDetectSetRange (

short nPlayer,

long nStartPosition,

long nEndPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nStartPosition | Start position expressed in milliseconds
nEndPosition | End position expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


CastingCreateFromPlayer method

CastingCreateFromPlayer method

Remarks

Creates a casting session that will output sound from the given player; if the player shouldn't have any sound loaded, the call to this method will fail.

After creating the casting session, you can start it through the CastingStart method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingCreateFromPlayer (

nPlayer as Integer,

strServer as String,

strPassword as String,

strIcecastMountName as String,

nEncodeFormat as enumEncodingFormats,

strName as String,

strURL as String,

strGenre as String,

strHeaders as String,

strIcecastDescription as String,

nEncodeMode as enumCastEncodeModes,

fEncodeValue as Single,

nResampleFrequency as Long,

nChannels as Integer

) as Long

[C++]

long control.CastingCreateFromPlayer (

short nPlayer,

LPCTSTR strServer,

LPCTSTR strPassword,

LPCTSTR strIcecastMountName,

short nEncodeFormat,

LPCTSTR strName,

LPCTSTR strURL,

LPCTSTR strGenre,

LPCTSTR strHeaders,

LPCTSTR strIcecastDescription,

short nEncodeMode,

float fEncodeValue,

long nResampleFrequency,

short nChannels

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strServer

Address of the cast server.

When connecting to a ShoutCAST Version 1 server or to an IceCast server, the address is in the format "address:port", for example "http://192.168.0.1:80"

When connecting to a ShoutCAST Version 2 server, which can manage more audio streams at the same time, the address is in the format "address:port,strid" where "strid" represents the identifier of the audio stream, for example "http://192.168.0.1:80,1234

strPassword

Password of the cast server

strIcecastMountName

Icecast mount name (for use with Icecast servers only)

nEncodeFormat

Encoding format

Supported values are the following:

Mnemonic constant | Value | Meaning
ENCODING_FORMAT_MP3 | 2 | MP3 format
ENCODING_FORMAT_OGG | 4 | OGG Vorbis format
ENCODING_FORMAT_AAC_PLUS | 22 | AAC+ (HE-AAC)

strName

Stream name

strURL

URL of the radio station

strGenre

Genre of the stream

strHeaders

Additional headers to send to the server

strIcecastDescription

Further description for Icecast streams (for use with Icecast servers only)

nEncodeMode

Encode mode

Supported values are the following:

Mnemonic constant | Value | Meaning
CAST_ENCODE_QUALITY | 0 | Casting is based upon Quality
CAST_ENCODE_BITRATE | 1 | Casting is based upon Bitrate

fEncodeValue

Value related to the chosen encode mode (ignored when the nEncodeFormat parameter is set to ENCODING_FORMAT_AAC_PLUS):

· if the value of the nEncodeMode parameter is set to CAST_ENCODE_QUALITY this parameter can assume the following range of values:

- if the value of the nEncodeFormat parameter is set to ENCODING_FORMAT_MP3 can be from 0 (high quality but slow) to 9 (poor quality but faster)

- if the value of the nEncodeFormat parameter is set to ENCODING_FORMAT_OGG can be from 0 (poor quality) to 10 (high quality)

· if the value of the nEncodeMode parameter is set to CAST_ENCODE_BITRATE the passed value represents the bitrate in kbps (kilo bits per second)

nResampleFrequency

Resample frequency

nChannels

Number of channels

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingCreateFromStreamMixer method

CastingCreateFromStreamMixer method

Remarks

Creates a casting session that will output sound from the given stream mixer.

After creating the casting session, you can start it through the CastingStart method.

A casting session supports mono or stereo only so the stream mixer cannot be multi-channel.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingCreateFromStreamMixer (

nStreamMixerID as Integer,

strServer as String,

strPassword as String,

strIcecastMountName as String,

nEncodeFormat as enumEncodingFormats,

strName as String,

strURL as String,

strGenre as String,

strHeaders as String,

strIcecastDescription as String,

nEncodeMode as enumCastEncodeModes,

fEncodeValue as Single,

nResampleFrequency as Long,

nChannels as Integer

) as Long

[C++]

long control.CastingCreateFromStreamMixer (

short nStreamMixerID,

LPCTSTR strServer,

LPCTSTR strPassword,

LPCTSTR strIcecastMountName,

short nEncodeFormat,

LPCTSTR strName,

LPCTSTR strURL,

LPCTSTR strGenre,

LPCTSTR strHeaders,

LPCTSTR strIcecastDescription,

short nEncodeMode,

float fEncodeValue,

long nResampleFrequency,

short nChannels

);

Parameter

Description

nStreamMixerID

Unique identifier of the stream mixer previously created through the StreamMixerCreate method.

strServer

Address of the cast server.

When connecting to a ShoutCAST Version 1 server or to an IceCast server, the address is in the format "address:port", for example "http://192.168.0.1:80"

When connecting to a ShoutCAST Version 2 server, which can manage more audio streams at the same time, the address is in the format "address:port,strid" where "strid" represents the identifier of the audio stream, for example "http://192.168.0.1:80,1234

strPassword

Password of the cast server

strIcecastMountName

Icecast mount name (for use with Icecast servers only)

nEncodeFormat

Encoding format

Supported values are the following:

Mnemonic constant | Value | Meaning
ENCODING_FORMAT_MP3 | 2 | MP3 format
ENCODING_FORMAT_OGG | 4 | OGG Vorbis format
ENCODING_FORMAT_AAC_PLUS | 22 | AAC+ (HE-AAC)

strName

Stream name

strURL

URL of the radio station

strGenre

Genre of the stream

strHeaders

Additional headers to send to the server

strIcecastDescription

Further description for Icecast streams (for use with Icecast servers only)

nEncodeMode

Encode mode

Supported values are the following:

Mnemonic constant | Value | Meaning
CAST_ENCODE_QUALITY | 0 | Casting is based upon Quality
CAST_ENCODE_BITRATE | 1 | Casting is based upon Bitrate

fEncodeValue

Value related to the chosen encode mode (ignored when the nEncodeFormat parameter is set to ENCODING_FORMAT_AAC_PLUS):

· if the value of the nEncodeMode parameter is set to CAST_ENCODE_QUALITY this parameter can assume the following range of values:

- if the value of the nEncodeFormat parameter is set to ENCODING_FORMAT_MP3 can be from 0 (high quality but slow) to 9 (poor quality but faster)

- if the value of the nEncodeFormat parameter is set to ENCODING_FORMAT_OGG can be from 0 (poor quality) to 10 (high quality)

· if the value of the nEncodeMode parameter is set to CAST_ENCODE_BITRATE the passed value represents the bitrate in kbps (kilo bits per second)

nResampleFrequency

Resample frequency

nChannels

Number of channels

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingCreateFromWasapiLoopback method

CastingCreateFromWasapiLoopback method

Remarks

Creates a casting session that will output sound from the given WASAPI loopback device.

The usage of this method allows sending to a streaming server any sound being played through an audio endpoint device by any application running inside the system.

After creating the casting session, you can start it through the CastingStart method.

This method is only intended for usage with Windows Vista and later versions.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.CastingCreateFromWasapiLoopback (

nDeviceIndex as Integer,

strServer as String,

strPassword as String,

strIcecastMountName as String,

nEncodeFormat as enumEncodingFormats,

strName as String,

strURL as String,

strGenre as String,

strHeaders as String,

strIcecastDescription as String,

nEncodeMode as enumCastEncodeModes,

fEncodeValue as Single,

nResampleFrequency as Long,

nChannels as Integer

) as Long

[C++]

long control.CastingCreateFromWasapiLoopback (

short nDeviceIndex,

LPCTSTR strServer,

LPCTSTR strPassword,

LPCTSTR strIcecastMountName,

short nEncodeFormat,

LPCTSTR strName,

LPCTSTR strURL,

LPCTSTR strGenre,

LPCTSTR strHeaders,

LPCTSTR strIcecastDescription,

short nEncodeMode,

float fEncodeValue,

long nResampleFrequency,

short nChannels

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI loopback device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method having the nDeviceType parameter set to WASAPI_DEVICE_TYPE_LOOPBACK.

strServer

Address of the cast server.

When connecting to a ShoutCAST Version 1 server or to an IceCast server, the address is in the format "address:port", for example "http://192.168.0.1:80"

When connecting to a ShoutCAST Version 2 server, which can manage more audio streams at the same time, the address is in the format "address:port,strid" where "strid" represents the identifier of the audio stream, for example "http://192.168.0.1:80,1234

strPassword

Password of the cast server

strIcecastMountName

Icecast mount name (for use with Icecast servers only)

nEncodeFormat

Encoding format

Supported values are the following:

Mnemonic constant | Value | Meaning
ENCODING_FORMAT_MP3 | 2 | MP3 format
ENCODING_FORMAT_OGG | 4 | OGG Vorbis format
ENCODING_FORMAT_AAC_PLUS | 22 | AAC+ (HE-AAC)

strName

Stream name

strURL

URL of the radio station

strGenre

Genre of the stream

strHeaders

Additional headers to send to the server

strIcecastDescription

Further description for Icecast streams (for use with Icecast servers only)

nEncodeMode

Encode mode

Supported values are the following:

Mnemonic constant | Value | Meaning
CAST_ENCODE_QUALITY | 0 | Casting is based upon Quality
CAST_ENCODE_BITRATE | 1 | Casting is based upon Bitrate

fEncodeValue

Value related to the chosen encode mode (ignored when the nEncodeFormat parameter is set to ENCODING_FORMAT_AAC_PLUS):

· if the value of the nEncodeMode parameter is set to CAST_ENCODE_QUALITY this parameter can assume the following range of values:

- if the value of the nEncodeFormat parameter is set to ENCODING_FORMAT_MP3 can be from 0 (high quality but slow) to 9 (poor quality but faster)

- if the value of the nEncodeFormat parameter is set to ENCODING_FORMAT_OGG can be from 0 (poor quality) to 10 (high quality)

· if the value of the nEncodeMode parameter is set to CAST_ENCODE_BITRATE the passed value represents the bitrate in kbps (kilo bits per second)

nResampleFrequency

Resample frequency

nChannels

Number of channels

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingGetXmlStatistics method

CastingGetXmlStatistics method

Remarks

Returns a XML formatted string containing statistics about the casting session previously created by a previous call to the CastingCreateFromStreamMixer or CastingCreateFromPlayer methods and started though the CastingStart method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingGetXmlStatistics (

nCastingUniqueID as Long

) as String

[C++]

LPCTSTR control.CastingGetXmlStatistics (

long nCastingUniqueID

);

Parameter | Description
nCastingUniqueID | Unique identifier of the casting session returned by a previous call to the CastingCreateFromStreamMixer or CastingCreateFromPlayer methods

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the XML formatted statistics


CastingIsActive method

CastingIsActive method

Remarks

Checks if the given WMA casting session is active and started.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingIsActive (

nCastingUniqueID as Long

) as Boolean

[C++]

BOOL control.CastingIsActive (

long nCastingUniqueID

);

Parameter | Description
nCastingUniqueID | Unique identifier of the casting session returned by a previous call to CastingCreateFromStreamMixer, CastingCreateFromPlayer, CastingWmaPubPointOpenForStreamMixer, CastingWmaPubPointOpenForPlayer, CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.

Return value

Value | Meaning
False | The casting session is not active
True | The casting session is active


CastingSendMetaData method

CastingSendMetaData method

Remarks

Sends metadata in binary format to a SHOUTcast version 2 casting session created by a previous call to the CastingCreateFromStreamMixer or CastingCreateFromPlayer methods. If you should need sending a string of metadata, for example for sending a well formed XML, you could use the CastingSendMetaDataString method.

Details about the protocol for communicating with a SHOUTcast version 2 server and available metadata can be found inside the WinAmp Developer Network site.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingSendMetaData (

nCastingUniqueID as Long,

nType as Long,

pBuffer as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.CastingSendMetaData (

long nCastingUniqueID,

long nType,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nCastingUniqueID | Unique identifier of the casting session returned by a previous call to the CastingCreateFromStreamMixer or CastingCreateFromPlayer methods
nType | Type of metadata. This is a SHOUTcast version 2 message class (in bits 12 to 15) and type (bits 0 to 11) that describes what the metadata is. For example, the hexadecimal "4103" is class 4 and type 3 which would indicate an album art (1xx) in GIF format.
pBuffer | Buffer containing metadata
nBufferLength | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


CastingSendMetaDataString method

CastingSendMetaDataString method

Remarks

Sends a string containing metadata to a SHOUTcast version 2 casting session created by a previous call to the CastingCreateFromStreamMixer or CastingCreateFromPlayer methods. If you should need sending metadata in binary format you could use the CastingSendMetaData method.

Details about the protocol for communicating with a SHOUTcast version 2 server and available metadata can be found inside the WinAmp Developer Network site.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingSendMetaDataString (

nCastingUniqueID as Long,

nType as Long,

strMetadata as String

) as enumErrorCodes

[C++]

short control.CastingSendMetaDataString (

long nCastingUniqueID,

long nType,

LPCTSTR strMetadata

);

Parameter

Description

nCastingUniqueID

Unique identifier of the casting session returned by a previous call to the CastingCreateFromStreamMixer or CastingCreateFromPlayer methods

nType

Type of metadata. This is a ShoutCAST version 2 message class (in bits 12 to 15) and type (bits 0 to 11) that describes what the metadata is.

For example, the hexadecimal "3902" is a class 3 message that would contain type 902 XML Metadata in SHOUTcast version 2.0 format

strMetadata

String containing metadata, typically a string containing well formed XML

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


CastingSetTitle method

CastingSetTitle method

Remarks

Sets the title of the casting session previously created by a previous call to the CastingCreateFromStreamMixer or CastingCreateFromPlayer methods.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingSetTitle (

nCastingUniqueID as Long,

strTitle as String,

strURL as String

) as enumErrorCodes

[C++]

short control.CastingSetTitle (

long nCastingUniqueID,

LPCTSTR strTitle,

LPCTSTR strURL

);

Parameter | Description
nCastingUniqueID | Unique identifier of the casting session returned by a previous call to the CastingCreateFromStreamMixer or CastingCreateFromPlayer methods
strTitle | Title of the casting session
strURL | URL of the casting session ((for use with ShoutCAST servers only))

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


CastingStart method

CastingStart method

Remarks

Starts the casting session created by a previous call to one of the following methods:

· for stream mixers: CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer
· for players: CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer
· for WASAPI loopback devices (Windows Vista and later versions only): CastingCreateFromWasapiLoopback, CastingWmaPubPointOpenFromWasapiLoopback, CastingWmaNetworkOpenFromWasapiLoopback

A started session can be stopped at any time through the CastingStop method.

The call to this method will generate the following events:

· If the casting session has been initiated by a custom Stream Mixer, the call to this method will generate the CastingStreamMixerStart event.
· If the casting session has been initiated by one of the available players, the call to the this method will generate the CastingPlayerStart event, followed by a number of CastingPlayerPerc event and finally by the CastingPlayerDone event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the this method will generate the CastingWasapiLoopbackStart event.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.CastingStart (

nCastingUniqueID as Long

) as enumErrorCodes

[C++]

short control.CastingStart (

long nCastingUniqueID

);

Parameter

Description

nCastingUniqueID

Unique identifier of the casting session returned by a previous call to one of the following methods:

· for stream mixers: CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer
· for players: CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer
· for WASAPI loopback devices: CastingCreateFromWasapiLoopback, CastingWmaPubPointOpenFromWasapiLoopback, CastingWmaNetworkOpenFromWasapiLoopback

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


CastingStop method

CastingStop method

Remarks

Stops the casting session previously started through the CastingStart method.

The call to this method will generate the following events:

· If the casting session has been initiated by a custom Stream Mixer, the call to this method will generate the CastingStreamMixerStop event.
· If the casting session has been initiated by one of the available players, the call to the this method will generate the CastingPlayerDone event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the this method will generate the CastingWasapiLoopbackStop event.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingStop (

nCastingUniqueID as Long

) as enumErrorCodes

[C++]

short control.CastingStop (

long nCastingUniqueID

);

Parameter

Description

nCastingUniqueID

Unique identifier of the casting session returned by a previous call to one of the following methods:

· for stream mixers: CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer
· for players: CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer
· for WASAPI loopback devices: CastingCreateFromWasapiLoopback, CastingWmaPubPointOpenFromWasapiLoopback, CastingWmaNetworkOpenFromWasapiLoopback

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


CastingWmaConnectedIPGetCount method

CastingWmaConnectedIPGetCount method

Remarks

Obtains the number of IP addresses connected to the WMA network session.

Single connected IP addresses can be obtained through the CastingWmaConnectedIPGetDesc method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingWmaConnectedIPGetCount (

nCastingUniqueID as Long

) as enumErrorCodes

[C++]

short control.CastingWmaConnectedIPGetCount (

long nCastingUniqueID

);

Parameter | Description
nCastingUniqueID | Unique identifier of the casting session returned by a previous call to CastingCreateFromStreamMixer, CastingCreateFromPlayer, CastingWmaPubPointOpenForStreamMixer, CastingWmaPubPointOpenForPlayer, CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | Number of connected IP addresses


CastingWmaConnectedIPGetDesc method

CastingWmaConnectedIPGetDesc method

Remarks

Obtains the descriptor of the requested IP address connected to the WMA network session.

The total number of connected IP addresses can be obtained through the CastingWmaConnectedIPGetCount method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingWmaConnectedIPGetDesc (

nCastingUniqueID as Long,

nIndexIP as Long

) as String

[C++]

LPCTSTR control.CastingWmaConnectedIPGetDesc (

long nCastingUniqueID,

long nIndexIP

);

Parameter | Description
nCastingUniqueID | Unique identifier of the casting session returned by a previous call to CastingCreateFromStreamMixer, CastingCreateFromPlayer, CastingWmaPubPointOpenForStreamMixer, CastingWmaPubPointOpenForPlayer, CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.
nIndexIP | Zero-based index of the requested IP address

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The requested IP address


CastingWmaGetInfo method

CastingWmaGetInfo method

Remarks

Obtains information about the WMA casting session.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingWmaGetInfo (

nCastingUniqueID as Long,

nConnectedClients as Long,

nOutputPort as Long

) as enumErrorCodes

[C++]

short control.CastingWmaGetInfo (

long nCastingUniqueID,

long nConnectedClients,

long nOutputPort

);

Parameter | Description
nCastingUniqueID | Unique identifier of the casting session returned by a previous call to CastingCreateFromStreamMixer, CastingCreateFromPlayer, CastingWmaPubPointOpenForStreamMixer, CastingWmaPubPointOpenForPlayer, CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.
nConnectedClients | Reference that, on return from the method call, will contain the current number of connected clients
nOutputPort | Reference that, on return from the method call, will contain the port number used by the casting session

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


CastingWmaNetworkOpenForPlayer method

CastingWmaNetworkOpenForPlayer method

Remarks

Creates a network session in WMA format to a certain port of the network for the output of the given player; if the player shouldn't have any sound loaded, the call to this method will fail.

After creating the casting session, you can start it through the CastingStart method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingWmaNetworkOpenForPlayer (

nPlayer as Integer,

strOutputPort as String

nMaxClients as Long

nBitrate as Long

) as Long

[C++]

long control.CastingWmaNetworkOpenForPlayer (

short nPlayer,

LPCTSTR strOutputPort,

long nMaxClients,

long nBitrate

);

Parameter | Description
nPlayer | Unique identifier of the stream mixer
strOutputPort | String representing the number representing the network output port
nMaxClients | Maximum number of accepted clients
nBitrate | Bitrate expressed in bits per seconds

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingWmaNetworkOpenForStreamMixer method

CastingWmaNetworkOpenForStreamMixer method

Remarks

Creates a network session in WMA format to a certain port of the network for the output of the given stream mixer.

After creating the casting session, you can start it through the CastingStart method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingWmaNetworkOpenForStreamMixer (

nStreamMixerID as Integer,

strOutputPort as String

nMaxClients as Long

nBitrate as Long

) as Long

[C++]

long control.CastingWmaNetworkOpenForStreamMixer (

short nStreamMixerID,

LPCTSTR strOutputPort,

long nMaxClients,

long nBitrate

);

Parameter | Description
nStreamMixerID | Unique identifier of the stream mixer
strOutputPort | String representing the number representing the network output port
nMaxClients | Maximum number of accepted clients
nBitrate | Bitrate expressed in bits per seconds

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingWmaNetworkOpenFromWasapiLoopback method

CastingWmaNetworkOpenFromWasapiLoopback method

Remarks

Creates a network session in WMA format to a certain port of the network for the output of the given loopback device.

The usage of this method allows sending on the WMA network session any sound being played through an audio endpoint device by any application running inside the system.

After creating the casting session, you can start it through the CastingStart method.

This method is only intended for usage with Windows Vista and later versions.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.CastingWmaNetworkOpenFromWasapiLoopback (

nDeviceIndex as Integer,

strOutputPort as String

nMaxClients as Long

nBitrate as Long

) as Long

[C++]

long control.CastingWmaNetworkOpenFromWasapiLoopback (

short nDeviceIndex,

LPCTSTR strOutputPort,

long nMaxClients,

long nBitrate

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the WASAPI loopback device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method having the nDeviceType parameter set to WASAPI_DEVICE_TYPE_LOOPBACK.
strOutputPort | String representing the number representing the network output port
nMaxClients | Maximum number of accepted clients
nBitrate | Bitrate expressed in bits per seconds

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingWmaPubPointOpenForPlayer method

CastingWmaPubPointOpenForPlayer method

Remarks

Creates a casting session in WMA format to a publishing point of a Windows Media Server for the output of the given player; if the player shouldn't have any sound loaded, the call to this method will fail.

After creating the casting session, you can start it through the CastingStart method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingWmaPubPointOpenForPlayer (

nPlayer as Integer,

strUrlPublishingPoint as String,

strUsername as String,

strPassword as String

nBitrate as Long

) as Long

[C++]

long control.CastingWmaPubPointOpenForPlayer (

short nPlayer,

LPCTSTR strUrlPublishingPoint,

LPCTSTR strUsername,

LPCTSTR strPassword,

long nBitrate

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strUrlPublishingPoint | URL of the publishing point
strUsername | Username of the server
strPassword | Password of the server
nBitrate | Bitrate expressed in bits per seconds

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingWmaPubPointOpenForStreamMixer method

CastingWmaPubPointOpenForStreamMixer method

Remarks

Creates a casting session in WMA format to a publishing point of a Windows Media Server for the output of the given stream mixer.

After creating the casting session, you can start it through the CastingStart method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingWmaPubPointOpenForStreamMixer (

nStreamMixerID as Integer,

strUrlPublishingPoint as String,

strUsername as String,

strPassword as String

nBitrate as Long

) as Long

[C++]

long control.CastingWmaPubPointOpenForStreamMixer (

short nStreamMixerID,

LPCTSTR strUrlPublishingPoint,

LPCTSTR strUsername,

LPCTSTR strPassword,

long nBitrate

);

Parameter | Description
nStreamMixerID | Unique identifier of the stream mixer
strUrlPublishingPoint | URL of the publishing point
strUsername | Username of the server
strPassword | Password of the server
nBitrate | Bitrate expressed in bits per seconds

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingWmaPubPointOpenFromWasapiLoopback method

CastingWmaPubPointOpenFromWasapiLoopback method

Remarks

Creates a casting session in WMA format to a publishing point of a Windows Media Server for the output of the given loopback device.

The usage of this method allows sending to a publishing point of a Windows Media Server any sound being played through an audio endpoint device by any application running inside the system.

After creating the casting session, you can start it through the CastingStart method.

This method is only intended for usage with Windows Vista and later versions.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.CastingWmaPubPointOpenFromWasapiLoopback (

nDeviceIndex as Integer,

strUrlPublishingPoint as String,

strUsername as String,

strPassword as String

nBitrate as Long

) as Long

[C++]

long control.CastingWmaPubPointOpenFromWasapiLoopback (

short nDeviceIndex,

LPCTSTR strUrlPublishingPoint,

LPCTSTR strUsername,

LPCTSTR strPassword,

long nBitrate

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the WASAPI loopback device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method having the nDeviceType parameter set to WASAPI_DEVICE_TYPE_LOOPBACK.
strUrlPublishingPoint | URL of the publishing point
strUsername | Username of the server
strPassword | Password of the server
nBitrate | Bitrate expressed in bits per seconds

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the casting session: this unique identifier will be used in order to invoke further methods related to the use of the casting session itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


CastingWmaSetTag method

CastingWmaSetTag method

Remarks

Sets a tag for the WMA casting session.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.CastingWmaSetTag (

nCastingUniqueID as Long,

strTagName as String,

strTagText as String

) as enumErrorCodes

[C++]

short control.CastingWmaSetTag (

long nCastingUniqueID,

LPCTSTR strTagName,

LPCTSTR strTagText

);

Parameter

Description

nCastingUniqueID

Unique identifier of the casting session returned by a previous call to CastingCreateFromStreamMixer, CastingCreateFromPlayer, CastingWmaPubPointOpenForStreamMixer, CastingWmaPubPointOpenForPlayer, CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.

strTagName

String containing the name of the tag.

Typical tags for WMA are the following:

String content | Meaning
Title | Title of the song
Author | Author of the song
Description | Description of the song
Copyright | Copyright message
Rating | Song rating
WM/AlbumTitle | Title of the album containing the song
WM/AlbumCoverURL | URL pointing to the picture of the album cover
WM/PromotionURL | URL pointing to a promotional web page
WM/Year | Year of publication
WM/Genre | Song genre

strTagText

String containing the tag's content

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


WmaBitrateCount method

WmaBitrateCount method

Remarks

Obtains the number of bitrates for WMA casting supported by a certain frequency and number of channels

Single bitrates can be obtained through the WmaBitrateGet method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.WmaBitrateCount (

nFrequency as Long,

nChannels as Integer

) as Integer

[C++]

short control.WmaBitrateCount (

long nFrequency,

short nChannels

);

Parameter | Description
nFrequency | Frequency expressed in Hertz
nChannels | Number of channels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | Number of supported bitrates


WmaBitrateGet method

WmaBitrateGet method

Remarks

Given a zero-based index, obtains a specific bitrate for WMA casting supported by a certain frequency and number of channels.

The total number of bitrates available for WMA casting can be obtained through the WmaBitrateCount method.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

control.WmaBitrateGet (

nFrequency as Long,

nChannels as Integer,

nIndexBitrate as Integer

) as Long

[C++]

long control.WmaBitrateGet (

long nFrequency,

short nChannels,

short nIndexBitrate

);

Parameter | Description
nFrequency | Frequency expressed in Hertz
nChannels | Number of channels
nIndexBitrate | Zero-based index of the bitrate

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | The requested bitrate


CddbGetAlbumInfo method

CddbGetAlbumInfo method

Retrieves a specific CDDB information about the CD currently inside the given CD drive.

See the How to get CD album information from a CDDB server tutorial for further details.

Syntax

[Visual Basic]

control.CddbGetAlbumInfo (

nCdDriveIndex as Integer,

nInfo as enumCddbAlbumInfo

) as String

[C++]

LPCTSTR control.CddbGetAlbumInfo (

short nCdDriveIndex,

short nInfo

);

Parameter

Description

nCdDriveIndex

Number representing the zero-based index of the involved CD drive

nInfo

Number representing the requested information code.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
CDDB_ALBUM_TITLE | 0 | The CD album title
CDDB_ALBUM_ARTIST | 1 | The CD album artist
CDDB_ALBUM_YEAR | 2 | The CD album year
CDDB_ALBUM_GENRE | 3 | The CD album genre
CDDB_ALBUM_CLIENT_INFO | 4 | The CD album client info

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The requested information


CddbGetServerName method

CddbGetServerName method

Remarks

Obtains the friendly name of the given CDDB server.

The total number of available CDDB servers can be requested through the CddbRequestServersList method: the method will fail if called before receiving the CddbServersListAvailable event.

Syntax

[Visual Basic]

control.CddbGetServerName (

nServerIndex as Integer

) as String

[C++]

LPCTSTR control.CddbGetServerName (

short nServerIndex

);

Parameter | Description
nServerIndex | Number representing the zero-based index of the CDDB server.

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The string containing the CDDB server's friendly name


CddbGetTrackTitle method

CddbGetTrackTitle method

Retrieves the CDDB title of the given track for the CD currently inside the given CD drive.

See the How to get CD album information from a CDDB server tutorial for further details.

Syntax

[Visual Basic]

control.CddbGetTrackTitle (

nCdDriveIndex as Integer,

nTrackIndex as Integer

) as String

[C++]

LPCTSTR control.CddbGetTrackTitle (

short nCdDriveIndex,

short nTrackIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
nTrackIndex | Number representing the one-based index of the CD audio track. The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The CD track title


CddbRequestAlbumInfo method

CddbRequestAlbumInfo method

Requests the CDDB album info for the CD currently inside the given CD drive: this call needs an active Internet connection.

When the CD info will be available, a CddbAlbumInfoAvailable event will be raised: at this point it will be possible:

· Obtaining the CD album info through the CddbGetAlbumInfo method.
· Getting each CD track title through the CddbGetTrackTitle method.

This method call will also try to obtain the CD cover pictures available on the Amazon web site: in case it should find them, the CdCoverURLsAvailable and CdCoverPictureFileAvailable events will be raised so it will be possible:

· Getting the URLs of the CD cover pictures from the Amazon Web Service using the GetCdCoverPictureURL method
· Getting the temporary file pathname, containing the CD cover pictures downloaded from the Amazon web site, using the GetCdCoverPictureFile method.

See the How to get CD album information from a CDDB server tutorial for further details.

Syntax

[Visual Basic]

control.CddbRequestAlbumInfo (

nCdDriveIndex as Integer,

nServerIndex as Integer,

) as enumErrorCodes

[C++]

short control.CddbRequestAlbumInfo (

short nCdDriveIndex,

short nServerIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive
nServerIndex | Number representing the zero-based index of the CDDB server that will be used in order to obtain the CD album information. The list of available CDDB servers can be obtained through the CddbRequestServersList method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


CddbRequestServersList method

CddbRequestServersList method

CddbRequestServersList method

Remarks

Requests the list of available CDDB servers and returns immediately.

When the list will be available, a CddbServersListAvailable event will be raised: at this point it will be possible requesting each CDDB server's friendly name using the CddbGetServerName method.

Syntax

[Visual Basic]

control.CddbRequestServersList (

) as enumErrorCodes

[C++]

short control.CddbRequestServersList (

);

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


CddbSetProxyDetails method

CddbSetProxyDetails method

Sets details for reaching CDDB information from behind a HTTP proxy.

See the How to get CD album information from a CDDB server tutorial for further details.

Syntax

[Visual Basic]

control.CddbSetProxyDetails (

strHost as String,

nPort as Long,

strUsername as String,

strPassword as String

)

[C++]

void control.CddbSetProxyDetails (

LPCTSTR strHost,

long nPort,

LPCTSTR strUsername,

LPCTSTR strPassword

);

Parameter | Description
strHost | String representing the proxy host address
nPort | Number representing the proxy port.
strUsername | String representing the username
strPassword | String representing the password

Return value

None


CdNavigateToPurchasePage method

CdNavigateToPurchasePage method

Remarks

After having obtained information about CD cover pictures of an Audio CD, allows navigating to the purchase page of that specific Audio CD on the Amazon web site.

For details about obtaining CD cover pictures from the Amazon store, refer to the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial.

Syntax

[Visual Basic]

control.CdNavigateToPurchasePage (

) as enumErrorCodes

[C++]

short control.CdNavigateToPurchasePage (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


CdRequestAlbumInfo method

CdRequestAlbumInfo method

Remarks

Given the name of an artist and the title of an album, tries to obtain titles of contained tracks and the related CD cover pictures from the Amazon catalogue.

This method obtains exactly the same information returned by the CddbRequestAlbumInfo method but it doesn't need the CD to be physically available inside the CD drive.

When requested information will become available, a CddbAlbumInfoAvailable event will be raised: at this point it will be possible:

· Obtaining the CD album info through the CddbGetAlbumInfo method.
· Getting each CD track title through the CddbGetTrackTitle method.

As already mentioned, this method call will also try to obtain the CD cover pictures available on the Amazon web site: in case it should find them, the CdCoverURLsAvailable and CdCoverPictureFileAvailable events will be raised so it will be possible:

· Getting the URLs of the CD cover pictures from the Amazon Web Service using the GetCdCoverPictureURL method
· Getting the temporary file pathname, containing the CD cover pictures downloaded from the Amazon web site, using the GetCdCoverPictureFile method.

See the How to get a CD cover picture tutorial for further details.

Syntax

[Visual Basic]

control.CdRequestAlbumInfo (

strArtist as String,

strAlbum as String,

strAmazonDeveloperCode as String

) as enumErrorCodes

[C++]

short control.CdRequestAlbumInfo (

LPCTSTR strArtist,

LPCTSTR strAlbum,

LPCTSTR strAmazonDeveloperCode

);

Parameter

Description

strArtist

String representing the artist name: if it shouldn't be complete the search session would try finding the best match.

strAlbum

String representing the album title: if it shouldn't be complete the search session would try finding the best match.

strAmazonDeveloperCode

String representing the Amazon developer code: this string is optional but it's strongly recommended that you obtain a developer code from Amazon; visit the Amazon Web Services site for creating your own account.

IMPORTANT TOPIC: starting from May 2009 the developer code is no more enough in order to access Amazon web services; from that date the access must be performed through a combination of the existing developer code and of a new secret key which is provided by Amazon itself to each registered developer. The new secret key can be requested through the Amazon control panel by accessing your Amazon account. Once you have obtained the new secret key, you can use this parameter in order to pass both the developer code and the secret key using the following syntax:

"DeveloperCode-----SecretKey"

where the existing developer code and the secret key are separated by 5 '-' (minus) characters.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


EnableCdMonitor method

EnableCdMonitor method

Remarks

Enables/disables monitoring the status of the available CD drives.

Certain type of CD drives, with old software drivers, will become inaccessible while the CD drives monitoring is running so be careful in enabling CD monitoring if not strictly needed.

Syntax

[Visual Basic]

control.EnableCdMonitor (

bEnable as enumBoolean)

)

[C++]

void control.EnableCdMonitor (

BOOL bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if the control must automatically monitor the status of the available CD drives.

Supported values are the following:

Mnemonic constant | Value | Meaning
FALSE (default) | 0 | Available CD drives won't be monitored. In this condition the GetCdStatus method will not work and the CdPlayerStatusChanged event will not be fired.
TRUE | 1 | CD drives will be monitored.

Return value

None


EnableCdTracksPrebuff method

EnableCdTracksPrebuff method

Remarks

Enables/disables pre-buffering of CD tracks.

Certain types of CD drives will not allow accessing a certain CD drive from two concurrent processes: by default, in order to free as soon as possible the CD drive, this control performs a pre-buffering in memory of the whole track's PCM allowing a faster release of the CD drive; a further advantage of pre-buffering is the fact that it allows the control to start loading a new CD track into a player while another CD track is still playing on another player.

The drawback with pre-buffering is the amount of RAM required to store the PCM of a full CD track: with normal CD tracks, containing songs whose duration is between 3 and 6 minutes, this won't be an issue but with other longer tracks there could be a certain memory load which could cause unwanted side effects: for this reason CD tracks whose duration is longer than 10 minutes aren't pre-buffered and, using this method, you have the option to avoid pre-buffering for shorter tracks also.

Syntax

[Visual Basic]

control.EnableCdTracksPrebuff (

bEnable as enumBoolean)

)

[C++]

void control.EnableCdTracksPrebuff (

BOOL bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if the control must automatically perform pre-buffering for CD tracks whose duration is less than 10 minutes.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Pre-buffering is disabled
BOOL_TRUE (default) | 1 | Pre-buffering is enabled

Return value

None


GetCdCoverPictureFile method

GetCdCoverPictureFile method

Remarks

Retrieves the full pathname of the local temporary file containing the downloaded CD cover picture.

See the How to get a CD cover picture tutorial for further details.

Syntax

[Visual Basic]

control.GetCdCoverPictureFile (

nCdDriveIndex as Integer

nCoverSize as enumCdCoverSizes

) as String

[C++]

LPCTSTR control.GetCdCoverPictureFile (

short nCdDriveIndex,

short nCdCoverSize

);

Parameter

Description

nCdDriveIndex

Number representing the zero-based index of the CD drive.

Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

nCoverSize

Identifies the size of the requested CD cover picture.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
CD_COVER_SIZE_SMALL | 0 | Small size (thumbnail)
CD_COVER_SIZE_MEDIUM | 1 | Medium size
CD_COVER_SIZE_LARGE | 2 | Large size

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The string containing the CD cover picture's full pathname


GetCdCoverPictureURL method

GetCdCoverPictureURL method

Remarks

Retrieves the URL containing one of the available CD cover pictures.

See the How to get a CD cover picture tutorial for further details.

Syntax

[Visual Basic]

control.GetCdCoverPictureURL (

nCdDriveIndex as Integer

nCoverSize as enumCdCoverSizes

) as String

[C++]

LPCTSTR control.GetCdCoverPictureURL (

short nCdDriveIndex,

short nCdCoverSize

);

Parameter

Description

nCdDriveIndex

Number representing the zero-based index of the CD drive.

Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

nCoverSize

Identifies the size of the requested CD cover picture.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
CD_COVER_SIZE_SMALL | 0 | Small size (thumbnail)
CD_COVER_SIZE_MEDIUM | 1 | Medium size
CD_COVER_SIZE_LARGE | 2 | Large size

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The string containing the CD cover picture's URL.


GetCdDriveDesc method

GetCdDriveDesc method

Remarks

Retrieves the friendly description of the requested CD drive. This method is very useful when you have to fill a combo box with the friendly names of the available CD drives.

Syntax

[Visual Basic]

control.GetCdDriveDesc (

nCdDriveIndex as Integer

) as String

[C++]

LPCTSTR control.GetCdDriveDesc (

short nCdDriveIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the CD drive whose friendly name must be retrieved. Installed CD drives can be enumerated using the GetCdDrivesCount method.

Return value

Value | Meaning
Empty string | The value of the nCdDriveIndex parameter was out of range. Use the value returned by the GetCdDrivesCount method in order to know how many CD drive are currently installed on the system.
Valid string | The string containing the friendly description of the requested CD drive.


GetCdDriveLetter method

GetCdDriveLetter method

Remarks

Retrieves the drive letter of the requested CD drive: for example it will return "D" (without quotes) for the drive "D:\".

Syntax

[Visual Basic]

control.GetCdDriveLetter (

nCdDriveIndex as Integer

) as String

[C++]

LPCTSTR control.GetCdDriveLetter (

short nCdDriveIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the CD drive whose letter must be retrieved. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

Return value

Value | Meaning
Empty string | The value of the nCdDriveIndex parameter was out of range. Use the value returned by the GetCdDrivesCount method in order to know how many CD drive are currently installed on the system.
Valid string | The string containing the letter of the requested CD drive.


GetCdDrivesCount method

GetCdDrivesCount method

Remarks

Retrieves the number of CD drives currently installed on the system.

The friendly name of each CD drive can be obtained using the GetCdDriveDesc method.

Syntax

[Visual Basic]

control.GetCdDrivesCount (

) as Integer

[C++]

short control.GetCdDrivesCount (

);

Return value

The number of output devices currently installed on the system.


GetCdIdentification method

GetCdIdentification method

Remarks

Retrieves a specific identification string from a CD.

Syntax

[Visual Basic]

control.GetCdIdentification (

nCdDriveIndex as Integer,

nIdentType as enumCdIdCodes

) as Integer

[C++]

short control.GetCdIdentification (

short nCdDriveIndex,

short nIdentType

);

Parameter

Description

nCdDriveIndex

Number representing the zero-based index of the involved CD drive.

Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

nIdentType

Number representing the kind of identification we need to retrieve.

Supported values are the following:

Mnemonic constant

Value

Meaning

CD_IDENTIF_TEXT

0

Retrieves the CD-Text information.

CD Text is a technology developed by Sony Corporation and Philips Electronics in 1996 that allows storing information about an audio CD and its tracks (such as artist name, album, or song name) directly on the disk. Currently, many commercially available audio CDs contain CD Text information.

If CD Text is written on a CD, it is no need to query Internet databases for artist name or track list. CD-Text Reader delivers this information fast and right from the disk. No typos or misspelled names: the information comes directly from the publisher.

CD-Text is still not available on the majority of CDs.

CD_IDENTIF_CDDB

1

Retrieves a CDDB identifier that can be used to get details on the CD from a CDDB server. Refer to the documentation available on the http://www.cddb.com and http://www.freedb.org web sites for more information on using a CDDB server.

CD_IDENTIF_MS

2

Retrieves an identifier, usually adopted by Windows Media Player, that can be used to get details on the CD from a Microsoft server.

CD_IDENTIF_UPC

3

Retrieves the catalog number of the CD. The number is an UPC/EAN barcode. This information might not be available for all CDs.

CD_IDENTIF_MUSICBRAINZ

4

Retrieves an identifier that can be used to get details on the CD's contents from MusicBrainz servers.

Return value

Value | Meaning
Empty string | The requested identification information was not found or an error occurred (see the LastError property for further error details)
Valid string | The identification string.


GetCdNumTracks method

GetCdNumTracks method

Remarks

Retrieves the number of audio tracks inside the given CD.

Syntax

[Visual Basic]

control.GetCdNumTracks (

nCdDriveIndex as Integer

) as Integer

[C++]

short control.GetCdNumTracks (

short nCdDriveIndex

);

Parameter

Description

nCdDriveIndex

Number representing the zero-based index of the involved CD drive.

Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

If the number of tracks to report has been obtained through a search through the Amazon catalogue, by calling the CdRequestAlbumInfo method, set this parameter to -1.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | The number of available audio tracks


GetCdStatus method

GetCdStatus method

Remarks

When the automatic CD monitoring is enabled, retrieves the given CD drive working status: see the EnableCdMonitor method for details about enabling CD drives status monitoring.

Syntax

[Visual Basic]

control.GetCdStatus (

nCdDriveIndex as Integer

) as enumCdStates

[C++]

short control.GetCdStatus (

short nCdDriveIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

Return value

Mnemonic Value | Numeric value | Meaning
ERR_xxx | Negative | An error occurred (see the LastError property for further error details)
CD_STATUS_OPEN | 0 | The CD drive door is open
CD_STATUS_CLOSED | 1 | The CD drive door is closed but no CD is available inside
CD_STATUS_READY | 2 | The CD drive door is closed and a CD is available inside and ready to play
CD_STATUS_BUSY | 3 | The CD drive door is closed and a CD is available inside but the drive is busy loading an audio track from the CD


GetCdTrackDuration method

GetCdTrackDuration method

Remarks

Retrieves the duration, expressed in seconds, of the given CD track into the CD drive. The track's duration in milliseconds can be retrieved using the GetCdTrackDurationMs method.

Syntax

[Visual Basic]

control.GetCdTrackDuration (

nCdDriveIndex as Integer,

nTrackIndex as Integer

) as Long

[C++]

long control.GetCdTrackDuration (

short nCdDriveIndex,

short nTrackIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
nTrackIndex | Number representing the one-based index of the CD audio track. The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | The audio track duration expressed in seconds


GetCdTrackDurationMs method

GetCdTrackDurationMs method

Remarks

Retrieves the duration, expressed in milliseconds, of the given CD track into the CD drive.

Syntax

[Visual Basic]

control.GetCdTrackDurationMs (

nCdDriveIndex as Integer,

nTrackIndex as Integer

) as Long

[C++]

long control.GetCdTrackDurationMs (

short nCdDriveIndex,

short nTrackIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
nTrackIndex | Number representing the one-based index of the CD audio track. The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | The audio track duration expressed in milliseconds


GetCdTrackPathname method

GetCdTrackPathname method

Remarks

Given an audio track number, retrieves the relative file pathname.

The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Syntax

[Visual Basic]

control.GetCdTrackPathname (

nCdDriveIndex as Integer,

nTrackIndex as Integer

) as String

[C++]

LPCTSTR control..GetCdTrackPathname (

short nCdDriveIndex,

short nTrackIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
nTrackIndex | Number representing the one-based index of the CD audio track. The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The string containing the CD track file pathname.


PerformActionOnCd method

PerformActionOnCd method

Remarks

Performs an action on the given CD drive.

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

Syntax

[Visual Basic]

control.PerformActionOnCd (

nDrive as Integer,

nAction as enumCdActions

) as enumErrorCodes

[C++]

short control.PerformActionOnCd (

short nDrive,

short nAction

);

Parameter

Description

nDrive

Number representing the zero-based index of the involved CD drive

nAction

Number representing the action to perform.

Supported values are the following:

Mnemonic constant | Value | Meaning
CD_ACTION_OPEN | 0 | Opens the CD door
CD_ACTION_CLOSE | 1 | Closes the CD door

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


CuePointsAdd method

CuePointsAdd method

Remarks

Adds a cue point to the given player: when the cue point is reached, the CuePointReached event is fired.

Cue points positioning is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always refer to the position of the song as it should be played at its original speed.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsAdd (

nPlayer as Integer,

strCuePointName as String,

nCuePointPos as Long

) as enumErrorCodes

[C++]

short control.CuePointsAdd (

short nPlayer,

LPCTSTR strCuePointName,

long nCuePointPos

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strCuePointName | String containing the unique name that will identify the cue point from now on. If this name should be already assigned to an existing cue point, an error code would be returned
nCuePointPos | Number representing the cue point position expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


CuePointsEnable method

CuePointsEnable method

Remarks

Enables/disables the given cue point. You can know the status of a cue point by calling the CuePointsIsEnabled method.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsEnable (

nPlayer as Integer,

strCuePointName as String,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.CuePointsEnable (

short nPlayer,

LPCTSTR strCuePointName,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strCuePointName

String containing the unique name of the cue point as defined when the cue point was added through the CuePointsAdd method.

bEnable

Boolean value that specifies if the cue point must be enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Disable cue point
BOOL_TRUE (default) | 1 | Enable cue point

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


CuePointsGetCount method

CuePointsGetCount method

Remarks

Obtains the number of cue points set into the given player.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsGetCount (

nPlayer as Integer

) as Long

[C++]

long control.CuePointsGetCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player owning the cue points

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The number of existing cue points


CuePointsGetName method

CuePointsGetName method

Remarks

Given the position inside the list, obtains the name of the related cue point.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsGetName (

nPlayer as Integer,

nIndex as long

) as Long

[C++]

long control.CuePointsGetName (

short nPlayer,

long nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndex | Number representing the zero-based index of the cue point

Return value

Value | Meaning
Empty string | The value of the nIndex parameter was out of range. Use the value returned by the CuePointsGetCount method in order to know how many cue points are currently set.
Valid string | The string containing the name of the requested cue point.


CuePointsGetPos method

CuePointsGetPos method

Remarks

Obtains the current position for the given cue point.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsGetPos (

nPlayer as Integer,

strCuePointName as String

) as Long

[C++]

long control.CuePointsGetPos (

short nPlayer,

LPCTSTR strCuePointName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strCuePointName | String containing the unique name of the cue point as defined when the cue point was added through the CuePointsAdd method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | The cue point position expressed in milliseconds


CuePointsIsEnabled method

CuePointsIsEnabled method

Remarks

Verifies if the given cue point is enabled or disabled.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsIsEnabled (

nPlayer as Integer,

strCuePointName as String

) as Boolean

[C++]

BOOL control.CuePointsIsEnabled (

short nPlayer,

LPCTSTR strCuePointName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strCuePointName | String containing the unique name of the cue point as defined when the cue point was added through the CuePointsAdd method.

Return value

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Cue point is disabled
BOOL_TRUE | 1 | Cue point is enabled


CuePointsLoadFromFile method

CuePointsLoadFromFile method

Remarks

Loads a set of cue points from a CUE file.

CUE files are in XML format and contain settings for defining a pool of pre-defined cue points: CUE files can be created through your own code or through a call to the CuePointsSaveToFile method.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsLoadFromFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.CuePointsLoadFromFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the source CUE file. An empty string will force the control to search for a CUE file having the same filename of the loaded sound but with extension .cue: if for example the loaded sound file should be named MySong.mp3, the corresponding searched CUE file would be named MySong.cue

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CuePointsRemove method

CuePointsRemove method

Remarks

Removes an existing cue point from the given player.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsRemove (

nPlayer as Integer,

strCuePointName as String

) as enumErrorCodes

[C++]

short control.CuePointsRemove (

short nPlayer,

LPCTSTR strCuePointName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strCuePointName | String containing the unique name of the cue point as defined when the cue point was added through the CuePointsAdd method. An empty string would cause deleting all of the existing cue points.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


CuePointsSaveToFile method

CuePointsSaveToFile method

Remarks

Saves existing cue points into a destination CUE file.

CUE files are in XML format and contain settings for defining a pool of pre-defined cue points: CUE files can be loaded through a call to the CuePointsLoadFromFile method or automatically, when a sound is loaded, if the sound's filename and the CUE file's filename match: if for example the loaded sound file should be named MySong.mp3, the corresponding XML file containing cue points should be named MySong.cue

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsSaveToFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.CuePointsSaveToFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the destination CUE file.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CuePointsSetPos method

CuePointsSetPos method

Remarks

Modifies the current position for the given cue point.

Cue points positioning is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always refer to the position of the song as it should be played at its original speed.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

control.CuePointsSetPos (

nPlayer as Integer,

strCuePointName as String,

nCuePointPos as Long

) as enumErrorCodes

[C++]

short control.CuePointsSetPos (

short nPlayer,

LPCTSTR strCuePointName,

long nCuePointPos

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strCuePointName | String containing the unique name of the cue point as defined when the cue point was added through the CuePointsAdd method.
nCuePointPos | Number representing the new cue point position expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


LrcIdTagGet method

LrcIdTagGet method

Remarks

Obtains a specific ID tag, if any, from the loaded LRC file.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcIdTagGet (

nPlayer as Integer,

nTagType as enumLrcFileIdTags

) as String

[C++]

LPCTSTR control.LrcIdTagGet (

short nPlayer,

short nTagType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTagType

Tag type.

Supported values are the following:

Mnemonic constant | Value | Meaning
LRC_FILE_ID_TAG_TITLE | 0 | Title
LRC_FILE_ID_TAG_ARTIST | 1 | Artist
LRC_FILE_ID_TAG_AUTHORS | 2 | Authors
LRC_FILE_ID_TAG_ALBUM | 3 | Album
LRC_FILE_ID_TAG_CREATOR | 4 | Creator
LRC_FILE_ID_TAG_PROGRAM | 5 | Program used to create the LRC file
LRC_FILE_ID_TAG_VERSION | 6 | Version of the program used to create the LRC file

Return value

String containing the requested ID tag: an empty string means that the requested ID tag is not available inside the LRC file.


LrcLoad method

LrcLoad method

Remarks

Loads a Lyrics LRC file that will be related to the current loaded song.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcLoad (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.LrcLoad (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the LRC file.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


LrcNotifEnableGet method

LrcNotifEnableGet method

Remarks

Returns the actual enabled status for Lyrics notifications and auto-load of LRC files. The status can be modified through the LrcNotifEnableSet method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcNotifEnableGet (

) as Boolean

[C++]

BOOL control.LrcNotifEnableGet (

);

Return value

Value | Meaning
FALSE | Lyrics notifications and auto-load of LRC files are disabled
TRUE | Lyrics notifications and auto-load of LRC files are enabled


LrcNotifEnableSet method

LrcNotifEnableSet method

Remarks

Enables/disabled Lyrics notifications and auto-loading of LRC files. The current status can be obtained through the LrcNotifEnableGet method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcNotifEnableSet (

bEnable as enumBoolean

)

[C++]

void control.LrcNotifEnableSet (

short bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if Lyrics notifications and auto-loading of LRC files must be performed.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Lyrics notifications and auto-loading of LRC files are disabled
BOOL_TRUE (default) | 1 | Lyrics notifications and auto-loading of LRC files are enabled

Return value

None


LrcNotifTimingsGet method

LrcNotifTimingsGet method

Remarks

Obtains the current timings for lyrics notification events. Timings can be modified through the LrcNotifTimingsSet method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcNotifTimingsGet (

ByRef nAdvanceTimeFullLine as Long,

ByRef nRealTimeCompensation as Long

) as Long

[C++]

long control.LrcNotifTimingsGet (

long *nAdvanceTimeFullLine,

long *nRealTimeCompensation

);

Parameter | Description
nAdvanceTimeFullLine | Reference that, on return from the method call, will contain the advance time, expressed in milliseconds, used to fire the LrcAdvanceTimeLineFull event.
nRealTimeCompensation | Reference that, on return from the method call, will contain the time compensation, expressed in milliseconds, used to fire the LrcRealTimeLineFull and LrcRealTimeLinePortion events.

Return value

Value | Meaning
Empty string | The line was empty or an error occurred (see the LastError property for further error details)
Valid string | String containing the text of the requested enhanced tag


LrcNotifTimingsSet method

LrcNotifTimingsSet method

Remarks

Sets the current timings for lyrics notification events. Current timings can be obtained through the LrcNotifTimingsGet method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcNotifTimingsGet (

nAdvanceTimeFullLine as Long,

nRealTimeCompensation as Long

) as Long

[C++]

long control.LrcNotifTimingsGet (

long nAdvanceTimeFullLine,

long nRealTimeCompensation

);

Parameter | Description
nAdvanceTimeFullLine | The advance time, expressed in milliseconds, used to fire the LrcAdvanceTimeLineFull event.
nRealTimeCompensation | The time compensation, expressed in milliseconds, used to fire the LrcRealTimeLineFull and LrcRealTimeLinePortion events.

Return value

Value | Meaning
Empty string | The line was empty or an error occurred (see the LastError property for further error details)
Valid string | String containing the text of the requested enhanced tag


LrcTimeTagsEnhGetAt method

LrcTimeTagsEnhGetAt method

Remarks

Obtains the string of text and the related timing position for a specific Enhanced Time Tag inside the Lyrics LRC file. The total number of Enhanced Time Tag stored inside the Lyrics LRC file can be obtained using the LrcTimeTagsEnhGetCount method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcTimeTagsEnhGetAt (

nPlayer as Integer,

nIndex as Long,

ByRef nPosition as Long,

ByRef nDuration as Long

) as Long

[C++]

long control.LrcTimeTagsEnhGetAt (

short nPlayer,

long nIndex,

long *nPosition,

long *nDuration

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndex | Zero-based index of the Enhanced Time Tag
nPosition | Reference that, on return from the method call, will contain the Enhanced Time Tag position expressed in milliseconds.
nDuration | Reference that, on return from the method call, will contain the Enhanced Time Tag duration expressed in milliseconds.

Return value

Value | Meaning
Empty string | The line was empty or an error occurred (see the LastError property for further error details)
Valid string | String containing the text of the requested enhanced tag


LrcTimeTagsEnhGetCount method

LrcTimeTagsEnhGetCount method

Remarks

Obtains the number of Enhanced Time Tags stored inside the Lyrics LRC file. The text of each tag and its timing position, expressed in milliseconds, can be obtained through the LrcTimeTagsEnhGetAt method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcTimeTagsEnhGetCount (

nPlayer as Integer

) as Long

[C++]

long control.LrcTimeTagsEnhGetCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | Number of Enhanced Time Tags


LrcTimeTagsSimpleGetAt method

LrcTimeTagsSimpleGetAt method

Remarks

Obtains the string of text and the related timing position for a specific Line Time Tag inside the Lyrics LRC file. The total number of Line Time Tags stored inside the Lyrics LRC file can be obtained using the LrcTimeTagsSimpleGetCount method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcTimeTagsSimpleGetAt (

nPlayer as Integer,

nIndex as Long,

ByRef nPosition as Long

) as Long

[C++]

long control.LrcTimeTagsSimpleGetAt (

short nPlayer,

long nIndex,

long *nPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndex | Zero-based index of the Line Time Tag
nPosition | Reference that, on return from the method call, will contain the Line Time Tag position expressed in milliseconds.

Return value

Value | Meaning
Empty string | The line was empty or an error occurred (see the LastError property for further error details)
Valid string | String containing the line of text


LrcTimeTagsSimpleGetCount method

LrcTimeTagsSimpleGetCount method

Remarks

Obtains the number of Line Time Tags stored inside the Lyrics LRC file. The text of each single line and its timing position, expressed in milliseconds, can be obtained through the LrcTimeTagsSimpleGetAt method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

control.LrcTimeTagsSimpleGetCount (

nPlayer as Integer

) as Long

[C++]

long control.LrcTimeTagsSimpleGetCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | Number of Line Time Tags


GetOutputDeviceDesc method

GetOutputDeviceDesc method

Remarks

Retrieves the friendly description of the requested output device (sound card). This method is useful when you have to fill a combo box with the friendly names of available output devices.

The total number of available output devices can be obtained using the GetOutputDevicesCount method.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.GetOutputDeviceDesc (

nIndex as Integer

) as String

[C++]

LPCTSTR control.GetOutputDeviceDesc (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the output device whose friendly name must be retrieved

Return value

Value | Meaning
Empty string | The value of the nIndex parameter was out of range. Use the value returned by the GetOutputDevicesCount method in order to know how many output devices are currently installed on the system.
Valid string | The string containing the friendly description of the requested output device.


GetOutputDeviceDriverType method

GetOutputDeviceDriverType method

Remarks

Given the index of an output device returns its type of driver (DirectSound or ASIO).

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.GetOutputDeviceDriverType (

nIndex as Integer

) as enumDriverTypes

[C++]

short control.GetOutputDeviceDriverType (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the output device whose driver type must be retrieved

Return value

Mnemonic value | Numeric value | Meaning
ERR_xxx | Negative | An error occurred (see the LastError property for further error details)
DRIVER_TYPE_DIRECT_SOUND | 0 | DirectSound driver
DRIVER_TYPE_ASIO | 1 | ASIO driver


GetOutputDeviceLatency method

GetOutputDeviceLatency method

Remarks

Retrieves the latency time (expressed in milliseconds) of a certain output device (sound card). For details about latency, take a look to the How to deal with latency section.

Syntax

[Visual Basic]

control.GetOutputDeviceLatency (

nIndex as Integer

) as Integer

[C++]

short control.GetOutputDeviceLatency (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the output device whose latency time must be retrieved

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 0 | The current latency time of the chosen output device.


GetOutputDeviceMinBufferLength method

GetOutputDeviceMinBufferLength method

Remarks

Retrieves the minimal DirectSound buffer length (expressed in milliseconds) supported by a certain output device (sound card). For details about latency, take a look to the How to deal with latency section.

Syntax

[Visual Basic]

control.GetOutputDeviceMinBufferLength (

nIndex as Integer

) as Integer

[C++]

short control.GetOutputDeviceMinBufferLength (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the output device whose minimal DirectSound buffer length must be retrieved

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 0 | The current minimal DirectSound buffer length supported by the chosen output device.


GetOutputDevicesCount method

GetOutputDevicesCount method

Remarks

Retrieves the number of output devices (sound cards) currently installed on the system.

The friendly name of each output device can be obtained using the GetOutputDeviceDesc method.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.GetOutputDevicesCount (

) as Integer

[C++]

short control.GetOutputDevicesCount (

);

Return value

The number of output devices currently installed on the system.


GetOutputDeviceUniqueID method

GetOutputDeviceUniqueID method

Remarks

Retrieves the Unique Identifier (GUID) assigned by the system to the requested output device (sound card). This method allows discriminating between identical sound cards having the same friendly name.

The total number of available output devices can be obtained using the GetOutputDevicesCount method. The friendly name of each output device can be obtained using the GetOutputDeviceDesc method.

Syntax

[Visual Basic]

control.GetOutputDeviceUniqueID (

nIndex as Integer

) as String

[C++]

LPCTSTR control.GetOutputDeviceUniqueID (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the output device whose unique ID name must be retrieved

Return value

Value | Meaning
Empty string | The value of the nIndex parameter was out of range. Use the value returned by the GetOutputDevicesCount method in order to know how many output devices are currently installed on the system.
Valid string | The string containing the unique ID of the requested output device.


GetOutputSpeakersConfig method

GetOutputSpeakersConfig method

Remarks

Gets the actual speakers configuration for the given output device.

The actual speakers configuration can be set through the SetOutputSpeakersConfig method.

This method doesn't work in Windows Vista and Windows 7 where speakers configuration can be only set through the Windows Control Panel.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.GetOutputSpeakersConfig (

nIndex as Integer

) as enumSpeakersConfig

[C++]

short control.GetOutputSpeakersConfig (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the involved output device.

Return value

Mnemonic value | Numeric value | Meaning
ERR_xxx | Negative | An error occurred (see the LastError property for further error details)
SPEAKERS_STEREO | 0 | 2 stereo speakers (Stereo)
SPEAKERS_QUADRAPHONIC | 1 | 4 stereo speakers (Quadraphonic)
SPEAKERS_5_1 | 2 | 6 stereo speakers (5.1)
SPEAKERS_7_1 | 3 | 8 stereo speakers (7.1)


GetOutputSpeakersCount method

GetOutputSpeakersCount method

Remarks

Retrieves the number of speakers available on the given output device (sound card).

The total number of available output devices can be obtained using the GetOutputDevicesCount method.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.GetOutputSpeakersCount (

nIndex as Integer

) as Integer

[C++]

short control.GetOutputSpeakersCount (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the involved output device.

Return value

Value | Meaning
Value > 0 | The number of speakers available on the given output device
Negative value | An error occurred (see the LastError property for further error details)


MixerGetCount method

MixerGetCount method

Remarks

Retrieves the number of mixers currently installed on your system: usually this number is strictly related to the number of sound cards currently installed on your system.

The friendly name of each mixer can be obtained using the MixerGetDesc method.

IMPORTANT NOTE ABOUT THE WINDOWS VERSION: This method is only intended for usage when the operating system is Windows XP or older versions; for Windows Vista and higher versions it's recommended using methods exposed by the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.MixerGetCount (

) as Integer

[C++]

short control.MixerGetCount (

);

Return value

The number of mixers currently installed on the system.


MixerGetDesc method

MixerGetDesc method

Remarks

Retrieves the friendly description of the requested mixer. This method is very useful when you have to fill a combo box with the friendly names of the available mixers.

The total number of available mixers can be obtained using the MixerGetCount method.

IMPORTANT NOTE ABOUT THE WINDOWS VERSION: This method is only intended for usage when the operating system is Windows XP or older versions; for Windows Vista and higher versions it's recommended using methods exposed by the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.MixerGetDesc (

nIndex as Integer

) as String

[C++]

LPCTSTR control.MixerGetDesc (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the mixer whose friendly name must be retrieved

Return value

Value | Meaning
Empty string | The value of the nIndex parameter was out of range. Use the value returned by the MixerGetCount method in order to know how many mixers are currently installed on the system.
Valid string | The string containing the friendly description of the requested mixer.


MixerMuteGet method

MixerMuteGet method

Remarks

Obtains the mute state from a specific component of the given mixer.

The mute state can be modified using the MixerMuteSet method.

The number of mixers currently installed on the system can be retrieved using the MixerGetCount method. A friendly description of the mixer can be retrieved using the MixerGetDesc method.

IMPORTANT NOTE ABOUT THE WINDOWS VERSION: This method is only intended for usage when the operating system is Windows XP or older versions; for Windows Vista and higher versions it's recommended using methods exposed by the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.MixerMuteGet (

nIndex as Integer,

nComponentType as enumComponentTypes,

bMute as enumBoolean

) as enumBoolean

[C++]

short control.MixerMuteGet (

short nIndex,

short nComponentType,

short *bMute

);

Parameter

Description

nIndex

Number representing the zero-based index of the mixer whose master mute status must be retrieved. The total number of mixers currently installed on the system can be retrieved through the MixerGetCount method.

nComponentType

The type of mixer's component.

Supported values are the following:

Mnemonic constant | Value | Meaning
COMPONENTTYPE_DST_DIGITAL | 0 | Audio line is a digital destination (for example, digital input to a DAT or CD audio device).
COMPONENTTYPE_DST_LINE | 1 | Audio line is a line level destination (for example, line level input from a CD audio device) that will be the final recording source for the analog-to-digital converter (ADC). Because most audio cards for personal computers provide some sort of gain for the recording audio source line, the mixer device will use the COMPONENTTYPE_DST_WAVEIN type.
COMPONENTTYPE_DST_MONITOR | 2 | Audio line is a destination used for a monitor.
COMPONENTTYPE_DST_SPEAKERS | 3 | This is usually identified on the user interface as "Master volume". Audio line is an adjustable (gain and/or attenuation) destination intended to drive speakers. This is the typical component type for the audio output of audio cards for personal computers.
COMPONENTTYPE_DST_HEADPHONES | 4 | Audio line is an adjustable (gain and/or attenuation) destination intended to drive headphones. Most audio cards use the same audio destination line for speakers and headphones, in which case the mixer device simply uses the COMPONENTTYPE_DST_SPEAKERS type.
COMPONENTTYPE_DST_TELEPHONE | 5 | Audio line is a destination that will be routed to a telephone line.
COMPONENTTYPE_DST_WAVEIN | 6 | Audio line is a destination that will be the final recording source for the waveform-audio input (ADC). This line typically provides some sort of gain or attenuation. This is the typical component type for the recording line of most audio cards for personal computers.
COMPONENTTYPE_DST_VOICEIN | 7 | Audio line is a destination that will be the final recording source for voice input. This component type is exactly like COMPONENTTYPE_DST_WAVEIN but is intended specifically for settings used during voice recording/recognition. Support for this line is optional for a mixer device. Many mixer devices provide only COMPONENTTYPE_DST_WAVEIN.
COMPONENTTYPE_SRC_DIGITAL | 8 | Audio line is a digital source (for example, digital output from a DAT or audio CD).
COMPONENTTYPE_SRC_LINE | 9 | Audio line is a line-level source (for example, line-level input from an external stereo) that can be used as an optional recording source. Because most audio cards for personal computers provide some sort of gain for the recording source line, the mixer device will use the COMPONENTTYPE_SRC_AUXILIARY type.
COMPONENTTYPE_SRC_MICROPHONE | 10 | This is usually identified on the user interface as "Microphone". Audio line is a microphone recording source. Most audio cards for personal computers provide at least two types of recording sources: an auxiliary audio line and microphone input. A microphone audio line typically provides some sort of gain. Audio cards that use a single input for use with a microphone or auxiliary audio line should use the COMPONENTTYPE_SRC_MICROPHONE component type.
COMPONENTTYPE_SRC_SYNTHESIZER | 11 | Audio line is a source originating from the output of an internal synthesizer. Most audio cards for personal computers provide some sort of MIDI synthesizer.
COMPONENTTYPE_SRC_COMPACTDISC | 12 | Audio line is a source originating from the output of an internal audio CD. This component type is provided for audio cards that provide an audio source line intended to be connected to an audio CD (or CD-ROM playing an audio CD).
COMPONENTTYPE_SRC_TELEPHONE | 13 | Audio line is a source originating from an incoming telephone line.
COMPONENTTYPE_SRC_PCSPEAKER | 14 | Audio line is a source originating from personal computer speaker. Several audio cards for personal computers provide the ability to mix what would typically be played on the internal speaker with the output of an audio card. Some audio cards support the ability to use this output as a recording source.
COMPONENTTYPE_SRC_WAVEOUT | 15 | This is usually identified on the user interface as "Wave volume". Audio line is a source originating from the waveform-audio output digital-to-analog converter (DAC). Most audio cards for personal computers provide this component type as a source to the COMPONENTTYPE_DST_SPEAKERS destination. Some cards also allow this source to be routed to the COMPONENTTYPE_DST_WAVEIN destination.
COMPONENTTYPE_SRC_AUXILIARY | 16 | Audio line is a source originating from the auxiliary audio line. This line type is intended as a source with gain or attenuation that can be routed to the COMPONENTTYPE_DST_SPEAKERS destination and/or recorded from the COMPONENTTYPE_DST_WAVEIN destination.
COMPONENTTYPE_SRC_ANALOG | 17 | Audio line is an analog source (for example, analog output from a video-cassette tape).

bMute

Reference that, on return from the method call, will contain the muting state.

Supported values are the following:

Mnemonic constant | Meaning
BOOL_FALSE | The audio stream is not muted
BOOL_TRUE | The audio stream is muted

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MixerMuteSet method

MixerMuteSet method

Remarks

Modifies the mute state for a specific component of the given mixer.

The current mute state can be modified using the MixerMuteGet method.

The number of mixers currently installed on the system can be retrieved using the MixerGetCount method. A friendly description of the mixer can be retrieved using the MixerGetDesc method.

IMPORTANT NOTE ABOUT THE WINDOWS VERSION: This method is only intended for usage when the operating system is Windows XP or older versions; for Windows Vista and higher versions it's recommended using methods exposed by the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.MixerMuteSet (

nIndex as Integer,

nComponentType as enumComponentTypes,

bMute as enumBoolean

) as enumBoolean

[C++]

short control.MixerMuteSet (

short nIndex,

short nComponentType,

short bMute

);

Parameter

Description

nIndex

Number representing the zero-based index of the mixer whose master mute status must be retrieved. The total number of mixers currently installed on the system can be retrieved through the MixerGetCount method.

nComponentType

The type of mixer's component.

Supported values are the following:

Mnemonic constant | Value | Meaning
COMPONENTTYPE_DST_DIGITAL | 0 | Audio line is a digital destination (for example, digital input to a DAT or CD audio device).
COMPONENTTYPE_DST_LINE | 1 | Audio line is a line level destination (for example, line level input from a CD audio device) that will be the final recording source for the analog-to-digital converter (ADC). Because most audio cards for personal computers provide some sort of gain for the recording audio source line, the mixer device will use the COMPONENTTYPE_DST_WAVEIN type.
COMPONENTTYPE_DST_MONITOR | 2 | Audio line is a destination used for a monitor.
COMPONENTTYPE_DST_SPEAKERS | 3 | This is usually identified on the user interface as "Master volume". Audio line is an adjustable (gain and/or attenuation) destination intended to drive speakers. This is the typical component type for the audio output of audio cards for personal computers.
COMPONENTTYPE_DST_HEADPHONES | 4 | Audio line is an adjustable (gain and/or attenuation) destination intended to drive headphones. Most audio cards use the same audio destination line for speakers and headphones, in which case the mixer device simply uses the COMPONENTTYPE_DST_SPEAKERS type.
COMPONENTTYPE_DST_TELEPHONE | 5 | Audio line is a destination that will be routed to a telephone line.
COMPONENTTYPE_DST_WAVEIN | 6 | Audio line is a destination that will be the final recording source for the waveform-audio input (ADC). This line typically provides some sort of gain or attenuation. This is the typical component type for the recording line of most audio cards for personal computers.
COMPONENTTYPE_DST_VOICEIN | 7 | Audio line is a destination that will be the final recording source for voice input. This component type is exactly like COMPONENTTYPE_DST_WAVEIN but is intended specifically for settings used during voice recording/recognition. Support for this line is optional for a mixer device. Many mixer devices provide only COMPONENTTYPE_DST_WAVEIN.
COMPONENTTYPE_SRC_DIGITAL | 8 | Audio line is a digital source (for example, digital output from a DAT or audio CD).
COMPONENTTYPE_SRC_LINE | 9 | Audio line is a line-level source (for example, line-level input from an external stereo) that can be used as an optional recording source. Because most audio cards for personal computers provide some sort of gain for the recording source line, the mixer device will use the COMPONENTTYPE_SRC_AUXILIARY type.
COMPONENTTYPE_SRC_MICROPHONE | 10 | This is usually identified on the user interface as "Microphone". Audio line is a microphone recording source. Most audio cards for personal computers provide at least two types of recording sources: an auxiliary audio line and microphone input. A microphone audio line typically provides some sort of gain. Audio cards that use a single input for use with a microphone or auxiliary audio line should use the COMPONENTTYPE_SRC_MICROPHONE component type.
COMPONENTTYPE_SRC_SYNTHESIZER | 11 | Audio line is a source originating from the output of an internal synthesizer. Most audio cards for personal computers provide some sort of MIDI synthesizer.
COMPONENTTYPE_SRC_COMPACTDISC | 12 | Audio line is a source originating from the output of an internal audio CD. This component type is provided for audio cards that provide an audio source line intended to be connected to an audio CD (or CD-ROM playing an audio CD).
COMPONENTTYPE_SRC_TELEPHONE | 13 | Audio line is a source originating from an incoming telephone line.
COMPONENTTYPE_SRC_PCSPEAKER | 14 | Audio line is a source originating from personal computer speaker. Several audio cards for personal computers provide the ability to mix what would typically be played on the internal speaker with the output of an audio card. Some audio cards support the ability to use this output as a recording source.
COMPONENTTYPE_SRC_WAVEOUT | 15 | This is usually identified on the user interface as "Wave volume". Audio line is a source originating from the waveform-audio output digital-to-analog converter (DAC). Most audio cards for personal computers provide this component type as a source to the COMPONENTTYPE_DST_SPEAKERS destination. Some cards also allow this source to be routed to the COMPONENTTYPE_DST_WAVEIN destination.
COMPONENTTYPE_SRC_AUXILIARY | 16 | Audio line is a source originating from the auxiliary audio line. This line type is intended as a source with gain or attenuation that can be routed to the COMPONENTTYPE_DST_SPEAKERS destination and/or recorded from the COMPONENTTYPE_DST_WAVEIN destination.
COMPONENTTYPE_SRC_ANALOG | 17 | Audio line is an analog source (for example, analog output from a video-cassette tape).

bMute

The new muting state.

Supported values are the following:

Mnemonic constant | Meaning
BOOL_FALSE | The audio stream is not muted
BOOL_TRUE | The audio stream is muted

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MixerVolumeGet method

MixerVolumeGet method

Remarks

Obtains the volume from a specific component of the given mixer.

The returned volume can be modified using the MixerVolumeSet method.

The number of mixers currently installed on the system can be retrieved using the MixerGetCount method. A friendly description of the mixer can be retrieved using the MixerGetDesc method.

IMPORTANT NOTE ABOUT THE WINDOWS VERSION: This method is only intended for usage when the operating system is Windows XP or older versions; for Windows Vista and higher versions it's recommended using methods exposed by the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.MixerVolumeGet (

nIndex as Integer,

nComponentType as enumComponentTypes,

nValue as Long

) as Integer

[C++]

short control.MixerVolumeGet (

short nIndex,

short nComponentType,

long *nValue

);

Parameter

Description

nIndex

Number representing the zero-based index of the mixer whose volume must be retrieved.

nComponentType

The type of mixer's component.

Supported values are the following:

Mnemonic constant | Value | Meaning
COMPONENTTYPE_DST_DIGITAL | 0 | Audio line is a digital destination (for example, digital input to a DAT or CD audio device).
COMPONENTTYPE_DST_LINE | 1 | Audio line is a line level destination (for example, line level input from a CD audio device) that will be the final recording source for the analog-to-digital converter (ADC). Because most audio cards for personal computers provide some sort of gain for the recording audio source line, the mixer device will use the COMPONENTTYPE_DST_WAVEIN type.
COMPONENTTYPE_DST_MONITOR | 2 | Audio line is a destination used for a monitor.
COMPONENTTYPE_DST_SPEAKERS | 3 | This is usually identified on the user interface as "Master volume". Audio line is an adjustable (gain and/or attenuation) destination intended to drive speakers. This is the typical component type for the audio output of audio cards for personal computers.
COMPONENTTYPE_DST_HEADPHONES | 4 | Audio line is an adjustable (gain and/or attenuation) destination intended to drive headphones. Most audio cards use the same audio destination line for speakers and headphones, in which case the mixer device simply uses the COMPONENTTYPE_DST_SPEAKERS type.
COMPONENTTYPE_DST_TELEPHONE | 5 | Audio line is a destination that will be routed to a telephone line.
COMPONENTTYPE_DST_WAVEIN | 6 | Audio line is a destination that will be the final recording source for the waveform-audio input (ADC). This line typically provides some sort of gain or attenuation. This is the typical component type for the recording line of most audio cards for personal computers.
COMPONENTTYPE_DST_VOICEIN | 7 | Audio line is a destination that will be the final recording source for voice input. This component type is exactly like COMPONENTTYPE_DST_WAVEIN but is intended specifically for settings used during voice recording/recognition. Support for this line is optional for a mixer device. Many mixer devices provide only COMPONENTTYPE_DST_WAVEIN.
COMPONENTTYPE_SRC_DIGITAL | 8 | Audio line is a digital source (for example, digital output from a DAT or audio CD).
COMPONENTTYPE_SRC_LINE | 9 | Audio line is a line-level source (for example, line-level input from an external stereo) that can be used as an optional recording source. Because most audio cards for personal computers provide some sort of gain for the recording source line, the mixer device will use the COMPONENTTYPE_SRC_AUXILIARY type.
COMPONENTTYPE_SRC_MICROPHONE | 10 | This is usually identified on the user interface as "Microphone". Audio line is a microphone recording source. Most audio cards for personal computers provide at least two types of recording sources: an auxiliary audio line and microphone input. A microphone audio line typically provides some sort of gain. Audio cards that use a single input for use with a microphone or auxiliary audio line should use the COMPONENTTYPE_SRC_MICROPHONE component type.
COMPONENTTYPE_SRC_SYNTHESIZER | 11 | Audio line is a source originating from the output of an internal synthesizer. Most audio cards for personal computers provide some sort of MIDI synthesizer.
COMPONENTTYPE_SRC_COMPACTDISC | 12 | Audio line is a source originating from the output of an internal audio CD. This component type is provided for audio cards that provide an audio source line intended to be connected to an audio CD (or CD-ROM playing an audio CD).
COMPONENTTYPE_SRC_TELEPHONE | 13 | Audio line is a source originating from an incoming telephone line.
COMPONENTTYPE_SRC_PCSPEAKER | 14 | Audio line is a source originating from personal computer speaker. Several audio cards for personal computers provide the ability to mix what would typically be played on the internal speaker with the output of an audio card. Some audio cards support the ability to use this output as a recording source.
COMPONENTTYPE_SRC_WAVEOUT | 15 | This is usually identified on the user interface as "Wave volume". Audio line is a source originating from the waveform-audio output digital-to-analog converter (DAC). Most audio cards for personal computers provide this component type as a source to the COMPONENTTYPE_DST_SPEAKERS destination. Some cards also allow this source to be routed to the COMPONENTTYPE_DST_WAVEIN destination.
COMPONENTTYPE_SRC_AUXILIARY | 16 | Audio line is a source originating from the auxiliary audio line. This line type is intended as a source with gain or attenuation that can be routed to the COMPONENTTYPE_DST_SPEAKERS destination and/or recorded from the COMPONENTTYPE_DST_WAVEIN destination.
COMPONENTTYPE_SRC_ANALOG | 17 | Audio line is an analog source (for example, analog output from a video-cassette tape).

nValue

Reference that, on return from the method call, will contain the current volume in the range from 0 to 100

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MixerVolumeSet method

MixerVolumeSet method

Remarks

Sets the volume on a specific component of the given mixer: changing this volume will affect the volume also for other applications currently using the given mixer inside the system.

The current volume can be retrieved using the MixerVolumeGet method.

The number of mixers currently installed on the system can be retrieved using the MixerGetCount method. A friendly description of the mixer can be retrieved using the MixerGetDesc method.

IMPORTANT NOTE ABOUT THE WINDOWS VERSION: This method is only intended for usage when the operating system is Windows XP or older versions; for Windows Vista and higher versions it's recommended using methods exposed by the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.MixerVolumeSet (

nIndex as Integer,

nComponentType as enumComponentTypes,

nValue as Long

) as enumErrorCodes

[C++]

short control.MixerVolumeSet (

short nIndex,

short nComponentType,

long nValue

);

Parameter

Description

nIndex

Number representing the zero-based index of the mixer whose master volume must be set

nComponentType

The type of mixer's component.

Supported values are the following:

Mnemonic constant | Value | Meaning
COMPONENTTYPE_DST_DIGITAL | 0 | Audio line is a digital destination (for example, digital input to a DAT or CD audio device).
COMPONENTTYPE_DST_LINE | 1 | Audio line is a line level destination (for example, line level input from a CD audio device) that will be the final recording source for the analog-to-digital converter (ADC). Because most audio cards for personal computers provide some sort of gain for the recording audio source line, the mixer device will use the COMPONENTTYPE_DST_WAVEIN type.
COMPONENTTYPE_DST_MONITOR | 2 | Audio line is a destination used for a monitor.
COMPONENTTYPE_DST_SPEAKERS | 3 | This is usually identified on the user interface as "Master volume". Audio line is an adjustable (gain and/or attenuation) destination intended to drive speakers. This is the typical component type for the audio output of audio cards for personal computers.
COMPONENTTYPE_DST_HEADPHONES | 4 | Audio line is an adjustable (gain and/or attenuation) destination intended to drive headphones. Most audio cards use the same audio destination line for speakers and headphones, in which case the mixer device simply uses the COMPONENTTYPE_DST_SPEAKERS type.
COMPONENTTYPE_DST_TELEPHONE | 5 | Audio line is a destination that will be routed to a telephone line.
COMPONENTTYPE_DST_WAVEIN | 6 | Audio line is a destination that will be the final recording source for the waveform-audio input (ADC). This line typically provides some sort of gain or attenuation. This is the typical component type for the recording line of most audio cards for personal computers.
COMPONENTTYPE_DST_VOICEIN | 7 | Audio line is a destination that will be the final recording source for voice input. This component type is exactly like COMPONENTTYPE_DST_WAVEIN but is intended specifically for settings used during voice recording/recognition. Support for this line is optional for a mixer device. Many mixer devices provide only COMPONENTTYPE_DST_WAVEIN.
COMPONENTTYPE_SRC_DIGITAL | 8 | Audio line is a digital source (for example, digital output from a DAT or audio CD).
COMPONENTTYPE_SRC_LINE | 9 | Audio line is a line-level source (for example, line-level input from an external stereo) that can be used as an optional recording source. Because most audio cards for personal computers provide some sort of gain for the recording source line, the mixer device will use the COMPONENTTYPE_SRC_AUXILIARY type.
COMPONENTTYPE_SRC_MICROPHONE | 10 | This is usually identified on the user interface as "Microphone". Audio line is a microphone recording source. Most audio cards for personal computers provide at least two types of recording sources: an auxiliary audio line and microphone input. A microphone audio line typically provides some sort of gain. Audio cards that use a single input for use with a microphone or auxiliary audio line should use the COMPONENTTYPE_SRC_MICROPHONE component type.
COMPONENTTYPE_SRC_SYNTHESIZER | 11 | Audio line is a source originating from the output of an internal synthesizer. Most audio cards for personal computers provide some sort of MIDI synthesizer.
COMPONENTTYPE_SRC_COMPACTDISC | 12 | Audio line is a source originating from the output of an internal audio CD. This component type is provided for audio cards that provide an audio source line intended to be connected to an audio CD (or CD-ROM playing an audio CD).
COMPONENTTYPE_SRC_TELEPHONE | 13 | Audio line is a source originating from an incoming telephone line.
COMPONENTTYPE_SRC_PCSPEAKER | 14 | Audio line is a source originating from personal computer speaker. Several audio cards for personal computers provide the ability to mix what would typically be played on the internal speaker with the output of an audio card. Some audio cards support the ability to use this output as a recording source.
COMPONENTTYPE_SRC_WAVEOUT | 15 | This is usually identified on the user interface as "Wave volume". Audio line is a source originating from the waveform-audio output digital-to-analog converter (DAC). Most audio cards for personal computers provide this component type as a source to the COMPONENTTYPE_DST_SPEAKERS destination. Some cards also allow this source to be routed to the COMPONENTTYPE_DST_WAVEIN destination.
COMPONENTTYPE_SRC_AUXILIARY | 16 | Audio line is a source originating from the auxiliary audio line. This line type is intended as a source with gain or attenuation that can be routed to the COMPONENTTYPE_DST_SPEAKERS destination and/or recorded from the COMPONENTTYPE_DST_WAVEIN destination.
COMPONENTTYPE_SRC_ANALOG | 17 | Audio line is an analog source (for example, analog output from a video-cassette tape).

nValue

The new volume value in the range from 0 to 100.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The master volume has been changed correctly


SetOutputSpeakersConfig method

SetOutputSpeakersConfig method

Remarks

Sets the actual speakers configuration for the given output device.

The actual speakers configuration can be retrieved through the GetOutputSpeakersConfig method.

This method doesn't work in Windows Vista and Windows 7 where speakers configuration can be only set through the Windows Control Panel.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.SetOutputSpeakersConfig (

nIndex as Integer,

nNewConfig as enumSpeakersConfig

) as enumErrorCodes

[C++]

short control.SetOutputSpeakersConfig (

short nIndex,

short nNewConfig

);

Parameter

Description

nIndex

Number representing the zero-based index of the involved output device.

nNewConfig

The new speakers configuration.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
SPEAKERS_STEREO | 0 | 2 stereo speakers (Stereo)
SPEAKERS_QUADRAPHONIC | 1 | 4 stereo speakers (Quadraphonic)
SPEAKERS_5_1 | 2 | 6 stereo speakers (5.1)
SPEAKERS_7_1 | 3 | 8 stereo speakers (7.1)

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


AmazonStoreCdInfoCreate method

AmazonStoreCdInfoCreate method

Remarks

If the song loaded into the given player contains tag information, after having obtained the author name and the album title creates a request for obtaining information about the CD containing the song itself from the Amazon store. After this method's call it will be possible obtaining relevant information about the CD using provided methods as seen inside the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial.

Syntax

[Visual Basic]

control.AmazonStoreCdInfoCreate (

nPlayer as Integer,

strAmazonDeveloperCode as String

) as enumErrorCodes

[C++]

short control.AmazonStoreCdInfoCreate (

short nPlayer,

LPCTSTR strAmazonDeveloperCode

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player.

strAmazonDeveloperCode

String representing the Amazon developer code: this string is optional but it's strongly recommended that you obtain a developer code from Amazon; visit the Amazon Web Services site for creating your own account.

IMPORTANT TOPIC: starting from May 2009 the developer code is no more enough in order to access Amazon web services; from that date the access must be performed through a combination of the existing developer code and of a new secret key which is provided by Amazon itself to each registered developer. The new secret key can be requested through the Amazon control panel by accessing your Amazon account. Once you have obtained the new secret key, you can use this parameter in order to pass both the developer code and the secret key using the following syntax:

"DeveloperCode-----SecretKey"

where the existing developer code and the secret key are separated by 5 '-' (minus) characters.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


AmazonStoreCdInfoGet method

AmazonStoreCdInfoGet method

Remarks

After having performed a request to the Amazon store through the AmazonStoreCdInfoCreate method, obtains specific information about a CD.

For further information about obtaining CD info from the Amazon store, refer to the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial.

Syntax

[Visual Basic]

control.AmazonStoreCdInfoGet (

nPlayer as Integer,

nInfo as enumAmazonStoreInfo

) as String

[C++]

LPCTSTR control.AmazonStoreCdInfoGet (

short nPlayer,

short nInfo

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player.

nInfo

Requested information.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
AMAZON_STORE_CD_URL_COVER_SMALL | 0 | URL for small size picture of the CD cover. The local pathname of picture file containing this CD cover can be obtained through the AmazonStoreCdCoverPictureFileGet method passing CD_COVER_SIZE_SMALL to the nCdCoverSize parameter.
AMAZON_STORE_CD_URL_COVER_MEDIUM | 1 | URL for medium size picture of the CD cover. The local pathname of picture file containing this CD cover can be obtained through the AmazonStoreCdCoverPictureFileGet method passing CD_COVER_SIZE_MEDIUM to the nCdCoverSize parameter.
AMAZON_STORE_CD_URL_COVER_LARGE | 2 | URL for large size picture of the CD cover. The local pathname of picture file containing this CD cover can be obtained through the AmazonStoreCdCoverPictureFileGet method passing CD_COVER_SIZE_LARGE to the nCdCoverSize parameter.
AMAZON_STORE_CD_TRACKS_NUM | 3 | Number of tracks inside the CD. After having converted the returned string value into a numerical value, title of each single track can be obtained through the AmazonStoreCdTrackTitleGet method.
AMAZON_STORE_CD_YEAR | 4 | Year.
AMAZON_STORE_CD_URL_PURCHASE | 5 | Purchase URL. There is the possibility to navigate to the returned URL directly through the AmazonStoreCdNavigateToUrl method.

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The string containing the requested info


AmazonStoreCdCoverPictureFileGet method

AmazonStoreCdCoverPictureFileGet method

Remarks

After having performed a request to the Amazon store through the AmazonStoreCdInfoCreate method, if available obtains the local pathname of a CD cover picture.

For further information about obtaining CD info from the Amazon store, refer to the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial.

Syntax

[Visual Basic]

control.AmazonStoreCdCoverPictureFileGet (

nPlayer as Integer,

nCoverSize as enumCdCoverSizes

) as String

[C++]

LPCTSTR control.AmazonStoreCdCoverPictureFileGet (

short nPlayer,

short nCdCoverSize

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player.

nCdCoverSize

Identifies the size of the requested CD cover picture.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
CD_COVER_SIZE_SMALL | 0 | Small size (thumbnail)
CD_COVER_SIZE_MEDIUM | 1 | Medium size
CD_COVER_SIZE_LARGE | 2 | Large size

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The string containing the CD cover picture's full pathname


AmazonStoreCdNavigateToUrl method

AmazonStoreCdNavigateToUrl method

Remarks

After having performed a request to the Amazon store through the AmazonStoreCdInfoCreate method, if available opens the default Internet browser and navigates to the URL of the CD purchase page.

For further information about obtaining CD info from the Amazon store, refer to the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial.

Syntax

[Visual Basic]

control.AmazonStoreCdNavigateToUrl (

nPlayer as Integer

) as String

[C++]

LPCTSTR control.AmazonStoreCdNavigateToUrl (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


AmazonStoreCdTrackTitleGet method

AmazonStoreCdTrackTitleGet method

Remarks

After having performed a request to the Amazon store through the AmazonStoreCdInfoCreate method, if available obtains the title of a specific track of the CD.

For further information about obtaining CD info from the Amazon store, refer to the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial.

Syntax

[Visual Basic]

control.AmazonStoreCdTrackTitleGet (

nPlayer as Integer,

nTrackIndex as Integer

) as String

[C++]

LPCTSTR control.AmazonStoreCdTrackTitleGet (

short nPlayer,

short nTrackIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.
nTrackIndex | Number representing the one-based index of the CD audio track.

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The string containing the title of the CD track


CloseSound method

CloseSound method

Remarks

Discards a loaded sound and frees its memory. In case the given player should have been loaded with a video clip, the call to this method would have the same effect of the VideoPlayer.Close method.

A successful call to this method will fire the SoundClosed event.

Syntax

[Visual Basic]

control.CloseSound (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.CloseSound (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


CopyExportedWavToMemory method

CopyExportedWavToMemory method

Remarks

After calling the RequestSoundExportToWav method, in order to export the loaded song into a WAV file stored in memory, and receiving a successful ExportToWavStop event, this method allows copying into a memory buffer, allocated by the container application, the full contents of the memory WAV file: after this call the original memory buffer is immediately discarded from memory.

For further details about exporting a sound to a file in WAV format take a look to the How to export the loaded song into a WAV file section.

Syntax

[Visual Basic]

control.CopyExportedWavToMemory (

nPlayer as Integer,

pBuffer as Variant,

nBufferLength as Long

) as enumErrorCodes

[C++]

short control.CopyExportedWavToMemory (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLength

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
pBuffer | Buffer where WAV memory file contents will be copied
nBufferLength | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


ForwardSound method

ForwardSound method

Remarks

Forwards a sound of the amount that has been set through a previous call to the SetForwardRewindGranularity method.

Syntax

[Visual Basic]

control.ForwardSound (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.ForwardSound (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


GetBitsPerSample method

GetBitsPerSample method

Remarks

Retrieves the number of bits per sample of the loaded sound.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetBitsPerSample (

nPlayer as Integer

) as Long

[C++]

long control.GetBitsPerSample (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 0 | The number of bits per sample of the loaded sound


GetChannels method

GetChannels method

Remarks

Retrieves the number of channels in the loaded song.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetChannels (

nPlayer as Integer

) as Integer

[C++]

short control.GetChannels (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
1 | Mono
2 | Stereo
4 | Quadraphonic
6 | 5.1 Surround
8 | 7.1 Surround


GetCurrentHour method

GetCurrentHour method

Remarks

Gets the hours value for the current position during a playback session. If for example the current position is 1:3:15:234 (1 hour, 3 minutes, 15 seconds, 234 ms) the call will return 1.

Syntax

[Visual Basic]

control.GetCurrentHour (

nPlayer as Integer

) as Integer

[C++]

short control.GetCurrentHour (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | The number of hours inside the current playing position


GetCurrentMinute method

GetCurrentMinute method

Remarks

Gets the minutes value for the current position during a playback session. If for example the current position is 3:15:234 (3 minutes, 15 seconds, 234 ms) the call will return 3.

Syntax

[Visual Basic]

control.GetCurrentMinute (

nPlayer as Integer

) as Integer

[C++]

short control.GetCurrentMinute (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | The number of minutes inside the current playing position


GetCurrentMs method

GetCurrentMs method

Remarks

Gets the milliseconds value for the current position during a playback session. If for example the current position is 3:15:234 (3 minutes, 15 seconds, 234 ms) the call will return 234.

Syntax

[Visual Basic]

control.GetCurrentMs (

nPlayer As Integer

) as Integer

[C++]

short control.GetCurrentMs (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | The number of milliseconds inside the current playing position


GetCurrentPercentage method

GetCurrentPercentage method

Remarks

Gets the percentage of performed song during a playback session with the specified player.

Syntax

[Visual Basic]

control.GetCurrentPercentage (

nPlayer as Integer

) as Integer

[C++]

short control.GetCurrentPercentage (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

The current percentage: a return value of 0 may also indicate that an error occurred: check the LastError property in order to see if an error occurred.


GetCurrentPercentageFloat method

GetCurrentPercentageFloat method

Remarks

Gets the percentage of performed song during a playback session with the specified player.

Syntax

[Visual Basic]

control.GetCurrentPercentageFloat (

nPlayer as Integer

) as single

[C++]

float control.GetCurrentPercentageFloat (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

The current percentage: a return value of 0.0 may also indicate that an error occurred: check the LastError property in order to see if an error occurred.


GetCurrentSecond method

GetCurrentSecond method

Remarks

Gets the seconds value for the current position during a playback session. If for example the current position is 3:15:234 (3 minutes, 15 seconds, 234 ms) the call will return 15.

Syntax

[Visual Basic]

control.GetCurrentSecond (

nPlayer As Integer

) as Integer

[C++]

short control.GetCurrentSecond (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | The number of seconds inside the current playing position


GetEAXEffect method

GetEAXEffect method

Remarks

Retrieves the actual EAX effect's reverb parameters for the given output device.

EAX effects can be applied/retrieved only if the IsEAXAvailable method returns TRUE. You can change the current EAX settings through a call to the SetEAXEffect method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.GetEAXEffect (

nIndex as Integer,

nEffect as enumEaxEffects,

fReverbVolume as Single,

fReverbDecayTime as Single,

fReverbDecayHFRatio as Single

) as enumErrorCodes

[C++]

short control.GetEAXEffect (

short nIndex,

long *nEffect,

float *fReverbVolume,

float *fReverbDecayTime,

float *fReverbDecayHFRatio

);

Parameter

Description

nIndex

Number representing the zero-based index of the output device whose EAX settings must be retrieved

nEffect

Reference that, on return from the method call, will contain the EAX effect currently set into the given output device.

Possible values are the following:

Mnemonic value | Value | Meaning
EAX_GENERIC | 0 | Generic
EAX_PADDEDCELL | 1 | Padded cell
EAX_ROOM | 2 | Room
EAX_BATHROOM | 3 | Bathroom
EAX_LIVINGROOM | 4 | Living room
EAX_STONEROOM | 5 | Stone room
EAX_AUDITORIUM | 6 | Auditorium
EAX_CONCERTHALL | 7 | Concert hall
EAX_CAVE | 8 | Cave
EAX_ARENA | 9 | Arena
EAX_HANGAR | 10 | Hangar
EAX_CARPETEDHALLWAY | 11 | Carpeted hallway
EAX_HALLWAY | 12 | Hallway
EAX_STONECORRIDOR | 13 | Stone corridor
EAX_ALLEY | 14 | Alley
EAX_FOREST | 15 | Forest
EAX_CITY | 16 | City
EAX_MOUNTAINS | 17 | Mountains
EAX_QUARRY | 18 | Quarry
EAX_PLAIN | 19 | Plain
EAX_PARKINGLOT | 20 | Parking lot
EAX_SEWERPIPE | 21 | Sewer pipe
EAX_UNDERWATER | 22 | Underwater
EAX_DRUGGED | 23 | Drugged
EAX_DIZZY | 24 | Dizzy
EAX_DIZZY | 25 | Psychotic

fReverbVolume

Reference that, on return from the method call, will contain a floating point value representing the volume of the reverb's effect.

The value is expressed in percentage and can assume values from 0 to 100.

fReverbDecayTime

Reference that, on return from the method call, will contain a floating point value representing the time, expressed in seconds, for reverb to fade to -60 dB.

Supported values can range from 0.1 to 20

fReverbDecayHFRatio

Reference that, on return from the method call, will contain a floating point value representing the reverb's decay HF Ratio.

The value is expressed in percentage and can assume values from -100 to 100 with the following meaning:

-100 = high frequencies decay quickest

0 = low and high frequencies decay equally

100 = low frequencies decays quickest

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


GetEAXEffectWetDryMix method

GetEAXEffectWetDryMix method

Remarks

Gets the EAX effect's wet/dry mix ratio on the given player.

The actual wet/dry mix can be modified through the SetEAXEffectWetDryMix method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.GetEAXEffectWetDryMix (

nPlayer as Integer,

fWetDryMixRatio as Single

) as enumErrorCodes

[C++]

short control.GetEAXEffectWetDryMix (

short nPlayer,

float *fWetDryMixRatio

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fWetDryMixRatio | Reference that, on return from the method call, will contain a floating point value representing the wet/dry mix ratio. The value is expressed in percentage and can assume values from 0 to 100.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


GetFileType method

GetFileType method

Remarks

Retrieves the format of the sound file loaded into the given player.

Syntax

[Visual Basic]

control.GetFileType (

nPlayer as Integer

) as enumFileTypes

[C++]

short control.GetFileType (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Mnemonic constant | Value | Format
ERR_xxx | Negative | An error occurred (see the LastError property for further error details)
SOUNDTYPE_MP3 | 0 | MP3
SOUNDTYPE_WAV | 1 | WAV
SOUNDTYPE_MP2 | 2 | MP2
SOUNDTYPE_MP1 | 3 | MP1
SOUNDTYPE_OGG | 4 | OGG Vorbis
SOUNDTYPE_WMA | 5 | Windows Media Audio
SOUNDTYPE_MOD | 6 | MOD Music
SOUNDTYPE_MTM | 7 | MTM MOD Music
SOUNDTYPE_S3M | 8 | S3M MOD Music
SOUNDTYPE_XM | 9 | XM MOD Music
SOUNDTYPE_IT | 10 | IT MOD Music
SOUNDTYPE_MO3 | 11 | MO3 MOD Music
SOUNDTYPE_CD | 12 | CD Track
SOUNDTYPE_AIFF | 13 | AIFF
SOUNDTYPE_FLAC | 14 | FLAC
SOUNDTYPE_AAC | 15 | AAC
SOUNDTYPE_MP4 | 16 | MP4
SOUNDTYPE_AC3 | 17 | AC3
SOUNDTYPE_ALAC | 18 | ALAC
SOUNDTYPE_WV | 19 | WavPack
SOUNDTYPE_WAV_ENCODED | 20 | Encoded WAV
SOUNDTYPE_AU | 21 | Sun/NeXT AU
SOUNDTYPE_PAF | 22 | Ensoniq PARIS
SOUNDTYPE_SVX | 23 | Commodore Amiga IFF / SVX
SOUNDTYPE_NIST | 24 | Sphere NIST
SOUNDTYPE_VOC | 25 | Creative VOC
SOUNDTYPE_IRCAM | 26 | Berkeley/IRCAM/CARL
SOUNDTYPE_W64 | 27 | Sonic Foundry's 64 bit RIFF/WAV
SOUNDTYPE_PVF | 28 | Portable Voice Format
SOUNDTYPE_CAF | 29 | Core Audio File
SOUNDTYPE_RAW | 30 | Raw file
SOUNDTYPE_APE | 31 | Monkey's audio
SOUNDTYPE_MPC | 32 | MusePack
SOUNDTYPE_SPX | 33 | Speex
SOUNDTYPE_MIDI | 34 | MIDI
SOUNDTYPE_MIDI_INSTRUMENT | 35 | MIDI instrument from VST plugin
SOUNDTYPE_OPUS | 36 | Opus
SOUNDTYPE_EXT_PLUGIN_ADX | 1000 | ADX audio file loaded through the external BASS plugin Bass_adx.dll in combination with the BassPluginStreamCreateFunc method.
SOUNDTYPE_EXT_PLUGIN_AIX | 1001 | AIX audio file loaded through the external BASS plugin Bass_aix.dll in combination with the BassPluginStreamCreateFunc method.
SOUNDTYPE_EXT_PLUGIN_OFR | 1002 | OptinFROG audio file loaded through the external BASS plugin Bass_OFR.dll in combination with the BassPluginStreamCreateFunc method.
SOUNDTYPE_EXT_PLUGIN_TTA | 1003 | TTA audio file loaded through the external BASS plugin Bass_tta.dll in combination with the BassPluginStreamCreateFunc method.


GetFormattedSoundFileDuration method

GetFormattedSoundFileDuration method

Remarks

Returns a formatted string, containing the duration of the given sound file, using the following format [hh:mm:ss:ms(3)] in which hh is for hours, mm is for minutes, ss is for seconds and ms(3) are three characters representing the milliseconds. For example [04:34:200] indicates a song during 0 hours (the hours number is automatically omitted if 0), 4 minutes, 34 seconds and 200 milliseconds.

Accepted formats are the same of the LoadSound method.

Syntax

[Visual Basic]

control.GetFormattedSoundFileDuration (

strPathame as String

) as Long

[C++]

long control.GetFormattedSoundFileDuration (

LPCTSTR strPathame

);

Parameter | Description
strPathname | String containing the absolute pathname of the song file to check.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The formatted song duration


GetForwardRewindGranularity method

GetForwardRewindGranularity method

Remarks

Retrieves the actual granularity for the forward and rewind operations of the current loaded sound or video clip: the returned value is expressed in the same unit specified by the ScaleUnits property.

A new granularity value can be specified through the SetForwardRewindGranularity method.

Syntax

[Visual Basic]

control.GetForwardRewindGranularity (

nPlayer as Integer,

fGranularity as single

) as enumErrorCodes

[C++]

short control.GetForwardRewindGranularity (

short nPlayer,

float *fGranularity

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fGranularity | Pointer to the granularity value expressed in the same unit specified by the ScaleUnits property.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GetFrequency method

GetFrequency method

Remarks

Retrieves the frequency of the loaded sound expressed in Hertz.

The availability of this information requires a prior call to the ReadSoundInfo method.

Syntax

[Visual Basic]

control.GetFrequency (

nPlayer as Integer

) as Long

[C++]

long control.GetFrequency (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 0 | The frequency of the loaded sound


GetLoadedSoundFile method

GetLoadedSoundFile method

Remarks

Obtains the absolute pathname of the sound file or the URL of the Internet stream currently loaded into the given player.

Syntax

[Visual Basic]

control.GetLoadedSoundFile (

nPlayer as Integer

) as String

[C++]

LPCTSTR control.GetLoadedSoundFile (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the absolute pathname


GetMp3BitrateType method

GetMp3BitrateType method

Remarks

If the sound file loaded inside the given player is in MP3 format, obtains its bitrate type.

Syntax

[Visual Basic]

control.GetMp3BitrateType (

nPlayer as Integer

) as enumMp3BitrateTypes

[C++]

short control.GetMp3BitrateType (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Mnemonic constant | Value | Meaning
ERR_xxx | Negative | An error occurred (see the LastError property for further error details)
BITRATE_TYPE_UNKNOWN | 0 | It wasn't possible determining the type
BITRATE_TYPE_CBR | 1 | Constant bitrate (CBR)
BITRATE_TYPE_VBR | 2 | Variable bitrate (VBR)


GetPlayerHandle method

GetPlayerHandle method

Remarks

Obtains the handle of the given player. This method can be used in combination with the PlayerSettingsApply method of the Active Sound Editor control.

Syntax

[Visual Basic]

control.GetPlayerHandle (

nPlayer as Integer

) as Long

[C++]

long control.GetPlayerHandle (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Value > 0 | The player's handle
Negative value | An error occurred (see the LastError property for further error details)


GetPlayerSpeakersCount method

GetPlayerSpeakersCount method

Remarks

Retrieves the number of speakers available on the output device (sound card) associated to the given player.

This method can be used in alternative to the GetOutputSpeakersCount method.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.GetPlayerSpeakersCount (

nPlayer as Integer

) as Integer

[C++]

short control.GetPlayerSpeakersCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.

Return value

Value | Meaning
Value > 0 | The number of speakers available on the given output device
Negative value | An error occurred (see the LastError property for further error details)


GetPlayerStatus method

GetPlayerStatus method

Remarks

Gets the given player working status.

Syntax

[Visual Basic]

control.GetPlayerStatus (

nPlayer as Integer

) as enumStates

[C++]

short control.GetPlayerStatus (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Mnemonic Value | Numeric value | Meaning
ERR_xxx | Negative | An error occurred (see the LastError property for further error details)
SOUND_NONE | 0 | The player is in a undetermined status (no sound has been loaded)
SOUND_PLAYING | 1 | The player is playing the loaded sound
SOUND_PAUSED | 2 | The player has been paused
SOUND_STOPPED | 3 | The player has been stopped
SOUND_BUFFERING | 4 | The player is buffering an Internet stream
SOUND_STREAM_QUEUE_STALLED | 5 | Playback of a queued sound stream created through the StreamQueueCreate method doesn't have enough data to play and has been stalled


GetSampleRate method

GetSampleRate method

Remarks

Gets the sample rate applied to DirectSound buffer during playback. The sample rate can be modified through the SetSampleRate method.

Syntax

[Visual Basic]

control.GetSampleRate (

nPlayer as Integer

) as Long

[C++]

long control.GetSampleRate (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

The sample rate rate expressed in samples per second.


GetSoundFileDuration method

GetSoundFileDuration method

Remarks

Returns the duration of the given sound file.

Accepted formats are the same of the LoadSound method.

Syntax

[Visual Basic]

control.GetSoundFileDuration (

strPathame as String

) as Long

[C++]

long control.GetSoundFileDuration (

LPCTSTR strPathame

);

Parameter | Description
strPathname | String containing the absolute pathname of the song file to check.

Return value

Value | Meaning
Value > 0 | Duration expressed in milliseconds
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadEncryptedSound method

LoadEncryptedSound method

Remarks

Loads a song, previously encrypted through the CryptSound™ application, from the specified file.

Accepted formats for the original (not encrypted) file are the same supported by the LoadSound method.

A successful call to this method will fire the SoundLoaded event.

For further details about encrypted songs usage check the How to protect your music through encryption section.

Syntax

[Visual Basic]

control.LoadEncryptedSound (

nPlayer as Integer,

strFileName as String,

strDecriptionKey as String

) as enumErrorCodes

[C++]

short control.LoadEncryptedSound (

short nPlayer,

LPCTSTR strFileName,

LPCTSTR strDecriptionKey

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the absolute pathname of the encrypted song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.
strDecriptionKey | String containing the key used to originally encrypt the song: its length can be from a minimum of 16 characters to a maximum of 32 characters.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadEncryptedSoundFromMemory method

LoadEncryptedSoundFromMemory method

Remarks

Loads a song, previously encrypted through the CryptSound™ application, from the given memory buffer.

Accepted formats for the original (not encrypted) file are the same supported by the LoadSound method.

A successful call to this method will fire the SoundLoaded event.

For further details about encrypted songs usage check the How to protect your music through encryption section.

Syntax

[Visual Basic]

control.LoadEncryptedSoundFromMemory (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

strDecriptionKey as String

) as enumErrorCodes

[C++]

short control.LoadEncryptedSoundFromMemory (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

LPCTSTR strDecriptionKey

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
pBuffer | Variant parameter containing the pointer to sound data previously loaded in memory.
nBufferLen | Length in bytes of the given buffer
strDecriptionKey | String containing the key used to originally encrypt the song: its length can be from a minimum of 16 characters to a maximum of 32 characters.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadEncryptedSoundFromMemorySync method

LoadEncryptedSoundFromMemorySync method

Remarks

Loads a song, previously encrypted through the CryptSound™ application, from the given memory buffer through a secondary thread..

Accepted formats for the original (not encrypted) file are the same supported by the LoadSound method.

Once the secondary thread is completed, a SoundSyncLoaded event will be fired.

For further details about encrypted songs usage check the How to protect your music through encryption section.

Syntax

[Visual Basic]

control.LoadEncryptedSoundFromMemorySync (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

strDecriptionKey as String

) as enumErrorCodes

[C++]

short control.LoadEncryptedSoundFromMemorySync (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

LPCTSTR strDecriptionKey

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
pBuffer | Variant parameter containing the pointer to sound data previously loaded in memory.
nBufferLen | Length in bytes of the given buffer
strDecriptionKey | String containing the key used to originally encrypt the song: its length can be from a minimum of 16 characters to a maximum of 32 characters.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadEncryptedSoundSync method

LoadEncryptedSoundSync method

Remarks

Loads a song, previously encrypted through the CryptSound™ application, from the specified file through a secondary thread.

Accepted formats for the original (not encrypted) file are the same supported by the LoadSound method.

Once the secondary thread is completed, a SoundSyncLoaded event will be fired.

For further details about encrypted songs usage check the How to protect your music through encryption section.

Syntax

[Visual Basic]

control.LoadEncryptedSoundSync (

nPlayer as Integer,

strFileName as String,

strDecriptionKey as String

) as enumErrorCodes

[C++]

short control.LoadEncryptedSoundSync (

short nPlayer,

LPCTSTR strFileName,

LPCTSTR strDecriptionKey

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the absolute pathname of the encrypted song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.
strDecriptionKey | String containing the key used to originally encrypt the song: its length can be from a minimum of 16 characters to a maximum of 32 characters.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadInternetStream method

LoadInternetStream method

Remarks

Loads a song from the Internet or from a Shoutcast/Icecast server.

This method will try to open the Internet stream using different audio format decoders until the compatible one is found: accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, AC3, FLAC, WAV, OGG Vorbis, WMA (*), ASF (**), WMV (**), OPUS and HLS (HTTP Live Streaming).

In case you should already know the exact audio format of the Internet stream, you may select the proper one through the LoadInternetStreamEx method, allowing a faster availability of audio data to play.

MOD formats are not accepted: if you want to play MOD music downloaded from the Internet, you should download the MOD file into local memory (for example using the Microsoft WININET API) and then use the LoadSoundFromMemory method.

A successful call to this method will fire the DownloadBuffering event.

In case you should be downloading a single file (not a radio stream), once the download completes the DownloadComplete event will be fired: if for example you need to retrieve the ID3V1 tag of a downloaded MP3 file, information available only on the latest bytes of the file, you could use this event to trigger the availability of the needed Tag.

Once the downloaded stream or file has enough playable data, the control will fire the StreamLoaded event.

Default settings related to Internet connections can be retrieved and modified through the InternetSettingsGet and InternetSettingsSet methods.

For further details about Internet streams support see the How to play Internet streams and radio stations section.

Syntax

[Visual Basic]

control.LoadInternetStream (

nPlayer as Integer,

strURL as String

) as enumErrorCodes

[C++]

short control.LoadInternetStream (

short nPlayer,

LPCTSTR strURL

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strURL | String containing the URL of the stream to load. Accepted URLs begin with "http://", "ftp://" or "mms://". Passing an empty string will cause to cancel any previous call to the LoadInternetStream method.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.

(*) Requires Microsoft Windows Media Format modules already installed on the target PC

(**) Performs sound tracks only (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs sound tracks only (no video)

The Windows Media Format modules can be installed using the redistribution setup package (wmfdist.exe) provided by Microsoft. Details about the integration of these modules inside your own setup package can be found on the following link of the official Microsoft web site (note that in the future this link could change due to the Microsoft site maintenance).


LoadInternetStreamEx method

LoadInternetStreamEx method

Remarks

Loads a song from the Internet or from a Shoutcast/Icecast server.

Accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, AC3, FLAC, WAV, OGG Vorbis, WMA (*), ASF (**), WMV (**), OPUS and HLS (HTTP Live Streaming).

MOD formats are not accepted: if you want to play MOD music downloaded from the Internet, you should download the MOD file into local memory (for example using the Microsoft WININET API) and then use the LoadSoundFromMemory method.

A successful call to this method will fire the DownloadBuffering event.

In case you should be downloading a single file (not a radio stream), once the download completes the DownloadComplete event will be fired: if for example you need to retrieve the ID3V1 tag of a downloaded MP3 file, information available only on the latest bytes of the file, you could use this event to trigger the availability of the needed Tag.

Once the downloaded stream or file has enough playable data, the control will fire the StreamLoaded event.

Default settings related to Internet connections can be retrieved and modified through the InternetSettingsGet and InternetSettingsSet methods.

For further details about Internet streams support see the How to play Internet streams and radio stations section.

Syntax

[Visual Basic]

control.LoadInternetStreamEx (

nPlayer as Integer,

strURL as String,

nFormat as enumFileTypes,

nOffsetInSizePerc as Long

) as enumErrorCodes

[C++]

short control.LoadInternetStreamEx (

short nPlayer,

LPCTSTR strURL,

short nFormat,

long nOffsetInSizePerc

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the sound

strURL

String containing the URL of the stream to load. Accepted URLs begin with "http://", "ftp://" or "mms://".

Passing an empty string will cause to cancel any previous call to the LoadInternetStream or LoadInternetStreamEx methods.

nFormat

Type of audio format to try first, allowing a faster creation of the Internet stream when the audio format produced by the server is known in advance.

In case the URL should produce a different audio format, the control will in any case try against other supported audio formats.

This parameter is ignored when set to -1.

Supported values are the following:

Mnemonic constant | Value | Format
SOUNDTYPE_MP3 | 0 | MP3
SOUNDTYPE_MP2 | 2 | MP2
SOUNDTYPE_MP1 | 3 | MP1
SOUNDTYPE_OGG | 4 | OGG Vorbis
SOUNDTYPE_WMA | 5 | Windows Media Audio
SOUNDTYPE_AIFF | 13 | AIFF
SOUNDTYPE_FLAC | 14 | FLAC
SOUNDTYPE_AAC | 15 | AAC
SOUNDTYPE_MP4 | 16 | MP4
SOUNDTYPE_AC3 | 17 | AC3
SOUNDTYPE_WV | 19 | WavPack
SOUNDTYPE_OPUS | 36 | Opus
SOUNDTYPE_HLS | 37 | HLS (HTTP Live Streaming)

nOffsetInSizePerc

Offset to start downloading from expressed in percentage of the original file size.

When the URL doesn't point to a continuous flow of audio data generated by Shoutcast/Icecast servers, as in the case of Internet radios, but points to an audio file having a defined size, this parameter allows discarding a certain amount of data at the beginning of the file itself and starting buffering audio data at a later position.

In case of compressed files like MP3, the percentage is related to the compressed file and not to the uncompressed and decoded audio data.

This parameter is ignored when set to 0.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.

(*) Requires Microsoft Windows Media Format modules already installed on the target PC

(**) Performs sound tracks only (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs sound tracks only (no video)

The Windows Media Format modules can be installed using the redistribution setup package (wmfdist.exe) provided by Microsoft. Details about the integration of these modules inside your own setup package can be found on the following link of the official Microsoft web site (note that in the future this link could change due to the Microsoft site maintenance).


LoadSound method

LoadSound method

Remarks

Loads a song from the specified file. The sound file can be a stream, a MOD music file or a CD audio track.

Accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, M4A, AC3, FLAC, WavPack, ALAC, WAV, OGG Vorbis, WMA (*), ASF (**), WMV (**), W64, AU, PAF, SVX, NIST, VOC, IRCAM, PVF, CAF, Speex, Musepack, Monkey's Audio (APE), OPUS.

Formats wrapped inside a RIFF container (for example GSM 6.10, ADPCM, CCITT, etc. ) are supported if the specific ACM (Audio Compression Manager) codec is installed inside the system.

Multi-channel WAV, AIFF, OGG Vorbis and WMA formats are accepted if the output sound card supports speakers assignment and have WDM drivers installed: it's important to note that multi-channel sound files won't allow changing Tempo, Pitch and Playback rate and won't support DMO or EAX effects.

Accepted MOD formats are: MOD, MTM, S3M, XM, IT and MO3

Accepted CD audio tracks format is CDA; CD tracks can be loaded with the LoadTrackFromCD method also.

If the file is in RAW format use the LoadSoundFromRawFile method.

Other formats not supported natively may be loaded through DirectShow: for formats not supported natively you can enable the automatic usage of DirectShow on a specific player by invoking the DirectShowAutoLoadEnable method with parameter "BOOL_TRUE". After a sound or video file has been loaded, you may eventually verify if its rendering is performed through DirectShow by invoking the IsDirectShowLoadedFile method.

A successful call to this method will fire the SoundLoaded event.

Syntax

[Visual Basic]

control.LoadSound (

nPlayer as Integer,

strFileName as String

) as enumErrorCodes

[C++]

short control.LoadSound (

short nPlayer,

LPCTSTR strFileName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the absolute pathname of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.

(*) Requires Microsoft Windows Media Format modules already installed on the target PC: you can verify the presence of these modules through a call to the IsWmaAvailable method.

(**) Performs sound tracks only (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs sound tracks only (no video)

The Windows Media Format modules can be installed using the redistribution setup package (wmfdist.exe) provided by Microsoft. Details about the integration of these modules inside your own setup package can be found on the following link of the official Microsoft web site (note that in the future this link could change due to the Microsoft site maintenance).


LoadSoundFast method

LoadSoundFast method

Remarks

Loads a song from the specified file.

This method acts exactly as the LoadSound method but performs a less detailed analysis for files in MP3 format: the use of this method is indicated when you need an immediate loading of MP3 files from a network.

A successful call to this method will fire the SoundLoaded event.

Syntax

[Visual Basic]

control.LoadSoundFast (

nPlayer as Integer,

strFileName as String

) as enumErrorCodes

[C++]

short control.LoadSoundFast (

short nPlayer,

LPCTSTR strFileName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the absolute pathname of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadSoundFastFromMemory method

LoadSoundFastFromMemory method

Remarks

Loads a sound file stored inside a memory buffer. The sound file can be a stream file (see the LoadSound method for accepted stream formats) or a MOD music file.

This method acts exactly as the LoadSoundFromMemory method but performs a less detailed analysis for files in MP3 format

A successful call to this method will fire the SoundLoaded event.

Syntax

[Visual Basic]

control.LoadSoundFastFromMemory (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.LoadSoundFastFromMemory (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the memory sound
pBuffer | Variant parameter containing the pointer to sound data previously loaded in memory.
nBufferLen | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


LoadSoundForEAX method

LoadSoundForEAX method

Remarks

Loads a song from the specified file with EAX compatible settings (Mono); After loading a song with this method it will be possible applying EAX effects.

Accepted sound formats are MP3, MP2, MP1 (Stereo or Mono) and sounds in Mono as supported by the LoadSound method.

A successful call to this method will fire the SoundLoaded event.

Note that songs loaded with this method will not have the possibility to change Tempo, Playback rate or Pitch and cannot be attached to custom stream mixers.

For further details about EAX effects take a look to the How to apply special effects to a playing sound section.

Syntax

[Visual Basic]

control.LoadSoundForEAX (

nPlayer as Integer,

strFileName as String,

bFast as enumBoolean

) as enumErrorCodes

[C++]

short control.LoadSoundForEAX (

short nPlayer,

LPCTSTR strFileName,

short bFast

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the absolute pathname of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.
bFast | Flag that determines if a less detailed analysis must be performed for files in MP3 format: the use of this method is indicated when you need an immediate loading of MP3 files from a network.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadSoundFromEditingSession method

LoadSoundFromEditingSession method

Remarks

Loads a sound from an instance of the Active Sound Editor control.

Syntax

[Visual Basic]

control.LoadSoundFromEditingSession (

nPlayer as Integer,

hWndEditorCtrl as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.LoadSoundFromEditingSession (

short nPlayer,

OLE_HANDLE hWndEditorCtrl

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
hWndEditorCtrl | Window handle to the instance of a Active Sound Editor control

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


LoadSoundFromMemory method

LoadSoundFromMemory method

Remarks

Loads a sound file stored inside a memory buffer. The sound file can be a stream file (see the LoadSound method for accepted stream formats) or a MOD music file.

If the sound is in RAW format use the LoadSoundFromRawMemory method.

A successful call to this method will fire the SoundLoaded event.

Syntax

[Visual Basic]

control.LoadSoundFromMemory (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.LoadSoundFromMemory (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the memory sound
pBuffer | Variant parameter containing the pointer to sound data previously loaded in memory.
nBufferLen | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.

Samples

Below you can find a couple of samples that demonstrate how to load a memory sound in Visual Basic 6 and Visual C++ 6: the memory sound has been taken from a .RES resource file using the "identifier" variable.

Visual Basic 6

' the memory buffer must be declared as global

Dim bytSound() As Byte

Private Sub Command1_Click()

 Dim length As Long

 bytSound = LoadResData(identifier, 10)

 length = UBound(bytSound)

 Amp3dj1.LoadSoundFromMemory 0, VarPtr(bytSound(0)), length

 Amp3dj1.PlaySound 0

End Sub

Visual C++ 6 with MFC

void CMyDialog::OnButton1()

{

 HINSTANCE hInst = AfxGetResourceHandle();

 HRSRC hrsrc = ::FindResource(hInst, MAKEINTRESOURCE (identifier), RT_RCDATA);

 if (!hrsrc)

     return;

 HGLOBAL hg = LoadResource(hInst, hrsrc);

 if (!hg)

     return;

 BYTE    *pRes = (BYTE*) LockResource(hg);

 ASSERT(pRes);

 int iSize = ::SizeofResource(hInst, hrsrc);

 VARIANT      va;

 VariantInit (&va);

 va.vt = VT_BYREF | VT_UI1;

 va.pbVal = (BYTE *) pRes;

 m_ctrlActiveDJ.LoadSoundFromMemory (0, va, iSize);

 m_ctrlActiveDJ.PlaySound (0);

}


LoadSoundFromMemorySync method

LoadSoundFromMemorySync method

Remarks

Loads a sound file, stored in memory, through a secondary thread. The sound file can be a stream file (see the LoadSound method for accepted stream formats) or a MOD music file.

A successful call to this method will fire the SoundSyncLoaded event.

Syntax

[Visual Basic]

control.LoadSoundFromMemorySync (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.LoadSoundFromMemorySync (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the memory sound
pBuffer | Variant parameter containing the pointer to sound data previously loaded in memory.
nBufferLen | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


LoadSoundFromRawFile method

LoadSoundFromRawFile method

Remarks

Loads a song from the specified file in RAW format.

A successful call to this method will fire the SoundLoaded event.

Syntax

[Visual Basic]

control.LoadSoundFromRawFile (

nPlayer as Integer,

strFileName as String,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as enumBoolean,

nFrequency as Long,

nChannels as Long

) as enumErrorCodes

[C++]

short control.LoadSoundFromRawFile (

short nPlayer,

LPCTSTR strFileName,

short nEncodeMode,

short bIsBigEndian,

long nFrequency,

long nChannels

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the absolute pathname of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
RAW_ENCODE_PCM_U8 | 0 | RAW PCM 8 bits Unsigned
RAW_ENCODE_PCM_S8 | 1 | RAW PCM 8 bits Signed
RAW_ENCODE_PCM_S16 | 2 | RAW PCM 16 bits Signed
RAW_ENCODE_PCM_S24 | 3 | RAW PCM 24 bits Signed
RAW_ENCODE_PCM_S32 | 4 | RAW PCM 32 bits Signed
RAW_ENCODE_FLOAT32 | 5 | RAW 32 bits floating point
RAW_ENCODE_G711_ULAW | 6 | RAW G711 U-LAW
RAW_ENCODE_G711_ALAW | 7 | RAW G711 A-LAW
RAW_ENCODE_GSM_610 | 8 | RAW GSM 6.10
RAW_ENCODE_DIALOGIC_VOX | 9 | RAW Dialogic ADPCM VOX

bIsBigEndian

Boolean flag that specifies if bits order inside the RAW file are little-endian or big-endian

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | The RAW file is encoded using little-endian
BOOL_TRUE | The RAW file is encoded using big-endian

nFrequency

Sample rate of the RAW file (e.g. 44100)

nChannels

Number of channels of the RAW file: 1 for Mono or 2 for Stereo

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadSoundFromRawMemory method

LoadSoundFromRawMemory method

Remarks

Loads a sound file in RAW format stored inside a memory buffer.

A successful call to this method will fire the SoundLoaded event.

IMPORTANT TOPIC: remember that the memory buffer containing song data must not be moved by the garbage collector and needs to be available till the call to the CloseSound method.

Syntax

[Visual Basic]

control.LoadSoundFromRawMemory (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as enumBoolean,

nFrequency as Long,

nChannels as Long

) as enumErrorCodes

[C++]

short control.LoadSoundFromRawMemory (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

short nEncodeMode,

short bIsBigEndian,

long nFrequency,

long nChannels

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the memory sound
pBuffer | Variant parameter containing the pointer to sound data previously loaded in memory.
nBufferLen | Length in bytes of the given buffer

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
RAW_ENCODE_PCM_U8 | 0 | RAW PCM 8 bits Unsigned
RAW_ENCODE_PCM_S8 | 1 | RAW PCM 8 bits Signed
RAW_ENCODE_PCM_S16 | 2 | RAW PCM 16 bits Signed
RAW_ENCODE_PCM_S24 | 3 | RAW PCM 24 bits Signed
RAW_ENCODE_PCM_S32 | 4 | RAW PCM 32 bits Signed
RAW_ENCODE_FLOAT32 | 5 | RAW 32 bits floating point
RAW_ENCODE_G711_ULAW | 6 | RAW G711 U-LAW
RAW_ENCODE_G711_ALAW | 7 | RAW G711 A-LAW
RAW_ENCODE_GSM_610 | 8 | RAW GSM 6.10
RAW_ENCODE_DIALOGIC_VOX | 9 | RAW Dialogic ADPCM VOX

bIsBigEndian

Boolean flag that specifies if bits order inside the RAW file are little-endian or big-endian

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | The RAW file is encoded using little-endian
BOOL_TRUE | The RAW file is encoded using big-endian

nFrequency

Sample rate of the RAW file (e.g. 44100)

nChannels

Number of channels of the RAW file: 1 for Mono or 2 for Stereo

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


LoadSoundFromRecordingSession method

LoadSoundFromRecordingSession method

Remarks

Loads a sound recorded by the given instance of Active Sound Recorder.

A successful call to this method will fire the SoundLoaded event.

For further details about the integration between Active DJ Studio and Active Sound Recorder, check the How to load and play sounds recorded by Active Sound Recorder section.

Syntax

[Visual Basic]

control.LoadSoundFromRecordingSession (

nPlayer as Integer,

hWndRecorderCtrl as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.LoadSoundFromRecordingSession (

short nPlayer,

OLE_HANDLE hWndRecorderCtrl

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
hWndRecorderCtrl | Window handle to the instance of Active Sound Recorder control

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


LoadSoundFromZip method

LoadSoundFromZip method

Remarks

Loads a specific entry (sound file) from the specified ZIP file. The sound file can be a stream or a MOD music file.

Accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, M4A, AC3, FLAC, WavPack, ALAC, WAV, OGG Vorbis, WMA (*), ASF (**), WMV (**), W64, AU, PAF, SVX, NIST, VOC, IRCAM, PVF, CAF, Speex, Musepack, Monkey's Audio (APE), OPUS.

Formats wrapped inside a RIFF container (for example GSM 6.10, ADPCM, CCITT, etc. ) are supported if the specific ACM (Audio Compression Manager) codec is installed inside the system.

Multi-channel WAV, AIFF, OGG Vorbis and WMA formats are accepted if the output sound card supports speakers assignment and have WDM drivers installed: it's important to note that multi-channel sound files won't allow changing Tempo, Pitch and Playback rate and won't support DMO or EAX effects.

Accepted MOD formats are: MOD, MTM, S3M, XM, IT and MO3

RAW formats are not supported directly but could be loaded in two steps by decompressing the entry into a memory buffer first, through the ZIP.EntryExtractToMemory method, and then by loading the memory buffer contents through the LoadSoundFromRawMemory method.

A successful call to this method will fire the SoundLoaded event.

For further details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.LoadSoundFromZip (

nPlayer as Integer,

strZipPathname as String,

strPassword as String,

strEntryName as String,

bFailOnLowMemory as enumBoolean

) as enumErrorCodes

[C++]

short control.LoadSoundFromZip (

short nPlayer,

LPCTSTR strZipPathname,

LPCTSTR strPassword,

LPCTSTR strEntryName,

short bFailOnLowMemory

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the sound

strZipPathname

String containing the absolute pathname of the ZIP file to load.

strPassword

String containing the optional password for accessing the requested entry; leave it empty if not needed.

strEntryName

String representing the name of the entry to extract and load.

bFailOnLowMemory

Flag that determines if, for security purposes, loading of the given entry should fail in case there should be no enough memory for storing the unzipped entry.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | In case memory shouldn't be enough to contain the unzipped entry, the same would be stored inside a temporary file. The temporary file would be automatically deleted when closing the sound file through the CloseSound method or after loading a new sound file into the given player.
BOOL_TRUE | In case memory shouldn't be enough to contain the unzipped entry, the method's call would fail.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.

(*) Requires Microsoft Windows Media Format modules already installed on the target PC: you can verify the presence of these modules through a call to the IsWmaAvailable method.

(**) Performs sound tracks only (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs sound tracks only (no video)

The Windows Media Format modules can be installed using the redistribution setup package (wmfdist.exe) provided by Microsoft. Details about the integration of these modules inside your own setup package can be found on the following link of the official Microsoft web site (note that in the future this link could change due to the Microsoft site maintenance).


LoadSoundFastFromZip method

LoadSoundFastFromZip method

Remarks

Loads a specific entry (sound file) from the specified ZIP file. This method acts exactly as the LoadSoundFromZip method but performs a less detailed analysis for files in MP3 format

A successful call to this method will fire the SoundLoaded event.

For further details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.LoadSoundFastFromZip (

nPlayer as Integer,

strZipPathname as String,

strPassword as String,

strEntryName as String,

bFailOnLowMemory as enumBoolean

) as enumErrorCodes

[C++]

short control.LoadSoundFastFromZip (

short nPlayer,

LPCTSTR strZipPathname,

LPCTSTR strPassword,

LPCTSTR strEntryName,

short bFailOnLowMemory

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the sound

strZipPathname

String containing the absolute pathname of the ZIP file to load.

strPassword

String containing the optional password for accessing the requested entry; leave it empty if not needed.

strEntryName

String representing the name of the entry to extract and load.

bFailOnLowMemory

Flag that determines if, for security purposes, loading of the given entry should fail in case there should be no enough memory for storing the unzipped entry.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | In case memory shouldn't be enough to contain the unzipped entry, the same would be stored inside a temporary file. The temporary file would be automatically deleted when closing the sound file through the CloseSound method or after loading a new sound file into the given player.
BOOL_TRUE | In case memory shouldn't be enough to contain the unzipped entry, the method's call would fail.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadSoundInMono method

LoadSoundInMono method

Remarks

Loads a song from the specified file and, if Stereo, converts it to Mono.

Accepted stream formats are MP1, MP2 and MP3 (Stereo and Mono): trying to load any other Stereo format will fail. If the song is already in Mono, this method will load any other format supported by the LoadSound method

A successful call to this method will fire the SoundLoaded event.

Syntax

[Visual Basic]

control.LoadSoundInMono (

nPlayer as Integer,

strFileName as String,

bFast as enumBoolean

) as enumErrorCodes

[C++]

short control.LoadSoundInMono (

short nPlayer,

LPCTSTR strFileName,

short bFast

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the absolute pathname of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.
bFast | Flag that determines if a less detailed analysis must be performed for files in MP3 format: the use of this method is indicated when you need an immediate loading of MP3 files from a network.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadSoundSync method

LoadSoundSync method

Remarks

Loads a song from the specified file through a secondary thread: as you may know, the only way to know the exact song's duration for MP3 files is scanning the file completely and, for very long files, the use of the LoadSound method could be quite lengthy and could temporarily freeze the user interface of the container application. This method avoids any user interface blocking and, once completed, a SoundSyncLoaded event will be fired.

Accepted audio formats are the same as seen inside the LoadSound method.

Syntax

[Visual Basic]

control.LoadSoundSync (

nPlayer as Integer,

strFileName as String

) as enumErrorCodes

[C++]

short control.LoadSoundSync (

short nPlayer,

LPCTSTR strFileName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the absolute pathname of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


LoadSoundSyncFromZip method

LoadSoundSyncFromZip method

Remarks

Loads a specific entry (sound file) from the specified ZIP file through a secondary thread: as you may know, the only way to know the exact song's duration for MP3 files is scanning the file completely and, for very long files, the use of the LoadSoundFromZip method could be quite lengthy and could temporarily freeze the user interface of the container application. This method avoids any user interface blocking and, once completed, a SoundSyncLoaded event will be fired.

Accepted audio formats are the same as seen inside the LoadSoundFromZip method.

For further details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.LoadSoundSyncFromZip (

nPlayer as Integer,

strZipPathname as String,

strPassword as String,

strEntryName as String,

bFailOnLowMemory as enumBoolean

) as enumErrorCodes

[C++]

short control.LoadSoundSyncFromZip (

short nPlayer,

LPCTSTR strZipPathname,

LPCTSTR strPassword,

LPCTSTR strEntryName,

short bFailOnLowMemory

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the sound

strZipPathname

String containing the absolute pathname of the ZIP file to load.

strPassword

String containing the optional password for accessing the requested entry; leave it empty if not needed.

strEntryName

String representing the name of the entry to extract and load.

bFailOnLowMemory

Flag that determines if, for security purposes, loading of the given entry should fail in case there should be no enough memory for storing the unzipped entry.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | In case memory shouldn't be enough to contain the unzipped entry, the same would be stored inside a temporary file. The temporary file would be automatically deleted when closing the sound file through the CloseSound method or after loading a new sound file into the given player.
BOOL_TRUE | In case memory shouldn't be enough to contain the unzipped entry, the method's call would fail.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The song file has been loaded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.

(*) Requires Microsoft Windows Media Format modules already installed on the target PC: you can verify the presence of these modules through a call to the IsWmaAvailable method.

(**) Performs sound tracks only (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs sound tracks only (no video)

The Windows Media Format modules can be installed using the redistribution setup package (wmfdist.exe) provided by Microsoft. Details about the integration of these modules inside your own setup package can be found on the following link of the official Microsoft web site (note that in the future this link could change due to the Microsoft site maintenance).


LoadTrackFromCd method

LoadTrackFromCd method

Remarks

Loads the given CD track into the given player.

CD tracks can be loaded with the LoadSound method also.

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Due to the nature of CD drives, the loading session of a full CD track can be a lengthy operation so, in order to avoid blocking the user interface, the CD track loading session is performed inside a dedicated thread: the container application can be informed about the advancement of the CD track loading session through the following events: CdReadTrackStart, CdReadTrackPercentage and CdReadTrackStop.

Syntax

[Visual Basic]

control.LoadTrackFromCd (

nPlayer as Integer,

nDrive as Integer,

nTrack as Integer

) as enumErrorCodes

[C++]

short control.LoadTrackFromCd (

short nPlayer,

short nDrive,

short nTrack

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nDrive | Number representing the zero-based index of the involved CD drive
nTrack | Number representing the one-based index of the CD audio track

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


PauseSound method

PauseSound method

Remarks

Pauses a playing song. In case the given player should have been loaded with a video clip, the call to this method would have the same effect of the VideoPlayer.Pause method.

A successful call to this method will fire the SoundPaused event.

Syntax

[Visual Basic]

control.PauseSound (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PauseSound (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


PlaySound method

PlaySound method

Remarks

Plays a sound that has been previously loaded through one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory.

By default playback continues till the end of the sound stream until the final position is not moved through the PlaySoundMoveFinalPos method.

In case the given player should have been loaded with a video clip, the call to this method would have the same effect of the VideoPlayer.Play method.

A successful call to this method will fire the SoundPlaying event. Once the sound has been performed completely, the control will fire the SoundDone event.

Syntax

[Visual Basic]

control.PlaySound (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PlaySound (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will play the sound

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


PlaySoundDisableLoop method

PlaySoundDisableLoop method

Remarks

Disables an eventual loop, set by a previous call to PlaySoundLoop, PlaySoundEnableLoop or PlaySoundRangeLoop methods, without stopping the current playback: playback will terminate when reaching the eventual end of the range established by the call to PlaySoundEnableLoop or PlaySoundRangeLoop method.

The loop can be also disabled by calling the PlaySound method: in this case the sound will continue playing without interruption until reaching the end of the sound file

Syntax

[Visual Basic]

control.PlaySoundDisableLoop (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PlaySoundDisableLoop (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will play the sound

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


PlaySoundEnableLoop method

PlaySoundEnableLoop method

Remarks

Enables looping of a specific range of sound for the given player.

The loop can be disabled at any time in two ways:

· by calling the PlaySoundDisableLoop method: in this case the sound will continue playing without interruption until reaching the final position of the established range
· by calling the PlaySound method: in this case the sound will continue playing without interruption until reaching the end of the sound file

By default playback continues till the end of the defined range until the final position is not moved through the PlaySoundMoveFinalPos method.

If the player should be already in playback state, the following situations may occur:

· If the current playback position is located before the position set through the nToPosition parameter, playback will continue without interruption till reaching the position set into the nToPosition parameter where the loop will occur; if you should need an immediate repositioning of the playback position at the beginning of the sound range, use the PlaySoundRangeLoop method.
· If the current playback position is located after the position set through the nToPosition parameter, playback is interrupted and restarted from the position set through the nFromPosition parameter.

If the player should be in stopped state, a successful call to this method will start playback on the given range and will fire the SoundPlaying event.

Each loop completion will cause the control to fire the RangeLoopDone event: the only exception is the completion of the latest loop that will cause the control to fire the SoundDone event.

Syntax

[Visual Basic]

control.PlaySoundEnableLoop (

nPlayer as Integer,

nFromPosition as Long,

nToPosition as Long,

nLoopCount as Long

) as enumErrorCodes

[C++]

short control.PlaySoundEnableLoop (

short nPlayer,

long nFromPosition,

long nToPosition,

long nLoopCount

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will play the sound interval
nFromPosition | Range starting point in the unit specified by the ScaleUnits property. Set this value to 0 for playing from the sound beginning.
nToPosition | Range ending point in the unit specified by the ScaleUnits property. Set this value to -1 for playing till the song end
nLoopCount | Specifies the number of loops over the defined range. Set this value to -1 for setting an infinite loop

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


PlaySoundFromRecorderEx method

PlaySoundFromRecorderEx method

Remarks

Activates the given instance of Active Sound Recorder and plays in real time sound data coming from the recorder.

In order to stop playing sound data coming from a recorder instance, always use the StopSoundFromRecorder method instead of the StopSound method..

A successful call to this method will fire the SoundPlaying event.

For further details about the integration between Active DJ Studio and Active Sound Recorder, check the How to load and play sounds recorded by Active Sound Recorder section.

Syntax

[Visual Basic]

control.PlaySoundFromRecorderEx (

nPlayer as Integer,

hWndRecorderCtrl as OLE_HANDLE,

bMono as enumBoolean,

nInputDevice as Integer,

nInputChannel as Integer

) as enumErrorCodes

[C++]

short control.PlaySoundFromRecorderEx (

short nPlayer,

OLE_HANDLE hWndRecorderCtrl,

short bMono,

short nInputDevice,

short nInputChannel

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

hWndRecorderCtrl

Window handle to the instance of Active Sound Recorder control

bMono

Boolean value that specifies to play incoming sound data in Mono or Stereo.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Play sound data in Stereo
BOOL_TRUE | 1 | Play sound data in Mono: use this setting if you want to apply EAX effects.

nInputDevice

Number representing the zero-based index of the DirectSound input device (sound card) that will be used for recording. Use the value returned by the GetInputDevicesCount method of Active Sound Recorder in order to know how many input devices are currently installed on the system and the GetInputDeviceDesc method of Active Sound Recorder in order to retrieve the friendly name of each input device.

nInputChannel

Number representing the zero-based index of the input channel (Microphone, Stereo Mix, Line-In, etc.) that will be used for recording on the input device set through the nInputDevice parameter (use -1 for setting the system default input channel).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


PlaySoundLoop method

PlaySoundLoop method

Remarks

Plays in looping mode a sound that has been previously loaded through one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory,

By default playback continues till the end of the sound stream until the final position is not moved through the PlaySoundMoveFinalPos method.

A successful call to this method will fire the SoundPlaying event. A looping sound can be stopped only through a call to the StopSound method. If you need a better control over sound looping use the PlaySoundRangeLoop method.

Syntax

[Visual Basic]

control.PlaySoundLoop (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PlaySoundLoop (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will play the sound

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


PlaySoundRange method

PlaySoundRange method

Remarks

Plays a specific range of sound that has been previously loaded through one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory,

By default playback continues till the end of the defined range until the final position is not moved through the PlaySoundMoveFinalPos method.

A successful call to this method will fire the SoundPlaying event. Once the sound portion has been performed completely, the control will fire the SoundDone event.

A portion of sound can be played a given number of times through the PlaySoundRangeLoop method.

Syntax

[Visual Basic]

control.PlaySoundRange (

nPlayer as Integer,

nFromPosition as Long,

nToPosition as Long

) as enumErrorCodes

[C++]

short control.PlaySoundRange (

short nPlayer,

long nFromPosition,

long nToPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will play the sound range
nFromPosition | Range starting point in the unit specified by the ScaleUnits property.
nToPosition | Range ending point in the unit specified by the ScaleUnits property. Set this value to -1 for playing till the song end

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


PlaySoundRangeLoop method

PlaySoundRangeLoop method

Remarks

Plays in loop mode a portion of sound that has been previously loaded through one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory,.

The loop can be disabled at any time in two ways:

· by calling the PlaySoundDisableLoop method: in this case the sound will continue playing without interruption until reaching the final position of the established range
· by calling the PlaySound method: in this case the sound will continue playing without interruption until reaching the end of the sound file

By default playback continues till the end of the defined range until the final position is not moved through the PlaySoundMoveFinalPos method.

A successful call to this method will fire the SoundPlaying event; each loop completion will cause the control to fire the RangeLoopDone event: the only exception is the completion of the latest loop that will cause the control to fire the SoundDone event.

Syntax

[Visual Basic]

control.PlaySoundRangeLoop (

nPlayer as Integer,

nFromPosition as Long,

nToPosition as Long,

nLoopCount as Long

) as enumErrorCodes

[C++]

short control.PlaySoundRangeLoop (

short nPlayer,

long nFromPosition,

long nToPosition,

long nLoopCount

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will play the sound interval
nFromPosition | Range starting point in the unit specified by the ScaleUnits property. Set this value to 0 for playing from the sound beginning.
nToPosition | Range ending point in the unit specified by the ScaleUnits property. Set this value to -1 for playing till the song end
nLoopCount | Specifies the number of loops over the defined range. Set this value to -1 for setting an infinite loop

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


PlaySoundMoveFinalPos method

PlaySoundMoveFinalPos method

Remarks

Moves the final playback position during a playback session started through the PlaySound method or through the PlaySoundRange and PlaySoundRangeLoop methods.

Syntax

[Visual Basic]

control.PlaySoundMoveFinalPos (

nPlayer as Integer

nToPosition as Long

) as enumErrorCodes

[C++]

short control.PlaySoundMoveFinalPos (

short nPlayer,

long nToPosition

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will play the sound

nToPosition

Final playback position expressed in the unit specified by the ScaleUnits property. Set this value to -1 for playing till the song end.

If the current playback position should be higher than the final range position, playback would be immediately stopped.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


ResumeSound method

ResumeSound method

Remarks

Resumes a paused sound. If the sound is not paused, the call is ignored. In case the given player should have been loaded with a video clip, the call to this method would have the same effect of the VideoPlayer.Resume method.

A successful call to this method will fire the SoundPlaying event.

Syntax

[Visual Basic]

control.ResumeSound (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.ResumeSound (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


RewindSound method

RewindSound method

Remarks

Rewinds a sound of the amount that has been set through a previous call to the SetForwardRewindGranularity method.

Syntax

[Visual Basic]

control.RewindSound (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.RewindSound (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


SeekSound method

SeekSound method

Remarks

Moves the given player to the specified position over the current song.

A call to this method is ignored if the embedded fader, through a call to the Fader.Init method, has been set to work with a single playlist (FADE_SINGLE_PLAYLIST).

If the status of the given player is "stopped" or "paused", a call to this method will move the playback position but will not cause the playback to start while, if the status of the given player is "playing", a call to this method will move the playback position and will continue playback without interruptions.

In case the given player should have been loaded with a video clip, the call to this method would have the same effect of the VideoPlayer.Seek method.

If the seek operation brings the playback position beyond the end of the file, the SoundDone event is generated.

Syntax

[Visual Basic]

control.SeekSound (

nPlayer as Integer,

nOffset as Long

) as enumErrorCodes

[C++]

short control.SeekSound (

short nPlayer,

long nOffset

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nOffset | Number representing the position to reach; its value depends upon the value of the ScaleUnits property. When the ScaleUnits property is expressed in percentage, from 0 to 100, the position doesn't keep count of eventual tempo and/or playback rate changes. In other cases the passed position must keep count of eventual tempo and/or playback rate changes so it must be a value between 0 and the sound duration returned by the SoundDurationGet method having its bKeepCountOfRateChange parameter set to "BOOL_TRUE".

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


SetEAXEffect method

SetEAXEffect method

Remarks

Applies/removes a specific EAX effect to the given output device.

EAX effects can be applied only if the IsEAXAvailable method returns TRUE and has effect only on sounds loaded through the LoadSoundForEAX method.

The current EAX effect, if any, and its reverb parameters can be retrieved through a call to the GetEAXEffect method.

Important note about EAX effects availability

EAX effects are only supported up to Windows XP and have been deprecated starting from Windows Vista and higher versions due to the lack of hardware mixing.

Although some sound card driver will tell you that it supports EAX, this doesn't guarantees that its EAX implementation quality will be the same available for Creative sound cards.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.SetEAXEffect (

nIndex as Integer,

nEffect as enumEaxEffects,

fReverbVolume as Single,

fReverbDecayTime as Single,

fReverbDecayHFRatio as Single

) as enumErrorCodes

[C++]

short control.SetEAXEffect (

short nIndex,

long nEffect,

float fReverbVolume,

float fReverbDecayTime,

float fReverbDecayHFRatio

);

Parameter

Description

nIndex

Number representing the zero-based index of the output device that will be affected by EAX settings

nEffect

Numeric value that determines the effect to apply.

Supported values are the following:

Mnemonic value | Value | Meaning
EAX_NONE | -1 | Removes any previous EAX effect
EAX_GENERIC | 0 | Generic
EAX_PADDEDCELL | 1 | Padded cell
EAX_ROOM | 2 | Room
EAX_BATHROOM | 3 | Bathroom
EAX_LIVINGROOM | 4 | Living room
EAX_STONEROOM | 5 | Stone room
EAX_AUDITORIUM | 6 | Auditorium
EAX_CONCERTHALL | 7 | Concert hall
EAX_CAVE | 8 | Cave
EAX_ARENA | 9 | Arena
EAX_HANGAR | 10 | Hangar
EAX_CARPETEDHALLWAY | 11 | Carpeted hallway
EAX_HALLWAY | 12 | Hallway
EAX_STONECORRIDOR | 13 | Stone corridor
EAX_ALLEY | 14 | Alley
EAX_FOREST | 15 | Forest
EAX_CITY | 16 | City
EAX_MOUNTAINS | 17 | Mountains
EAX_QUARRY | 18 | Quarry
EAX_PLAIN | 19 | Plain
EAX_PARKINGLOT | 20 | Parking lot
EAX_SEWERPIPE | 21 | Sewer pipe
EAX_UNDERWATER | 22 | Underwater
EAX_DRUGGED | 23 | Drugged
EAX_DIZZY | 24 | Dizzy
EAX_DIZZY | 25 | Psychotic

fReverbVolume

Floating point value representing the reverb volume for the given effect.

The value is expressed in percentage and can assume values from 0 to 100.

fReverbDecayTime

Floating point value representing the time, expressed in seconds, for reverb to fade to -60 dB.

Supported values can range from 0.1 to 20

fReverbDecayHFRatio

Floating point value representing the reverb's decay HF Ratio.

The value is expressed in percentage and can assume values from -100 to 100 with the following meaning:

-100 = high frequencies decay quickest

0 = low and high frequencies decay equally

100 = low frequencies decays quickest

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SetEAXEffectPresets method

SetEAXEffectPresets method

Remarks

Applies a certain EAX effect to the given output device using the default reverb presets.

EAX effects can be applied only if the IsEAXAvailable method returns TRUE and has effect only on sounds loaded through the LoadSoundForEAX method.

The current EAX effect, if any, and its reverb parameters can be retrieved through a call to the GetEAXEffect method.

Important note about EAX effects availability

EAX effects are only supported up to Windows XP and have been deprecated starting from Windows Vista and higher versions due to the lack of hardware mixing.

Although some sound card driver will tell you that it supports EAX, this doesn't guarantees that its EAX implementation quality will be the same available for Creative sound cards.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.SetEAXEffectPresets (

nIndex as Integer,

nEffect as enumEaxEffects

) as enumErrorCodes

[C++]

short control.SetEAXEffectPresets (

short nIndex,

long nEffect

);

Parameter

Description

nIndex

Number representing the zero-based index of the output device that will be affected by EAX settings

nEffect

Numeric value that determines the effect to apply.

Supported values are the following:

Mnemonic value | Value | Meaning
EAX_NONE | -1 | Removes any previous EAX effect
EAX_GENERIC | 0 | Generic
EAX_PADDEDCELL | 1 | Padded cell
EAX_ROOM | 2 | Room
EAX_BATHROOM | 3 | Bathroom
EAX_LIVINGROOM | 4 | Living room
EAX_STONEROOM | 5 | Stone room
EAX_AUDITORIUM | 6 | Auditorium
EAX_CONCERTHALL | 7 | Concert hall
EAX_CAVE | 8 | Cave
EAX_ARENA | 9 | Arena
EAX_HANGAR | 10 | Hangar
EAX_CARPETEDHALLWAY | 11 | Carpeted hallway
EAX_HALLWAY | 12 | Hallway
EAX_STONECORRIDOR | 13 | Stone corridor
EAX_ALLEY | 14 | Alley
EAX_FOREST | 15 | Forest
EAX_CITY | 16 | City
EAX_MOUNTAINS | 17 | Mountains
EAX_QUARRY | 18 | Quarry
EAX_PLAIN | 19 | Plain
EAX_PARKINGLOT | 20 | Parking lot
EAX_SEWERPIPE | 21 | Sewer pipe
EAX_UNDERWATER | 22 | Underwater
EAX_DRUGGED | 23 | Drugged
EAX_DIZZY | 24 | Dizzy
EAX_DIZZY | 25 | Psychotic

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SetEAXEffectWetDryMix method

SetEAXEffectWetDryMix method

Remarks

Sets the EAX effect's wet/dry mix ratio on the given player.

The actual wet/dry mix can be obtained through the GetEAXEffectWetDryMix method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.SetEAXEffectWetDryMix (

nPlayer as Integer,

fWetDryMixRatio as Single

) as enumErrorCodes

[C++]

short control.SetEAXEffectWetDryMix (

short nPlayer,

float fWetDryMixRatio

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fWetDryMixRatio | Floating point value representing the wet/dry mix ratio. The value is expressed in percentage and can assume values from 0 to 100.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


SetForwardRewindGranularity method

SetForwardRewindGranularity method

Remarks

Sets the new granularity for the forward and rewind operations of the current loaded sound or video clip: the passed value is expressed in the same unit specified by the ScaleUnits property.

The actual granularity can be retrieved through the GetForwardRewindGranularity method.

Syntax

[Visual Basic]

control.SetForwardRewindGranularity (

nPlayer as Integer,

fGranularity as single

) as enumErrorCodes

[C++]

short control.SetForwardRewindGranularity (

short nPlayer,

float fGranularity

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fGranularity | Granularity value expressed in the same unit specified by the ScaleUnits property.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SetSampleRate method

SetSampleRate method

Remarks

Sets the sample rate applied to DirectSound buffer during playback. The use of this method will speed up the sound playback and voices will result altered as if an LP disc was played at wrong RPM rate. The current sample rate can be obtained through the GetSampleRate method.

Although the final result could be similar to the one obtained through the Effects.PlaybackRateSet method, this method is not based upon a DSP but acts directly on the DirectSound buffer by changing its frequency.

Syntax

[Visual Basic]

control.SetSampleRate (

nPlayer as Integer,

nSampleRate as Long

) as enumErrorCodes

[C++]

short control.SetSampleRate (

short nPlayer,

long nSampleRate

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nSampleRate | Sample rate expressed in samples per second

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


SetSmoothingTimeOnSeekOps method

SetSmoothingTimeOnSeekOps method

Remarks

Sets the smoothing time applied during seeking and looping operations in order to avoid clicks on the speakers caused by sudden volume level changes or by sound card drivers not correctly cleaning the playback buffer as needed.

With certain kind of speakers sudden volume level changes when moving the playback position from a position where the volume level is low to a position where the volume level is high (and vice versa) may result in audible popping and/or clicks. Applying a small volume fade could sometime help eliminating the issue.

Syntax

[Visual Basic]

control.SetSmoothingTimeOnSeekOps (

nPlayer as Integer,

nSmoothTime as Long

) as enumErrorCodes

[C++]

short control.SetSmoothingTimeOnSeekOps (

short nPlayer,

long nSmoothTime

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSmoothTime

The smoothing time, expressed in milliseconds, required to perform a smooth fade-out/fade-in after calling a method that will move the current playback position (like SeekSound, RewindSound or ForwardSound) or when a loop occurs.

Accepted values are from 0 (no smoothing) to 500: higher or lower values will be automatically cut to the nearest supported value. The default value is 50 milliseconds.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SoundDurationGet method

SoundDurationGet method

Remarks

Gets the duration of the song currently loaded.

Due to the format of an MPEG Audio bitstream, it is not possible to know the type and duration of a MP3 file by just looking at a header. Some guesses can be made, but for a precise measurement of the contents of an MPEG Audio file, the entire file has to be scanned: this method performs only a foresight of the sound duration.

A formatted string of the loaded sound duration can be obtained through the SoundDurationStringGet method.

Syntax

[Visual Basic]

control.SoundDurationGet (

nPlayer as Integer,

fDuration as Double,

bKeepCountOfRateChange as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundDurationGet (

short nPlayer,

double *fDuration,

short bKeepCountOfRateChange

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player whose information must be retrieved

fDuration

Reference that, on return from the method call, will contain the duration of the loaded sound expressed in milliseconds.

bKeepCountOfRateChange

Boolean flag that specifies if the returned position must keep count of eventual playback rate changes set through previous calls to the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Don't keep count of playback rate changes
BOOL_TRUE | 1 | Keep count of playback rate changes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


SoundDurationStringGet method

SoundDurationStringGet method

Remarks

Retrieves a string containing the formatted sound duration using the following format [hh:mm:ss:ms(3)] in which hh is for hours, mm is for minutes, ss is for seconds and ms(3) are three characters representing the milliseconds. For example [04:34:200] indicates a song during 0 hours (the hours number is automatically omitted if 0), 4 minutes, 34 seconds and 200 milliseconds.

The song duration in milliseconds can be obtained using the SoundDurationGet method.

Syntax

[Visual Basic]

control.SoundDurationStringGet (

nPlayer as Integer,

bShowHour as enumBoolean,

bShowMs as enumBoolean,

strHourSeparator as String,

strMsSeparator as String,

nNumberOfMsDigits as Integer,

bKeepCountOfRateChange as enumBoolean,

) as String

[C++]

LPCTSTR control.SoundDurationStringGet (

short nPlayer,

short bShowHour,

short bShowMs,

BSTR strHourSeparator,

BSTR strMsSeparator,

short nNumberOfMsDigits,

short bKeepCountOfRateChange,

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player whose information must be retrieved

bShowHour

Boolean value that specifies the player to avoid displaying the 'hour' position field.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't show hour value
BOOL_TRUE | 1 | Shows hour value

bShowMs

Boolean value that specifies the player to avoid displaying the 'milliseconds' position field.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't show milliseconds value
BOOL_TRUE | 1 | Shows milliseconds value

strHourSeparator

Character used to separate hours, minutes and seconds, typically this should be set to ":"

strMsSeparator

Character used to separate seconds and milliseconds, typically this should be set to "."

nNumberOfMsDigits

Number of characters used to represent milliseconds digits, can be in the range from 1 to 3; values outside this range will be automatically set to 3.

bKeepCountOfRateChange

Boolean flag that specifies if the returned position must keep count of eventual playback rate changes set through previous calls to the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't keep count of playback rate changes
BOOL_TRUE | 1 | Keeps count of playback rate changes

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The formatted song duration


SoundPositionGet method

SoundPositionGet method

Remarks

Obtains the current position during a playback session.

A formatted string of the current sound position can be obtained through the SoundPositionStringGet method.

Syntax

[Visual Basic]

control.SoundPositionGet (

nPlayer as Integer,

fPosition as Double,

bKeepCountOfRateChange as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundPositionGet (

short nPlayer,

double *fPosition,

short bKeepCountOfRateChange

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player whose information must be retrieved

fPosition

Reference that, on return from the method call, will contain the current position. Its effective value depends upon the actual value of the ScaleUnits property.

bKeepCountOfRateChange

Boolean flag that specifies if the returned position must keep count of eventual playback rate changes set through previous calls to the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Don't keep count of playback rate changes
BOOL_TRUE | 1 | Keep count of playback rate changes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


SoundPositionStringGet method

SoundPositionStringGet method

Remarks

Obtains a formatted string representing the current position during a playback session.

The string is formatted as hh:mm:ss:ms in which hh is for hours, mm is for minutes, ss is for seconds and ms is for milliseconds. For example [04:34:200] indicates that the playing sound has performed 4 minutes, 34 seconds and 200 milliseconds.

The numerical song position can be obtained using the SoundPositionGet method.

Syntax

[Visual Basic]

control.SoundPositionStringGet (

nPlayer as Integer,

bShowHour as enumBoolean,

bShowMs as enumBoolean,

strHourSeparator as String,

strMsSeparator as String,

nNumberOfMsDigits as Integer,

bKeepCountOfRateChange as enumBoolean,

) as String

[C++]

LPCTSTR control.SoundPositionStringGet (

short nPlayer,

short bShowHour,

short bShowMs,

BSTR strHourSeparator,

BSTR strMsSeparator,

short nNumberOfMsDigits,

short bKeepCountOfRateChange,

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player whose information must be retrieved

bShowHour

Boolean value that specifies the player to avoid displaying the 'hour' position field.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't show hour value
BOOL_TRUE | 1 | Shows hour value

bShowMs

Boolean value that specifies the player to avoid displaying the 'milliseconds' position field.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't show milliseconds value
BOOL_TRUE | 1 | Shows milliseconds value

strHourSeparator

Character used to separate hours, minutes and seconds, typically this should be set to ":"

strMsSeparator

Character used to separate seconds and milliseconds, typically this should be set to "."

nNumberOfMsDigits

Number of characters used to represent milliseconds digits, can be in the range from 1 to 3; values outside this range will be automatically set to 3.

bKeepCountOfRateChange

Boolean flag that specifies if the returned position must keep count of eventual playback rate changes set through previous calls to the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't keep count of playback rate changes
BOOL_TRUE | 1 | Keeps count of playback rate changes

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The formatted sound position


StopSound method

StopSound method

Remarks

Stops a playing song; if no song is currently playing, the method call is ignored. In case the given player should have been loaded with a video clip, the call to this method would have the same effect of the VideoPlayer.Stop method.

A successful call to this method will seek the song to its initial position and will fire the SoundStopped event.

Syntax

[Visual Basic]

control.StopSound (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.StopSound (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


StopSoundFromRecorder method

StopSoundFromRecorder method

Remarks

Stops a playback previously activated through a call to the PlaySoundFromRecorderEx method.

A successful call to this method will fire the SoundStopped event.

For further details about the integration between Active DJ Studio and Active Sound Recorder, check the How to load and play sounds recorded by Active Sound Recorder section.

Syntax

[Visual Basic]

control.StopSoundFromRecorder (

nPlayer as Integer,

hWndRecorderCtrl as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.StopSoundFromRecorder (

short nPlayer,

OLE_HANDLE hWndRecorderCtrl

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
hWndRecorderCtrl | Window handle to the instance of Active Sound Recorder control

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


StreamBalanceGet method

StreamBalanceGet method

Remarks

Obtains the current volume balance for the given player. The volume balance can be modified through the StreamBalanceSet method.

Syntax

[Visual Basic]

control.StreamBalanceGet (

nPlayer as Integer,

fValue as Single

) as enumErrorCodes

[C++]

short control.StreamBalanceGet (

short nPlayer,

float *fValue

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fValue | Reference that, on return from the method call, will contain the volume balance.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


StreamBalanceSet method

StreamBalanceSet method

Remarks

Changes the volume balance for the given player: changing this value will not affect the volume balance of other players. The current volume balance can be obtained through the StreamBalanceGet method.

This method is ignored if speakers assignment has been enabled through the EnableSpeakers property.

Syntax

[Visual Basic]

control.StreamBalanceSet (

nPlayer as Integer,

fValue as Single

) as enumErrorCodes

[C++]

short control.StreamBalanceSet (

short nPlayer,

float fValue

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fValue | The new volume balance value in the range from -50 to 50. The value 0 means that the balance is centered

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


StreamMixerCreate method

StreamMixerCreate method

Remarks

Creates a new custom stream mixer object that will send the mixed stream to a given output device.

Custom stream mixers cannot be created when the InitDriversType method has been called with the nDriverType parameter set to a value different from DRIVER_TYPE_DIRECT_SOUND.

Further information about the use of custom Stream Mixers can be found inside the How to use custom Stream Mixers tutorial.

Syntax

[Visual Basic]

control.StreamMixerCreate (

nOutput as Integer,

nFrequency as Long,

nChannels as Integer

) as Long

[C++]

long control.StreamMixerCreate (

short nOutput,

long nFrequency,

short nChannels

);

Parameter

Description

nOutput

Number representing the zero-based index of the output device. The number and descriptions of available output devices can be obtained with a prior call to the GetOutputDevicesCount and GetOutputDeviceDesc

In case you should simply need sending the output of the stream mixer to a streaming server, without the need to hear what is being played, and you shouldn't need to record PCM in output from the stream mixer using the Active Sound Recorder control, the presence of an output device wouldn't be needed so you could set this parameter to -1.

In this specific case the playback stream is not created in "playback mode" but in another mode called "decode mode", in this situation, where the sound card driver is not involved, no synchronization is available between the decoder and what is being passed to the encoder: the encoder always requests to the player to pass as much data as possible so you will certainly observe the stream being "played" (but it would be better to say "consumed") at a higher speed: client PCs connected to the same network stream will obviously play at normal speed.

nFrequency

Sample rate expressed in samples per second

nChannels

Number of output channels: can be set to 1 (Mono) or 2 (Stereo). In order to create a multi-channel stream mixer, use the StreamMixerCreateWithSurround method.

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the stream mixer: this unique identifier will be used in order to invoke further methods related to the use of the stream mixer itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


StreamMixerCreateWithSurround method

StreamMixerCreateWithSurround method

Remarks

Creates a new custom stream mixer object with multi-channel surround support that will send the mixed stream to a given output device.

Stream mixers with surround support cannot be used as a source for casting sessions: for these purposes, always use the StreamMixerCreate method.

Custom stream mixers cannot be created when the InitDriversType method has been called with the nDriverType parameter set to a value different from DRIVER_TYPE_DIRECT_SOUND.

Further information about the use of custom Stream Mixers can be found inside the How to use custom Stream Mixers tutorial.

Syntax

[Visual Basic]

control.StreamMixerCreateWithSurround (

nOutput as Integer,

nFrequency as Long,

nChannels as Integer

) as Long

[C++]

long control.StreamMixerCreateWithSurround (

short nOutput,

long nFrequency,

short nChannels

);

Parameter

Description

nOutput

Number representing the zero-based index of the output device. The number and descriptions of available output devices can be obtained with a prior call to the GetOutputDevicesCount and GetOutputDeviceDesc

In case you should simply need sending the output of the stream mixer to a streaming server, without the need to hear what is being played, and you shouldn't need to record PCM in output from the stream mixer using the Active Sound Recorder control, the presence of an output device wouldn't be needed so you could set this parameter to -1.

In this specific case the playback stream is not created in "playback mode" but in another mode called "decode mode", in this situation, where the sound card driver is not involved, no synchronization is available between the decoder and what is being passed to the encoder: the encoder always requests to the player to pass as much data as possible so you will certainly observe the stream being "played" (but it would be better to say "consumed") at a higher speed: client PCs connected to the same network stream will obviously play at normal speed.

nFrequency

Sample rate expressed in samples per second

nChannels

Number of output channels: can be a value from 1 to 8

Return value

Value | Meaning
> 0 | Numeric value representing the unique identifier of the stream mixer: this unique identifier will be used in order to invoke further methods related to the use of the stream mixer itself
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


StreamMixerGetIdFromOutput method

StreamMixerGetIdFromOutput method

Remarks

Given the index of an output device returns the unique identifier of its internal stream mixer that was automatically created and linked to the output device after a call to the InitDriversType method having the nDriverType parameter set to a value different from DRIVER_TYPE_DIRECT_SOUND.

Through the unique identifier of the stream mixer you have the possibility to apply special effects to the mixed stream (as seen inside the How to use custom Stream Mixers tutorial) just before is sent to the physical output device.

See the How to manage audio flow through WASAPI and How to manage ASIO drivers tutorials for further details.

Syntax

[Visual Basic]

control.StreamMixerGetIdFromOutput (

nIndex as Integer

) as Integer

[C++]

short control.StreamMixerGetIdFromOutput (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the involved output device

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 0 | The unique identifier of the stream mixer internal to the output device


StreamMixerPlayerAdd method

StreamMixerPlayerAdd method

Remarks

Adds a player to the given stream mixer; when a player is added to a stream mixer it will redirect its audio output to the stream mixer instead of sending it to the output device set into the InitDJSystem method.

A player added to a stream mixer can be removed at a later time through the StreamMixerPlayerRemove method.

Further information about the use of custom Stream Mixers can be found inside the How to use custom Stream Mixers tutorial.

Syntax

[Visual Basic]

control.StreamMixerPlayerAdd (

nStreamMixerID as Long,

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.StreamMixerPlayerAdd (

long nStreamMixerID,

short nPlayer

);

Parameter | Description
nStreamMixerID | Unique identifier of the stream mixer created by a previous call to the StreamMixerCreate method
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


StreamMixerPlayerAddToSpeaker method

StreamMixerPlayerAddToSpeaker method

Remarks

Adds a player to a specific speaker of the given stream mixer having multi-channel surround support; when a player is added to a stream mixer it will redirect its audio output to the stream mixer instead of sending it to the output device set into the InitDJSystem method.

A player added to a stream mixer can be removed at a later time through the StreamMixerPlayerRemove method.

Further information about the use of custom Stream Mixers can be found inside the How to use custom Stream Mixers tutorial.

Syntax

[Visual Basic]

control.StreamMixerPlayerAddToSpeaker (

nStreamMixerID as Long,

nPlayer as Integer,

nSpeaker as enumSpeakers

) as enumErrorCodes

[C++]

short control.StreamMixerPlayerAddToSpeaker (

long nStreamMixerID,

short nPlayer,

short nSpeaker

);

Parameter

Description

nStreamMixerID

Unique identifier of the stream mixer created by a previous call to the StreamMixerCreateWithSurround method

nPlayer

Number representing the zero-based index of the involved player

nSpeaker

The speaker assigned to the given player.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
SPEAKER_FRONT | 0 | Front speakers (Stereo)
SPEAKER_REAR | 1 | Rear speakers (Stereo)
SPEAKER_CENTER_LFE | 2 | Center speakers (Stereo)
SPEAKER_REAR_CENTER | 3 | Rear center speakers (Stereo)
SPEAKER_FRONT_LEFT | 4 | Front-left speaker (Mono)
SPEAKER_FRONT_RIGHT | 5 | Front-right speaker (Mono)
SPEAKER_REAR_LEFT | 6 | Rear-left speaker (Mono)
SPEAKER_REAR_RIGHT | 7 | Rear-right speaker (Mono)
SPEAKER_CENTER | 8 | Center speaker (Mono)
SPEAKER_LFE | 9 | LFE or Subwoofer speaker (Mono)
SPEAKER_REAR_CENTER_LEFT | 10 | Rear Center Left speaker (Mono)
SPEAKER_REAR_CENTER_RIGHT | 11 | Rear Center Right speaker (Mono)

Below you can see the positioning of the Stereo speakers on a wide 7.1 configuration (the reported blue numbers corresponds to the Numeric value of the parameter)

and below you can see the positioning of the Mono speakers on the same wide 7.1 configuration

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


StreamMixerPlayerRemove method

StreamMixerPlayerRemove method

Remarks

Removes a player from the given stream mixer; when a player is removed from a stream mixer it will redirect its audio output to the output device set into the InitDJSystem method.

Further information about the use of custom Stream Mixers can be found inside the How to use custom Stream Mixers tutorial.

Syntax

[Visual Basic]

control.StreamMixerPlayerRemove (

nStreamMixerID as Long,

nPlayerIndex as Integer

) as enumErrorCodes

[C++]

short control.StreamMixerPlayerRemove (

long nStreamMixerID,

short nPlayerIndex

);

Parameter | Description
nStreamMixerID | Unique identifier of the stream mixer created by a previous call to the StreamMixerCreate method
nPlayerIndex | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


StreamOutputDeviceGet method

StreamOutputDeviceGet method

Remarks

Retrieves the current output device (sound card) for the given player.

By default, the output device is set at the very beginning through a call to the InitDJSystem method and can be changed at a later time through the StreamOutputDeviceSet method.

For further details about output devices management, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.StreamOutputDeviceGet (

nPlayer as Integer

) as Integer

[C++]

short control.StreamOutputDeviceGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | Number representing the index of the output device assigned to the given player.


StreamOutputDeviceSet method

StreamOutputDeviceSet method

Remarks

Changes the output device (sound card) for the given player. This method can be called at any time, also during playback. The current selected device can be obtained through the StreamOutputDeviceGet method.

By default, the output device is set at the very beginning through a call to the InitDJSystem method.

Use the value returned by the GetOutputDevicesCount method in order to know how many output devices are currently installed on the system and the GetOutputDeviceDesc method in order to retrieve the friendly name of every output device.

If the output device is changed successfully, the OutputDeviceChanged event is fired.

A call to this method will have no effect if the involved player has been added to a custom stream mixer through the StreamMixerPlayerAdd method.

IMPORTANT NOTE WHEN DEALING WITH VIDEO PLAYBACK: when playing a video clip through the VideoPlayer COM object, this method doesn't have any effect for players whose audio rendering mode has been set to AUDIO_RENDERER_MODE_DS_STANDARD or AUDIO_RENDERER_MODE_CUSTOM_2 through the VideoPlayer.AudioRendererModeSet method; in these specific situations the way to go is the VideoPlayer.AudioRendererDsDeviceSet method.

Syntax

[Visual Basic]

control.StreamOutputDeviceSet (

nPlayer as Integer,

nIndex as Integer

) as enumErrorCodes

[C++]

short control.StreamOutputDeviceSet (

short nPlayer,

short nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndex | Number representing the index of the output device that will be used by the given player. The value of this parameter can be in the range between 0 and the value returned by the GetOutputDevicesCount method so it can be used to redirect sound to both DirectSound and ASIO devices (see the InitDriversType method for details about the use of ASIO devices).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


StreamOutputSpeakerGet method

StreamOutputSpeakerGet method

Remarks

Obtains the current output speaker of the current output device for the given player. The output speaker can be modified through the StreamOutputSpeakerSet method.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.StreamOutputSpeakerGet (

nPlayer as Integer

) as enumSpeakers

[C++]

short control.StreamOutputSpeakerGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.

Return value

Value

Meaning

Negative value

An error occurred (see the LastError property for further error details)

Value >= 0

The output speaker assigned to the given player.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
SPEAKER_FRONT | 0 | Front speakers (Stereo)
SPEAKER_REAR | 1 | Rear speakers (Stereo)
SPEAKER_CENTER_LFE | 2 | Center speakers (Stereo)
SPEAKER_REAR_CENTER | 3 | Rear center speakers (Stereo)
SPEAKER_FRONT_LEFT | 4 | Front-left speaker (Mono)
SPEAKER_FRONT_RIGHT | 5 | Front-right speaker (Mono)
SPEAKER_REAR_LEFT | 6 | Rear-left speaker (Mono)
SPEAKER_REAR_RIGHT | 7 | Rear-right speaker (Mono)
SPEAKER_CENTER | 8 | Center speaker (Mono)
SPEAKER_LFE | 9 | LFE or Subwoofer speaker (Mono)
SPEAKER_REAR_CENTER_LEFT | 10 | Rear Center Left speaker (Mono)
SPEAKER_REAR_CENTER_RIGHT | 11 | Rear Center Right speaker (Mono)

Below you can see the positioning of the Stereo speakers on a wide 7.1 configuration (the reported blue numbers corresponds to the Numeric value of the parameter)

and below you can see the positioning of the Mono speakers on the same wide 7.1 configuration


StreamOutputSpeakerSet method

StreamOutputSpeakerSet method

Remarks

Redirects the output of the given player to a specific speaker of the current output device. The current output speaker can be obtained through the StreamOutputSpeakerGet method.

A call to this method will have no effect if the involved player has been added to a custom stream mixer through the StreamMixerPlayerAdd or StreamMixerPlayerAddToSpeaker methods.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.StreamOutputSpeakerSet (

nPlayer as Integer,

nSpeaker as enumSpeakers

) as enumErrorCodes

[C++]

short control.StreamOutputSpeakerSet (

short nPlayer,

short nSpeaker

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player.

nSpeaker

The new speaker assigned to the given player.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
SPEAKER_FRONT | 0 | Front speakers (Stereo)
SPEAKER_REAR | 1 | Rear speakers (Stereo)
SPEAKER_CENTER_LFE | 2 | Center speakers (Stereo)
SPEAKER_REAR_CENTER | 3 | Rear center speakers (Stereo)
SPEAKER_FRONT_LEFT | 4 | Front-left speaker (Mono)
SPEAKER_FRONT_RIGHT | 5 | Front-right speaker (Mono)
SPEAKER_REAR_LEFT | 6 | Rear-left speaker (Mono)
SPEAKER_REAR_RIGHT | 7 | Rear-right speaker (Mono)
SPEAKER_CENTER | 8 | Center speaker (Mono)
SPEAKER_LFE | 9 | LFE or Subwoofer speaker (Mono)
SPEAKER_REAR_CENTER_LEFT | 10 | Rear Center Left speaker (Mono)
SPEAKER_REAR_CENTER_RIGHT | 11 | Rear Center Right speaker (Mono)

Below you can see the positioning of the Stereo speakers on a wide 7.1 configuration (the reported blue numbers corresponds to the Numeric value of the parameter)

and below you can see the positioning of the Mono speakers on the same wide 7.1 configuration

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


StreamOutputSpeakersRearAndCenterSwap method

StreamOutputSpeakersRearAndCenterSwap method

Remarks

Swaps the Rear and Center speakers for the given player: some specific output device (for example the Maya EX7 sound card) will invert the Rear and Center speakers assignment by default so calling this method could be of help in certain situations.

This method will also work when the output device is an ASIO device by inverting the channels pair 3 and 4 with channels pair 5 and 6.

A call to this method will have no effect if the involved player has been added to a custom stream mixer through the StreamMixerPlayerAdd method.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.StreamOutputSpeakersRearAndCenterSwap (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.StreamOutputSpeakersRearAndCenterSwap (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.

Return value

Value | Meaning
Value > 0 | The number of speakers available on the given output device
Negative value | An error occurred (see the LastError property for further error details)


StreamOutputSpeakerSwap method

StreamOutputSpeakerSwap method

Remarks

Given two players, both assigned to the same output device, swaps the respective assigned speakers: note that it's not allowed swapping speakers of players currently redirecting their output to different output devices.

A call to this method will have no effect if the involved player has been added to a custom stream mixer through the StreamMixerPlayerAdd method.

For further details about speakers assignment, take a look to the How to work with multiple output devices and speakers section.

Syntax

[Visual Basic]

control.StreamOutputSpeakerSwap (

nPlayer1 as Integer,

nPlayer2 as Integer

) as enumErrorCodes

[C++]

short control.StreamOutputSpeakerSwap (

short nPlayer1,

short nPlayer2

);

Parameter | Description
nPlayer1 | Number representing the zero-based index of the first involved player.
nPlayer2 | Number representing the zero-based index of the second involved player.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


StreamPeakLevelsGet method

StreamPeakLevelsGet method

Remarks

Retrieves peak levels on the current playback position of the given player or stream mixer using the specified scale.

The VUMeterValueChange event is used for the purpose of retrieving peak levels of the audio stream during playback: this method can be used as an integration of the existing VUMeterValueChange event in order to retrieve peak levels for various channels of a multi-channel audio stream: a good place to invoke this method is indeed inside the event handler function of the VUMeterValueChange event.

Syntax

[Visual Basic]

control.StreamPeakLevelsGet (

nPlayer as Integer,

tPeakLevels as Single,

nLengthInMs as Long,

bRms as enumBoolean,

bStereo as enumBoolean,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.StreamPeakLevelsGet (

short nPlayer,

float *tPeakLevels,

long nLengthInMs,

short bRms,

short bStereo,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

tPeakLevels

Table that, on return from the method call, will contain floating point values representing detected peak levels for each of the audio stream's channels.

In order to avoid issues, the size of this table should be adapted to the possibility to store up to 8 channels.

nLengthInMs

The amount of data to inspect to calculate the peak level, expressed in milliseconds. The maximum value is 1000.

bRms

Boolean value indicating if values to retrieve are RMS (Root-Mean-Square) levels or peak levels.

Supported values are the following:

Mnemonic constant | Meaning
BOOL_FALSE | Use peak levels.
BOOL_TRUE | Use RMS levels.

bStereo

Boolean value indicating if values to retrieve should be considered as mono or stereo levels.

Supported values are the following:

Mnemonic constant | Meaning
BOOL_FALSE | Get mono levels, allowing to retrieve a separate level for each channel.
BOOL_TRUE | Get stereo levels meaning that the left level will be from the even channels, and the right level will be from the odd channels. If there are an odd number of channels then the left and right levels will both include all channels.

nScaleType

The scaling type of values reported into the tPeakLevels table.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Returned values are based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)
SCALE_LOG | 1 | Returned values, expressed in dB, are based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume) The actual applied formula for converting a linear value into a logarithmic value is the following: ValueInDB = 20 * log10 (ValueLinear/100) The C syntax for converting a logarithmic value into a linear value is the following: ValueLinear = 100 * pow (10, ValueInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The volume has been changed correctly


StreamQueueCreate method

StreamQueueCreate method

Remarks

Allows creating a sound stream that will receive uncompressed PCM data from an external source. PCM data can be fed into the stream through the StreamQueuePushData method. The sound stream can be played through the PlaySound method.

Syntax

[Visual Basic]

control.StreamQueueCreate (

nPlayer as Integer,

nFrequency as Long,

nChannels as Integer,

nBitsPerSample as Integer

) as enumErrorCodes

[C++]

short control.StreamQueueCreate (

short nPlayer,

long nFrequency,

short nChannels

short nBitsPerSample

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nFrequency | Sample rate of the sound stream (e.g. 44100)
nChannels | Number of channels of the sound stream: (e.g. 1 for Mono or 2 for Stereo)
nBitsPerSample | Number of bits per sample (e.g. 8 or 16)

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


StreamQueueBufferedDataGet method

StreamQueueBufferedDataGet method

Remarks

Obtains the amount of sound data still buffered into the sound stream queue created with the StreamQueueCreate method and fed with the StreamQueuePushData method.

Syntax

[Visual Basic]

control.StreamQueueBufferedDataGet (

nPlayer as Integer,

nDataLength as Long

) as enumErrorCodes

[C++]

short control.StreamQueueBufferedDataGet (

short nPlayer,

long *nDataLength

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nDataLength | Reference that, on return from the method call, will contain the amount of buffered sound data expressed in bytes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


StreamQueuePushData method

StreamQueuePushData method

Remarks

Pushes uncompressed PCM data into a stream previously created through the StreamQueueCreate method. When feeding PCM data into a stream in playback, this method should be called at a rate sufficient to sustain playback without glitches: if for any reason the control shouldn't receive enough PCM data, it would be forced to stall playback and to fire a StreamQueueStalled event; when enough PCM data should be available again, the SoundPlaying event would be fired automatically.

The amount of still buffered bytes can be obtained through the StreamQueueBufferedDataGet method.

Syntax

[Visual Basic]

control.StreamQueuePushData (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.StreamQueuePushData (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
pBuffer | Variant parameter containing the pointer to uncompressed PCM data to push into the queue
nBufferLen | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


StreamVolumeDirectSoundBufferGet method

StreamVolumeDirectSoundBufferGet method

Remarks

Retrieves the current volume, applied directly to the DirectSound buffer, for the given player. This volume can be changed through the StreamVolumeDirectSoundBufferSet method.

Syntax

[Visual Basic]

control.StreamVolumeDirectSoundBufferGet (

nPlayer as Integer,

nScaleType as enumVolumeScales

) as single

[C++]

float control.StreamVolumeDirectSoundBufferGet (

short nPlayer,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The returned volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The current volume (the meaning of the passed value depends upon the nScaleType parameter).


StreamVolumeDirectSoundBufferSet method

StreamVolumeDirectSoundBufferSet method

Remarks

Changes the volume for the given player directly on the DirectSound buffer: changing this volume will not affect the volume of other players. The current volume applied to the DirectSound buffer can be retrieved through the StreamVolumeDirectSoundBufferGet method.

This method is ignored and returns a ERR_PLAYER_BUSY error when called during a volume sliding started by a volume automation procedure or by the embedded fader.

Due to the fact that this method acts directly at DirectSound level and not at mixing level, when applied to a custom stream mixer, created using the StreamMixerCreate method having the nOutput parameter set to a value different from -1, the volume change affects the audio stream being sent to the sound card speakers but doesn't affect the audio streams eventually sent to the recorder control or to a streaming server.

If you want to apply a volume level that will work at mixing level inside the custom stream mixer, affecting all of the outgoing audio streams, you should use StreamVolumeLevelSet method,

See the How to use custom Stream Mixers tutorial for further details about stream mixers.

Syntax

[Visual Basic]

control.StreamVolumeDirectSoundBufferSet (

nPlayer as Integer,

fValue as single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.StreamVolumeDirectSoundBufferSet (

short nPlayer,

float fValue,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player whose volume will change

fValue

Number representing the new volume (the meaning of the passed value depends upon the nScaleType parameter).

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The passed volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The volume has been changed correctly


StreamVolumeLevelGet method

StreamVolumeLevelGet method

Remarks

Retrieves the current volume for the given player. The volume can be changed through the StreamVolumeLevelSet method.

Syntax

[Visual Basic]

control.StreamVolumeLevelGet (

nPlayer as Integer,

fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.StreamVolumeLevelGet (

short nPlayer,

float *fValue,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

fValue

Reference that, on return from the method call, will contain the current volume (the meaning of the value depends upon the nScaleType parameter).

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The returned volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The volume has been changed correctly


StreamVolumeLevelSet method

StreamVolumeLevelSet method

Remarks

Changes the volume for the given player: changing this volume will not affect the volume of other players. The current volume can be retrieved through the StreamVolumeLevelGet method.

This method is ignored and returns a ERR_PLAYER_BUSY error when called during a volume sliding started by a volume automation procedure or by the embedded fader.

Important change affecting backward compatibility when dealing with DirectSound drivers

Till version 6.x of the component, this method was used to set the volume directly on the DirectSound buffer used for performing playback, allowing a smaller latency on volume changes. Starting from version 7.0 of the component, the volume set through this method no more applies to the DirectSound buffer directly but only to the internal volume-related DSP used for volume sliding purposes, so the volume change will be affected by the DirectSound latency.

In order to continue setting the volume directly on the DirectSound buffer as seen for versions till 6.x, you should change your existing source code and use the new StreamVolumeDirectSoundBufferSet method in place of the StreamVolumeLevelSet method.

Syntax

[Visual Basic]

control.StreamVolumeLevelSet (

nPlayer as Integer,

fValue as single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.StreamVolumeLevelSet (

short nPlayer,

float fValue,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player whose volume will change

fValue

Number representing the new volume (the meaning of the passed value depends upon the nScaleType parameter).

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The passed volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The volume has been changed correctly


StreamVolumeIsSliding method

StreamVolumeIsSliding method

Remarks

Verifies if a volume sliding is actually occurring on the given player.

The volume sliding may have been started by:

· a call to the StreamVolumeSlide or StreamVolumeSlideEx methods.
· a call to the PlaySound or StopSound methods when the volume smoothing has been predisposed through calls to the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods.
· during a volume automation procedure.
· during an automatic fade performed through the embedded automatic fader.

Syntax

[Visual Basic]

control.StreamVolumeIsSliding (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.StreamVolumeIsSliding (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Volume sliding is not being performed
BOOL_TRUE | 1 | Volume sliding is being performed


StreamVolumeSlide method

StreamVolumeSlide method

Remarks

Starts a volume sliding procedure that brings the current volume to a target volume in a given amount of time. You can know if a volume sliding is already being performed through the StreamVolumeIsSliding method.

During the sliding the FadingVolumeChanged event is generated every 15 milliseconds. When the volume sliding reaches the target volume, the VolumeSlideCompleted event is generated.

Syntax

[Visual Basic]

control.StreamVolumeSlide (

nPlayer as Integer,

nSlideDuration as Long,

fVolumeTarget as Single,

nScaleType as enumVolumeScales,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.StreamVolumeSlide (

short nPlayer,

long nSlideDuration,

float fVolumeTarget,

short nScaleType,

short nCurveType,

long nDesignerUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSlideDuration

The time required to perform the volume sliding from the current volume level to the target level set into the fVolumeTarget parameter below.

fVolumeTarget

Target volume reached when the sliding is completed; the meaning of this value depends upon the nScaleType parameter below.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

nCurveType

Type of curve applied to the volume sliding.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

If you don't want to display the custom curve designer on your user interface but you know the exact position of the control points to set, you can use the StreamVolumeSlideEx method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


StreamVolumeSlideEx method

StreamVolumeSlideEx method

Remarks

Starts a volume sliding procedure that brings the current volume to a target volume in a given amount of time. You can know if a volume sliding is already being performed through the StreamVolumeIsSliding method.

During the sliding the FadingVolumeChanged event is generated every 15 milliseconds. When the volume sliding reaches the target volume, the VolumeSlideCompleted event is generated.

Syntax

[Visual Basic]

control.StreamVolumeSlideEx (

nPlayer as Integer,

nSlideDuration as Long,

fVolumeTarget as Single,

nScaleType as enumVolumeScales,

nCurveType as enumVolumeCurves,

nLeftX as Integer,

nLeftY as Integer,

nRightX as Integer,

nRightY as Integer

) as enumErrorCodes

[C++]

short control.StreamVolumeSlideEx (

short nPlayer,

long nSlideDuration,

float fVolumeTarget,

short nScaleType,

short nCurveType,

short nLeftX,

short nLeftY,

short nRightX,

short nRightY

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSlideDuration

The time required to perform the volume sliding from the current volume level to the target level set into the fVolumeTarget parameter below.

fVolumeTarget

Target volume reached when the sliding is completed; the meaning of this value depends upon the nScaleType parameter below.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

nCurveType

Type of curve applied to the volume sliding.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nLeftX

The horizontal position, expressed in percentage of the custom curve designer's area, of the left control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nLeftY

The vertical position, expressed in percentage of the custom curve designer's area, of the left control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nRightX

The horizontal position, expressed in percentage of the custom curve designer's area, of the right control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nRightY

The vertical position, expressed in percentage of the custom curve designer's area, of the right control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

(*) The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


StreamVolumeSmoothingSet method

StreamVolumeSmoothingSet method

Remarks

Sets the smoothing times, expressed in milliseconds, and related volume curve required to perform a fade-in after a PlaySound call and a fade-out after a StopSound call.

During the fading session the following events may be generated:

· FadeInStarted, FadingVolumeChanged and FadeInCompleted after a call to the PlaySound method
· FadeOutStarted, FadingVolumeChanged and FadeOutCompleted after a call to the StopSound method

Syntax

[Visual Basic]

control.StreamVolumeSmoothingSet (

nPlayer as Integer,

bfadeIn as enumBoolean,

nSlideDuration as Long,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.StreamVolumeSmoothingSet (

short nPlayer,

short bfadeIn,

long nSlideDuration,

short nCurveType,

long nDesignerUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bfadeIn

Boolean value indicating if the smoothing, obtained through a volume sliding. must be applied on start or stop of playback.

Supported values are the following:

Mnemonic constant | Meaning
false | The volume slide setting is intended as a fade-out activated when the StopSound method is invoked.
true | The volume slide setting is intended as a fade-in activated when the PlaySound method is invoked.

nSlideDuration

The time required to perform the volume sliding after a call to the PlaySound or StopSound method.

Accepted values are from 0 (default value, no sliding, immediate play or stop) to 20000: higher or lower values will be automatically cut to the nearest supported value.

nCurveType

Type of curve applied to the volume sliding.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

If you don't want to display the custom curve designer on your user interface but you know the exact position of the control points to set, you can use the StreamVolumeSmoothingSetEx method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


StreamVolumeSmoothingSetEx method

StreamVolumeSmoothingSetEx method

Remarks

Sets the smoothing times, expressed in milliseconds, and related volume curve required to perform a fade-in after a PlaySound call and a fade-out after a StopSound call.

During the fading session the following events may be generated:

· FadeInStarted, FadingVolumeChanged and FadeInCompleted after a call to the PlaySound method
· FadeOutStarted, FadingVolumeChanged and FadeOutCompleted after a call to the StopSound method

Syntax

[Visual Basic]

control.StreamVolumeSmoothingSetEx (

nPlayer as Integer,

bfadeIn as enumBoolean,

nSlideDuration as Long,

nCurveType as enumVolumeCurves,

nLeftX as Integer,

nLeftY as Integer,

nRightX as Integer,

nRightY as Integer

) as enumErrorCodes

[C++]

short control.StreamVolumeSmoothingSetEx (

short nPlayer,

short bfadeIn,

long nSlideDuration,

short nCurveType,

short nLeftX,

short nLeftY,

short nRightX,

short nRightY

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bfadeIn

Boolean value indicating if the smoothing, obtained through a volume sliding. must be applied on start or stop of playback.

Supported values are the following:

Mnemonic constant | Meaning
false | The volume slide setting is intended as a fade-out activated when the StopSound method is invoked.
true | The volume slide setting is intended as a fade-in activated when the PlaySound method is invoked.

nSlideDuration

The time required to perform the volume sliding after a call to the PlaySound or StopSound method.

Accepted values are from 0 (default value, no sliding, immediate play or stop) to 20000: higher or lower values will be automatically cut to the nearest supported value.

nCurveType

Type of curve applied to the volume sliding.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nLeftX

The horizontal position, expressed in percentage of the custom curve designer's area, of the left control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nLeftY

The vertical position, expressed in percentage of the custom curve designer's area, of the left control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nRightX

The horizontal position, expressed in percentage of the custom curve designer's area, of the right control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nRightY

The vertical position, expressed in percentage of the custom curve designer's area, of the right control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

(*) The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


PlayListAddItem method

PlayListAddItem method

Remarks

Adds a song (item) to the loaded playlist.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListAddItem (

nPlayer as Integer,

strPathname as String,

nIndex as Integer

) as enumErrorCodes

[C++]

short control.PlayListAddItem (

short nPlayer,

LPCTSTR strPathname,

short nIndex

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the playlist

strPathname

String containing the absolute pathname of the element to add.

If the playlist has been loaded or created with volume automation enabled, you can add a new item containing all the needed mixing positions, volume automation points and cue points in one single shot by passing a well formatted XML string to this parameter; an example of well formatted string is the following:

 <Item pathname="C:\sounds\drumtrik01_120bpm.wav" DurationSec="16.00" StartPosSec="2.0" MixPosSec="12.0" EndPosSec="16.0" >

   <VolumePoints>

     <VolumePoint name="start fade-in" VolumeLevelLinear="0.0" PosSec="2.0" CurveType="5"

                LeftX="11" LeftY="3" RightX="93" RightY="43" />

     <VolumePoint name="end fade-in" VolumeLevelLinear="100.0" PosSec="5.5" CurveType="0" />

     <VolumePoint name="start fade-out" VolumeLevelLinear="100.0" PosSec="11.9" CurveType="5"

                LeftX="83" LeftY="13" RightX="32" RightY="41" />

     <VolumePoint name="end fade-out" VolumeLevelLinear="0.0" PosSec="15.9" CurveType="0" />

   </VolumePoints>

   <CuePoints>

     <CuePoint name="Silence end" PosMs="1000" />

     <CuePoint name="Fading point" PosMs="12000" />

     <CuePoint name="Silence start" PosMs="15900" />

   </CuePoints>

 </Item>

For details about XML syntax of the string above refer to the How to manage Volume Automation tutorial.

If the playlist has been loaded or created without volume automation enabled, you can add a new encrypted item by passing a well formatted XML string to this parameter; an example of well formatted string is the following:

 <Item pathname="C:\sounds\drumtrik01_120bpm.wav" DecryptKey="JHDG78TR45JHGaf654MAAKHNF235TY" />

nIndex

Number representing the zero-based insertion position: if the nIndex parameter value exceed the playlist length, the song will be placed at the bottom of the playlist

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


PlayListAddItemEx method

PlayListAddItemEx method

Remarks

Adds a song or another playlist or the full content of a directory to the loaded playlist.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListAddItemEx (

nPlayer as Integer,

strPathname as String,

nIndex as Integer,

nItemType as enumPlayListItemType

) as enumErrorCodes

[C++]

short control.PlayListAddItemEx (

short nPlayer,

LPCTSTR strPathname,

short nIndex,

short nItemType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the playlist

strPathname

String containing the absolute pathname of the element to add.

If the playlist has been loaded or created with volume automation enabled, you can add a new item containing all the needed mixing positions, volume automation points and cue points in one single shot by passing a well formatted XML string to this parameter; an example of well formatted string is the following:

 <Item pathname="C:\sounds\drumtrik01_120bpm.wav" DurationSec="16.00" StartPosSec="2.0" MixPosSec="12.0" EndPosSec="16.0" >

   <VolumePoints>

     <VolumePoint name="start fade-in" VolumeLevelLinear="0.0" PosSec="2.0" CurveType="5"

                LeftX="11" LeftY="3" RightX="93" RightY="43" />

     <VolumePoint name="end fade-in" VolumeLevelLinear="100.0" PosSec="5.5" CurveType="0" />

     <VolumePoint name="start fade-out" VolumeLevelLinear="100.0" PosSec="11.9" CurveType="5"

                LeftX="83" LeftY="13" RightX="32" RightY="41" />

     <VolumePoint name="end fade-out" VolumeLevelLinear="0.0" PosSec="15.9" CurveType="0" />

   </VolumePoints>

   <CuePoints>

     <CuePoint name="Silence end" PosMs="1000" />

     <CuePoint name="Fading point" PosMs="12000" />

     <CuePoint name="Silence start" PosMs="15900" />

   </CuePoints>

 </Item>

For details about XML syntax of the string above refer to the How to manage Volume Automation tutorial.

If the playlist has been loaded or created without volume automation enabled, you can add a new encrypted item by passing a well formatted XML string to this parameter; an example of well formatted string is the following:

 <Item pathname="C:\sounds\drumtrik01_120bpm.wav" DecryptKey="JHDG78TR45JHGaf654MAAKHNF235TY" />

nIndex

Number representing the zero-based insertion position: if the nIndex parameter value exceed the playlist length, the song will be placed at the bottom of the playlist

nItemType

Type of item to add

Supported values are the following:

Mnemonic constant

Value

Meaning

PLAYLIST_ITEM_SOUND_FILE

0

Adds a single sound file whose pathname is found inside the strPathname parameter

PLAYLIST_ITEM_PLAYLIST_FILE

1

Adds full contents of an existing playlist file whose pathname is specified inside the strPathname parameter.

This operation is performed inside a secondary thread so, when the method returns, the list of items could be still not completed. In this case the container application is informed about the loading advancement through the PlayListLoadStart, PlayListLoadPerc and PlayListLoadDone events.

PLAYLIST_ITEM_DIRECTORY

2

Adds sound related contents of an existing directory whose path is specified inside the strPathname parameter.

This operation is performed inside a secondary thread so, when the method returns, the list of items could be still not completed. In this case the container application is informed about the loading advancement through the PlayListLoadStart, PlayListLoadPerc and PlayListLoadDone events.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


PlayListAddItemWithTag method

PlayListAddItemWithTag method

Remarks

Adds a song with an associated custom tag string to the loaded playlist. When the container application receives the PlaylistSoundLoaded event, the custom tag string is passed as parameter.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListAddItemWithTag (

nPlayer as Integer,

strPathname as String,

nIndex as Integer,

strTag as String

) as enumErrorCodes

[C++]

short control.PlayListAddItemWithTag (

short nPlayer,

LPCTSTR strPathname,

short nIndex,

LPCTSTR strTag

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the playlist

strPathname

String containing the absolute pathname of the element to add.

If the playlist has been loaded or created with volume automation enabled, you can add a new item containing all the needed mixing positions, volume automation points and cue points in one single shot by passing a well formatted XML string to this parameter; an example of well formatted string is the following:

 <Item pathname="C:\sounds\drumtrik01_120bpm.wav" DurationSec="16.00" StartPosSec="2.0" MixPosSec="12.0" EndPosSec="16.0" >

   <VolumePoints>

     <VolumePoint name="start fade-in" VolumeLevelLinear="0.0" PosSec="2.0" CurveType="5"

                LeftX="11" LeftY="3" RightX="93" RightY="43" />

     <VolumePoint name="end fade-in" VolumeLevelLinear="100.0" PosSec="5.5" CurveType="0" />

     <VolumePoint name="start fade-out" VolumeLevelLinear="100.0" PosSec="11.9" CurveType="5"

                LeftX="83" LeftY="13" RightX="32" RightY="41" />

     <VolumePoint name="end fade-out" VolumeLevelLinear="0.0" PosSec="15.9" CurveType="0" />

   </VolumePoints>

   <CuePoints>

     <CuePoint name="Silence end" PosMs="1000" />

     <CuePoint name="Fading point" PosMs="12000" />

     <CuePoint name="Silence start" PosMs="15900" />

   </CuePoints>

 </Item>

For details about XML syntax of the string above refer to the How to manage Volume Automation tutorial.

If the playlist has been loaded or created without volume automation enabled, you can add a new encrypted item by passing a well formatted XML string to this parameter; an example of well formatted string is the following:

 <Item pathname="C:\sounds\drumtrik01_120bpm.wav" DecryptKey="JHDG78TR45JHGaf654MAAKHNF235TY" />

nIndex

Number representing the zero-based insertion position: if the nIndex parameter value exceed the playlist length, the song will be placed at the bottom of the playlist

strTag

String containing a custom tag

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


PlayListCreate method

PlayListCreate method

Remarks

Creates a new playlist associated with the specified player. This method must precede any other playlist related method apart from the PlayListLoad method.

By default the playlist will use the PLAYLIST_FULL_MODE loading mode: with this setting the exact duration of each of the local (not Internet) playlist items will be calculated causing a longer time for adding a new item; if you want to create a playlist using the PLAYLIST_SPEED_MODE loading mode you will have to call the PlayListCreateSpeed method.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListCreate (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PlayListCreate (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will own the new playlist

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


PlayListCreateAutomation method

PlayListCreateAutomation method

Remarks

Creates a new playlist associated to the given player using the PLAYLIST_AUTOMATION_MODE loading mode; this setting will allow managing volume automation for each new item added to the playlist.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListCreateAutomation (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PlayListCreateAutomation (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will own the new playlist

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


PlayListCreateSpeed method

PlayListCreateSpeed method

Remarks

Creates a new playlist associated to the given player using the PLAYLIST_SPEED_MODE loading mode; this setting will allow a faster loading time for each new item added to the playlist and is strongly suggested when adding items coming from a network resource instead of the local hard disk.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListCreateSpeed (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PlayListCreateSpeed (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will own the new playlist

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The call was successful.


PlayListCurrIndexGet method

PlayListCurrIndexGet method

Remarks

Obtains the index of the item in playlist that is currently being executed. The index of the next item can be obtained through the PlayListNextIndexGet method.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListCurrIndexGet (

nPlayer as Integer,

ByRef nIndex as Integer

) as enumErrorCodes

[C++]

short control.PlayListCurrIndexGet (

short nPlayer,

short *nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist
nIndex | Reference that, on return from the method call, will contain the zero-based index of the current playlist item

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


PlayListExecAt method

PlayListExecAt method

Remarks

Starts the playlist execution from the given position.

The usage of this method is disabled when the playlist execution has been started through the Fader.StartManualFading method.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListExecAt (

nPlayer as Integer,

nIndex as Integer

) as enumErrorCodes

[C++]

short control.PlayListExecAt (

short nPlayer,

short nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist
nIndex | Number representing the zero-based position of the item to play.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListExecNext method

PlayListExecNext method

Remarks

Executes the next song inside the playlist. The playlist execution must be already started through the PlayListExecute or through the PlayListExecAt.

The usage of this method is disabled when the playlist execution has been started through the Fader.StartManualFading method.

If the latest played song was the last one inside the playlist, this call will execute the first song.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListExecNext (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PlayListExecNext (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListExecPrev method

PlayListExecPrev method

Remarks

Executes the previous song inside the playlist. The playlist execution must be already started through the PlayListExecute or through the PlayListExecAt.

The usage of this method is disabled when the playlist execution has been started through the Fader.StartManualFading method.

If the latest played song was the first one inside the playlist, this call will execute the last song.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListExecPrev (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.PlayListExecPrev (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListExecute method

PlayListExecute method

Remarks

Executes the playlist associated with the specified player.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListExecute (

nPlayer as Integer,

bFromBegin as enumBoolean

) as enumErrorCodes

[C++]

short control.PlayListExecute (

short nPlayer,

short bFromBegin

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the playlist

bFromBegin

Boolean value that specifies to execute the playlist from the beginning (only considered in case of a previous stopped playlist execution).

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't execute the playlist from the beginning
BOOL_TRUE | 1 | Executes the playlist from the beginning

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListExecOrderTableGet method

PlayListExecOrderTableGet method

Remarks

Retrieves the table containing the ordered sequence of execution of playlist's items.

This method may be useful to obtain the exact playlist's execution order when in "shuffle" mode (see the PlayListSetShuffle method).

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

Public Function PlayListExecOrderTableGet (

nPlayer as Integer,

tableValues() as Integer,

nTableLength as Integer

) as enumErrorCodes

[C++]

public: enumErrorCodes PlayListExecOrderTableGet (

short nPlayer,

short *tableValues,

short nTableLength

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Spectrum
tableValues | Memory buffer that, on exit, will contain the sequence of items indexes. The size of the table should correspond to the number of playlist's items as returned by the PlayListGetCount method.
nTableLength | Length of the table that needs to be obtained expressed in number of playlist's items as returned by the PlayListGetCount method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


PlayListGetCount method

PlayListGetCount method

Remarks

Obtains the number of songs (items) contained inside the playlist

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListGetCount (

nPlayer as Integer

) as Integer

[C++]

short control.PlayListGetCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will own the new playlist

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The number of items available inside the playlist


PlayListGetItemString method

PlayListGetItemString method

Remarks

Obtains a string containing information about the given playlist song.

Strings are only available if the playlist has not been loaded using "speed mode" (see the nMode parameter of the PlayListLoad method for details). Some string (see table below) is available only when the song is loaded and ready for playing.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListGetItemString (

nPlayer as Integer,

nItem as Integer,

nString as enumPlayListFieldsForDj

) as String

[C++]

short control.PlayListGetItemString (

short nPlayer,

short nItem,

short nString

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the playlist

nItem

Number representing the zero-based index of the song (item) whose information must be obtained. The number of available items can be obtained using the PlayListGetCount method.

nString

The identifier of the string to obtain.

Supported values are the following:

Mnemonic constant

Value

Meaning

PL_STRING_URL

0

Full pathname of the song file

PL_STRING_FILENAME

1

Song filename

PL_STRING_INFO_FRAMES

2

Number of frames inside the song (MP3 only) (available only when the song is loaded)

PL_STRING_INFO_DURATION

3

Duration of the song in seconds

This information is not available when the playlist is loaded with the PLAYLIST_SPEED_MODE setting and for video clips.

PL_STRING_INFO_LEVEL

4

MPEG level (MP3 only) (available only when the song is loaded)

PL_STRING_INFO_LAYER

5

MPEG layer (MP3 only) (available only when the song is loaded)

PL_STRING_INFO_BITRATE

6

Bitrate (available only when the song is loaded)

PL_STRING_INFO_FREQ

7

Sampling frequency (available only when the song is loaded)

PL_STRING_INFO_MODE

8

MPEG mode (MP3 only) (available only when the song is loaded)

PL_STRING_INFO_CHANNELS

9

Number of channels (1 for mono, 2 for stereo) (available only when the song is loaded)

PL_STRING_INFO_TITLE

10

Title of the song contained in the ID3V1 tag (MP3 only).

In case the loaded sound file shouldn't be in MP3 format or should not contain the ID3V1 tag, the following possibilities would apply:

· if the sound file should have been loaded from a playlist in PLS format, the returned string would contain contents of the "TitleX" field corresponding to the item (same as requesting PL_STRING_INFO_TITLE_PLS)
· if the sound file should have been loaded from a playlist in PDJ format, the returned string would contain contents of the "Title" attribute corresponding to the item
· in all other cases the returned string would contain the filename of the sound file (same as requesting PL_STRING_FILENAME)

PL_STRING_INFO_ARTIST

11

Artist (contained in the ID3V1 tag) (MP3 only)

PL_STRING_INFO_ALBUM

12

Album (contained in the ID3V1 tag) (MP3 only)

PL_STRING_INFO_YEAR

13

Year (contained in the ID3V1 tag) (MP3 only)

PL_STRING_INFO_COMMENT

14

Comment (contained in the ID3V1 tag) (MP3 only)

PL_STRING_INFO_TRACK

15

Track number (contained in the ID3V1.1 tag) (MP3 only)

PL_STRING_INFO_GENRECODE

16

Genre code (contained in the ID3V1 tag, see Appendix A for supported values) (MP3 only)

PL_STRING_INFO_GENRE_STR

17

Genre description (based upon the genre code contained in the ID3V1 tag, see Appendix A for supported values) (MP3 only)

PL_STRING_INFO_FORMATTED_DURAT

18

Formatted sound duration using the following format [hh:mm:ss:ms]. For example [04:34:200] indicates a song during 0 hours (the hours number is automatically omitted if 0), 4 minutes, 34 seconds and 200 milliseconds.

This information is not available when the playlist is loaded with the PLAYLIST_SPEED_MODE setting and for video clips.

PL_STRING_INFO_FORMATTED_DURAT_NO_MS

19

Formatted sound duration, without milliseconds, using the following format [hh:mm:ss]. Also in this case the hours number is automatically omitted if 0.

This information is not available when the playlist is loaded with the PLAYLIST_SPEED_MODE setting and for video clips.

PL_STRING_INFO_TITLE_PLS

20

If the sound file should have been loaded from a playlist in PLS format, contents of the "TitleX" field corresponding to the item

PL_STRING_INFO_LENGTH_PLS

21

If the sound file should have been loaded from a playlist in PLS format, contents of the "LengthX" field corresponding to the item

Return value

Value | Meaning
Empty string | The information was not available or an error occurred (see the LastError property for further error details)
Valid string | The requested string


PlayListItemCuePointAdd method

PlayListItemCuePointAdd method

Remarks

Adds a new cue point to an item of the playlist: when the cue point is reached, the CuePointReached event is fired.

This method will return an error if the playlist has not been created with the PlayListCreateAutomation method or loaded with the PlayListLoad or PlayListLoadSync methods having the nMode parameter set to PLAYLIST_AUTOMATION_MODE.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

For further details about cue points see the How to add Triggers and Cue Points to a player tutorial.

Syntax

[Visual Basic]

control.PlayListItemCuePointAdd (

nPlayer as Integer,

nItem as Integer,

strCuePointName as String,

nPositionUnit as enumVolumeAutomationPositionUnits,

fPosition as Single

) as enumErrorCodes

[C++]

short control.PlayListItemCuePointAdd (

short nPlayer,

short nItem,

LPCTSTR strCuePointName,

short nPositionUnit,

float fPosition

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nItem

Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.

strCuePointName

String containing the unique name that will identify the cue point from now on.

If this name should be already assigned to an existing cue point, an error code would be returned

nPositionUnit

The unit used to define the position of the cue point through the fPosition parameter below.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Position is expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Position is expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Position is expressed in milliseconds

fPosition

Number representing the cue point position expressed in nPositionUnit

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


PlayListItemCuePointCountGet method

PlayListItemCuePointCountGet method

Remarks

Obtains the number of cue points added to a playlist's item. The cue can have been previously added through the PlayListItemCuePointAdd method or as a result of a playlist loading through the PlayListLoad method.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemCuePointCountGet (

nPlayer as Integer,

nItem as Integer,

nCount as Integer

) as enumErrorCodes

[C++]

short control.PlayListItemCuePointCountGet (

short nPlayer,

short nItem,

short *nCount

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nItem | Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.
nCount | Reference that, on return from the method call, will contain the number of cue points added to a specific playlist's item.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


PlayListItemCuePointGet method

PlayListItemCuePointGet method

Remarks

Obtains information about a specific cue point from an item of the playlist.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

For further details about cue points see the How to add Triggers and Cue Points to a player tutorial.

Syntax

[Visual Basic]

control.PlayListItemCuePointGet (

nPlayer as Integer,

nItem as Integer,

nCuePointIndex as Integer,

nPositionUnit as enumVolumeAutomationPositionUnits,

fPosition as Single

) as String

[C++]

LPCTSTR control.PlayListItemCuePointGet (

short nPlayer,

short nItem,

short nCuePointIndex,

short nPositionUnit,

float *fPosition

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItem

Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.

nCuePointIndex

Number representing the zero-based index of the cue point. The number of available cue points can be obtained using the PlayListItemCuePointCountGet method.

nPositionUnit

The unit used to define the position of the cue point through the fPosition parameter below.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Position is expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Position is expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Position is expressed in milliseconds

fPosition

Reference that, on return from the method call, will contain the position of the volume point expressed in the same unit set into the nPositionUnit parameter.

Return value

Value | Meaning
Empty string | The information was not available or an error occurred (see the LastError property for further error details)
Valid string | The name of the cue point


PlayListItemCuePointRemove method

PlayListItemCuePointRemove method

Remarks

Removes a cue point from an item of the playlist.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

For further details about cue points see the How to add Triggers and Cue Points to a player tutorial.

Syntax

[Visual Basic]

control.PlayListItemCuePointRemove (

nPlayer as Integer,

nItem as Integer,

strCuePointName as String

) as enumErrorCodes

[C++]

short control.PlayListItemCuePointRemove (

short nPlayer,

short nItem,

LPCTSTR strCuePointName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nItem | Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.
strCuePointName | String containing the unique name that identifies the cue point: this name must be identical to the one used when the cue point was created through the PlayListItemCuePointAdd method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


PlayListItemVolAutomPointAdd method

PlayListItemVolAutomPointAdd method

Remarks

Adds a new volume point to an item of the playlist.

This method will return an error if the playlist has not been created with the PlayListCreateAutomation method or loaded with the PlayListLoad or PlayListLoadSync methods having the nMode parameter set to PLAYLIST_AUTOMATION_MODE.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemVolAutomPointAdd (

nPlayer as Integer,

nItem as Integer,

strVolumePointName as String,

nPositionUnit as enumVolumeAutomationPosUnits,

fPosition as Single,

nVolumeScaleType as enumVolumeScales,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.PlayListItemVolAutomPointAdd (

short nPlayer,

short nItem,

LPCTSTR strVolumePointName,

short nPositionUnit,

float fPosition,

short nVolumeScaleType,

float fVolumeLevel,

short nCurveType,

long nDesignerUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nItem

Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.

strVolumePointName

String representing the friendly name of the volume point to add: there is no naming convention so you are free to decide your own set of names. This name will be used in next calls that will act on this specific volume point.

nPositionUnit

The unit used to define positions of volume points.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Positions are expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Positions are expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Positions are expressed in milliseconds

fPosition

Position of the volume point expressed in the same unit set into the nPositionUnit parameter.

nVolumeScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The returned volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

fVolumeLevel

Volume level expressed in the same unit set into the nVolumeScaleType parameter

nCurveType

Type of curve applied to reach the next volume point.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_NONE | 0 | No curve is applied: volume will be changed immediately and will be kept till next volume point.
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


PlayListItemVolAutomPointCountGet method

PlayListItemVolAutomPointCountGet method

Remarks

Obtains the number of volume automation points added to a playlist's item. The volume point can have been previously added through the PlayListItemVolAutomPointAdd method or as a result of a playlist loading through the PlayListLoad method.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemVolAutomPointCountGet (

nPlayer as Integer,

nItem as Integer,

nCount as Integer

) as enumErrorCodes

[C++]

short control.PlayListItemVolAutomPointCountGet (

short nPlayer,

short nItem,

short *nCount

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nItem | Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.
nCount | Reference that, on return from the method call, will contain the number of volume automation points added to a specific playlist's item.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


PlayListItemVolAutomPointModify method

PlayListItemVolAutomPointModify method

Remarks

Modifies an existing volume point of a playlist's item. The volume point can have been previously added through the PlayListItemVolAutomPointAdd method or as a result of a playlist loading through the PlayListLoad method.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemVolAutomPointModify (

nPlayer as Integer,

nItem as Integer,

strVolumePointName as String,

nPositionUnit as enumVolumeAutomationPosUnits,

fPosition as Single,

nVolumeScaleType as enumVolumeScales,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.PlayListItemVolAutomPointModify (

short nPlayer,

short nItem,

LPCTSTR strVolumePointName,

short nPositionUnit,

float fPosition,

short nVolumeScaleType,

float fVolumeLevel,

short nCurveType,

long nDesignerUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player.

nItem

Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.

strVolumePointName

String representing the friendly name of the volume point to modify

nPositionUnit

The unit used to define positions of volume points.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Positions are expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Positions are expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Positions are expressed in milliseconds

fPosition

Position of the volume point expressed in the same unit set into the nPositionUnit parameter.

Set this parameter to -1 if you need to leave the current position value unchanged.

nVolumeScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The returned volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

fVolumeLevel

Volume level expressed in the same unit set into the nVolumeScaleType parameter.

Set this parameter to -1 if you need to leave the current volume level unchanged.

nCurveType

Type of curve applied to reach the next volume point.

Set this parameter to -1 if you need to leave the current curve type unchanged.

Supported values are the following:

Mnemonic constant | Value | Meaning
 | -1 | Ignore this setting and leave the current curve type unchanged.
VOLUME_CURVE_NONE | 0 | No curve is applied: volume will be changed immediately and will be kept till next volume point.
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


PlayListItemVolAutomPointNameGet method

PlayListItemVolAutomPointNameGet method

Remarks

Obtains the name of a given volume automation point added to an item of the playlist. The volume point can have been previously added through the PlayListItemVolAutomPointAdd method or as a result of a playlist loading through the PlayListLoad method.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemVolAutomPointNameGet (

nPlayer as Integer,

nItem as Integer,

nPointIndex as Integer

) as String

[C++]

short control.PlayListItemVolAutomPointNameGet (

short nPlayer,

short nItem,

short nPointIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist
nItem | Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.
nPointIndex | Number representing the zero-based index of the volume point. The number of available volume automation points can be obtained using the PlayListItemVolAutomPointCountGet method.

Return value

Value | Meaning
Empty string | The information was not available or an error occurred (see the LastError property for further error details)
Valid string | The name of the volume point


PlayListItemVolAutomPointParamsGet method

PlayListItemVolAutomPointParamsGet method

Remarks

Obtains parameters of an existing volume point of a playlist's item. The volume point can have been previously added through the PlayListItemVolAutomPointAdd method or as a result of a playlist loading through the PlayListLoad method.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemVolAutomPointParamsGet (

nPlayer as Integer,

nItem as Integer,

strVolumePointName as String,

nPositionUnit as enumVolumeAutomationPosUnits,

fPosition as Single,

nVolumeScaleType as enumVolumeScales,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.PlayListItemVolAutomPointParamsGet (

short nPlayer,

short nItem,

LPCTSTR strVolumePointName,

short nPositionUnit,

float *fPosition,

short nVolumeScaleType,

float *fVolumeLevel,

short *nCurveType,

short *nLeftX,

short *nLeftY,

short *nRightX,

short *nRightY

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player.

nItem

Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.

strVolumePointName

String representing the friendly name of the volume point to modify

nPositionUnit

The unit used to define positions of volume points.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Positions are expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Positions are expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Positions are expressed in milliseconds

fPosition

Reference that, on return from the method call, will contain the position of the volume point expressed in the same unit set into the nPositionUnit parameter.

nVolumeScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The returned volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

fVolumeLevel

Reference that, on return from the method call, will contain the volume level expressed in the same unit set into the nVolumeScaleType parameter.

nCurveType

Reference that, on return from the method call, will contain the type of curve applied to reach the next volume point.

Set this parameter to -1 if you need to leave the current curve type unchanged.

Supported values are the following:

Mnemonic constant | Value | Meaning
 | -1 | Ignore this setting and leave the current curve type unchanged.
VOLUME_CURVE_NONE | 0 | No curve is applied: volume will be changed immediately and will be kept till next volume point.
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve. When this values is obtained, positions of Bézier curve's control points are returned inside the nLeftX, nLeftY, nRightX and nRightY parameters below.

nLeftX

Reference that, on return from the method call, will contain the horizontal position, expressed in percentage of the designer's area, of the left control point. This parameter can be ignored when the nCurveType parameter above is set to a value different from VOLUME_CURVE_CUSTOM.

nLeftY

Reference that, on return from the method call, will contain the vertical position, expressed in percentage of the designer's area, of the left control point. This parameter can be ignored when the nCurveType parameter above is set to a value different from VOLUME_CURVE_CUSTOM.

nRightX

Reference that, on return from the method call, will contain the horizontal position, expressed in percentage of the designer's area, of the right control point. This parameter can be ignored when the nCurveType parameter above is set to a value different from VOLUME_CURVE_CUSTOM.

nRightY

Reference that, on return from the method call, will contain the vertical position, expressed in percentage of the designer's area, of the right control point This parameter can be ignored when the nCurveType parameter above is set to a value different from VOLUME_CURVE_CUSTOM.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


PlayListItemVolAutomPointRemove method

PlayListItemVolAutomPointRemove method

Remarks

Removes a volume point from an item of the playlist. The volume point can have been previously added through the PlayListItemVolAutomPointAdd method or as a result of a playlist loading through the PlayListLoad method.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemVolAutomPointRemove (

nPlayer as Integer,

nItem as Integer,

strVolumePointName as String

) as enumErrorCodes

[C++]

short control.PlayListItemVolAutomPointRemove (

short nPlayer,

short nItem,

LPCTSTR strVolumePointName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nItem | Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.
strVolumePointName | String representing the friendly name of the volume point to remove.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


PlayListItemVolAutomGetMixPos method

PlayListItemVolAutomGetMixPos method

Remarks

Obtains volume automation mixing positions from an item of the playlist. Current mixing positions can be modified through the PlayListItemVolAutomSetMixPos method.

The volume point can have been previously added through the PlayListItemVolAutomPointAdd method or as a result of a playlist loading through the PlayListLoad method.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemVolAutomGetMixPos (

nPlayer as Integer,

nItem as Integer,

nPositionUnit as enumVolumeAutomationPositionUnits,

fStartPos as Single,

fMixPos as Single,

fEndPos as Single

) as enumErrorCodes

[C++]

short control.PlayListItemVolAutomGetMixPos (

short nPlayer,

short nItem,

short nPositionUnit,

float *fStartPos,

float *fMixPos,

float *fEndPos

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nItem

Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.

nPositionUnit

The unit used to define the position parameters fStartPos,fMixPos and fEndPos below.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Positions are expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Positions are expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Positions are expressed in milliseconds

fStartPos

Reference that, on return from the method call, will contain the start position expressed in nPositionUnit. This parameter is the equivalent of the StartPosSec/StartPosMs/StartPosPerc attributes of the Item sub-key of the PDJ format.

fMixPos

Reference that, on return from the method call, will contain the mixing position expressed in nPositionUnit. This parameter is the equivalent of the MixPosSec/MixPosMs/MixPosPerc attributes of the Item sub-key of the PDJ format.

fEndPos

Reference that, on return from the method call, will contain the end position expressed in nPositionUnit. This parameter is the equivalent of the EndPosSec/EndPosMs/EndPosPerc attributes of the Item sub-key of the PDJ format.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


PlayListItemVolAutomSetMixPos method

PlayListItemVolAutomSetMixPos method

Remarks

Sets volume automation mixing positions to an item of the playlist. Current mixing positions can be obtained through the PlayListItemVolAutomGetMixPos method.

The volume point can have been previously added through the PlayListItemVolAutomPointAdd method or as a result of a playlist loading through the PlayListLoad method.

This method will return an error if the playlist has not been created with the PlayListCreateAutomation method or loaded with the PlayListLoad or PlayListLoadSync methods having the nMode parameter set to PLAYLIST_AUTOMATION_MODE.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListItemVolAutomSetMixPos (

nPlayer as Integer,

nItem as Integer,

nPositionUnit as enumVolumeAutomationPositionUnits,

fStartPos as Single,

fMixPos as Single,

fEndPos as Single

) as enumErrorCodes

[C++]

short control.PlayListItemVolAutomSetMixPos (

short nPlayer,

short nItem,

short nPositionUnit,

float fStartPos,

float fMixPos,

float fEndPos

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nItem

Number representing the zero-based index of the item inside the playlist. The number of available items can be obtained using the PlayListGetCount method.

nPositionUnit

The unit used to define the position parameters fStartPos,fMixPos and fEndPos below.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Position is expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Position is expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Position is expressed in milliseconds

fStartPos

Number representing the start position expressed in nPositionUnit. This parameter is the equivalent of the StartPosSec/StartPosMs/StartPosPerc attributes of the Item sub-key of the PDJ format.

fMixPos

Number representing the mixing position expressed in nPositionUnit. This parameter is the equivalent of the MixPosSec/MixPosMs/MixPosPerc attributes of the Item sub-key of the PDJ format.

fEndPos

Number representing the end position expressed in nPositionUnit. This parameter is the equivalent of the EndPosSec/EndPosMs/EndPosPerc attributes of the Item sub-key of the PDJ format.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


PlayListLoad method

PlayListLoad method

Remarks

Loads a playlist from the specified file. A call to this method won't return control to the container application until the playlist has been loaded completely so, if the playlist should be very long, it could block your user interface for a while; for this reason there is the possibility to call the PlayListLoadSync method which will perform playlist analysis and loading in a separate thread.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListLoad (

nPlayer as Integer,

strPathname as String,

nMode as enumPlayListModes

) as enumErrorCodes

[C++]

short control.PlayListLoad (

short nPlayer,

LPCTSTR strPathname,

short nMode

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will own the new playlist

strPathname

String containing the name of the playlist file: accepted playlist formats are M3U and PLS

nMode

Loading mode.

Supported values are the following:

Mnemonic constant | Value | Meaning
PLAYLIST_SPEED_MODE | 0 | Speed mode: playlist songs analysis is not performed: suggested when adding items coming from a local network
PLAYLIST_FULL_MODE | 1 | Full mode: will be calculated the duration of each of the local (not Internet) playlist items. The playlist loading will be longer.
PLAYLIST_AUTOMATION_MODE | 2 | Automation mode: allows the use of the PDJ playlist format with fader attributes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListLoadFromCd method

PlayListLoadFromCd method

Remarks

Composes a playlist with all of the tracks contained inside a CD.

Syntax

[Visual Basic]

control.PlayListLoadFromCd (

nPlayer as Integer,

nDrive as Integer

) as Integer

[C++]

short control.PlayListLoadFromCd (

short nPlayer,

short nDrive

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nDrive | Number representing the zero-based index of the involved CD drive

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListLoadSync method

PlayListLoadSync method

Remarks

Loads a playlist from a file through a secondary thread.

Differently from the PlayListLoad method, this call will perform playlist loading and analysis inside a secondary thread, avoiding any block of the user interface when dealing with very long playlists: in this case the container application is informed about the loading advancement through the PlayListLoadStart, PlayListLoadPerc and PlayListLoadDone events.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListLoadSync (

nPlayer as Integer,

strPathname as String,

nMode as enumPlayListModes

) as enumErrorCodes

[C++]

short control.PlayListLoadSync (

short nPlayer,

LPCTSTR strPathname,

short nMode

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will own the new playlist

strPathname

String containing the name of the playlist file: accepted playlist formats are M3U and PLS

nMode

Loading mode.

Supported values are the following:

Mnemonic constant | Value | Meaning
PLAYLIST_SPEED_MODE | 0 | Speed mode: playlist songs analysis is not performed: suggested when adding items coming from a local network
PLAYLIST_FULL_MODE | 1 | Full mode: will be calculated the duration of each of the local (not Internet) playlist items. The playlist loading will be longer.
PLAYLIST_AUTOMATION_MODE | 2 | Automation mode: allows the use of the PDJ playlist format

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListMoveItem method

PlayListMoveItem method

Remarks

Moves a song (item) from a source position to a destination position inside the playlist.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListMoveItem (

nPlayer as Integer,

nOldIndex as Integer,

nNewIndex as Integer

) as enumErrorCodes

[C++]

short control.PlayListMoveItem (

short nPlayer,

short nOldIndex,

short nNewIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist
nOldIndex | Number representing the zero-based source position
nNewIndex | Number representing the zero-based destination position

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListNextIndexGet method

PlayListNextIndexGet method

Remarks

Obtains the index of the next item in playlist that will be executed after completing the current one. The index of the current item can be obtained through the PlayListCurrIndexGet method.

This method may be useful to understand which item will be executed after the current one when the playlist is executed in "shuffle" mode (see the PlayListSetShuffle method).

You may modify the next index of the item to be executed through the PlayListNextIndexSet method.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListNextIndexGet (

nPlayer as Integer,

nIndex as Integer

) as enumErrorCodes

[C++]

short control.PlayListNextIndexGet (

short nPlayer,

short *nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist
nIndex | Reference that, on return from the method call, will contain the zero-based index of the next playlist item

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListNextIndexSet method

PlayListNextIndexSet method

Remarks

Sets the index of the next item in playlist that will be executed after completing the current one. The current index of the next item can be obtained through the PlayListNextIndexGet method.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListNextIndexSet (

nPlayer as Integer,

nIndex as Integer

) as enumErrorCodes

[C++]

short control.PlayListNextIndexSet (

short nPlayer,

short nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist
nIndex | The zero-based index of the next playlist item

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListRemoveItem method

PlayListRemoveItem method

Remarks

Removes a song (item) from the playlist associated with the specified player.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListRemoveItem (

nPlayer as Integer,

nIndex as Integer

) as enumErrorCodes

[C++]

short control.PlayListRemoveItem (

short nPlayer,

short nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist
nIndex | Number representing the zero-based deletion position: if the nIndex parameter value is set to -1, all the items are removed from the playlist

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListSave method

PlayListSave method

Remarks

Saves the current playlist into the given file.

Syntax

[Visual Basic]

control.PlayListSave (

nPlayer as Integer,

strPathname as String,

nFormat as enumPlayListFormats

) as enumErrorCodes

[C++]

short control.PlayListSave (

short nPlayer,

LPCTSTR strPathname,

short nFormat

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will own the new playlist

strPathname

String containing the name of the output playlist file

nFormat

Save format.

Supported values are the following:

Mnemonic constant | Value | Meaning
PLAYLIST_FORMAT_M3U | 0 | M3U format
PLAYLIST_FORMAT_PLS | 1 | PLS format
PLAYLIST_FORMAT_WPL | 2 | WPL format
PLAYLIST_FORMAT_PDJ | 3 | PDJ format; this is a MultiMedia Soft proprietary format: see the How to create and manage a playlist tutorial for details.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListSaveAutomation method

PlayListSaveAutomation method

Remarks

Saves the current playlist into the given file in PDJ format using given position unit and volume scale.

A playlist can be saved with volume automation information only if it has been loaded through the PlayListLoad or PlayListLoadSync methods having the nMode parameter set to PLAYLIST_AUTOMATION_MODE or if it has been created at runtime using the PlayListCreateAutomation method.

For further details about playlists management see the How to create and manage a playlist tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.PlayListSaveAutomation (

nPlayer as Integer,

strPathname as String,

nPosUnit as enumVolumeAutomationPositionUnits

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.PlayListSaveAutomation (

short nPlayer,

LPCTSTR strPathname,

short nPosUnit,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will own the new playlist

strPathname

String containing the name of the output playlist file (PDJ format)

nPosUnit

The unit used to define positions of volume points.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Positions are expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Positions are expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Positions are expressed in milliseconds

nScaleType

Volume scale type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Volume, expressed in percentage, is based upon a linear scale: - value 0.0 means that channel is muted - values higher than 0.0 and smaller than 100.0 attenuate the channel volume - value 100.0 keeps original sound level unchanged - values higher than 100.0 amplify the sound level
SCALE_LOG | 1 | Volume, expressed in dB, is based upon a logarithmic scale: - value -100.0 means that channel is muted - values higher than -100.0 and smaller than 0.0 attenuate the channel volume - value 0.0 keeps original sound level unchanged - values higher than 0.0 amplify the sound level The actual applied formula for converting a linear volume into a logarithmic volume is the following: VolumeInDB = 20 * log10 (VolumeLinear/100) The C syntax for converting a logarithmic volume into a linear volume is the following: VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListSetLoop method

PlayListSetLoop method

Remarks

Sets the playlist execution in looping mode: this means that, once the playlist execution has been completed, it will automatically restart from the beginning.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListSetLoop (

nPlayer as Integer,

bLoop as enumBoolean

) as enumErrorCodes

[C++]

short control.PlayListSetLoop (

short nPlayer,

short bLoop

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the playlist

bLoop

Boolean value that specifies to go in loop mode once the playlist execution has been completed.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Playlist is executed only once
BOOL_TRUE | 1 | Playlist is executed in Loop mode

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListSetShuffle method

PlayListSetShuffle method

Remarks

Sets the playlist execution in random order.

The execution order is changed each time this method is called with the bShuffle parameter set to "BOOL_TRUE".

If the playlist has the Loop mode set to "BOOL_TRUE" (through the PlayListSetLoop method), each time the playlist is completed the execution order is automatically changed.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListSetShuffle (

nPlayer as Integer,

bShuffle as enumBoolean

) as enumErrorCodes

[C++]

short control.PlayListSetShuffle (

short nPlayer,

short bShuffle

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the playlist

bShuffle

Boolean value that specifies to execute the playlist in shuffle mode

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Playlist is executed in ordered mode
BOOL_TRUE | 1 | Playlist is executed in Shuffle mode

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


PlayListStop method

PlayListStop method

Remarks

Stops execution of the playlist associated with the specified player.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

control.PlayListStop (

nPlayer as Integer,

bStopCurrSound as enumBoolean

) as enumErrorCodes

[C++]

short control.PlayListStop (

short nPlayer,

short bStopCurrSound

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the playlist

bStopCurrSound

Boolean value that specifies if also the sound currently playing must be stopped.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Stops the playlist after completing the currently playing sound
BOOL_TRUE | 1 | Stops both the playlist and the currently playing sound

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


TriggersAdd method

TriggersAdd method

Remarks

Adds a trigger to the given player at a certain song position: when the trigger is reached, the TriggerReached event is fired.

Triggers positioning is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always refer to the position of the song as it should be played at its original speed.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersAdd (

nPlayer as Integer,

nTriggerID as Integer,

nTriggerPos as Long

) as enumErrorCodes

[C++]

short control.TriggersAdd (

short nPlayer,

short nTriggerID,

long nTriggerPos

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nTriggerID | Number representing the identifier of the new trigger. If this identifier should be already assigned to another trigger, an error code would be returned.
nTriggerPos | Number representing the trigger position; it's effective value depends upon the value of the ScaleUnits property. If this position should be already assigned to an existing trigger, an error code would be returned.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


TriggersAddPerc method

TriggersAddPerc method

Remarks

Adds a trigger to the given player at a certain song position: when the trigger is reached, the TriggerReached event is fired.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersAddPerc (

nPlayer as Integer,

nTriggerID as Integer,

fTriggerPosPerc as single

) as enumErrorCodes

[C++]

short control.TriggersAddPerc (

short nPlayer,

short nTriggerID,

float fTriggerPosPerc

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nTriggerID | Number representing the identifier of the new trigger. If this identifier should be already assigned to another trigger, an error code would be returned.
fTriggerPosPerc | Number representing the trigger position expressed in percentage. If this position should be already assigned to another trigger, an error code would be returned.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


TriggersEnable method

TriggersEnable method

Remarks

Enables/disable the given trigger.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersEnable (

nPlayer as Integer,

nTriggerID as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.TriggersEnable (

short nPlayer,

short nTriggerID,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTriggerID

Number representing the identifier of the new trigger. If this identifier should be already assigned to another trigger, an error code would be returned.

bEnable

Boolean value that specifies if the trigger must be enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Disable trigger
BOOL_TRUE (default) | 1 | Enable trigger

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


TriggersGetCount method

TriggersGetCount method

Remarks

Obtains the number of existing triggers set into the given player

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersGetCount (

nPlayer as Integer

) as Long

[C++]

long control.TriggersGetCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player owning the triggers

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The number of existing triggers


TriggersGetPos method

TriggersGetPos method

Remarks

Obtains the current position for the given trigger.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersGetPos (

nPlayer as Integer,

nTriggerID as Integer

) as Long

[C++]

long control.TriggersGetPos (

short nPlayer,

short nTriggerID

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nTriggerID | Number representing the identifier of the new trigger

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | The trigger position expressed in milliseconds


TriggersGetPosPerc method

TriggersGetPosPerc method

Remarks

Obtains the current position for the given trigger.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersGetPosPerc (

nPlayer as Integer,

nTriggerID as Integer

) as Single

[C++]

float control.TriggersGetPosPerc (

short nPlayer,

short nTriggerID

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nTriggerID | Number representing the identifier of the new trigger

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | The trigger position expressed in percentage


TriggersIsEnabled method

TriggersIsEnabled method

Remarks

Verifies if the given trigger is enabled or disabled.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersIsEnabled (

nPlayer as Integer,

nTriggerID as Integer,

) as Boolean

[C++]

BOOL control.TriggersIsEnabled (

short nPlayer,

short nTriggerID

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nTriggerID | Number representing the identifier of the new trigger. If this identifier should be already assigned to another trigger, an error code would be returned.

Return value

Mnemonic constant | Value | Meaning
FALSE | 0 | Trigger is disabled
TRUE | 1 | Trigger is enabled


TriggersRemove method

TriggersRemove method

Remarks

Removes an existing trigger from the given player.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersRemove (

nPlayer as Integer,

nTriggerID as Integer

) as enumErrorCodes

[C++]

short control.TriggersRemove (

short nPlayer,

short nTriggerID

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nTriggerID | Number representing the identifier of the trigger to remove. If this parameter is set to -1 all the existing triggers will be removed.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


TriggersSetPos method

TriggersSetPos method

Remarks

Modifies the current position for the given trigger.

Triggers positioning is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always refer to the position of the song as it should be played at its original speed.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersSetPos (

nPlayer as Integer,

nTriggerID as Integer,

nTriggerPos as Long

) as enumErrorCodes

[C++]

short control.TriggersSetPos (

short nPlayer,

short nTriggerID,

long nTriggerPos

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTriggerID

Number representing the identifier of the new trigger

nTriggerPos

Number representing the trigger position: it's effective value depends upon the value of the ScaleUnits property.

If this position should be already assigned to another trigger, the existing trigger would be removed from the list of existing triggers and replaced by the new one.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.WARNING_TRIGGER_REMOVED (1) | An existing trigger having the same position has been removed from the list of existing triggers
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


TriggersSetPosPerc method

TriggersSetPosPerc method

Remarks

Modifies the current position for the given trigger.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.TriggersSetPosPerc (

nPlayer as Integer,

nTriggerID as Integer,

fTriggerPosPerc as Single

) as enumErrorCodes

[C++]

short control.TriggersSetPosPerc (

short nPlayer,

short nTriggerID,

float fTriggerPosPerc

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nTriggerID | Number representing the identifier of the new trigger
nTriggerPosPerc | Number representing the trigger position expressed in percentage. If this position should be already assigned to another trigger, the existing trigger would be removed from the list of existing triggers and replaced by the new one.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.WARNING_TRIGGER_REMOVED (1) | An existing trigger having the same position has been removed from the list of existing triggers
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


AudioExtractFromVideoDone event

AudioExtractFromVideoDone event

Remarks

Occurs at the end of the extraction of the audio track from a video file. The audio extraction is started through a previous call to the VideoPlayer.AudioTrackExtract method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

AudioExtractFromVideoDone (

ByVal nPlayer as Integer,

ByVal bOutputSwitchedToFile as enumBoolean

ByVal nResult as enumErrorCodes

)

[C++]

void AudioExtractFromVideoDone (

short nPlayer,

short bOutputSwitchedToFile,

short nResult

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that fired the event

bOutputSwitchedToFile

Boolean flag that warns when the extracted audio track, that was originally requested to be stored in memory, has been put into a temporary file due to missing memory space.

If the original request was to store the extracted audio track inside a temporary file, this flag can be ignored.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The extracted audio track has been stored in memory as requested
BOOL_TRUE | 1 | Due to missing memory space, the extracted audio track has been stored inside a temporary file which can be accessed through the VideoPlayer.AudioTrackGetTempFilePathname and VideoPlayer.AudioTrackGetTempFileSize methods.

nResult

Result of the audio extraction: see the LastError property for details about the specific error code.


AudioExtractFromVideoPerc event

AudioExtractFromVideoPerc event

Remarks

Occurs during the extraction of the audio track from a video file to notify about the advancement. The audio extraction is started through a previous call to the VideoPlayer.AudioTrackExtract method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

AudioExtractFromVideoPerc (

ByVal nPlayer as Integer,

ByVal nPercentage as Integer

)

[C++]

void AudioExtractFromVideoPerc (

short nPlayer,

short nPercentage

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nPercentage | Number representing the current percentage of the audio extraction


AudioExtractFromVideoStart event

AudioExtractFromVideoStart event

Remarks

Occurs at the beginning of the extraction of the audio track from a video file. The audio extraction is started through a previous call to the VideoPlayer.AudioTrackExtract method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

AudioExtractFromVideoStart (

ByVal nPlayer as Integer

)

[C++]

void AudioExtractFromVideoStart (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


BeatDetectedRealTime event

BeatDetectedRealTime event

Remarks

Occurs when a beat is detected during a playback session of the loaded sound. Real-time beats detection can be enabled/disabled through a previous call to the BeatsDetectEnableRT method.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

BeatDetectedRealTime (

ByVal nPlayer as Integer,

ByVal nBeatPosition as Long

)

[C++]

void BeatDetectedRealTime (

short nPlayer,

short nBeatPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nBeatPosition | Beat's position expressed in milliseconds


BeatsAvailableOffline event

BeatsAvailableOffline event

Remarks

Occurs when the offline beats detection is completed. Offline beats detection can be started through a previous call to the BeatsDetectRequest method

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

BeatsAvailableOffline (

ByVal nPlayer as Integer,

ByVal nBeatsDetected as Long

)

[C++]

void BeatsAvailableOffline (

short nPlayer,

short nBeatsDetected

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nBeatsDetected | Number of beats detected


BPMAvailable event

BPMAvailable event

Remarks

Occurs when a song BPM has been detected.

For further details about BPM detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

BPMAvailable (

ByVal nPlayer as Integer,

ByVal fBPM as single

)

[C++]

void BPMAvailable (

short nPlayer,

float fBPM

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fBPM | The detected song BPM.


CastingPlayerDone event

CastingPlayerDone event

Remarks

Occurs when a player completes a casting session previously created by one between the CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer methods and started through the CastingStart method .

This event may also occur if the connection with the server should die for external reasons: in this case the error code would be reported inside the nResult parameter.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

CastingPlayerDone (

ByVal nCastingUniqueId as Integer,

ByVal nResult as enumErrorCodes

)

[C++]

void CastingPlayerDone (

short nCastingUniqueId,

short nResult

);

Parameter | Description
nCastingUniqueId | Unique identifier of the casting session returned by a previous call to CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer methods.
nResult | The result of the operation. See the LastError property for details about the returned result code. In case this parameter should indicate that an error occurred, be sure to close the casting session by calling the CastingStop method.


CastingPlayerPerc event

CastingPlayerPerc event

Remarks

Occurs during a player-based casting session to inform about the advancement percentage.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

CastingPlayerPerc (

ByVal nCastingUniqueId as Integer,

ByVal nPercentage as Integer

)

[C++]

void CastingPlayerPerc (

short nCastingUniqueId,

short nPercentage

);

Parameter | Description
nCastingUniqueId | Unique identifier of the casting session returned by a previous call to CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer methods.
nPercentage | Number representing the current percentage of the player-based casting session


CastingPlayerStart event

CastingPlayerStart event

Remarks

Occurs when a player, through a call to the the CastingStart method, starts a casting session previously created by one between the CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer methods.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

CastingPlayerStart (

ByVal nCastingUniqueId as Integer

)

[C++]

void CastingPlayerStart (

short nCastingUniqueId

);

Parameter | Description
nCastingUniqueId | Unique identifier of the casting session returned by a previous call to CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer methods.


CastingStreamMixerStart event

CastingStreamMixerStart event

Remarks

Occurs when a stream mixer, through a call to the the CastingStart method, starts a casting session previously created by one between the CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer methods, .

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

CastingStreamMixerStart (

ByVal nCastingUniqueId as Integer

)

[C++]

void CastingStreamMixerStart (

short nCastingUniqueId

);

Parameter | Description
nCastingUniqueId | Unique identifier of the casting session returned by a previous call to CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer methods.


CastingStreamMixerStop event

CastingStreamMixerStop event

Remarks

Occurs when a stream mixer, through a call to the the CastingStop method, stops a casting session previously created by one between the CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer methods and started through the CastingStart method.

This event may also occur if the connection with the server should die for external reasons: in this case the error code would be reported inside the nResult parameter.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

CastingStreamMixerStop (

ByVal nCastingUniqueId as Integer,

ByVal nResult as enumErrorCodes

)

[C++]

void CastingStreamMixerStop (

short nCastingUniqueId,

short nResult

);

Parameter | Description
nCastingUniqueId | Unique identifier of the casting session returned by a previous call to CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer methods.
nResult | The result of the operation. See the LastError property for details about the returned result code. In case this parameter should indicate that an error occurred, be sure to close the casting session by calling the CastingStop method.


CastingWasapiLoopbackStart event

CastingWasapiLoopbackStart event

Remarks

Occurs when a WASAPI loopack device, through a call to the the CastingStart method, starts a casting session previously created by one between the CastingCreateFromWasapiLoopback, CastingWmaPubPointOpenFromWasapiLoopback or CastingWmaNetworkOpenFromWasapiLoopback methods.

This event is only intended for usage with Windows Vista and later versions.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

For further details about the use of WASAPI see the WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

CastingWasapiLoopbackStart (

ByVal nCastingUniqueId as Integer

)

[C++]

void CastingWasapiLoopbackStart (

short nCastingUniqueId

);

Parameter | Description
nCastingUniqueId | Unique identifier of the casting session returned by a previous call to CastingCreateFromWasapiLoopback, CastingWmaPubPointOpenFromWasapiLoopback or CastingWmaNetworkOpenFromWasapiLoopback methods.


CastingWasapiLoopbackStop event

CastingWasapiLoopbackStop event

Remarks

Occurs when a WASAPI loopack device, through a call to the the CastingStop method, stops a casting session previously created by one between the CastingCreateFromStreamMixer, CastingWmaPubPointOpenForStreamMixer or CastingWmaNetworkOpenForStreamMixer methods and started through the CastingStart method .

This event may also occur if the connection with the server should die for external reasons: in this case the error code would be reported inside the nResult parameter.

This event is only intended for usage with Windows Vista and later versions.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

For further details about the use of WASAPI see the WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

CastingWasapiLoopbackStop (

ByVal nCastingUniqueId as Integer,

ByVal nResult as enumErrorCodes

)

[C++]

void CastingWasapiLoopbackStop (

short nCastingUniqueId,

short nResult

);

Parameter | Description
nCastingUniqueId | Unique identifier of the casting session returned by a previous call to CastingCreateFromWasapiLoopback, CastingWmaPubPointOpenFromWasapiLoopback or CastingWmaNetworkOpenFromWasapiLoopback methods.
nResult | The result of the operation. See the LastError property for details about the returned result code. In case this parameter should indicate that an error occurred, be sure to close the casting session by calling the CastingStop method.


CdCoverPictureFileAvailableEx event

CdCoverPictureFileAvailableEx event

Remarks

Occurs when a certain CD cover's picture file has been downloaded from the Amazon web site.

See the How to get a CD cover picture tutorial for further details.

Syntax

[Visual Basic]

CdCoverPictureFileAvailableEx (

ByVal nCdDriveIndex as integer,

ByVal nSize as enumCdCoverSizes,

ByVal nResult as enumErrorCodes

)

[C++]

void CdCoverPictureFileAvailableEx (

short nCdDriveIndex,

short nSize,

long nResult

);

Parameters

Description

nCdDriveIndex

Number representing the zero-based index of the CD drive that fired the event. The total number of available CD drives can be obtained using the GetCdDrivesCount method.

nSize

Specifies the size of the picture.

Supported values are the following:

Mnemonic Value | Value | Meaning
CD_COVER_SIZE_SMALL | 0 | Small sized picture
CD_COVER_SIZE_MEDIUM | 1 | Medium sized picture
CD_COVER_SIZE_LARGE | 2 | Large sized picture

nResult

The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.


CdCoverURLsAvailableEx event

CdCoverURLsAvailableEx event

Remarks

Occurs when the Internet URLs of the CD cover's pictures have been obtained from the Amazon Web Service.

See the How to get a CD cover picture tutorial for further details.

Syntax

[Visual Basic]

CdCoverURLsAvailableEx (

ByVal nCdDriveIndex as integer,

ByVal nResult as enumErrorCodes

)

[C++]

void CdCoverURLsAvailableEx (

short nCdDriveIndex,

long nResult

);

Parameters

Description

nCdDriveIndex

Number representing the zero-based index of the CD drive that fired the event. The total number of available CD drives can be obtained using the GetCdDrivesCount method.

nResult

The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.


CddbAlbumInfoAvailable event

CddbAlbumInfoAvailable event

Remarks

Occurs when the CDDB server returns the CD album information requested through a previous call to the CddbRequestAlbumInfo method.

If successful, after receiving this event it will be possible:

· Obtaining the CD album info through the CddbGetAlbumInfo method.
· Getting each CD track title through the CddbGetTrackTitle method.

See the How to get CD album information from a CDDB server tutorial for further details.

Syntax

[Visual Basic]

CddbAlbumInfoAvailable (

ByVal nCdDriveIndex as Integer,

ByVal bSuccess as enumBoolean

)

[C++]

void CddbAlbumInfoAvailable (

short nCdDriveIndex,

long bSuccess

);

Parameter

Description

nCdDriveIndex

Number representing the zero-based index of the CD drive that fired the event.

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

bSuccess

Boolean value that specifies if the CDDB information was retrieved successfully.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
BOOL_FALSE | 0 | The request failed
BOOL_TRUE | 1 | The request succeeded and CDDB information is available


CddbServersListAvailable event

CddbServersListAvailable event

Remarks

Occurs when the list of CDDB servers, requested through a previous call to the CddbRequestServersList method, is available.

The friendly name for each server can be retrieved at a later time using the CddbGetServerName method.

Syntax

[Visual Basic]

CddbServersListAvailable (

ByVal nServersCount as Integer

)

[C++]

void CddbServersListAvailable (

short nServersCount

);

Parameter | Description
nServersCount | The number of CDDB servers found. If this parameter value is 0, this means that an error occurred during the connection to the CDDB site. The friendly name for each server can be retrieved at a later time using the CddbGetServerName method.


CdPlayerStatusChanged event

CdPlayerStatusChanged event

Remarks

If the automatic CD monitoring is enabled, occurs whenever an installed CD drive changes its status: see the EnableCdMonitor method for details about enabling CD drives status monitoring.

Syntax

[Visual Basic]

CdPlayerStatusChanged (

ByVal nCdDriveIndex as Integer,

ByVal nCdStatus as enumCdStates

)

[C++]

void CdPlayerStatusChanged (

short nCdDriveIndex,

long nCdStatus

);

Parameter

Description

nDrive

Number representing the zero-based index of the CD drive that fired the event.

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

nCdStatus

The CD drive status.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
CD_STATUS_OPEN | 0 | The CD drive door is open
CD_STATUS_CLOSED | 1 | The CD drive door is closed but no CD is available inside
CD_STATUS_READY | 2 | The CD drive door is closed and a CD is available inside and ready to play
CD_STATUS_BUSY | 3 | The CD drive door is closed and a CD is available inside but the drive is busy loading an audio track from the CD


CdReadTrackPercentage event

CdReadTrackPercentage event

Remarks

Occurs during a CD track loading session, started through the LoadTrackFromCd method, in order to notify the loading advancement percentage.

Syntax

[Visual Basic]

CdReadTrackPercentage (

ByVal nDrive as Integer,

ByVal nTrack as Integer,

ByVal nPercentage as Integer

)

[C++]

void CdReadTrackPercentage (

short nDrive,

short nTrack,

short nPercentage

);

Parameter | Description
nDrive | Number representing the zero-based index of the CD drive that fired the event. The total number of available CD drives can be obtained using the GetCdDrivesCount method.
nTrack | Number representing the one-based index of the CD audio track that is being loaded.
nPercentage | Number representing the CD track loading advancement percentage.


CdReadTrackStart event

CdReadTrackStart event

Remarks

Occurs at the beginning of a new CD track's loading session started through the LoadTrackFromCd method.

Syntax

[Visual Basic]

CdReadTrackStart (

ByVal nDrive as Integer,

ByVal nTrack as Integer

)

[C++]

void CdReadTrackStart (

short nDrive,

short nTrack

);

Parameter | Description
nDrive | Number representing the zero-based index of the CD drive that fired the event. The total number of available CD drives can be obtained using the GetCdDrivesCount method.
nTrack | Number representing the one-based index of the CD audio track that is being loaded.


CdReadTrackStop event

CdReadTrackStop event

Remarks

Occurs at the end of a CD track's loading session started through the LoadTrackFromCd method.

Syntax

[Visual Basic]

CdReadTrackStop (

ByVal nDrive as Integer,

ByVal nTrack as Integer

)

[C++]

void CdReadTrackStop (

short nDrive,

short nTrack

);

Parameter | Description
nDrive | Number representing the zero-based index of the CD drive that fired the event. The total number of available CD drives can be obtained using the GetCdDrivesCount method.
nTrack | Number representing the one-based index of the CD audio track that is being loaded.


CoreAudioDeviceAdded event

CoreAudioDeviceAdded event

Remarks

Occurs when a new audio endpoint device is added to the system. After catching this event you can get the updated list of available audio endpoint devices by calling again the CoreAudioDevices.Enum method.

This event is only generated in Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

CoreAudioDeviceAdded (

)

[C++]

void CoreAudioDeviceAdded (

);


CoreAudioDeviceDefaultChange event

CoreAudioDeviceDefaultChange event

Remarks

Occurs when the system defined default audio endpoint device changes. The current system default device can be also queried using the CoreAudioDevices.DefaultGet method..

By design this event is only sent to the first instance of the component.

This event is only generated in Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

CoreAudioDeviceDefaultChange (

nDeviceIndex as Integer,

nDataFlow as enumCoreAudioDataFlows,

nRole as enumCoreAudioRoles

)

[C++]

void CoreAudioDeviceDefaultChange (

short nDeviceIndex,

short nDataFlow,

short nRole

);

Parameter

Description

nDeviceIndex

Zero-based index of the audio endpoint which is now the system default for the role set into the nRole parameter. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

This parameter may be set to -1 in case the device should have been unplugged from the system when the previous enumeration occurred, for example because an USB device was installed but not plugged in.

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nRole

The role that the system has assigned to the audio endpoint device that became the new system default.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_ROLE_CONSOLE | 0 | Games, system notification sounds, and voice commands
DEVICE_ROLE_MULTIMEDIA | 1 | Music, movies, narration, and live music recording
DEVICE_ROLE_COMMUNICATIONS | 2 | Voice communications


CoreAudioDeviceRemoved event

CoreAudioDeviceRemoved event

Remarks

Occurs when a new audio endpoint device is removed from the system. After catching this event you can get the updated list of available audio endpoint devices by calling again the CoreAudioDevices.Enum method.

This event is only generated in Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

CoreAudioDeviceRemoved (

)

[C++]

void CoreAudioDeviceRemoved (

);


CoreAudioDeviceStateChange event

CoreAudioDeviceStateChange event

Remarks

Occurs when the state of an audio endpoint device changes. The current status of an audio endpoint device could be also queried using the CoreAudioDevices.StatusGet method..

This event is only generated in Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

CoreAudioDeviceStateChange (

nDeviceIndex as Integer,

nDataFlow as enumCoreAudioDataFlows,

nNewState as enumCoreAudioDeviceStates

)

[C++]

void CoreAudioDeviceStateChange (

short nDeviceIndex,

short nDataFlow,

short nNewState

);

Parameter

Description

nDeviceIndex

Zero-based index of the audio endpoint device which generated the event. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

When this parameter is set to -1 the application is notified about the fact that the status of one of the audio endpoint devices not previously enumerated through the call to the CoreAudioDevices.Enum method (for example a disabled device which become active and ready) has now changed its status so it could be worth calling again the CoreAudioDevices.Enum method in order to update the list of available audio endpoint devices.

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nNewState

New status assumed by the audio endpoint device.

The returned value can be a combination of the following flags:

Mnemonic Value | Value | Meaning
DEVICE_STATE_ACTIVE | 1 | The device is active
DEVICE_STATE_DISABLED | 2 | The device is disabled
DEVICE_STATE_NOTPRESENT | 4 | The device is not present: the audio endpoint device is considered "not present" when the audio adapter has been installed and configured inside the system but it was physically removed at a later time: quite typical situation with devices connected through USB.
DEVICE_STATE_UNPLUGGED | 8 | The device is unplugged: the audio endpoint device is considered "unplugged" when the audio adapter that contains the jack for the endpoint device is present and enabled, but the endpoint device is not plugged into the jack


CoreAudioDeviceVolumeChange event

CoreAudioDeviceVolumeChange event

Remarks

Occurs when the volume level of an audio endpoint device changes. After receiving this event you can query current volume through the CoreAudioDevices.ChannelVolumeGet and CoreAudioDevices.MasterVolumeGet methods.

This event is only generated in Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

CoreAudioDeviceVolumeChange (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer

)

[C++]

void CoreAudioDeviceVolumeChange (

short nDataFlow,

short nDeviceIndex

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device which generated the event. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.


CoreAudioDeviceVuMeterChange event

CoreAudioDeviceVuMeterChange event

Remarks

Occurs when the VU-Meter level of an audio endpoint device changes. After receiving this event you can query current peak values through the CoreAudioDevices.VuMeterMasterPeakValueGet and CoreAudioDevices.VuMeterChannelPeakValueGet methods.

This event is only generated after a specific request to the CoreAudioDevices.VuMeterEnableNotifications method and only in Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

CoreAudioDeviceVuMeterChange (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer

)

[C++]

void CoreAudioDeviceVuMeterChange (

short nDataFlow,

short nDeviceIndex

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device which generated the event. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.


CuePointReached event

CuePointReached event

Remarks

Occurs when an existing cue point is reached during playback.

During playback this event is not generated if the current playback position should be moved, through a call to the SeekSound or ForwardSound methods, to a position exceeding the one of the cue point itself.

See the How to add Triggers and Cue Points to a player section for further details about cue points.

Syntax

[Visual Basic]

CuePointReached (

ByVal nPlayer as Integer,

ByVal strCuePointName as String,

nPosition as Long

)

[C++]

void CuePointReached (

short nPlayer,

LPCTSTR strCuePointName,

long nPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strCuePointName | String containing the unique name of the cue point as defined when the cue point was added through the CuePointsAdd method.
nPosition | Number representing the position, expressed in milliseconds, of the cue point


CuePointsLoaded event

CuePointsLoaded event

Remarks

Occurs when a file containing cue points have been loaded into the player.

Syntax

[Visual Basic]

CuePointsLoaded (

ByVal nPlayer as Integer

)

[C++]

void CuePointsLoaded (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player


DeviceChange event

DeviceChange event

Remarks

Occurs whenever the system default multimedia input/output device (sound card) is changed through the Windows Control Panel's multimedia settings or when a new USB device is plugged or unplugged.

This event is only intended for usage with Windows XP and earlier versions. When dealing with Windows Vista and higher versions it's recommended catching the CoreAudioDeviceAdded, CoreAudioDeviceRemoved, CoreAudioDeviceStateChange and CoreAudioDeviceDefaultChange events.

Syntax

[Visual Basic]

DeviceChange (

)

[C++]

void DeviceChange (

);


DisplayConfigurationChanged event

DisplayConfigurationChanged event

Remarks

Occurs whenever the configuration of the system display is changed, allowing management of full screen configuration.

For details about full screen management refer to the How to render video clips in full screen tutorial.

Syntax

[Visual Basic]

DisplayConfigurationChanged (

)

[C++]

void DisplayConfigurationChanged (

);


DownloaderSessionCompleted event

DownloaderSessionCompleted event

Remarks

Occurs at the end of a successful downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

DownloaderSessionCompleted (

ByVal nDllSessionUniqueId as Long

)

[C++]

void DownloaderSessionCompleted (

long nDllSessionUniqueId

);

Parameter | Description
nDllSessionUniqueId | Unique identifier of the downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.


DownloaderSessionFailed event

DownloaderSessionFailed event

Remarks

Occurs in case of failure of a downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

DownloaderSessionFailed (

ByVal nDllSessionUniqueId as Long,

ByVal nDjErrorCode as enumErrorCodes,

ByVal nWinSdkErrorCode as Long,

ByVal nExceptionCause as Long

)

[C++]

void DownloaderSessionFailed (

long nDllSessionUniqueId,

short nDjErrorCode,

long nWinSdkErrorCode,

long nExceptionCause

);

Parameter

Description

nDllSessionUniqueId

Unique identifier of the downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.

nDjErrorCode

Error code generated by the component

nWinSdkErrorCode

Eventual error code defined inside the Windows SDK.

nExceptionCause

In case the nDjErrorCode parameter should report an error of type ERR_DOWNLOADER_REMOTE_FILE_FAILURE or ERR_DOWNLOADER_LOCAL_FILE_FAILURE, this parameter reports the eventual file exception raised when accessing the remote or the local file.

Possible exception values can be seen on the table below:

Value | Meaning
1 | An unspecified error occurred.
2 | The file could not be located.
3 | All or part of the path is invalid.
4 | The permitted number of open files was exceeded.
5 | The file could not be accessed.
6 | There was an attempt to use an invalid file handle.
7 | The current working directory cannot be removed.
8 | There are no more directory entries.
9 | There was an error trying to set the file pointer.
10 | There was a hardware error.
11 | SHARE.EXE was not loaded, or a shared region was locked.
12 | There was an attempt to lock a region that was already locked.
13 | The disk is full.
14 | The end of file was reached.


DownloaderSessionInvalidFile event

DownloaderSessionInvalidFile event

Remarks

Occurs at the end of a successful downloading session, generated by a previous call to the Downloader.SessionStartToPlayer.method, when the player is unable to load the downloaded media file due to the fact that the format of the file itself is not supported.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

DownloaderSessionInvalidFile (

ByVal nDllSessionUniqueId as Long

)

[C++]

void DownloaderSessionInvalidFile (

long nDllSessionUniqueId

);

Parameter | Description
nDllSessionUniqueId | Unique identifier of the downloading session generated by a previous call to the Downloader.SessionStartToPlayer.method.


DownloaderSessionProgress event

DownloaderSessionProgress event

Remarks

Occurs during a downloading session, generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods, to notify the container application about the current advancement.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

DownloaderSessionProgress (

ByVal nDllSessionUniqueId as Long,

ByVal nProgressPerc as Integer

)

[C++]

void DownloaderSessionProgress (

long nDllSessionUniqueId,

short nProgressPerc

);

Parameter | Description
nDllSessionUniqueId | Unique identifier of the downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.
nProgressPerc | Advancement of the download session expressed in percentage


DownloaderSessionStarted event

DownloaderSessionStarted event

Remarks

Occurs at the beginning of a downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

DownloaderSessionStarted (

ByVal nDllSessionUniqueId as Long

)

[C++]

void DownloaderSessionStarted (

long nDllSessionUniqueId

);

Parameter | Description
nDllSessionUniqueId | Unique identifier of the downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.


DownloaderSessionStopped event

DownloaderSessionStopped event

Remarks

Occurs when a downloading session, generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods, is stopped through the Downloader.SessionStop method.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

DownloaderSessionStopped (

ByVal nDllSessionUniqueId as Long

)

[C++]

void DownloaderSessionStopped (

long nDllSessionUniqueId

);

Parameter | Description
nDllSessionUniqueId | Unique identifier of the downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.


DownloadBuffering event

DownloadBuffering event

Remarks

Occurs when an Internet stream doesn't have enough data for playback and starts buffering new data and also when there are enough buffered data for resuming the stalled playback.

For further details about Internet streams support see the How to play Internet streams section.

Syntax

[Visual Basic]

DownloadBuffering (

ByVal nPlayer as Integer,

ByVal nState as enumEventStreaming

)

[C++]

void DownloadBuffering (

short nPlayer,

long nState

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that fired the event

nState

The buffering status.

Supported values are the following:

Mnemonic value | Value | Meaning
STREAMING_BUFFERING | 0 | The player is stalled and started buffering data from the Internet
STREAMING_PLAYING | 1 | The player has enough data to play and resumed the stalled playback


DownloadComplete event

DownloadComplete event

Remarks

Occurs when an Internet stream (usually a file) has been downloaded completely.

For further details about Internet streams support see the How to play Internet streams section.

Syntax

[Visual Basic]

DownloadComplete (

ByVal nPlayer as Integer

)

[C++]

void DownloadComplete (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


DownloadPercentage event

DownloadPercentage event

Remarks

Occurs during the download of an Internet stream to inform about buffering percentage.

For further details about Internet streams support see the How to play Internet streams section.

Syntax

[Visual Basic]

DownloadPercentage (

ByVal nPlayer as Integer,

ByVal nPercentage as Integer

)

[C++]

void DownloadPercentage (

short nPlayer,

long nState

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nPercentage | Number representing the download percentage.


EqualizerLoaded event

EqualizerLoaded event

Remarks

Occurs when settings of an equalizer file are applied to a sound.

For further details about defining the equalizer settings and about the EDJ format refer to the How to create and use an Equalizer section.

Syntax

[Visual Basic]

EqualizerLoaded (

ByVal nPlayer as Integer

)

[C++]

void EqualizerLoaded (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


ExportToWavPerc event

ExportToWavPerc event

Remarks

Occurs during an exporting session of the loaded sound into a file in WAV format in order to notify the container application about the exporting advancement. The exporting session is started through a previous call to the RequestSoundExportToWav method.

For further details about exporting a sound to a file in WAV format take a look to the How to export the loaded song into a WAV file section.

Syntax

[Visual Basic]

ExportToWavPerc (

ByVal nPlayer as Integer,

ByVal nPercentage as Integer

)

[C++]

void ExportToWavPerc (

short nPlayer,

short nPercentage

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nPercentage | Number representing the percentage of advancement for the current exporting session


ExportToWavStart event

ExportToWavStart event

Remarks

Occurs when the export of the loaded song into a file in WAV format begins. The exporting session is started through a previous call to the RequestSoundExportToWav method.

For further details about exporting a sound to a file in WAV format take a look to the How to export the loaded song into a WAV file section.

Syntax

[Visual Basic]

ExportToWavStart (

ByVal nPlayer as Integer

)

[C++]

void ExportToWavStart (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


ExportToWavStop event

ExportToWavStop event

Remarks

Occurs at the end of an exporting session of the loaded sound into a file in WAV format. The exporting session is started through a previous call to the RequestSoundExportToWav method.

For further details about exporting a sound to a file in WAV format take a look to the How to export the loaded song into a WAV file section.

Syntax

[Visual Basic]

ExportToWavStop (

ByVal nPlayer as Integer,

ByVal nTotalSize as Long

)

[C++]

void ExportToWavStop (

short nPlayer,

long nTotalSize

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that fired the event

nTotalSize

Number representing the total size, expressed in bytes, of the exported WAV file.

In case of an export to a memory file, this value is useful for the container application in order to allocate the buffer that will be passed to the CopyExportedWavToMemory method.

If this parameter's value is 0, an error occurred and the sound was not exported successfully: the cause of the error can be checked through the LastError property.


FadeInCompleted event

FadeInCompleted event

Remarks

Occurs when the fade-in is completed.

This event is also generated at the end of a fade-in session performed after a call to the PlaySound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

For further details about the use of the embedded Automatic Fader, refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

FadeInCompleted (

ByVal nPlayer as Integer

)

[C++]

void FadeInCompleted (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


FadeInStarted event

FadeInStarted event

Remarks

Occurs when the song fading-in starts playing

This event is also generated at the start of a fade-in session performed after a call to the PlaySound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

For further details about the use of the embedded Automatic Fader, refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

FadeInStarted (

ByVal nPlayer as Integer

)

[C++]

void FadeInStarted (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


FadeOutCompleted event

FadeOutCompleted event

Remarks

Occurs when the fade-out is completed.

This event is also generated at the end of a fade-out session performed after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

For further details about the use of the embedded Automatic Fader, refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

FadeOutCompleted (

ByVal nPlayer as Integer

)

[C++]

void FadeOutCompleted (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


FadeOutStarted event

FadeOutStarted event

Remarks

Occurs when the song fading-out starts lowering its volume.

This event is also generated at the start of a fade-out session performed after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

For further details about the use of the embedded Automatic Fader, refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

FadeOutStarted (

ByVal nPlayer as Integer

)

[C++]

void FadeOutStarted (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


FadingPointReached event

FadingPointReached event

Remarks

Occurs when the playback of the song that will fade-out reaches the Fader.FadeStartFromEnd position

For further details about the use of the embedded Automatic Fader, refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

FadingPointReached (

ByVal nPlayer as Integer

)

[C++]

void FadingPointReached (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


FadingVolumeChanged event

FadingVolumeChanged event

Remarks

During a cross-fading, performed by the embedded Automatic Fader, or during a volume sliding operation, performed through call to the StreamVolumeSlide or StreamVolumeSlideEx methods, allows to know in real time the volume of a certain player: this event is generated every 15 milliseconds and not for any single/minimal change of the volume level.

This event is also generated during a fading session performed after a call to the PlaySound method and after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

For further details about the use of the embedded Automatic Fader, refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

FadingVolumeChanged (

ByVal nPlayer as Integer,

ByVal fVolume As single

)

[C++]

void FadingVolumeChanged (

short nPlayer,

float fVolume

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
fVolume | The player's current volume


LrcAdvanceTimeLineFull event

LrcAdvanceTimeLineFull event

Remarks

Occurs when it's time to display, with a certain advance set through the LrcNotifTimingsSet method, a full line of text of the loaded lyrics LRC file.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

LrcAdvanceTimeLineFull (

ByVal nPlayer as Integer,

ByVal nLineIndex as Integer,

ByVal strLine as String,

ByVal nPosition as Long

)

[C++]

void LrcAdvanceTimeLineFull (

short nPlayer,

short nItemIndex,

LPCTSTR strLine,

long nPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nItemIndex | The zero based-index of the Line Time Tag
strLine | String containing the full line of text of the Line Time Tag
nPosition | Position, expressed in milliseconds, within the song of the Line Time Tag


LrcFileAvailable event

LrcFileAvailable event

Remarks

Occurs when a lyrics LRC file is found and loaded.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

LrcFileAvailable (

ByVal nPlayer as Integer,

ByVal bIsEnhanced as enumBoolean

)

[C++]

void LrcFileAvailable (

short nPlayer,

short bIsEnhanced

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that fired the event

bIsEnhanced

Boolean value that specifies if the loaded LRC file is simple or enhanced.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | LRC file is in simple format
BOOL_TRUE | 1 | LRC file is in enhanced format


LrcRealTimeLineFull event

LrcRealTimeLineFull event

Remarks

Occurs when it's time to display in real-time a full line of text of the loaded lyrics LRC file. Timing can be fine tuned through the LrcNotifTimingsSet method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

LrcRealTimeLineFull (

ByVal nPlayer as Integer,

ByVal nLineIndex as Integer,

ByVal strLine as String,

ByVal nPosition as Long

)

[C++]

void LrcRealTimeLineFull (

short nPlayer,

short nItemIndex,

LPCTSTR strLine,

long nPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nItemIndex | The zero based-index of the Line Time Tag
strLine | String containing the full line of text of the Line Time Tag
nPosition | Position, expressed in milliseconds, within the song of the Line Time Tag


LrcRealTimeLinePortion event

LrcRealTimeLinePortion event

Remarks

Occurs when it's time to display in real-time a portion of line of text of the loaded lyrics LRC file in Enhanced format. Timing can be fine tuned through the LrcNotifTimingsSet method.

See the How to manage lyrics coming from LRC files section for further details about LRC files.

Syntax

[Visual Basic]

LrcRealTimeLinePortion (

ByVal nPlayer as Integer,

ByVal nLineIndex as Integer,

ByVal strLine as String,

ByVal nPosition as Long,

ByVal nDuration as Long

)

[C++]

void LrcRealTimeLinePortion (

short nPlayer,

short nItemIndex,

LPCTSTR strLine,

long nPosition,

long nDuration

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nItemIndex | The zero based-index of the Enhanced Time Tag
strLine | String containing the Enhanced Time Tag which is a portion of a Line Time Tag
nPosition | Position, expressed in milliseconds, within the song of the Enhanced Time Tag
nDuration | Duration, expressed in milliseconds, of the Enhanced Time Tag


MetaTagChanged event

MetaTagChanged event

Remarks

Occurs, during an Internet stream playback, when the Shoutcast metadata of the playing stream is changed from the provider.

After catching this event it will be possible retrieving the new strings of metadata through the GetTagString method.

For further details about Internet streams support see the How to play Internet streams section.

Syntax

[Visual Basic]

MetaTagChanged (

ByVal nPlayer as Integer

)

[C++]

void MetaTagChanged (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


MidiKeyboardNotification event

MidiKeyboardNotification event

Remarks

Occurs when one of the keys on the virtual piano keyboard, previously created through the MIDI.KeyboardCreate method, is pressed or released.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

MidiKeyboardNotification (

hWndKeyboard as OLE_HANDLE,

nNote as Integer,

bPressed as enumBoolean,

bSimulated as enumBoolean

)

[C++]

void MidiKeyboardNotification (

OLE_HANDLE hWndKeyboard,

short nNote,

short bPressed,

short bSimulated

);

Parameter

Description

hWndKeyboard

Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method

nNote

Note played through pressure of one of the keys of the virtual piano keyboard. Can be a key number from 0 to 127; 60 means middle C

bPressed

Boolean flag that specifies if the key was pressed or released.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The key was released
BOOL_TRUE | 1 | The key was pressed

bSimulated

Boolean flag that specifies if the key pressure is simulated. When the key pressure is simulated, the key appears pressed on the piano keyboard but no real event is generated on the MIDI stream in playback, allowing to display a note played through an external physical MIDI keyboard attached to one of the MIDI input channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The call to this method will play the requested note on the MIDI stream in playback
BOOL_TRUE | 1 | The call to this method will not play the requested note on the MIDI stream in playback but will display the corresponding key as pressed on the piano keyboard.


MidiMarkerNotification event

MidiMarkerNotification event

Remarks

Occurs when a specific type of MIDI marker, previously enabled for notification, has been found inside the MIDI stream during playback.

Notifications of a specific MIDI marker can be enabled/disabled through the MIDI.MarkersEnableNotifications method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

MidiMarkerNotification (

ByVal nPlayer as Integer,

ByVal nMarkerType as enumMidiMarkerNotifications,

ByVal nTrack as Integer,

ByVal fPositionInMs as Double,

ByVal fPositionInTicks as Double,

ByVal fPositionInPercentage as Double,

ByVal strText as String

)

[C++]

void MidiMarkerNotification (

short nPlayer,

long nMarkerType,

short nTrack,

double fPositionInMs,

double fPositionInTicks,

double fPositionInPercentage,

BSTR strText

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMarkerType

Type of MIDI marker.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_NOTIFICATION_LYRIC | 0 | Lyrics (MIDI meta event 5)
MIDI_NOTIFICATION_TEXT | 1 | Text (MIDI meta event 1)
MIDI_NOTIFICATION_MARKER | 2 | Marker (MIDI meta event 6)
MIDI_NOTIFICATION_CUE | 3 | Cue point (MIDI meta event 7)
MIDI_NOTIFICATION_TIME_SIGNATURE | 4 | Time signature (MIDI meta event 88). The reported text is in the form of "a b", where a is the number of sharps, if positive, or flats, if negative, and b signifies major, if 0, or minor, if 1.
MIDI_NOTIFICATION_KEY_SIGNATURE | 5 | Key signature (MIDI meta event 89). The reported text is in the form of "a/b c d", where a is the numerator, b is the denominator, c is the metronome pulse and d is the number of 32nd notes per MIDI quarter-note.
MIDI_NOTIFICATION_COPYRIGHT | 6 | Copyright notice (MIDI meta event 2).
MIDI_NOTIFICATION_TRACK | 7 | Track name (MIDI meta event 3).
MIDI_NOTIFICATION_INSTRUMENT | 8 | Instrument name (MIDI meta event 4).

nTrack

Number representing the zero-based index of the MIDI track. The total number of available MIDI tracks can be obtained through the MIDI:TrackCountGet method.

fPositionInMs

Position of the marker, expressed in milliseconds, inside the MIDI stream

fPositionInTicks

Position of the marker, expressed in MIDI ticks, inside the MIDI stream

fPositionInPercentage

Position of the marker, expressed in percentage, inside the MIDI stream

strText

String containing the text of the marker


MidiStreamEventNotification event

MidiStreamEventNotification event

Remarks

Occurs when a specific type of MIDI event, previously enabled for notification, has been found inside the MIDI stream during playback.

Notifications of a specific MIDI event can be enabled/disabled through the MIDI.StreamEventsEnableNotifications method.

This event is not generated for MIDI events sent to a VST Instrument.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

MidiStreamEventNotification (

ByVal nPlayer as Integer,

ByVal nMidiEvent as enumMidiStreamEvents,

ByVal nMidiParam1 as Long,

ByVal nMidiParam2 as Long,

ByVal nMidiChannel as Integer,

ByVal fPositionInMs as Double,

ByVal fPositionInTicks as Double,

ByVal fPositionInPercentage as Double

)

[C++]

void MidiStreamEventNotification (

short nPlayer,

long nMidiEvent,

long nMidiParam1,

long nMidiParam2,

short nMidiChannel,

double fPositionInMs,

double fPositionInTicks,

double fPositionInPercentage

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMidiEvent

The type of MIDI event.

Supported values, with related parameters, are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_NOTE | 1 | Presses or releases a key note. nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: velocity; 0 means key released while values from 1 to 127 mean pressure
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument. nMidiParam1: the preset program number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure. nMidiParam1: the pressure level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position. nMidiParam1: the pitch wheel position; can range from 0 to 16383 nMidiParam2: not used
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0). nMidiParam1: the pitch wheel range nMidiParam2: not used
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel. nMidiParam1: if set to 0 melody channels are used, if set to 1 the rhythm channel is used. nMidiParam2: not used
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1). nMidiParam1: fine tuning in cents, can range from 0 to 16383. 0 means a fine tuning of -100, 8192 means normal while 16383 means a fine tuning of +100. nMidiParam2: not used
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2). nMidiParam1: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63. nMidiParam2: not used
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume. nMidiParam1: can range from 0 to 16383 where 0 means silence and 16383 means max volume. nMidiParam2: not used
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0). nMidiParam1: the bank number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1). nMidiParam1: the modulation level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7). nMidiParam1: the volume level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10). nMidiParam1: the pan position from 0 to 128. 0 means left, 64 means middle, 127 means right while 128 sets a random position. nMidiParam2: not used
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11). nMidiParam1: the expression level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64). nMidiParam1: from 0 to 63 the sustain is off while from 64 to 127 the sustain is on. nMidiParam2: not used
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65). nMidiParam1: from 0 to 63 the portamento is off while from 64 to 127 the portamento is on. nMidiParam2: not used
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5). nMidiParam1: the portamento time from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84). nMidiParam1: the key number from 1 to 127; 60 means middle C nMidiParam2: not used
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127) nMidiParam1: 0 means poly while 1 means mono nMidiParam2: not used
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91). nMidiParam1: the reverb level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93). nMidiParam1: the chorus level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h). nMidiParam1: cutoff level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h). nMidiParam1: resonance level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h). nMidiParam1: release time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h). nMidiParam1: attack time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time. nMidiParam1: reverb time in milliseconds. nMidiParam2: not used
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay. nMidiParam1: reverb delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level. nMidiParam1: reverb level; 0 means no reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay. nMidiParam1: chorus delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth. nMidiParam1: chorus depth in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate. nMidiParam1: chorus in 100ths of Hertz. nMidiParam2: not used
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback.. nMidiParam1: the chorus feedback level, can range from 0 to 200. 0 means -100%, 100 means that feedback is off while 200 means +100%. nMidiParam2: not used
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level. nMidiParam1: chorus level; 0 means no chorus, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level. nMidiParam1: chorus reverb level; 0 means no chorus reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: fine tune in cents, can range from 0 to 127. 0 means -100, 64 means normal while 127 means +100.
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63.
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the pan position from 0 to 127. 0 means left, 64 means middle while 127 means right. .
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the reverb level from 0 to 128.
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh) nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the chorus level from 0 to 128.
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: cutoff level from 0 to 127
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: resonance level from 0 to 127
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: level from 0 to 127; 127 means full level.
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67). nMidiParam1: from 0 to 63 the soft pedal is off while from 64 to 127 the soft pedal is on. nMidiParam2: not used
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81). nMidiParam1: tempo in microseconds per quarter note. nMidiParam2: not used
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave. nMidiParam1: tuning change in cents, can range from 0 to 16383. 0 means a tuning of -100, 8192 means normal while 16383 means a tuning of +100. nMidiParam2: note; can range from 0 to 11 where 0 is note C
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth. nMidiParam1: vibrato depth effect in cents (0=none, 128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch. nMidiParam1: pitch effect in semitones (0=-24, 24=none, 48=+24). . nMidiParam2: not used
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff. nMidiParam1: filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600). nMidiParam2: not used
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume. nMidiParam1: volume effect percentage (0=-100, 100=none, 200=+100). nMidiParam2: not used
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5). nMidiParam1: vibrato depth in cents (128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32). nMidiParam1: bank number LSB (0-127). nMidiParam2: not used
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file. nMidiParam1: volume level; 0 means silence, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes. nMidiParam1: amount of transposition in semitones, can range from 0 to 200. 0 means -100, 100 means normal while 200 means +100. nMidiParam2: not used
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used

nMidiParam2

Number representing the first parameter related to the event (see the MIDI events table above for details)

nMidiParam2

Number representing the second parameter related to the event (see the MIDI events table above for details)

nMidiChannel

Number representing the MIDI channel on which the event occurred. The current number of channels can be retrieved through a call to the MIDI.ChannelsGet method.

fPositionInMs

Position of the event, expressed in milliseconds, inside the MIDI stream

fPositionInTicks

Position of the event, expressed in MIDI ticks, inside the MIDI stream

fPositionInPercentage

Position of the event, expressed in percentage, inside the MIDI stream


OutputDeviceChanged event

OutputDeviceChanged event

Remarks

Occurs when the output device (sound card) has been changed through a successful call to the StreamOutputDeviceSet method.

Syntax

[Visual Basic]

OutputDeviceChanged (

ByVal nPlayer as Integer,

ByVal nOutput as Integer

)

[C++]

void OutputDeviceChanged (

short nPlayer,

short nOutput

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nOutput | Number representing the zero-based index of the new output device for the given player


PlayerDisconnected event

PlayerDisconnected event

Remarks

Occurs when the output device connected to a certain player is disconnected from the system: this may happen when using USB devices; with this event you can be informed that the player cannot continue playback on the output device and that a new device should be used.

Syntax

[Visual Basic]

PlayerDisconnected (

ByVal nPlayer as Integer

)

[C++]

void PlayerDisconnected (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


PlayListDone event

PlayListDone event

Remarks

Occurs when a playlist has been performed completely.

Syntax

[Visual Basic]

PlayListDone (

ByVal nPlayer as Integer

)

[C++]

void PlayListDone (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


PlayListLoadDone event

PlayListLoadDone event

Remarks

Occurs when the synchronized loading of a playlist is completed. A synchronized loading is started through a call to the PlayListLoadSync method.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

PlayListLoadDone (

ByVal nPlayer as Integer,

ByVal bSuccess as enumBoolean

)

[C++]

void PlayListLoadDone (

short nPlayer,

short bSuccess

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that fired the event

bSuccess

Boolean value that specifies if the playlist was loaded successfully.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
BOOL_FALSE | 0 | The request failed
BOOL_TRUE | 1 | The request succeeded


PlayListLoadPerc event

PlayListLoadPerc event

Remarks

Occurs during the synchronized loading of a playlist. A synchronized loading is started through a call to the PlayListLoadSync method.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

PlayListLoadPerc (

ByVal nPlayer as Integer,

ByVal nPercentage as Integer

)

[C++]

void PlayListLoadPerc (

short nPlayer,

short nPercentage

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nPercentage | Number representing the percentage of advancement for the loading session


PlayListLoadStart event

PlayListLoadStart event

Remarks

Occurs when the synchronized loading of a playlist starts. A synchronized loading is started through a call to the PlayListLoadSync method.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

PlayListLoadStart (

ByVal nPlayer as Integer

)

[C++]

void PlayListLoadStart (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


PlaylistSoundLoaded event

PlaylistSoundLoaded event

Remarks

Occurs when a song included inside a playlist is loaded in memory from a file.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

PlaylistSoundLoaded (

ByVal nPlayer as Integer,

ByVal nItemIndex as Integer,

ByVal strTag as String

)

[C++]

void PlaylistSoundLoaded (

short nPlayer,

short nItemIndex,

LPCTSTR strTag

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nItemIndex | Number representing the zero-based index of the song in the player playlist; if the song is not inserted into a playlist it's always set to 0
strTag | String containing a custom tag associated to this item. Custom tag strings can be associated to a playlist item through the PlayListAddItemWithTag method.


PlayListSoundLoadFailure event

PlayListSoundLoadFailure event

Remarks

Occurs when the loading of a playlist's song fails.

Syntax

[Visual Basic]

PlayListSoundLoadFailure (

ByVal nPlayer as Integer,

ByVal nItemIndex as Integer

)

[C++]

void PlayListSoundLoadFailure (

short nPlayer,

short nItemIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nItemIndex | Number representing the zero-based index of the song in the player playlist


PlayListStreamLoaded event

PlayListStreamLoaded event

Remarks

Occurs when a playlist Internet stream item has been loaded.

Syntax

[Visual Basic]

PlayListStreamLoaded (

ByVal nPlayer as Integer,

ByVal nItemIndex as Integer

)

[C++]

void PlayListStreamLoaded (

short nPlayer,

short nItemIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nItemIndex | The zero based-index of the loaded item: in case of failure in loading the stream taken from the playlist this parameter would be set to -1


RangeLoopDone event

RangeLoopDone event

Remarks

Occurs when a loop of a sound or video range playback, started through a call to the PlaySoundRangeLoop or the VideoPlayer.PlayRangeWithLoop methods, has been completed.

Syntax

[Visual Basic]

RangeLoopDone (

ByVal nPlayer as Integer,

ByVal nRemainingLoops as Long

)

[C++]

void RangeLoopDone (

short nPlayer,

long nRemainingLoops

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nRemainingLoops | Number representing the amount of loops that must be still performed


ServerClosed event

ServerClosed event

Remarks

Occurs when the Internet connection drops or when the remote stream server closes the streaming channel during the buffering of an Internet stream: this last situation could happen when using a slow dial-up connection (56 Kbits or slower).

For further details about Internet streams support see the How to play Internet streams section.

Syntax

[Visual Basic]

ServerClosed (

ByVal nPlayer as Integer

)

[C++]

void ServerClosed (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


SilenceDetectionStateChange event

SilenceDetectionStateChange event

Remarks

Occurs during playback of a sound stream having realtime silence detection enabled through the SilenceDetectionRealTimeEnable method.

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

SilenceDetectionStateChange (

ByVal nPlayer as Integer,

ByVal bIsSilent as enumBoolean,

ByVal nPositionInMs as Long

)

[C++]

void SilenceDetectionStateChange (

short nPlayer,

short bIsSilent,

long nPositionInMs

);

Parameters

Description

nPlayer

Number representing the zero-based index of the involved player

bIsSilent

Boolean value specifying detection of silent data or of audible data.

Supported values are the following:

Mnemonic constant | Meaning
BOOL_FALSE | Audible sound data has been detected
BOOL_TRUE | Silent sound data has been detected

nPositionInMs

Number representing the position inside the sound stream, expressed in milliseconds, where the silence threshold was crossed.


SilencePositionAvailable event

SilencePositionAvailable event

Remarks

Occurs when the control has completed the detection of silent portions at the start and end of a loaded song.

Silence detection is performed automatically if the SilenceDetectionOnPlayerLoadAutoSet method has been previously called or on-demand after a call to the SilenceDetectionOnPlayerRequest method.

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

SilencePositionAvailable (

ByVal nPlayer as Integer,

ByVal nInitialSilencePos as Long,

ByVal nFinalSilencePos as Long

)

[C++]

void SilencePositionAvailable (

short nPlayer,

long nInitialSilencePos,

long nFinalSilencePos

);

Parameters | Description
nPlayer | Number representing the zero-based index of the involved player
nInitialSilencePos | Number representing the position in milliseconds where the sound level is higher than the initial threshold. If no sound has been detected, due to the threshold level being higher respect to existing sound, this parameter is set to -1.
nFinalSilencePos | Number representing the position in milliseconds where the sound level is lower than the final threshold. If no sound has been detected, due to the threshold level being higher respect to existing sound, this parameter is set to -1.


SoundClosed event

SoundClosed event

Remarks

Occurs when a song is closed and discarded from memory.

Syntax

[Visual Basic]

SoundClosed (

ByVal nPlayer as Integer

)

[C++]

void SoundClosed (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


SoundComposerItemDone event

SoundComposerItemDone event

Remarks

Occurs whenever playback of a sound added to a sound composer session is completed and the item is removed from the sound composer session itself.

When this event is received, the unique identifier becomes automatically invalid and cannot be used for further actions.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

SoundComposerItemDone (

ByVal nPlayer as Integer,

nUniqueId as Long

)

[C++]

void SoundComposerItemDone (

short nPlayer,

long nUniqueId

);

Parameters | Description
nPlayerIndex | Number representing the zero-based index of the player that fired the event
nUniqueId | Unique identifier of the item.


SoundComposerItemStart event

SoundComposerItemStart event

Remarks

Occurs whenever playback of a sound added to a sound composer session is started.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

SoundComposerItemStart (

ByVal nPlayer as Integer,

nUniqueId as Long

)

[C++]

void SoundComposerItemStart (

short nPlayer,

long nUniqueId

);

Parameters | Description
nPlayerIndex | Number representing the zero-based index of the player that fired the event
nUniqueId | Unique identifier of the item.


SoundDone event

SoundDone event

Remarks

Occurs when a song has been performed completely.

Syntax

[Visual Basic]

SoundDone (

ByVal nPlayer as Integer

)

[C++]

void SoundDone (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


SoundDurationChanged event

SoundDurationChanged event

Remarks

Occurs after a successful call to the Effects.PlaybackTempoSet and Effects.PlaybackRateSet methods to notify that the original sound duration has been altered.

Further details about songs mixing can be found inside the How to mix your songs section.

Syntax

[Visual Basic]

SoundDurationChanged (

ByVal nPlayer as Integer,

ByVal nNewDuration as Single

)

[C++]

void SoundDurationChanged (

short nPlayer,

float fNewDuration

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fNewDuration | The updated sound duration expressed in seconds.


SoundLoaded event

SoundLoaded event

Remarks

Occurs when a song is loaded in memory from a file.

Syntax

[Visual Basic]

SoundLoaded (

ByVal nPlayer as Integer,

ByVal nItemIndex as Integer

)

[C++]

void SoundLoaded (

short nPlayer,

short nItemIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nItemIndex | Number representing the zero-based index of the song in the player playlist; if the song is not inserted into a playlist it's always set to 0


SoundLyricsAvailable event

SoundLyricsAvailable event

Remarks

Occurs when a previous request to the SoundLyricsRequest method is completed.

Syntax

[Visual Basic]

SoundLyricsAvailable (

ByVal nPlayer as Integer,

ByVal nResult as enumErrorCodes

)

[C++]

void SoundLyricsAvailable (

short nPlayer,

short nResult

);

Parameters

Description

nPlayer

Number representing the zero-based index of the involved player

nResult

The result of the lyrics search operation. See the LastError property for details about the returned result code.

If the result is enumErrorCodes.ERR_NOERROR, lyrics text can be retrieved through the SoundLyricsGet method.


SoundPaused event

SoundPaused event

Remarks

Occurs when a song is paused.

Syntax

[Visual Basic]

SoundPaused (

ByVal nPlayer as Integer

)

[C++]

void SoundPaused (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


SoundPlaying event

SoundPlaying event

Remarks

Occurs when a song starts playing.

Syntax

[Visual Basic]

SoundPlaying (

ByVal nPlayer as Integer

)

[C++]

void SoundPlaying (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


SoundStopped event

SoundStopped event

Remarks

Occurs when a song is stopped.

Syntax

[Visual Basic]

SoundStopped (

ByVal nPlayer as Integer

)

[C++]

void SoundStopped (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


SoundSyncLoaded event

SoundSyncLoaded event

Remarks

Occurs when a song or video has been loaded in memory from a file after a call to the LoadSoundSync, LoadSoundFromMemorySync, LoadEncryptedSoundSync, LoadEncryptedSoundFromMemorySync or VideoPlayer.LoadSync method.

Syntax

[Visual Basic]

SoundSyncLoaded (

ByVal nPlayer as Integer,

ByVal nResult As enumErrorCodes

)

[C++]

void SoundSyncLoaded (

short nPlayer,

short nResult

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nResult | The result of the loading operation. See the LastError property for details about the returned result code.


SpectrumValueChange event

SpectrumValueChange event

Remarks

Occurs whenever there is a change on the Spectrum peak values: this event, generated every 15 milliseconds, can be useful if you need to implement your own Spectrum graphical representation; after receiving this event, in order to obtain the Spectrum values to render graphically, you need to perform a call to the Spectrum.GetTable method.

This event is fired only if you have previously created the Spectrum object though a call to the Spectrum.Create method.

Syntax

[Visual Basic]

SpectrumValueChange (

ByVal nPlayer as Integer

)

[C++]

void SpectrumValueChange (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


StreamConnecting event

StreamConnecting event

Remarks

Occurs when the player starts the connection to an Internet stream.

For further details about Internet streams support see the How to play Internet streams section.

Syntax

[Visual Basic]

StreamConnecting (

ByVal nPlayer as Integer

)

[C++]

void StreamConnecting (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


StreamLoaded event

StreamLoaded event

Remarks

Occurs when the player has buffered enough data from an Internet stream in order to start playback. In case the Internet stream should have been successfully loaded from a playlist, this event would be fired immediately before the StreamLoadedFromInetPlaylist event.

For further details about Internet streams support see the How to play Internet streams section.

Syntax

[Visual Basic]

StreamLoaded (

ByVal nPlayer as Integer,

ByVal nResult as enumEventLoadStreamResults

)

[C++]

void StreamLoaded (

short nPlayer,

long nState

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that fired the event

nState

The stream loading result.

Supported values are the following:

Mnemonic value | Value | Meaning
STREAM_LOAD_FAIL | 0 | The stream loading failed
STREAM_LOAD_OK | 1 | The stream loading was successful


StreamLoadedFromInetPlaylist event

StreamLoadedFromInetPlaylist event

Remarks

Occurs after the player has tried to load an Internet stream taken from a playlist stored inside a web server.

For further details about Internet streams support see the How to play Internet streams section.

Syntax

[Visual Basic]

StreamLoadedFromInetPlaylist (

ByVal nPlayer as Integer,

ByVal bSuccess as enumBoolean,

ByVal strItemURL as String

)

[C++]

void StreamLoadedFromInetPlaylist (

short nPlayer,

long bSuccess,

LPCTSTR strItemURL

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that fired the event

bSuccess

The stream loading result.

Supported values are the following:

Mnemonic value | Value | Meaning
BOOL_FALSE | 0 | The stream loading failed
BOOL_TRUE | 1 | The stream loading was successful. In this situation also the StreamLoaded event is fired

strItemURL

String containing the URL of the Internet stream


StreamQueueStalled event

StreamQueueStalled event

Remarks

Occurs when a queued stream, created through the StreamQueueCreate method and fed through the StreamQueuePushData method, doesn't have PCM data to play.

Syntax

[Visual Basic]

StreamQueueStalled (

ByVal nPlayer as Integer

)

[C++]

void StreamQueueStalled (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


TriggerReached event

TriggerReached event

Remarks

Occurs when the song playback reaches an existing trigger position.

During playback this event is not generated if the current playback position should be moved, through a call to the SeekSound or ForwardSound methods, to a position exceeding the one of the trigger itself.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

TriggerReached (

ByVal nPlayer as Integer,

ByVal nTriggerID as Integer

)

[C++]

void TriggerReached (

short nPlayer,

short nTriggerID

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nTriggerID | Number representing the trigger identifier


VolumeAutomationLoaded event

VolumeAutomationLoaded event

Remarks

Occurs when a volume automation procedure is loaded from a VDJ file.

The VDJ file could have been loaded manually through the VolumeAutomation.Load method or automatically if a VDJ file having the same filename of the loaded sound should be found inside the same directory: if for example the loaded sound file should be named MySong.mp3, the corresponding searched VDJ file would be named MySong.vdj

For details about using Volume Automation and for a reference about VDJ format refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

VolumeAutomationLoaded (

ByVal nPlayer as Integer

)

[C++]

void VolumeAutomationLoaded (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


VolumeAutomationPointReached event

VolumeAutomationPointReached event

Remarks

Occurs when a volume automation point is reached during playback.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

VolumeAutomationPointReached (

ByVal nPlayer as Integer,

ByVal strVolumePointName as String,

ByVal fPosition as Single

)

[C++]

void VolumeAutomationPointReached (

short nPlayer,

LPCTSTR strVolumePointName,

float fPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strVolumePointName | String containing the friendly name of the volume point as defined when the volume point was added through the VolumeAutomation.PointAdd method.
fPosition | Number representing the position of the volume point expressed in the same unit set into the VolumeAutomation.PositionUnit property


VolumeCurveDesignerChanged event

VolumeCurveDesignerChanged event

Remarks

Occurs when the curve inside a curve designer control is modified by dragging one of the control points through the mouse interaction.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

VolumeCurveDesignerChanged (

ByVal nDesignerUniqueId as Long,

ByVal nLeftX as Integer,

ByVal nLeftY as Integer,

ByVal nRightX as Integer,

ByVal nRightY as Integer

)

[C++]

void VolumeCurveDesignerChanged (

long nDesignerUniqueId,

short nLeftX,

short nLeftY,

short nRightX,

short nRightY

);

Parameter | Description
nDesignerUniqueId | Number representing the unique identifier of the curve designer as created by the VolumeAutomation.CurveDesigner.Create method
nLeftX | Horizontal position, expressed in percentage, of the left side control point of the Bézier curve
nLeftY | Vertical position, expressed in percentage, of the left side control point of the Bézier curve
nRightX | Horizontal position, expressed in percentage, of the right side control point of the Bézier curve
nRightY | Vertical position, expressed in percentage, of the right side control point of the Bézier curve


VolumeSlideCompleted event

VolumeSlideCompleted event

Remarks

Occurs when a volume sliding, started through the StreamVolumeSlide or StreamVolumeSlideEx methods, is completed.

Syntax

[Visual Basic]

VolumeSlideCompleted (

ByVal nPlayer as Integer

)

[C++]

void VolumeSlideCompleted (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


VstEditorResized event

VstEditorResized event

Remarks

Occurs when the editor of the VST effect is resized.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

VstEditorResized (

ByVal nPlayer as Integer,

ByVal nIdVst as Long,

ByVal nWidth as Integer,

ByVal nHeight as Integer

)

[C++]

void VstEditorResized (

short nPlayer,

long nIdVst,

short nWidth,

short nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nIdVst | Unique identifier of the VST effect
nWidth | New width, expressed in pixels, of the VST effect's editor
nHeight | New height, expressed in pixels, of the VST effect's editor


VstParamChangedValue event

VstParamChangedValue event

Remarks

Occurs when a parameter of the VST has been changed through its editor.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

VstParamChangedValue (

ByVal nPlayer as Integer,

ByVal nIdVst as Long,

ByVal nParamIndex as Long,

ByVal fValue as Single

)

[C++]

void VstParamChangedValue (

short nPlayer,

long nIdVst,

long nParamIndex,

float fValue

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nIdVst | Unique identifier of the VST
nParamIndex | Number representing the zero-based index of the changed parameter
fValue | Number representing the new value of the parameter


VUMeterValueChange event

VUMeterValueChange event

Remarks

Occurs whenever there is a change on the VU-Meter peak values: this event, generated every 15 milliseconds, can be useful if you need to implement your own VU-Meter graphical representation.

For regular mono or stereo streams, peak levels are reported inside the nLeftPeak and nRightPeak parameters: in case you should need to retrieve peak levels or RMS (Root-Mean-Square) levels for each of the channels of a multi-channel audio stream, you could use the StreamPeakLevelsGet method.

This event is fired only if you have created the VUMeter object though a call to the VUMeter.Create method.

For further details about synchronization through Events see the How to synchronize the container application through events tutorial.

Syntax

[Visual Basic]

VUMeterValueChange (

ByVal nPlayer as Integer,

ByVal nLeftPeak as Integer,

ByVal nRightPeak as Integer

)

[C++]

void VUMeterValueChange (

short nPlayer,

short nLeftPeak,

short nRightPeak

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nLeftPeak | Number representing the peak value for the left channel: can assume values from 0 (no sound) to 32767 (max volume).
nRightPeak | Number representing the peak value for the right channel: can assume values from 0 (no sound) to 32767 (max volume). If the sound is in Mono, the nLeftPeak and nRightPeak parameters assume the same value.


WarnNoOutputDevice event

WarnNoOutputDevice event

Remarks

Occurs when the multimedia engine detects that no sound card with a valid output device is installed inside the system.

Syntax

[Visual Basic]

WarnNoOutputDevice (

)

[C++]

void WarnNoOutputDevice (

);


WaveAnalysisDone event

WaveAnalysisDone event

Remarks

Occurs when the analysis of a sound's waveform has been completed or aborted. The analysis is started through a previous call to the Waveform.AnalyzeFullSound method.

Syntax

[Visual Basic]

WaveAnalysisDone (

ByVal nPlayer as Integer,

ByVal nTotalPeaksDetected as Long,

ByVal fPeakDurationInMs as Single,

ByVal nMaxPeakLeft as Long,

ByVal nMaxPeakRight as Long

)

[C++]

void WaveAnalysisDone (

short nPlayer,

long nTotalPeaksDetected,

float fPeakDurationInMs,

long nMaxPeakLeft,

long nMaxPeakRight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event.
nTotalPeaksDetected | Number representing the amount of peaks detected during the sound's analysis.
fPeakDurationInMs | Floating point number representing the duration in milliseconds of each detected peak.
nMaxPeakLeft | Level of max peak detected on the left channel; the peak value can be in the range from 0 to 32767
nMaxPeakRight | Level of max peak detected on the right channel; the peak value can be in the range from 0 to 32767


WaveAnalysisPerc event

WaveAnalysisPerc event

Remarks

Occurs during the analysis of a sound's waveform in order to notify the container application about the analysis advancement. The analysis is started through a previous call to the Waveform.AnalyzeFullSound method.

Syntax

[Visual Basic]

WaveAnalysisPerc (

ByVal nPlayer as Integer,

ByVal nPercentage as Integer

)

[C++]

void WaveAnalysisPerc (

short nPlayer,

short nPercentage

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nPercentage | Number representing the percentage of advancement for the current sound analysis


WaveAnalysisStart event

WaveAnalysisStart event

Remarks

Occurs when the analysis of a sound's waveform begins. The analysis is started through a previous call to the Waveform.AnalyzeFullSound method.

Syntax

[Visual Basic]

WaveAnalysisStart (

ByVal nPlayer as Integer

)

[C++]

void WaveAnalysisStart (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event


WaveformValueChange event

WaveformValueChange event

Remarks

Occurs whenever there is a change on the waveform peak values: this event, generated every 15 milliseconds, can be useful if you need to implement your own waveform graphical representation.

For further details about synchronization through Events see the How to synchronize the container application through events tutorial.

Syntax

[Visual Basic]

WaveformValueChange (

ByVal nPlayer as Integer,

ByVal nPeakMin as Integer,

ByVal nPeakMax as Integer

)

[C++]

void WaveformValueChange (

short nPlayer,

short nPeakMin,

short nPeakMax

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event
nPeakMin | Number representing the min peak value: can assume values from 0 (no sound) to 32767 (max volume).
nPeakMax | Number representing the max peak value: can assume values from 0 (no sound) to 32767 (max volume).


WaveScrollerManualScroll event

WaveScrollerManualScroll event

Remarks

Occurs when a manual move is performed through the mouse on the waveform scroller.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

WaveScrollerManualScroll (

ByVal nPlayer as Integer,

ByVal hWndWaveformScroller as OLE_HANDLE,

ByVal nNewPosInMs as Long

)

[C++]

void WaveScrollerManualScroll (

short nPlayer,

OLE_HANDLE hWndWaveformScroller,

long nNewPosInMs

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that fired the event.
hWndWaveformScroller | Handle of the waveform scroller control returned by a previous call to the WaveformScroller.Create method
nNewPosInMs | New sound position expressed in milliseconds after a manual scrolling operation


WaveScrollerMouseNotification event

WaveScrollerMouseNotification event

Remarks

Occurs when a mouse action happens over the waveform scroller.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

WaveScrollerMouseNotification (

ByVal nPlayer as Integer,

ByVal hWndWaveformScroller as OLE_HANDLE,

ByVal nAction as enumMouseActions,

ByVal nFlags as Long,

ByVal xPos as Long,

ByVal yPos as Long,

ByVal nPressPosInPix as Long,

ByVal nPressPosInMs as Long

)

[C++]

void WaveScrollerMouseNotification (

short nPlayer,

OLE_HANDLE hWndWaveformScroller,

long nNewPosInMs,

short nAction,

long nFlags,

long xPos,

long yPos,

long nPressPosInPix,

long nPressPosInMs

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that fired the event.

hWndWaveformScroller

Handle of the waveform scroller control returned by a previous call to the WaveformScroller.Create method

nAction

Mouse action type.

Supported values are the following:

Mnemonic constant | Value | Meaning
MOUSE_ACTION_LEFT_DOWN | 0 | Left mouse button down
MOUSE_ACTION_LEFT_UP | 1 | Left mouse button up
MOUSE_ACTION_LEFT_CLICK | 2 | Left mouse button click
MOUSE_ACTION_LEFT_DBLCLICK | 3 | Left mouse button double click
MOUSE_ACTION_RIGHT_DOWN | 4 | Right mouse button down
MOUSE_ACTION_RIGHT_UP | 5 | Right mouse button up
MOUSE_ACTION_RIGHT_CLICK | 6 | Right mouse button click
MOUSE_ACTION_RIGHT_DBLCLICK | 7 | Right mouse button double click
MOUSE_ACTION_MOVE | 8 | Mouse move

nFlags

Can be a combination of the following values:

Value | Meaning
1 | Set if left mouse button is down (defined as MK_LBUTTON inside the Windows SDK)
2 | Set if right mouse button is down (defined as MK_RBUTTON inside the Windows SDK)
4 | Set if keyboard's SHIFT key is down (defined as MK_SHIFT inside the Windows SDK)
8 | Set if keyboard's CTRL key is down (defined as MK_CONTROL inside the Windows SDK)
16 (hex 10) | Set if middle mouse button is down (defined as MK_MBUTTON inside the Windows SDK)

xPos

Horizontal position, expressed in pixels respect to the waveform's client area, where the mouse generated the notification

yPos

Vertical position, expressed in pixels respect to the waveform's client area, where the mouse generated the notification

nPressPosInPix

Number representing the position expressed in pixels where the mouse button was pressed. If the mouse action should have been performed outside of the waveform's area, this parameter would be set to -1.

It's important to note that this parameter doesn't represent the horizontal position on the waveform's visible area (for this you can refer to the xPos parameter) but to the horizontal position in pixels calculated respect to the bitmap representation of the total waveform's width in pixels at the current horizontal zoom factor.

nPressPosInMs

Number representing the position expressed in milliseconds where the mouse button was pressed. If the mouse action should have been performed outside of the waveform's area, this parameter would be set to -1.


WmaNetworkClientConnect event

WmaNetworkClientConnect event

Remarks

Occurs when a client is connected/disconnected on a WMA network session created through a call to CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.

Further information about management of casting sessions can be found inside the How to use the control as a source for streaming servers like SHOUTcast tutorial.

Syntax

[Visual Basic]

WmaNetworkClientConnect (

ByVal nCastingUniqueId as Integer,

ByVal bConnected as enumBoolean,

ByVal strIP as String

)

[C++]

void WmaNetworkClientConnect (

short nCastingUniqueId,

short bConnected,

LPCTSTR strIP

);

Parameter

Description

nCastingUniqueId

Unique identifier of the WMA network session returned by a previous call to CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.

bConnected

Boolean value that specifies if the client was connected or disconnected.

Supported values are the following:

Mnemonic Value | Value | Meaning
BOOL_FALSE | 0 | The client was disconnected
BOOL_TRUE | 1 | The client was connected

strIP

String representing the IP address of the client


ZipOperationDone event

ZipOperationDone event

Remarks

Occurs at the end of a lengthy ZIP operation started through a previous call to one between the ZIP.EntryAdd, ZIP.EntryAddFromMemory, ZIP.EntryExtractToFile or ZIP.EntryExtractToMemory methods.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

ZipOperationDone (

ByVal nResult as enumErrorCodes

)

[C++]

void ZipOperationDone (

long nResult

);

Parameter

Description

nResult

The result of the append session.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The ZIP operation was completed successfully.


ZipOperationPerc event

ZipOperationPerc event

Remarks

Occurs during a ZIP operation in order to inform about the total advancement percentage.

The ZIP operation could have been started through a previous call to one between the ZIP.EntryAdd, ZIP.EntryAddFromMemory, ZIP.EntryExtractToFile or ZIP.EntryExtractToMemory methods.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

ZipOperationPerc (

ByVal nPercentage as integer

)

[C++]

void ZipOperationPerc (

short nPercentage

);

Parameter | Description
nPercentage | Number representing the percentage of advancement of the ZIP operation


ZipOperationStart event

ZipOperationStart event

Remarks

Occurs at the beginning of a ZIP operation started through a previous call to one between the ZIP.EntryAdd, ZIP.EntryAddFromMemory, ZIP.EntryExtractToFile or ZIP.EntryExtractToMemory methods.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

ZipOperationStart (

)

[C++]

void ZipOperationStart (

);


ASIO object

ASIO object

The ASIO object, accessible through the control's ASIO property, is internally implemented as a COM interface called IASIO and contains methods needed to manage ASIO compatible devices and drivers.

The ASIO object is implemented through the following methods:

AttachInputChannelToPlayer

ControlPanelDisplay

DeviceChannelVolumeGet

DeviceChannelVolumeSet

DeviceGetChannelDesc

DeviceGetChannelsCount

DeviceGetCount

DeviceGetDesc

DeviceGetDriverPathame

DeviceGetIndexFromOutput

DeviceGetOutputIndex

DeviceIsStarted

DeviceLatencyGet

DeviceListenInputStart

DeviceListenInputPause

DeviceListenInputResume

DeviceListenInputPlayerGet

DeviceMasterVolumeGet

DeviceMasterVolumeSet

DeviceMonoToStereoSet

DeviceSampleRateCurrentGet

DeviceSampleRateSupportedCountGet

DeviceSampleRateSupportedGet

DeviceStart

DeviceStop

PlayerOutputChannelGet

PlayerOutputChannelSet

Further information about management of ASIO drivers can be found inside the How to manage ASIO drivers tutorial.

Samples of management of ASIO compatible devices and drivers in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- AsioList

- AsioSpeakersManager

- AsioVideoPlayer

- AsioStreamMixer (requires the installation of Active Sound Suite)


ASIO.AttachInputChannelToPlayer method

ASIO.AttachInputChannelToPlayer method

Remarks

Attaches one or more ASIO input channels of the given ASIO device to the given player allowing to playback incoming sound directly to the output device selected for the given player. Using input channels as playback channels allows to get sound coming from an input channel of the ASIO device, for example the Line-in or the Microphone, and to send it in playback with very low latency.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.AttachInputChannelToPlayer (

nPlayer as Integer,

nDeviceIndex as Integer,

nFirstChannel as Integer,

nTotalChannels as Integer

) as enumErrorCodes

[C++]

short control.ASIO.AttachInputChannelToPlayer (

short nPlayer,

short nDeviceIndex,

short nFirstChannel,

short nTotalChannels

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

nFirstChannel

Number representing the zero-based index of the first ASIO input channel to attach to the player.

nTotalChannels

Total number of ASIO input channels that will be mixed together, starting from the input channel set into the nFirstChannel parameter, and played through the given player.

All ASIO channels are in mono so let's make some example of use:

- if you should need to playback the first pair of input channels, you should specify 0 for the nFirstChannel parameter and 2 for the nTotalChannels parameter.

- if you should need to playback one single ASIO input channel, for example the fourth channel, you should specify 3 (remember that channels are zero-based) for the nFirstChannel parameter and 1 for the nTotalChannels parameter.

- if you should need to mix all of the available ASIO input channels of a sound card having 10 input channels, you should specify 0 for the nFirstChannel parameter and 10 for the nTotalChannels parameter.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.ControlPanelDisplay method

ASIO.ControlPanelDisplay method

Remarks

Opens the control panel for the given ASIO device.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.ControlPanelDisplay (

nDeviceIndex as Integer

) as enumErrorCodes

[C++]

short control.ASIO.ControlPanelDisplay (

short nDeviceIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceChannelVolumeGet method

ASIO.DeviceChannelVolumeGet method

Remarks

Obtains the volume for a specific input or output ASIO channel. This volume can be modified through the ASIO.DeviceChannelVolumeSet method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceChannelVolumeGet (

nDeviceIndex as Integer,

nChannelIndex as Integer,

bInputChannel as enumBoolean,

nScaleType as enumVolumeScales

) as Single

[C++]

float control.ASIO.DeviceChannelVolumeGet (

short nDeviceIndex,

short nChannelIndex,

short bInputChannel,

short nScaleType

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

nChannelIndex

Number representing the zero-based index of the ASIO channel of interest

bInputChannel

Boolean value that specifies if the nChannelIndex parameter is related to an input or output channel.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Output channel
BOOL_TRUE | 1 | Input channel

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Returned volume, expressed in percentage, is based upon a linear scale: - value 0.0 means that channel is muted - values higher than 0.0 and smaller than 100.0 attenuate the channel volume - value 100.0 keeps original sound level unchanged - values higher than 100.0 amplify the sound level
SCALE_LOG | 1 | Returned volume, expressed in dB, is based upon a logarithmic scale: - value -100.0 means that channel is muted - values higher than -100.0 and smaller than 0.0 attenuate the channel volume - value 0.0 keeps original sound level unchanged - values higher than 0.0 amplify the sound level The actual applied formula for converting a linear volume into a logarithmic volume is the following: VolumeInDB = 20 * log10 (VolumeLinear/100) The C syntax for converting a logarithmic volume into a linear volume is the following: VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The current channel volume


ASIO.DeviceChannelVolumeSet method

ASIO.DeviceChannelVolumeSet method

Remarks

Sets the volume for a specific input or output ASIO channel.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceChannelVolumeSet (

nDeviceIndex as Integer,

nChannelIndex as Integer,

bInputChannel as enumBoolean,

fVolume as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.ASIO.DeviceChannelVolumeSet (

short nDeviceIndex,

short nChannelIndex,

short bInputChannel,

float fVolume,

short nScaleType

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

nChannelIndex

Number representing the zero-based index of the ASIO channel of interest

bInputChannel

Boolean value that specifies if the nChannelIndex parameter is related to an input or output channel.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Output channel
BOOL_TRUE | 1 | Input channel

fVolume

New volume expressed in the unit specified by the nScaleType parameter below.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The passed volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceGetChannelDesc method

ASIO.DeviceGetChannelDesc method

Remarks

Retrieves the friendly description of the requested ASIO channel. This method is useful when you have to fill a combo box with the friendly names of available ASIO channels.

The total number of available ASIO channels can be obtained using the ASIO.DeviceGetChannelsCount method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceGetChannelDesc (

nDeviceIndex as Integer,

nChannelIndex as Integer,

bInputChannel as enumBoolean

) as String

[C++]

LPCTSTR control.ASIO.DeviceGetChannelDesc (

short nDeviceIndex,

short nChannelIndex,

short bInputChannel

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

nChannelIndex

Number representing the zero-based index of the ASIO channel of interest

bInputChannel

Boolean value that specifies if the we want to obtain the friendly description of an input or of an output channel.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Output channel
BOOL_TRUE | 1 | Input channel

Return value

Value | Meaning
Empty string | The value of the nDeviceIndex parameter or of the nChannelIndex parameter was out of range. Use the value returned by the ASIO.DeviceGetCount method in order to know how many ASIO devices are currently installed inside the system and the value returned by the ASIO.DeviceGetChannelsCount method in order to know how many ASIO channels are currently available inside the given ASIO device.
Valid string | The string containing the friendly description of the requested output device.


ASIO.DeviceGetChannelsCount method

ASIO.DeviceGetChannelsCount method

Remarks

Obtains the number of output or input channels for the given ASIO device. The friendly name of each channel can be obtained through the ASIO.DeviceGetChannelDesc method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceGetChannelsCount (

nDeviceIndex as Integer,

bInputChannel as enumBoolean

) as Integer

[C++]

short control.ASIO.DeviceGetChannelsCount (

short nDeviceIndex,

short bInputChannel

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

bInputChannel

Boolean value that specifies if the we want to obtain the number of input or of output channel.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Output channels
BOOL_TRUE | 1 | Input channels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The number of available channels


ASIO.DeviceGetCount method

ASIO.DeviceGetCount method

Remarks

Retrieves the number of ASIO devices currently installed inside the system.

The friendly name of each ASIO device can be obtained using the ASIO.DeviceGetDesc method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceGetCount (

) as Integer

[C++]

short control.ASIO.DeviceGetCount (

);

Return value

The number of ASIO devices currently installed inside the system.


ASIO.DeviceGetDesc method

ASIO.DeviceGetDesc method

Remarks

Retrieves the friendly description of the requested ASIO device. This method is useful when you have to fill a combo box with the friendly names of available ASIO devices.

The total number of available ASIO devices can be obtained using the ASIO.DeviceGetCount method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceGetDesc (

nDeviceIndex as Integer

) as String

[C++]

LPCTSTR control.ASIO.DeviceGetDesc (

short nDeviceIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device whose friendly name must be retrieved

Return value

Value | Meaning
Empty string | The value of the nDeviceIndex parameter was out of range. Use the value returned by the ASIO.DeviceGetCount method in order to know how many ASIO devices are currently installed inside the system.
Valid string | The string containing the friendly description of the requested output device.


ASIO.DeviceGetDriverPathname method

ASIO.DeviceGetDriverPathname method

Remarks

Retrieves the absolute pathname of the file containing the ASIO driver of the given ASIO device.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceGetDriverPathname (

nDeviceIndex as Integer

) as String

[C++]

LPCTSTR control.ASIO.DeviceGetDriverPathname (

short nDeviceIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

Return value

Value | Meaning
Empty string | The value of the nDeviceIndex parameter was out of range. Use the value returned by the ASIO.DeviceGetCount method in order to know how many ASIO devices are currently installed inside the system.
Valid string | The string containing the absolute pathname of the ASIO driver


ASIO.DeviceGetIndexFromOutput method

ASIO.DeviceGetIndexFromOutput method

Remarks

Given the zero-index of a generic output device, obtains the zero-based index of the corresponding ASIO device inside the list of available ASIO devices.

The list of generic output devices, which may include both DirectSound and ASIO devices, can be enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods. The list of ASIO devices, which includes ASIO devices only, can be enumerated through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods.

When the InitDriversType method has been called with the nDriverType parameter set to DRIVER_TYPE_ASIO or DRIVER_TYPE_BOTH_ASIO_FIRST, indexes of generic output devices will always match indexes of ASIO devices so the use of this method could be avoided.

When the InitDriversType method has been called with the nDriverType parameter set to DRIVER_TYPE_BOTH_DS_FIRST, DirectSound output devices will be listed first inside the list of available generic output devices so indexes of generic output devices will not match indexes of ASIO devices: in this case this specific method allows matching a generic output device to a specific ASIO device.

If you know the zero-based index of an ASIO device inside the list of available ASIO devices and you need to know its zero-based index inside the list of generic output devices, you can use the ASIO.DeviceGetOutputIndex method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceGetIndexFromOutput (

nOutputIndex as Integer

) as Integer

[C++]

short control.ASIO.DeviceGetIndexFromOutput (

short nOutputIndex

);

Parameter | Description
nOutputIndex | Zero-based index of the output device as enumerated by the combination of the GetOutputDevicesCount and GetOutputDeviceDesc methods.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The zero-based index of the ASIO device inside the list of available ASIO devices


ASIO.DeviceGetOutputIndex method

ASIO.DeviceGetOutputIndex method

Remarks

Given the zero-index of an ASIO device, obtains the zero-based index of the corresponding output device inside the list of available generic output devices.

The list of generic output devices, which may include both DirectSound and ASIO devices, can be enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods. The list of ASIO devices, which includes ASIO devices only, can be enumerated through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods.

When the InitDriversType method has been called with the nDriverType parameter set to DRIVER_TYPE_ASIO or DRIVER_TYPE_BOTH_ASIO_FIRST, indexes of generic output devices will always match indexes of ASIO devices so the use of this method could be avoided.

When the InitDriversType method has been called with the nDriverType parameter set to DRIVER_TYPE_BOTH_DS_FIRST, DirectSound output devices will be listed first inside the list of available generic output devices so indexes of generic output devices will not match indexes of ASIO devices: in this case this specific method allows matching a specific ASIO device to a generic output device.

If you know the zero-based index of an output device inside the list of available generic output devices and you need to know its zero-based index inside the list of ASIO devices, you can use the ASIO.DeviceGetIndexFromOutput method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceGetOutputIndex (

nDeviceIndex as Integer

) as Integer

[C++]

short control.ASIO.DeviceGetOutputIndex (

short nDeviceIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The zero-based index of the ASIO device inside the list of available ASIO devices


ASIO.DeviceIsStarted method

ASIO.DeviceIsStarted method

Remarks

Indicates if the given ASIO device has been started through a previous call to the ASIO.DeviceStart method or through the ASIO.DeviceListenInputStart method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceIsStarted (

nDeviceIndex as Integer

) as Boolean

[C++]

BOOL control.ASIO.DeviceIsStarted (

short nDeviceIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

Return value

Value | Meaning
FALSE | The given device is stopped
TRUE | The given device is started


ASIO.DeviceLatencyGet method

ASIO.DeviceLatencyGet method

Remarks

Obtains the latency, expressed in samples per second, of input or output channels belonging to the given ASIO device.

For input channels the latency is the delay between the sound being recorded and finally reaching the encoder while, for output channels, is the delay between the sample data being extracted from the decoding buffer and currently being heard. The latency is dependant on the buffer size of the ASIO device: the buffer size can be modified through the control panel provided by the driver of the ASIO device itself and accessible through the ASIO.ControlPanelDisplay method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceLatencyGet (

nDeviceIndex as Integer,

bInputChannel as enumBoolean

) as Long

[C++]

long control.ASIO.DeviceLatencyGet (

short nDeviceIndex,

short bInputChannel

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

bInputChannel

Boolean value that specifies if the we want to obtain the latency of input or of output channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Output channels
BOOL_TRUE | 1 | Input channels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 0 | Latency expressed in samples per second


ASIO.DeviceListenInputStart method

ASIO.DeviceListenInputStart method

Remarks

Starts the given ASIO device in order to allow direct playback of audio data incoming from one or more input channels to one or more output channels.

In order to allow the call to this method, the ASIO device must be in stopped state.

A started device can be stopped at any time through the ASIO.DeviceStop method.

You can know if a certain device is started or stopped through the ASIO.DeviceIsStarted method.

In this case direct playback is not performed through the stream mixer described inside the How to manage ASIO drivers tutorial as incoming audio data is rendered to the output channel(s) directly but you can still apply special effects to rendered audio data by obtaining the index of the involved internal player through the ASIO.DeviceListenInputPlayerGet method and by using the returned index with any of the methods of the Effects COM object or with the StreamVolumeLevelSet method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceListenInputStart (

nDeviceIndex as Integer,

nInputChannelFirst as Integer,

nOutputChannelFirst as Integer,

nTotalChannels as Integer

) as enumErrorCodes

[C++]

short control.ASIO.DeviceListenInputStart (

short nDeviceIndex,

short nInputChannelFirst,

short nOutputChannelFirst,

short nTotalChannels

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.
nInputChannelFirst | Zero-based index of the first input channel used for getting incoming audio data.
nOutputChannelFirst | Zero-based index of the first output channel used for direct playback of incoming audio data.
nTotalChannels | Total number of input/output channels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceListenInputPause method

ASIO.DeviceListenInputPause method

Remarks

Pauses direct playback of the given ASIO device previously started through the ASIO.DeviceListenInputStart method. A paused device can be resumed through the ASIO.DeviceListenInputResume method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceListenInputPause (

nDeviceIndex as Integer

) as enumErrorCodes

[C++]

short control.ASIO.DeviceListenInputPause (

short nDeviceIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device previously started through a call to the ASIO.DeviceListenInputStart method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceListenInputPlayerGet method

ASIO.DeviceListenInputPlayerGet method

Remarks

When the given ASIO device has been started through the ASIO.DeviceListenInputStart method, obtains the index of the internal player used for direct playback on one or more output channels of audio data incoming from one or more input channels.

The returned index can be used with any of the methods of the Effects COM object or with the StreamVolumeLevelSet method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceListenInputPlayerGet (

nDeviceIndex as Integer,

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.ASIO.DeviceListenInputPlayerGet (

short nDeviceIndex,

short *nPlayer

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device previously started through a call to the ASIO.DeviceListenInputStart method.
nPlayer | Reference that, on return from the method call, will contain the index of the internal player used for direct playback of incoming audio data.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceListenInputResume method

ASIO.DeviceListenInputResume method

Remarks

Resumes direct playback of the given ASIO device previously started through the ASIO.DeviceListenInputStart method and paused through the ASIO.DeviceListenInputPause method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceListenInputResume (

nDeviceIndex as Integer

) as enumErrorCodes

[C++]

short control.ASIO.DeviceListenInputResume (

short nDeviceIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device previously started through a call to the ASIO.DeviceListenInputStart method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceMasterVolumeGet method

ASIO.DeviceMasterVolumeGet method

Remarks

Obtains the master volume for input or output ASIO channels of a specific ASIO device. This volume can be modified through the ASIO.DeviceMasterVolumeSet method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceMasterVolumeGet (

nDeviceIndex as Integer,

bInputChannel as enumBoolean,

nScaleType as enumVolumeScales

) as Single

[C++]

float control.ASIO.DeviceMasterVolumeGet (

short nDeviceIndex,

short bInputChannel,

short nScaleType

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

bInputChannel

Boolean value that specifies if we need to obtain the master volume for input or output channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Output channels
BOOL_TRUE | 1 | Input channels

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Returned volume, expressed in percentage, is based upon a linear scale: - value 0.0 means that channel is muted - values higher than 0.0 and smaller than 100.0 attenuate the channel volume - value 100.0 keeps original sound level unchanged - values higher than 100.0 amplify the sound level
SCALE_LOG | 1 | Returned volume, expressed in dB, is based upon a logarithmic scale: - value -100.0 means that channel is muted - values higher than -100.0 and smaller than 0.0 attenuate the channel volume - value 0.0 keeps original sound level unchanged - values higher than 0.0 amplify the sound level The actual applied formula for converting a linear volume into a logarithmic volume is the following: VolumeInDB = 20 * log10 (VolumeLinear/100) The C syntax for converting a logarithmic volume into a linear volume is the following: VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The current master volume


ASIO.DeviceMasterVolumeSet method

ASIO.DeviceMasterVolumeSet method

Remarks

Sets the master volume for input or output ASIO channels of a specific ASIO device.

When changing the master volume, original volume level for single channels will be maintained and multiplied by the master volume. If for example you have set the volume level for channel 0 to "50" and the volume level for channel 1 to "75", by applying an amplified master volume of "200" you will obtain that channel 0 will have a volume level of "100" and channel 1 a volume level of "150".

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceMasterVolumeSet (

nDeviceIndex as Integer,

bInputChannel as enumBoolean,

fVolume as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.ASIO.DeviceMasterVolumeSet (

short nDeviceIndex,

short bInputChannel,

float fVolume,

short nScaleType

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

bInputChannel

Boolean value that specifies if we need to modify the master volume for input or output channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Output channel
BOOL_TRUE | 1 | Input channel

fVolume

New volume expressed in the unit specified by the nScaleType parameter below.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Volume, expressed in percentage, is based upon a linear scale: - value 0.0 means that channel is muted - values higher than 0.0 and smaller than 100.0 attenuate the channel volume - value 100.0 keeps original sound level unchanged - values higher than 100.0 amplify the sound level
SCALE_LOG | 1 | Volume, expressed in dB, is based upon a logarithmic scale: - value -100.0 means that channel is muted - values higher than -100.0 and smaller than 0.0 attenuate the channel volume - value 0.0 keeps original sound level unchanged - values higher than 0.0 amplify the sound level The actual applied formula for converting a linear volume into a logarithmic volume is the following: VolumeInDB = 20 * log10 (VolumeLinear/100) The C syntax for converting a logarithmic volume into a linear volume is the following: VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceMonoToStereoSet method

ASIO.DeviceMonoToStereoSet method

Remarks

Tells to the ASIO device to reproduce mono streams as stereo.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceMonoToStereoSet (

nDeviceIndex as Integer,

bMonoToStereo as enumBoolean

) as enumErrorCodes

[C++]

short control.ASIO.DeviceMonoToStereoSet (

short nDeviceIndex,

short bMonoToStereo

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

bMonoToStereo

Boolean value that specifies if we need to modify the master volume for input or output channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Mono streams are reproduced in mono on a single ASIO channel.
BOOL_TRUE | 1 | Mono streams are reproduced in stereo on two ASIO channels. This option should be used ONLY when dealing with mono streams: the quality of the output is not guaranteed in case stereo streams should be played by players attached to this output device.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceSampleRateCurrentGet method

ASIO.DeviceSampleRateCurrentGet method

Remarks

Obtains the sample rate currently selected inside the given ASIO device.

This method can be only used after the ASIO device has been started through the ASIO.DeviceStart method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceSampleRateCurrentGet (

nDeviceIndex as Integer,

nRate as Long

) as enumErrorCodes

[C++]

short control.ASIO.DeviceSampleRateCurrentGet (

short nDeviceIndex,

long *nRate

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.
nRate | Reference that, on return from the method call, will contain the sample rate currently selected inside the given ASIO device.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceSampleRateSupportedCountGet method

ASIO.DeviceSampleRateSupportedCountGet method

Remarks

Obtains the number of sample rates supported by the given ASIO device. Single supported sample rates can be obtained through the ASIO.DeviceSampleRateSupportedGet method.

This method can be only used after the ASIO device has been started through the ASIO.DeviceStart method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceSampleRateSupportedCountGet (

nDeviceIndex as Integer,

nCount as Long

) as enumErrorCodes

[C++]

short control.ASIO.DeviceSampleRateSupportedCountGet (

short nDeviceIndex,

long *nCount

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.
nCount | Reference that, on return from the method call, will contain the number of sample rates supported by the given ASIO device.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceSampleRateSupportedGet method

ASIO.DeviceSampleRateSupportedGet method

Remarks

Obtains a specific sample rate supported by the given ASIO device.

This method can be only used after the ASIO device has been started through the ASIO.DeviceStart method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceSampleRateSupportedGet (

nDeviceIndex as Integer,

nSampleRateIndex as Long,

nRate as Long

) as enumErrorCodes

[C++]

short control.ASIO.DeviceSampleRateSupportedGet (

short nDeviceIndex,

long nSampleRateIndex,

long *nRate

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.
nSampleRateIndex | Number representing the zero-based index of a specific sample rate supported by the given ASIO device. The total number of supported sample rates can be obtained through the ASIO.DeviceSampleRateSupportedCountGet method.
nRate | Reference that, on return from the method call, will contain the requested sample rate supported by the given ASIO device.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceStart method

ASIO.DeviceStart method

Remarks

Starts the given ASIO device.

This call is mandatory in order to start working with a specific ASIO device for playback or for recording purposes; if you simply need to render audio data incoming from one or more input channels directly to one or more output channels, a possible alternative to this method is to invoke the ASIO.DeviceListenInputStart method.

In order to allow the call to this method, the ASIO device must be in stopped state.

A started device can be stopped at any time through the ASIO.DeviceStop method.

You can know if a certain device is started or stopped through the ASIO.DeviceIsStarted method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceStart (

nDeviceIndex as Integer,

nSampleRate as Long,

nChannelMode as enumAsioChannelModes,

nOutputChannelFirst as Integer

) as enumErrorCodes

[C++]

short control.ASIO.DeviceStart (

short nDeviceIndex,

long nSampleRate,

short nChannelMode,

short nOutputChannelFirst

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the ASIO device.

This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

nSampleRate

Sample rate to set into the ASIO device (0=leave current).

nChannelMode

Channel mode.

Supported values are the following:

Mnemonic constant

Value

Meaning

ASIO_CHANNEL_MODE_MULTI

0

Enables multi-channel mode: with this mode, if the loaded sound in in Mono or in Stereo, there is the possibility to perform speakers assignment through the ASIO.PlayerOutputChannelSet method.

If the loaded song is multi-channel, for example a 5.1, each channel will be automatically routed to output channels available inside the ASIO device.

ASIO_CHANNEL_MODE_STEREO

1

Enables stereo mode. This mode is needed when you need to send what is being played through a certain ASIO device to a streaming server (casting session) or when the ASIO device needs to be used for recording purposes through the Active Sound Recorder control.

When using this mode you can set specific channels that will be used for stereo output rendering through the nOutputChannelFirst parameter below.

ASIO_CHANNEL_MODE_MIRROR_STEREO

2

Enables stereo channels mirroring mode. This mode will set the ASIO device in stereo mode and then will mirror the output of channel "0" to other pair channels (2, 4, etc.) and the output of channel "1" to other odd channels (3, 5, etc.)

ASIO_CHANNEL_MODE_MIRROR_MONO

3

Enables mono channel mirroring mode. This mode will set the ASIO device in mono and then will mirror the output of channel "0" to all of the other available output channels of the ASIO device.

nOutputChannelFirst

Zero-based index of the first output channel used for sound rendering: this parameter is only used when the nChannelMode parameter is set to ASIO_CHANNEL_MODE_STEREO and is ignored in all other cases.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.DeviceStop method

ASIO.DeviceStop method

Remarks

Stops the given ASIO device previously started through a call to the ASIO.DeviceStart method or through the ASIO.DeviceListenInputStart method.

You can know if a certain device is started or stopped through the ASIO.DeviceIsStarted method.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.DeviceStop (

nDeviceIndex as Integer

) as enumErrorCodes

[C++]

short control.ASIO.DeviceStop (

short nDeviceIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device. This index is related to available ASIO devices so it must be the related to the enumeration performed through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods: it must not be confused with indexes related to generic output devices enumerated through the GetOutputDevicesCount and GetOutputDeviceDesc methods which may contain both DirectSound and ASIO devices.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ASIO.PlayerOutputChannelGet method

ASIO.PlayerOutputChannelGet method

Remarks

If the given player is attached to an ASIO device, gets its ASIO output channel. The output channel can be modified through the ASIO.PlayerOutputChannelSet method.

If the sound loaded into the given player is in stereo, this method will in any case return only the zero-based index of the first channel.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.PlayerOutputChannelGet (

nPlayer as Integer

) as Integer

[C++]

short control.ASIO.PlayerOutputChannelGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | Zero-based index of the ASIO channel


ASIO.PlayerOutputChannelSet method

ASIO.PlayerOutputChannelSet method

Remarks

If the given player is attached to an ASIO device, sets its ASIO output channel for audio playback.

ASIO channels are always in Mono so, if the sound loaded inside the given player is Stereo, you only need to set the first channel index that will output the left channel of the original Stereo sound and the player will automatically send the right channel of the original Stereo sound to the next available output ASIO channel.

For further details about the use of ASIO drivers see the ASIO object section and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

control.ASIO.PlayerOutputChannelSet (

nPlayer as Integer,

nChannelIndex as Integer

) as enumErrorCodes

[C++]

short control.ASIO.PlayerOutputChannelSet (

short nPlayer,

short nChannelIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nChannelIndex | Number representing the zero-based index of the output ASIO channel

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices object

CoreAudioDevices object

The CoreAudioDevices object, accessible through the control's CoreAudioDevices property, is internally implemented as a COM interface called ICoreAudioDevices and contains methods needed to manage audio devices under Windows Vista and later versions.

The CoreAudioDevices object is implemented through the following methods:

DisplaySoundApplet

Enum

Free

CapturePartChannelCountGet

CapturePartChannelVolumeGet

CapturePartChannelVolumeSet

ChannelCountGet

ChannelVolumeGet

ChannelVolumeSet

CountGet

DefaultGet

DefaultSet

DescGet

JackCountGet

JackDescriptorGet

MasterVolumeGet

MasterVolumeSet

MuteGet

MuteSet

RenderPartChannelCountGet

RenderPartChannelVolumeGet

RenderPartChannelVolumeSet

RenderPartMuteGet

RenderPartMuteSet

StatusGet

TypeGet

VuMeterChannelPeakValueGet

VuMeterEnableNotifications

VuMeterMasterPeakValueGet

Further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Samples of usage of access to audio devices in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- CoreAudioDevices


CoreAudioDevices.DisplaySoundApplet method

CoreAudioDevices.DisplaySoundApplet method

Remarks

Displays the sound applet of the Windows control panel.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.DisplaySoundApplet (

strOptionalParams as String

)

[C++]

void control.CoreAudioDevices.DisplaySoundApplet (

BSTR strOptionalParams

);

Parameter

Description

strOptionalParams

String containing optional command line parameters.

Tabs of the sound applet can be opened by specifying the tab to display through a string having the format ",,x" where "x" indicates the index of the tab to display; tabs are zero-based so, if for example you should need to display the first tab, usually the one containing playback devices, you should use the string ",,0" while for the second tab, usually the one containing recording devices, you should use the string ",,1".

When this string is left empty the first tab of the sound applet should be displayed, exactly as specifying the string ",,0".

Return value

None


CoreAudioDevices.Enum method

CoreAudioDevices.Enum method

Remarks

Enumerates audio endpoint devices installed inside the system.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.Enum (

nStateMask as enumCoreAudioDeviceStates

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.Enum (

short nStateMask

);

Parameter

Description

nStateMask

The states of the devices that are to be included in the collection.

This value can be a combination of the following flags:

Mnemonic Value | Value | Meaning
DEVICE_STATE_ACTIVE | 1 | Include active audio endpoint devices
DEVICE_STATE_DISABLED | 2 | Include disabled audio endpoint devices
DEVICE_STATE_NOTPRESENT | 4 | Include not present audio endpoint devices: the audio endpoint device is considered "not present" when the audio adapter has been installed and configured inside the system but it was phisically removed at a later time: quite typical situation with devices connected through USB.
DEVICE_STATE_UNPLUGGED | 8 | Include unplugged audio endpoint devices: the audio endpoint device is considered "unplugged" when the audio adapter that contains the jack for the endpoint device is present and enabled, but the endpoint device is not plugged into the jack

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.Free method

CoreAudioDevices.Free method

Remarks

Frees the list of audio endpoint devices and related resources.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.Free (

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.Free (

);

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.CapturePartChannelCountGet method

CoreAudioDevices.CapturePartChannelCountGet method

Remarks

Obtains the number of channels of a part embedded inside the given capture audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.CapturePartChannelCountGet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioCaptureParts,

nChannelsCount as Integer

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.CapturePartChannelCountGet (

short nDeviceIndex,

short nPartId,

short *nChannelsCount

);

Parameter

Description

nDeviceIndex

Zero-based index of the capture audio endpoint device. The total number of capture audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method passing DEVICE_DATA_FLOW_CAPTURE to the nDataFlow parameter.

nPartId

Identifier of the capture part.

Supported values are the following:

Mnemonic Value | Value | Meaning
CAPTURE_PART_MIC_BOOST | 0 | Microphone boost.

nChannelsCount

Reference that, on return from the method call, will contain the number of channels of the part. The returned value is 0 if the requested part is unsupported by the capture audio endpoint device.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.CapturePartChannelVolumeGet method

CoreAudioDevices.CapturePartChannelVolumeGet method

Remarks

Obtains the channel's level of a part embedded inside the given capture audio endpoint device. The current level for the same part can be modified through the CoreAudioDevices.CapturePartChannelVolumeSet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.CapturePartChannelVolumeGet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioCaptureParts,

nChannel as Integer,

fLevelIndB as Single,

fRangeMinIndB as Single,

fRangeMaxIndB as Single,

fSteppingIndB as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.CapturePartChannelVolumeGet (

short nDeviceIndex,

short nPartId,

short nChannel,

float *fLevelIndB,

float *fRangeMinIndB,

float *fRangeMaxIndB,

float *fSteppingIndB

);

Parameter

Description

nDeviceIndex

Zero-based index of the capture audio endpoint device. The total number of capture audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method passing DEVICE_DATA_FLOW_CAPTURE to the nDataFlow parameter.

nPartId

Identifier of the capture part.

Supported values are the following:

Mnemonic Value | Value | Meaning
CAPTURE_PART_MIC_BOOST | 0 | Microphone boost.

nChannel

Zero-based index of the channel. The total number of channels can be obtained through the CoreAudioDevices.CapturePartChannelCountGet method.

fLevelIndB

Reference that, on return from the method call, will contain the volume level expressed in dB

fRangeMinIndB

Reference that, on return from the method call, will contain the minimum supported level in dB.

fRangeMaxIndB

Reference that, on return from the method call, will contain the maximum supported level in dB.

fSteppingIndB

Reference that, on return from the method call, will contain the stepping value between consecutive levels in the range fRangeMinIndB to fRangeMaxIndB.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.CapturePartChannelVolumeSet method

CoreAudioDevices.CapturePartChannelVolumeSet method

Remarks

Sets the channel's level of a part embedded inside the given capture audio endpoint device. The current level can be obtained through the CoreAudioDevices.CapturePartChannelVolumeGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.CapturePartChannelVolumeSet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioCaptureParts,

nChannel as Integer,

fLevelIndB as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.CapturePartChannelVolumeSet (

short nDeviceIndex,

short nPartId,

short nChannel,

float fLevelIndB

);

Parameter

Description

nDeviceIndex

Zero-based index of the capture audio endpoint device. The total number of capture audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method passing DEVICE_DATA_FLOW_CAPTURE to the nDataFlow parameter.

nPartId

Identifier of the capture part.

Supported values are the following:

Mnemonic Value | Value | Meaning
CAPTURE_PART_MIC_BOOST | 0 | Microphone boost.

nChannel

Zero-based index of the channel. The total number of channels can be obtained through the CoreAudioDevices.CapturePartChannelCountGet method.

If this parameter is set to -1 the volume level is applied to all of the available channels.

fLevelIndB

The new level, expressed in dB, of the Microphone Boost setting.

The range of acceptable values to apply can be determined by checking the fRangeMinIndB and fRangeMaxIndB parameters of the CoreAudioDevices.MicBoostChannelLevelGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.ChannelCountGet method

CoreAudioDevices.ChannelCountGet method

Remarks

After having enumerated the list of available audio endpoint devices through the CoreAudioDevices.Enum method, obtains the number of channels for a specific audio endpoint device having a specific data flow (playback or recording).

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.ChannelCountGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nChannelsCount as Integer

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.ChannelCountGet (

short nDataFlow,

short nDeviceIndex,

short *nChannelsCount

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nChannelsCount

Reference that, on return from the method call, will contain the number of channels for the given audio endpoint device.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.ChannelVolumeGet method

CoreAudioDevices.ChannelVolumeGet method

Remarks

Obtains the volume of a channel of the given audio endpoint device. The current channel volume can be modified through the CoreAudioDevices.ChannelVolumeSet method.

You can be notified in real-time about volume changes by catching the CoreAudioDeviceVolumeChange event.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.ChannelVolumeGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nChannelIndex as Integer,

nScaleType as enumVolumeScales,

fVolumeLevel as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.ChannelVolumeGet (

short nDataFlow,

short nDeviceIndex,

short nChannelIndex,

short nScaleType,

float *fVolumeLevel

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nChannelIndex

Zero-based index of the channel. The total number of channels for an audio endpoint device can be obtained through the CoreAudioDevices.ChannelCountGet method.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)
SCALE_LOG | 1 | The passed volume, expressed in dB, is based upon a logarithmic scale.

IMPORTANT NOTE ABOUT UNITS OF MEASURE:When dealing with values expressed in percentage the effective value can have different meaning depending upon the implementation of the sound card driver: for example, usually a percentage value of 100 is assumed as 0 dB: this is not the case when dealing with Core Audio API because, if the sound card driver allows applying a volume range from -100 dB (total silence) to +20 dB (sound amplification of +20 dB), a percentage value of 100 would mean that the applied volume is +20 dB. The range of volume values accepted by the sound card driver can be obtained by calling the CoreAudioDevices.MasterVolumeGet method.

IMPORTANT NOTE ABOUT CONVERSION BETWEEN UNITS OF MEASURE: When setting a volume expressed in percentage through one of our component's methods, the value displayed inside the "Sound" applet of the Control Panel may report a value slightly different respect to the one effectively set: this issue is due to a rounding problem when converting from percentage to dB (all values are stored in dB inside the driver); if this should be a problem for you, in order to avoid this minor issue you should always use dB as unit of measure when calling our component's methods and to set the "Sound" applet of the Control Panel to display values in dB instead of the percentage default.

fVolumeLevel

Reference that, on return from the method call, will contain the channel's volume level (the meaning of the returned value depends upon the nScaleType parameter).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.ChannelVolumeSet method

CoreAudioDevices.ChannelVolumeSet method

Remarks

Sets the volume of a channel of the given audio endpoint device. The current channel volume can be obtained through the CoreAudioDevices.ChannelVolumeGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.ChannelVolumeSet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nChannelIndex as Integer,

nScaleType as enumVolumeScales,

fVolumeLevel as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.ChannelVolumeSet (

short nDataFlow,

short nDeviceIndex,

short nChannelIndex,

short nScaleType,

float fVolumeLevel

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nChannelIndex

Zero-based index of the channel. The total number of channels for an audio endpoint device can be obtained through the CoreAudioDevices.ChannelCountGet method.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)
SCALE_LOG | 1 | The passed volume, expressed in dB, is based upon a logarithmic scale.

IMPORTANT NOTE ABOUT UNITS OF MEASURE:When dealing with values expressed in percentage the effective value can have different meaning depending upon the implementation of the sound card driver: for example, usually a percentage value of 100 is assumed as 0 dB: this is not the case when dealing with Core Audio API because, if the sound card driver allows applying a volume range from -100 dB (total silence) to +20 dB (sound amplification of +20 dB), a percentage value of 100 would mean that the applied volume is +20 dB. The range of volume values accepted by the sound card driver can be obtained by calling the CoreAudioDevices.MasterVolumeGet method.

IMPORTANT NOTE ABOUT CONVERSION BETWEEN UNITS OF MEASURE: When setting a volume expressed in percentage through one of our component's methods, the value displayed inside the "Sound" applet of the Control Panel may report a value slightly different respect to the one effectively set: this issue is due to a rounding problem when converting from percentage to dB (all values are stored in dB inside the driver); if this should be a problem for you, in order to avoid this minor issue you should always use dB as unit of measure when calling our component's methods and to set the "Sound" applet of the Control Panel to display values in dB instead of the percentage default.

fVolumeLevel

Number representing the new volume (the meaning of the passed value depends upon the nScaleType parameter).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.CountGet method

CoreAudioDevices.CountGet method

Remarks

After having enumerated the list of available audio endpoint devices through the CoreAudioDevices.Enum method, obtains the number of enumerated audio endpoint devices for a specific data flow (playback or recording).

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.CountGet (

nDataFlow as enumCoreAudioDataFlows,

nDevicesCount as Integer

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.CountGet (

short nDataFlow,

short *nDevicesCount

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDevicesCount

Reference that, on return from the method call, will contain the number of audio endpoint devices for the given type of data flow.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.DefaultGet method

CoreAudioDevices.DefaultGet method

Remarks

Obtains the system default device for the given role. The container application can be notified about changes to the system default device by catching the CoreAudioDeviceDefaultChange event.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.DefaultGet (

nDataFlow as enumCoreAudioDataFlows,

nRole as enumCoreAudioRoles,

nDeviceIndex as Integer

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.DefaultGet (

short nDataFlow,

short nRole,

short *nDeviceIndex

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nRole

The role that the system has assigned to an audio endpoint device.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_ROLE_CONSOLE | 0 | Games, system notification sounds, and voice commands
DEVICE_ROLE_MULTIMEDIA | 1 | Music, movies, narration, and live music recording
DEVICE_ROLE_COMMUNICATIONS | 2 | Voice communications

nDeviceIndex

Reference that, on return from the method call, will contain the zero-based index of the default audio endpoint device for the given type of data flow and role.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.DefaultSet method

CoreAudioDevices.DefaultSet method

Remarks

Sets the system default device for the given role.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.DefaultSet (

nDataFlow as enumCoreAudioDataFlows,

nRole as enumCoreAudioRoles,

nDeviceIndex as Integer

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.DefaultSet (

short nDataFlow,

short nRole,

short nDeviceIndex

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nRole

The role that the system has assigned to an audio endpoint device.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_ROLE_CONSOLE | 0 | Games, system notification sounds, and voice commands
DEVICE_ROLE_MULTIMEDIA | 1 | Music, movies, narration, and live music recording
DEVICE_ROLE_COMMUNICATIONS | 2 | Voice communications

nDeviceIndex

The zero-based index of the audio endpoint device to set as system default.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.DescGet method

CoreAudioDevices.DescGet method

Remarks

Obtains the friendly name of the audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.DescGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nTypeOfName as enumCoreAudioDeviceNames

) as String

[C++]

LPCSTSTR control.CoreAudioDevices.DescGet (

short nDataFlow,

short nDeviceIndex,

short nTypeOfName

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nTypeOfName

Type of friendly name that we need to obtain.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_NAME_COMPOSITE | 0 | The friendly name of the endpoint device, for example "Speakers (XYZ Audio Adapter)"
DEVICE_NAME_DESCRIPTION | 1 | The device description of the endpoint device, for example "Speakers"
DEVICE_NAME_SOUND_CARD | 2 | The friendly name of the audio adapter to which the endpoint device is attached, for example "XYZ Audio Adapter"

Return value

Value | Meaning
Empty string | An error occurred or information not available, check the LastError property value in order to get the error code
Valid string | The requested friendly name


CoreAudioDevices.JackCountGet method

CoreAudioDevices.JackCountGet method

Remarks

Obtains the number of jacks on the connector, required to connect to an audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.JackCountGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nJacksCount as Integer

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.JackCountGet (

short nDataFlow,

short nDeviceIndex,

short *nJacksCount

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nJacksCount

Reference that, on return from the method call, will contain the number of jacks associated with the connector of the selected device.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.JackDescriptorGet method

CoreAudioDevices.JackDescriptorGet method

Remarks

Obtains the description of an audio jack on the connector.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.JackDescriptorGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nJackIndex as Integer,

desc as Long

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.JackDescriptorGet (

short nDataFlow,

short nDeviceIndex,

short nJackIndex,

long desc

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nJackIndex

Zero-based index of the jack. The total number of jacks for an audio endpoint device can be obtained through the CoreAudioDevices.JackCountGet method.

desc

Address of a structure of type KSJACK_DESCRIPTION that receives in output the descriptor of the jack; you can refer to the MSDN (Microsoft Developers Network) website for further information about this structure.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.MasterVolumeGet method

CoreAudioDevices.MasterVolumeGet method

Remarks

Obtains the master volume of the given audio endpoint device. The current master volume can be modified through the CoreAudioDevices.MasterVolumeSet method.

You can be notified in real-time about volume changes by catching the CoreAudioDeviceVolumeChange event.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.MasterVolumeGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nScaleType as enumVolumeScales,

fVolumeLevel as Single,

fLevelMinIndB as Single,

fLevelMaxIndB as Single,

fVolumeIncrementIndB as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.MasterVolumeGet (

short nDataFlow,

short nDeviceIndex,

short nScaleType,

float *fVolumeLevel,

float *fLevelMinIndB,

float *fLevelMaxIndB,

float *fVolumeIncrementIndB

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)
SCALE_LOG | 1 | The passed volume, expressed in dB, is based upon a logarithmic scale.

IMPORTANT NOTE ABOUT UNITS OF MEASURE:When dealing with values expressed in percentage the effective value can have different meaning depending upon the implementation of the sound card driver: for example, usually a percentage value of 100 is assumed as 0 dB: this is not the case when dealing with Core Audio API because, if the sound card driver allows applying a volume range from -100 dB (total silence) to +20 dB (sound amplification of +20 dB), a percentage value of 100 would mean that the applied volume is +20 dB. The range of volume values accepted by the sound card driver can be obtained by calling the CoreAudioDevices.MasterVolumeGet method.

IMPORTANT NOTE ABOUT CONVERSION BETWEEN UNITS OF MEASURE: When setting a volume expressed in percentage through one of our component's methods, the value displayed inside the "Sound" applet of the Control Panel may report a value slightly different respect to the one effectively set: this issue is due to a rounding problem when converting from percentage to dB (all values are stored in dB inside the driver); if this should be a problem for you, in order to avoid this minor issue you should always use dB as unit of measure when calling our component's methods and to set the "Sound" applet of the Control Panel to display values in dB instead of the percentage default.

fVolumeLevel

Reference that, on return from the method call, will contain the master's volume level (the meaning of the returned value depends upon the nScaleType parameter).

fLevelMinIndB

Reference that, on return from the method call, will contain the minimum volume level, expressed in dB, supported by the audio endpoint device.

fLevelMaxIndB

Reference that, on return from the method call, will contain the maximum volume level, expressed in dB, supported by the audio endpoint device.

fVolumeIncrementIndB

Reference that, on return from the method call, will contain the volume increment, expressed in dB, supported by the audio endpoint device.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.MasterVolumeSet method

CoreAudioDevices.MasterVolumeSet method

Remarks

Sets the master volume of the given audio endpoint device. The current master volume can be obtained through the CoreAudioDevices.MasterVolumeGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.MasterVolumeSet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nScaleType as enumVolumeScales,

fVolumeLevel as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.MasterVolumeSet (

short nDataFlow,

short nDeviceIndex,

short nScaleType,

float fVolumeLevel

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)
SCALE_LOG | 1 | The passed volume, expressed in dB, is based upon a logarithmic scale.

IMPORTANT NOTE ABOUT UNITS OF MEASURE:When dealing with values expressed in percentage the effective value can have different meaning depending upon the implementation of the sound card driver: for example, usually a percentage value of 100 is assumed as 0 dB: this is not the case when dealing with Core Audio API because, if the sound card driver allows applying a volume range from -100 dB (total silence) to +20 dB (sound amplification of +20 dB), a percentage value of 100 would mean that the applied volume is +20 dB. The range of volume values accepted by the sound card driver can be obtained by calling the CoreAudioDevices.MasterVolumeGet method.

IMPORTANT NOTE ABOUT CONVERSION BETWEEN UNITS OF MEASURE: When setting a volume expressed in percentage through one of our component's methods, the value displayed inside the "Sound" applet of the Control Panel may report a value slightly different respect to the one effectively set: this issue is due to a rounding problem when converting from percentage to dB (all values are stored in dB inside the driver); if this should be a problem for you, in order to avoid this minor issue you should always use dB as unit of measure when calling our component's methods and to set the "Sound" applet of the Control Panel to display values in dB instead of the percentage default.

fVolumeLevel

Number representing the new master's volume level (the meaning of this value depends upon the nScaleType parameter).

The range of acceptable values, expressed in dB, to apply can be determined by checking the fLevelMinIndB and fLevelMaxIndB parameters of the CoreAudioDevices.MasterVolumeGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.MuteGet method

CoreAudioDevices.MuteGet method

Remarks

Obtains the muting state of the audio stream that enters or leaves the given audio endpoint device. The muting state can be modified through the CoreAudioDevices.MuteSet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.MuteGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

bMute as enumBoolean

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.MuteGet (

short nDataFlow,

short nDeviceIndex,

short *bMute

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

bMute

Reference that, on return from the method call, will contain the muting state.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The audio stream is not muted
BOOL_TRUE | 1 | The audio stream is muted

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.MuteSet method

CoreAudioDevices.MuteSet method

Remarks

Applies the muting state of the audio stream that enters or leaves the given audio endpoint device. The current muting state can be obtained through the CoreAudioDevices.MuteGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.MuteSet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

bMute as enumBoolean

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.MuteSet (

short nDataFlow,

short nDeviceIndex,

short bMute

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

bMute

The new muting state to apply.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The audio stream is not muted
BOOL_TRUE | 1 | The audio stream is muted

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.RenderPartChannelCountGet method

CoreAudioDevices.RenderPartChannelCountGet method

Remarks

Obtains the number of channels of a part embedded inside the given render audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.RenderPartChannelCountGet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioRenderParts,

nChannelsCount as Integer

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.RenderPartChannelCountGet (

short nDeviceIndex,

short nPartId,

short *nChannelsCount

);

Parameter

Description

nDeviceIndex

Zero-based index of the render audio endpoint device. The total number of render audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method passing DEVICE_DATA_FLOW_RENDER to the nDataFlow parameter.

nPartId

Identifier of the render part.

Supported values are the following:

Mnemonic Value | Value | Meaning
RENDER_PART_CD_AUDIO | 0 | CD Audio
RENDER_PART_MIC | 1 | Microphone
RENDER_PART_LINEIN | 2 | Line In

nChannelsCount

Reference that, on return from the method call, will contain the number of channels of the part. The returned value is 0 if the requested part is unsupported by the render audio endpoint device.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.RenderPartChannelVolumeGet method

CoreAudioDevices.RenderPartChannelVolumeGet method

Remarks

Obtains the channel's level of a part embedded inside the given render audio endpoint device. The current level for the same part can be modified through the CoreAudioDevices.RenderPartChannelVolumeSet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.RenderPartChannelVolumeGet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioRenderParts,

nChannel as Integer,

fLevelIndB as Single,

fRangeMinIndB as Single,

fRangeMaxIndB as Single,

fSteppingIndB as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.RenderPartChannelVolumeGet (

short nDeviceIndex,

short nPartId,

short nChannel,

float *fLevelIndB,

float *fRangeMinIndB,

float *fRangeMaxIndB,

float *fSteppingIndB

);

Parameter

Description

nDeviceIndex

Zero-based index of the render audio endpoint device. The total number of render audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method passing DEVICE_DATA_FLOW_RENDER to the nDataFlow parameter.

nPartId

Identifier of the render part.

Supported values are the following:

Mnemonic Value | Value | Meaning
RENDER_PART_CD_AUDIO | 0 | CD Audio
RENDER_PART_MIC | 1 | Microphone
RENDER_PART_LINEIN | 2 | Line In

nChannel

Zero-based index of the channel. The total number of channels can be obtained through the CoreAudioDevices.RenderPartChannelCountGet method.

fLevelIndB

Reference that, on return from the method call, will contain the volume level expressed in dB

fRangeMinIndB

Reference that, on return from the method call, will contain the minimum supported level in dB.

fRangeMaxIndB

Reference that, on return from the method call, will contain the maximum supported level in dB.

fSteppingIndB

Reference that, on return from the method call, will contain the stepping value between consecutive levels in the range fRangeMinIndB to fRangeMaxIndB.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.RenderPartChannelVolumeSet method

CoreAudioDevices.RenderPartChannelVolumeSet method

Remarks

Sets the channel's level of a part embedded inside the given render audio endpoint device. The current level can be obtained through the CoreAudioDevices.RenderPartChannelVolumeGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.RenderPartChannelVolumeSet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioRenderParts,

nChannel as Integer,

fLevelIndB as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.RenderPartChannelVolumeSet (

short nDeviceIndex,

short nPartId,

short nChannel,

float fLevelIndB

);

Parameter

Description

nDeviceIndex

Zero-based index of the render audio endpoint device. The total number of render audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method passing DEVICE_DATA_FLOW_RENDER to the nDataFlow parameter.

nPartId

Identifier of the render part.

Supported values are the following:

Mnemonic Value | Value | Meaning
RENDER_PART_CD_AUDIO | 0 | CD Audio
RENDER_PART_MIC | 1 | Microphone
RENDER_PART_LINEIN | 2 | Line In

nChannel

Zero-based index of the channel. The total number of channels can be obtained through the CoreAudioDevices.RenderPartChannelCountGet method.

If this parameter is set to -1 the volume level is applied to all of the available channels.

fLevelIndB

The new level, expressed in dB, of the Microphone Boost setting.

The range of acceptable values to apply can be determined by checking the fRangeMinIndB and fRangeMaxIndB parameters of the CoreAudioDevices.MicBoostChannelLevelGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.RenderPartMuteGet method

CoreAudioDevices.RenderPartMuteGet method

Remarks

Obtains the muting state of the stream leaving the render part of the given audio endpoint device. The muting state can be modified through the CoreAudioDevices.RenderPartMuteSe t method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.RenderPartMuteGet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioRenderParts,

bMute as enumBoolean

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.RenderPartMuteGet (

short nDeviceIndex,

short nPartId,

short *bMute

);

Parameter

Description

nDeviceIndex

Zero-based index of the render audio endpoint device. The total number of render audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method passing DEVICE_DATA_FLOW_RENDER to the nDataFlow parameter.

nPartId

Identifier of the render part.

Supported values are the following:

Mnemonic Value | Value | Meaning
RENDER_PART_CD_AUDIO | 0 | CD Audio
RENDER_PART_MIC | 1 | Microphone
RENDER_PART_LINEIN | 2 | Line In

bMute

Reference that, on return from the method call, will contain the muting state.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The audio stream is not muted
BOOL_TRUE | 1 | The audio stream is muted

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.RenderPartMuteSet method

CoreAudioDevices.RenderPartMuteSet method

Remarks

Applies the muting state of the stream leaving the render part of the given audio endpoint device. The current muting state can be obtained through the CoreAudioDevices.RenderPartMuteGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.RenderPartMuteSet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioRenderParts,

bMute as enumBoolean

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.RenderPartMuteSet (

short nDeviceIndex,

short nPartId,

short bMute

);

Parameter

Description

nDeviceIndex

Zero-based index of the render audio endpoint device. The total number of render audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method passing DEVICE_DATA_FLOW_RENDER to the nDataFlow parameter.

nPartId

Identifier of the render part.

Supported values are the following:

Mnemonic Value | Value | Meaning
RENDER_PART_CD_AUDIO | 0 | CD Audio
RENDER_PART_MIC | 1 | Microphone
RENDER_PART_LINEIN | 2 | Line In

bMute

The new muting state to apply.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The audio stream is not muted
BOOL_TRUE | 1 | The audio stream is muted

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.StatusGet method

CoreAudioDevices.StatusGet method

Remarks

Obtains the status of the given audio endpoint device.

The container application can be informed in real time about changes of the device status by catching the CoreAudioDeviceStateChange event.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.StatusGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nStatus as enumCoreAudioDeviceStates

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.StatusGet (

short nDataFlow,

short nDeviceIndex,

short *nStatus

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nStatus

Reference that, on return from the method call, will contain the status of the given audio endpoint device.

The returned value can be a combination of the following flags:

Mnemonic Value | Value | Meaning
DEVICE_STATE_ACTIVE | 1 | The device is active
DEVICE_STATE_DISABLED | 2 | The device is disabled
DEVICE_STATE_NOTPRESENT | 4 | The device is not present: the audio endpoint device is considered "not present" when the audio adapter has been installed and configured inside the system but it was physically removed at a later time: quite typical situation with devices connected through USB.
DEVICE_STATE_UNPLUGGED | 8 | The device is unplugged: the audio endpoint device is considered "unplugged" when the audio adapter that contains the jack for the endpoint device is present and enabled, but the endpoint device is not plugged into the jack

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.TypeGet method

CoreAudioDevices.TypeGet method

Remarks

Obtains the type of a specific audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.TypeGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nDeviceType as enumCoreAudioDeviceTypes

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.TypeGet (

short nDataFlow,

short nDeviceIndex,

long *nDeviceType

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nDeviceType

Reference that, on return from the method call, will contain the type of the given device.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_TYPE_NETWORK_DEVICE | 0 | An audio endpoint device that the user accesses remotely through a network.
DEVICE_TYPE_SPEAKERS | 1 | A set of speakers.
DEVICE_TYPE_LINE_LEVEL | 2 | An audio endpoint device that sends a line-level analog signal to a line-input jack on an audio adapter or that receives a line-level analog signal from a line-output jack on the adapter.
DEVICE_TYPE_HEADPHONES | 3 | A set of headphones.
DEVICE_TYPE_MICROPHONE | 4 | A microphone.
DEVICE_TYPE_HEADSET | 5 | An earphone or a pair of earphones with an attached mouthpiece for two-way communication.
DEVICE_TYPE_HANDSET | 6 | The part of a telephone that is held in the hand and that contains a speaker and a microphone for two-way communication.
DEVICE_TYPE_DIGITAL_PASSTHROUGH | 7 | An audio endpoint device that connects to an audio adapter through a connector for a digital interface of unknown type that transmits non-PCM data in digital pass-through mode.
DEVICE_TYPE_SPDIF | 8 | An audio endpoint device that connects to an audio adapter through a Sony/Philips Digital Interface (S/PDIF) connector.
DEVICE_TYPE_HDMI | 9 | An audio endpoint device that connects to an audio adapter through a High-Definition Multimedia Interface (HDMI) connector or a display port.
DEVICE_TYPE_UNKNOWN | 10 | An audio endpoint device with unknown physical attributes.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.VuMeterChannelPeakValueGet method

CoreAudioDevices.VuMeterChannelPeakValueGet method

Remarks

Obtains the VU-Meter's peak value for a specific channel of the given audio endpoint device. You can be informed about changes of VU-meters peaks by enabling notification about VU-meters changes (through the CoreAudioDevices.VuMeterEnableNotifications method) and by catching the CoreAudioDeviceVuMeterChange event.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.VuMeterChannelPeakValueGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

nChannelIndex as Integer,

fPeakValue as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.VuMeterChannelPeakValueGet (

short nDataFlow,

short nDeviceIndex,

short nChannelIndex,

float *fPeakValue

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

nChannelIndex

Zero-based index of the channel. The total number of channels for an audio endpoint device can be obtained through the CoreAudioDevices.ChannelCountGet method.

fPeakValue

Reference that, on return from the method call, will contain the the channel's peak value.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.VuMeterEnableNotifications method

CoreAudioDevices.VuMeterEnableNotifications method

Remarks

Enables/disables VU-Meter notifications, sent through the CoreAudioDeviceVuMeterChange event, for audio endpoint devices supporting Vu-Meters.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.VuMeterEnableNotifications (

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.VuMeterEnableNotifications (

short bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if the CoreAudioDeviceVuMeterChange event must be enabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The event is disabled
BOOL_TRUE | 1 | The event is enabled

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CoreAudioDevices.VuMeterMasterPeakValueGet method

CoreAudioDevices.VuMeterMasterPeakValueGet method

Remarks

Obtains the master VU-Meter's peak value for the given audio endpoint device. You can be informed about changes of VU-meters peaks by enabling notification about VU-meters changes (through the CoreAudioDevices.VuMeterEnableNotifications method) and by catching the CoreAudioDeviceVuMeterChange event.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevices COM object.

Syntax

[Visual Basic]

control.CoreAudioDevices.VuMeterMasterPeakValueGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Integer,

fPeakValue as Single

) as enumErrorCodes

[C++]

short control.CoreAudioDevices.VuMeterMasterPeakValueGet (

short nDataFlow,

short nDeviceIndex,

float *fPeakValue

);

Parameter

Description

nDataFlow

Direction in which audio data flows between an audio endpoint device and an application.

Supported values are the following:

Mnemonic Value | Value | Meaning
DEVICE_DATA_FLOW_RENDER | 0 | Audio rendering stream. Audio data flows from the application to the audio endpoint device, which renders the stream
DEVICE_DATA_FLOW_CAPTURE | 1 | Audio capture stream. Audio data flows from the audio endpoint device that captures the stream, to the application.

nDeviceIndex

Zero-based index of the audio endpoint device. The total number of audio endpoint devices can be obtained through the CoreAudioDevices.CountGet method.

fPeakValue

Reference that, on return from the method call, will contain the the master peak value.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CustomDSP object

CustomDSP object

The CustomDSP object, accessible through the control's CustomDSP property, is internally implemented as a COM interface called ICustomDSP and contains methods needed to apply custom DSP effects during a playback session.

The CustomDSP object is implemented through the following methods:

Enable

ExternalEditorGetInfo

ExternalEditorShow

ExternalGetParameters

ExternalLoad

ExternalSendCommand

ExternalSetFunction

ExternalSetParameters

Free

InternalLoad

InternalSetFunction

UseFloatSamples

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

In order to have a better understanding about the use and implementation of custom DSP effects, you will find some sample of usage of these internal and external DSP effects inside the CustomDSP and CustomDSPWithUI samples installed by the product's setup package. You will also find two projects, written in Visual C++ 6, that demonstrate the implementation of two external custom DSP effects, one containing an editor (named MyCustomDspWithUI) that will implement a simple "Bass Boost" effect and one without any editor (named MyCustomDsp) that will implement two different effects: a simple "Reverb" effect and a simple "Balance" effect.


CustomDSP.Enable method

CustomDSP.Enable method

Remarks

Enables/disables the given DSP effect.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.Enable (

nPlayer as Integer,

nIdDsp as Long,

bEnable as enumBoolean,

nUserData as Long,

nPriority as Long

) as enumErrorCodes

[C++]

short control.CustomDSP.Enable (

short nPlayer,

long nIdDsp,

short bEnable,

long nUserData,

long nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdDsp

Unique identifier of the custom DSP

bEnable

Boolean flag that specifies if the custom DSP must be enabled or disabled.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Disables the custom DSP effect
BOOL_TRUE | Enables the custom DSP effect

nUserData

User data to pass to the custom DSP

nPriority

DSP priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added..

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CustomDSP.ExternalEditorGetInfo method

CustomDSP.ExternalEditorGetInfo method

Remarks

If available, obtains information about the editor (user interface) of the given external DSP effect. You are free to define your own set of information about a certain editor.

The concept of "editor" implemented by external custom DSP effects is very similar to the concept of "editor" implemented by VST effects: as for VST effects, having an available editor is not mandatory but, in some case, it could be useful.

The editor can be shown, hidden or moved using the CustomDSP.ExternalEditorShow method.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.ExternalEditorGetInfo (

nPlayer as Integer,

nIdDsp as Long,

pInfo as Long

) as enumErrorCodes

[C++]

short control.CustomDSP.ExternalEditorGetInfo (

short nPlayer,

long nIdDsp,

long pInfo

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdDsp | Unique identifier of the custom DSP
pInfo | Pointer in memory to the data structure containing information about the DSP's editor. As already mentioned before, you are free to define your own set of information about a certain editor; a typical implementation of this data structure could be the one provided below in C++ language: typedef struct { HWND hWnd; // HWND of the window bool bIsVisible; // visibility flag long nLeftPosPx; // left position in pixels long nTopPosPx; // to position in pixels long nWidthPx; // width in pixels long nHeightPx; // height in pixels } DSP_EDITOR_WINDOW_INFO;

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CustomDSP.ExternalEditorShow method

CustomDSP.ExternalEditorShow method

Remarks

If available, shows/hides the editor (user interface) of the given external DSP effect.

The concept of "editor" implemented by external custom DSP effects is very similar to the concept of "editor" implemented by VST effects: as for VST effects, having an available editor is not mandatory but, in some case, it could be useful.

Information about the editor can be obtained through the CustomDSP.ExternalEditorGetInfo method.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.ExternalEditorShow (

nPlayer as Integer,

nIdDsp as Long,

bShow as enumBoolean,

hWndParent as OLE_HANDLE,

leftPos as Long,

topPos as Long

) as enumErrorCodes

[C++]

short control.CustomDSP.ExternalEditorShow (

short nPlayer,

long nIdDsp,

short bShow,

OLE_HANDLE hWndParent,

long leftPos,

long topPos

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdDsp

Unique identifier of the custom DSP

bShow

Show/hide flag..

Supported values are the following:

Value | Meaning
BOOL_FALSE | Hides the editor window
BOOL_TRUE | Shows the editor window

hWndParent

Handle of the window (HWND) that will be parent of the editor's window.

leftPos

Left position, respect to the container window client area, expressed in pixels

topPos

Top position, respect to the container window client area, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | A custom return value: you can define your own set of return values in order to let the container application know the result of the custom command


CustomDSP.ExternalGetParameters method

CustomDSP.ExternalGetParameters method

Remarks

Retrieves parameters currently set into an external custom DSP effect.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.ExternalGetParameters (

nPlayer as Integer,

nIdDsp as Long,

pParameters as Long

) as enumErrorCodes

[C++]

short control.CustomDSP.ExternalGetParameters (

short nPlayer,

long nIdDsp,

long pParameters

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdDsp | Unique identifier of the custom DSP
pParameters | Pointer in memory to the data structure containing specific parameters for the custom DSP effect: this data structure is not predefined and its fields strictly depends upon the parameters effectively needed by the DSP algorithm: it's very important that this data structure reflects exactly (also in terms of bytes length) the data structure used inside the DLL containing the external DSP

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CustomDSP.ExternalLoad method

CustomDSP.ExternalLoad method

Remarks

Loads a custom DSP effect from an external dynamic-link library (DLL) file.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.ExternalLoad (

nPlayer as Integer,

strPathname as String

) as Long

[C++]

long control.CustomDSP.ExternalLoad (

short nPlayer,

LPCTSTR strPathname

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strPathname

String representing the filename or absolute pathname of the DLL file containing the custom DSP.

If the string specifies a path but the file does not exist in the specified directory, the function fails. When specifying a path, be sure to use backslashes (\), not forward slashes (/).

If the string does not specify a path, the function uses the standard search strategy of the LoadLibrary Windows API to find the file.

Return value

Value | Meaning
0 | An error occurred: see the LastError property for further error details or for a list of the possible error values.
Other values | Numeric value representing the unique identifier of the custom DSP: this unique identifier will be used in order to invoke further methods related to the use of the loaded custom DSP


CustomDSP.ExternalSendCommand method

CustomDSP.ExternalSendCommand method

Remarks

Sends a custom command to the given DSP effect.

You can define your own set of custom commands that will allow communicating with the external DSP effect. The DSP effect will have the possibility to immediately reply to a custom command through the return value of this method or, at a later time, through the use of the PostMessage Windows API, sending a user-defined message to the window (HWND) of the container form or dialog box.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.ExternalSendCommand (

nPlayer as Integer,

nIdDsp as Long,

hWndParent as OLE_HANDLE,

strCommand as String

) as Long

[C++]

long control.CustomDSP.ExternalSendCommand (

short nPlayer,

long nIdDsp,

OLE_HANDLE hWndParent,

LPCTSTR strCommand

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdDsp

Unique identifier of the custom DSP

hWndParent

Handle of the window (HWND) containing the Active DJ Studio control or any other window that should manage custom responses from the external DSP effect.

This is quite useful when the command will start a secondary thread in order to perform a custom action and the command's result will not be immediately available to be returned through the return value of this method: the external DSP effect will use this HWND as a parameter for a call to the PostMessage Window API.

strCommand

String containing the custom command to be sent to the DSP effect: you are absolutely free to define your own set of commands with related parameters.

Custom commands can be seen as a sort of "command line" where you can define your own set of options and parameters: parsing available options and parameters will be a task of the external custom DSP effect.

One further possible use of this parameter is sending XML formatted strings that will be parsed and managed by the external DSP effect.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details). You can define your own set of negative return values, which usually define an error condition, using values under -1000.
>= 0 | A custom return value: you can define your own set of return values in order to let the container application know the result of the custom command.


CustomDSP.ExternalSetFunction method

CustomDSP.ExternalSetFunction method

Remarks

Sets the name of a specific function of the external custom DSP.

As you may know, the GetProcAddress Windows API allows retrieving the address of an exported function from a specified dynamic-link library (DLL) file previously loaded through the LoadLibrary Windows API: in a very similar way, the CustomDSP.ExternalSetFunction method allows retrieving the address of an exported function from a specified dynamic-link library (DLL) file previously loaded through the CustomDSP.ExternalLoad method. Through this mechanism you can set the callback function that will effectively manage the DSP effect, retrieving/setting DSP effect's parameters, asking the DSP to display its own user interface (also known as "Editor") and also send your own custom commands to the DSP.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.ExternalSetFunction (

nPlayer as Integer,

nIdDsp as Long,

nFunctionType as enumDspExternalFunctions,

strFunctionName as String

) as enumErrorCodes

[C++]

short control.CustomDSP.ExternalSetFunction (

short nPlayer,

long nIdDsp,

short nFunctionType,

LPCTSTR strFunctionName

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdDsp

Unique identifier of the custom DSP

nFunctionType

Type of function to set.

Supported values are the following:

Mnemonic constant

Value

Meaning

DSP_FUNC_CALLBACK

0

Sets the callback function containing the code that will effectively modify original WAV PCM data. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

The Visual C++ definition of an external callback function is as follows:

void WINAPI MyCustomCallback (

void *bufferSamples,

DWORD bufferSamplesLength,

DWORD nUserData

);

where

bufferSamples

Pointer to the buffer containing WAV PCM samples to be processed by the DSP in one of the following formats:

8-bit samples are unsigned

16-bit samples are signed

32-bit floating-point samples can range from -1 to +1: note that they are not clipped so they could be outside the mentioned range.

You can instruct the DSP using 32-bit floating-point samples only through the CustomDSP.UseFloatSample method.

bufferSamplesLength

The length in bytes of the buffer above

nUserData

User specific data

DSP_FUNC_PARAMS_GET

1

Sets the function used to obtain current parameters from the external DSP

DSP_FUNC_PARAMS_SET

2

Sets the function used to set parameters to the external DSP

DSP_FUNC_COMMAND_SEND

3

Sets the function used to send your own custom commands to the external DSP

DSP_FUNC_EDITOR_DISPLAY

4

Sets the function used to display the editor (user interface) of the external DSP: the availability of a user interface is not mandatory

DSP_FUNC_EDITOR_GET_INFO

5

Sets the function used to obtain information about the editor (user interface) of the external DSP

strFunctionName

Name of the function exported by the dynamic-link library (DLL)

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CustomDSP.ExternalSetParameters method

CustomDSP.ExternalSetParameters method

Remarks

Modifies parameters of an external custom DSP effect.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.ExternalSetParameters (

nPlayer as Integer,

nIdDsp as Long,

pParameters as Long

) as enumErrorCodes

[C++]

short control.CustomDSP.ExternalSetParameters (

short nPlayer,

long nIdDsp,

long pParameters

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdDsp | Unique identifier of the custom DSP
pParameters | Pointer in memory to the data structure containing specific parameters for the custom DSP effect: this data structure is not predefined and its fields strictly depends upon the parameters effectively needed by the DSP algorithm: it's very important that this data structure reflects exactly (also in terms of bytes length) the data structure used inside the DLL containing the external DSP

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CustomDSP.Free method

CustomDSP.Free method

Remarks

Discards from memory a previously loaded custom DSP.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.Free (

nPlayer as Integer,

nIdDsp as Long

) as enumErrorCodes

[C++]

short control.CustomDSP.Free (

short nPlayer,

long nIdDsp

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdDsp | Unique identifier of the custom DSP to discard from memory. Passing -1 will cause discarding from memory all of the loaded custom DSPs.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CustomDSP.InternalLoad method

CustomDSP.InternalLoad method

Remarks

Loads a custom DSP contained inside the source code of the container application.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.InternalLoad (

nPlayer as Integer

) as Long

[C++]

long control.CustomDSP.InternalLoad (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
0 | An error occurred: see the LastError property for further error details or for a list of the possible error values.
Other values | Numeric value representing the unique identifier of the custom DSP: this unique identifier will be used in order to invoke further methods related to the use of the loaded custom DSP


CustomDSP.InternalSetFunction method

CustomDSP.InternalSetFunction method

Remarks

Sets the the callback function of the internal custom DSP. The callback of an internal custom DSP is nothing more than a simple function that will receive original WAV PCM sound data to be modified on the fly.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.InternalSetFunction (

nPlayer as Integer,

nIdDsp as Long,

pCallback as Long

) as enumErrorCodes

[C++]

short control.CustomDSP.InternalSetFunction (

short nPlayer,

long nIdDsp,

long pCallback

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdDsp

Unique identifier of the custom DSP

pCallback

Pointer to the callback function containing the code that will effectively modify original WAV PCM data. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

A callback function is defined like this:

[Visual Basic ]

Public Sub MyCustomCallback(

ByVal bufferSamples As Long,

ByVal bufferSamplesLength As Long,

ByVal nUserData As Long

)

[Visual C++]

void MyCustomCallback (

void *bufferSamples,

DWORD bufferSamplesLength,

DWORD nUserData

);

where

bufferSamples

Pointer to the buffer containing WAV PCM samples to be processed by the DSP in one of the following formats:

8-bit samples are unsigned

16-bit samples are signed

32-bit floating-point samples can range from -1 to +1: note that they are not clipped so they could be outside the mentioned range.

You can instruct the DSP using 32-bit floating-point samples only through the CustomDSP.UseFloatSample method.

bufferSamplesLength

The length in bytes of the buffer above

nUserData

User specific data

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CustomDSP.UseFloatSamples method

CustomDSP.UseFloatSamples method

Remarks

Tells to the component to pass floating point samples to DSP callbacks instead of 8 or 16 bits samples.

For further details about methods related to the use of custom DSP effects refer to the CustomDSP COM object.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

control.CustomDSP.UseFloatSamples (

bUseFloatSamples as enumBoolean

) as enumErrorCodes

[C++]

short control.CustomDSP.UseFloatSamples (

short bUseFloatSamples

);

Parameter

Description

bUseFloatSamples

Boolean value that specifies if the callback function needs to receive floating point samples.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The callback function will receive original 8 or 16 bits samples
BOOL_TRUE | 1 | The callback function will receive samples converted to floating point values. The use of this setting and of floating point DSPs is mandatory when an embedded filter (activated through the FilterApply method) or the normalization filter (activated through the NormalizationEnable method) are enabled.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


DelayedPlayback object

DelayedPlayback object

The DelayedPlayback object, accessible through the control's DelayedPlayback property, is internally implemented as a COM interface called IDelayedPlayback and allows implementing and managing delayed playback of sound files.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

The DelayedPlayback object is implemented through the following properties and methods:

Properties

AllowOverlapping

Methods

ListAddItem

ListAddItemEx

ListAddItemByDate

ListAddItemByDateEx

ListGetCount

ListRemoveItem

ListRemoveAll

ItemGetDuration

ItemPlayNow

ItemResetDelay

ItemGetRange

ItemSetRange

ItemGetLoopCount

ItemSetLoopCount

ItemGetFadeTime

ItemSetFadeTime


DelayedPlayback.AllowOverlapping property

DelayedPlayback.AllowOverlapping property

Type

short for Visual C++

enumBoolean for Visual Basic

Syntax

object.DelayedPlayback.AllowOverlapping [=Integer]

Remarks

If time positioning and duration of a new item should overlap with the time positioning and duration of an existing item, this properties determines if accepting or denying its insertion inside the list.

Supported values are the following:

Mnemonic value | Meaning
BOOL_FALSE | Overlapping is not allowed
BOOL_TRUE (default) | Overlapping is allowed

See also

DelayedPlayback COM object.

DelayedPlayback property

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.


DelayedPlayback.ItemGetDuration method

DelayedPlayback.ItemGetDuration method

Remarks

Obtains the duration of a sound file added to delayed playbacks list.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemGetDuration (

nFileUniqueID as Long

) as Long

[C++]

long control.DelayedPlayback.ItemGetDuration (

long nFileUniqueID

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | Sound duration expressed in milliseconds


DelayedPlayback.ItemGetFadeTime method

DelayedPlayback.ItemGetFadeTime method

Remarks

Obtains the fading times applied during start and end of playback of the given file. The current fading time can be modified through the DelayedPlayback.ItemSetFadeTime method.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemGetFadeTime (

nFileUniqueID as Long,

nFadeInLength as Long,

nFadeOutLength as Long

) as enumErrorCodes

[C++]

long control.DelayedPlayback.ItemGetFadeTime (

long nFileUniqueID,

long *nFadeInLength,

long *nFadeOutLength

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method
nFadeInLength | Reference that, on return from the method call, will contain the fade-in time length expressed in milliseconds
nFadeOutLength | Reference that, on return from the method call, will contain the fade-out time length expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ItemGetLoopCount method

DelayedPlayback.ItemGetLoopCount method

Remarks

Obtains the number of loops applied to the given file during playback. The current number of loops can be modified through the DelayedPlayback.ItemSetLoopCount method.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemGetLoopCount (

nFileUniqueID as Long,

nLoopCount as Long

) as enumErrorCodes

[C++]

long control.DelayedPlayback.ItemGetLoopCount (

long nFileUniqueID,

long *nLoopCount

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method
nLoopCount | Reference that, on return from the method call, will contain the number of loops to apply. A value of -1 would mean infinite loops.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ItemGetRange method

DelayedPlayback.ItemGetRange method

Remarks

Obtains the range that will be performed during playback of the given file. The current range can be modified through the DelayedPlayback.ItemSetRange method.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemGetRange (

nFileUniqueID as Long,

nStartPos as Long,

nEndPos as Long

) as enumErrorCodes

[C++]

long control.DelayedPlayback.ItemGetRange (

long nFileUniqueID,

long *nStartPos,

long *nEndPos

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method
nStartPos | Reference that, on return from the method call, will contain the start position of the playback range expressed in milliseconds
nEndPos | Reference that, on return from the method call, will contain the end position of the playback range expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ItemPlayNow method

DelayedPlayback.ItemPlayNow method

Remarks

Starts an immediate playback of the given file.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemPlayNow (

nFileUniqueID as Long,

bRemoveFromList as enumBoolean

) as enumErrorCodes

[C++]

long control.DelayedPlayback.ItemPlayNow (

long nFileUniqueID,

short bRemoveFromList

);

Parameter

Description

nFileUniqueID

Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method

bRemoveFromList

Boolean value that specifies if the file should be removed from the list of delayed playbacks after starting the playback session.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Item is not removed from the list after starting playback session
BOOL_TRUE | 1 | Item is removed from the list after starting playback session

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ItemResetDelay method

DelayedPlayback.ItemResetDelay method

Remarks

Resets the delay previously set for the given file.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemResetDelay (

nFileUniqueID as Long,

nDelay as Long

) as enumErrorCodes

[C++]

long control.DelayedPlayback.ItemResetDelay (

long nFileUniqueID,

long nDelay

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method
nDelay | New delay expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ItemSetFadeTime method

DelayedPlayback.ItemSetFadeTime method

Remarks

Sets the fading times applied during start and end of playback of the given file. The current fading time can be obtained through the DelayedPlayback.ItemGetFadeTime method.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemSetFadeTime (

nFileUniqueID as Long,

nFadeInLength as Long,

nFadeOutLength as Long

) as enumErrorCodes

[C++]

long control.DelayedPlayback.ItemSetFadeTime (

long nFileUniqueID,

long nFadeInLength,

long nFadeOutLength

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method
nFadeInLength | The fade-in time length expressed in milliseconds
nFadeOutLength | The fade-out time length expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ItemSetLoopCount method

DelayedPlayback.ItemSetLoopCount method

Remarks

Modifies the number of loops applied to the given file during playback. The current number of loops can be obtained through the DelayedPlayback.ItemGetLoopCount method.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemSetLoopCount (

nFileUniqueID as Long,

nLoopCount as Long

) as enumErrorCodes

[C++]

long control.DelayedPlayback.ItemSetLoopCount (

long nFileUniqueID,

long nLoopCount

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method
nLoopCount | The number of loops to apply. A value of -1 would mean infinite loops.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ItemSetRange method

DelayedPlayback.ItemSetRange method

Remarks

Modifies the range that will be performed during playback of the given file. The current range can be obtained through the DelayedPlayback.ItemGetRange method.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ItemSetRange (

nFileUniqueID as Long,

nStartPos as Long,

nEndPos as Long

) as enumErrorCodes

[C++]

long control.DelayedPlayback.ItemSetRange (

long nFileUniqueID,

long nStartPos,

long nEndPos

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem method
nStartPos | The start position of the playback range expressed in milliseconds
nEndPos | The end position of the playback range expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ListAddItem method

DelayedPlayback.ListAddItem method

Remarks

Adds a song (item) to the list of delayed playbacks.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ListAddItem (

nPlayer as Integer,

strPathname as String,

nDelay as Long

) as Long

[C++]

long control.DelayedPlayback.ListAddItem (

short nPlayer,

LPCTSTR strPathname,

long nDelay

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the element to add. If this string is left empty, the current sound or video clip loaded into the given player will be added.
nDelay | Number representing the delay expressed in milliseconds

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the file that will have a delayed playback


DelayedPlayback.ListAddItemEx method

DelayedPlayback.ListAddItemEx method

Remarks

Adds a song (item) to the list of delayed playbacks and predisposes its initial settings.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ListAddItemEx (

nPlayer as Integer,

strPathname as String,

nDelay as Long,

nStartPos as Long,

nEndPos as Long,

nLoopCount as Long,

nFadeInLength as Long,

nFadeOutLength as Long

) as Long

[C++]

long control.DelayedPlayback.ListAddItemEx (

short nPlayer,

LPCTSTR strPathname,

long nDelay,

long nStartPos,

long nEndPos,

long nLoopCount,

long nFadeInLength,

long nFadeOutLength

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the playlist
strPathname | String containing the absolute pathname of the element to add. If this string is left empty, the current sound loaded into the given player will be added.
nDelay | Number representing the delay expressed in milliseconds
nStartPos | Playback range start position expressed in milliseconds
nEndPos | Playback range end position expressed in milliseconds
nLoopCount | Number of loops applied to the given range
nFadeInLength | Fade-in length expressed in milliseconds
nFadeOutLength | Fade-out length expressed in milliseconds

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the file that will have a delayed playback


DelayedPlayback.ListAddItemByDate method

DelayedPlayback.ListAddItemByDate method

Remarks

Adds a song (item) to the list of delayed playbacks.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ListAddItemByDate (

nPlayer as Integer,

strPathname as String,

nYear as Long,

nMonth as Long,

nDay as Long,

nHour as Long,

nMinute as Long,

nSecond as Long

) as Long

[C++]

long control.DelayedPlayback.ListAddItemByDate (

short nPlayer,

LPCTSTR strPathname,

long nYear,

long nMonth,

long nDay,

long nHour,

long nMinute,

long nSecond

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the element to add. If this string is left empty, the current sound or video clip loaded into the given player will be added.
nYear | Number representing the year
nMonth | Number representing the month
nDay | Number representing the day of the month
nHour | Number representing the hour of the day
nMinute | Number representing the minute of the hour
nSecond | Number representing the second of the minute

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the file that will have a delayed playback


DelayedPlayback.ListAddItemByDateEx method

DelayedPlayback.ListAddItemByDateEx method

Remarks

Adds a song (item) to the list of delayed playbacks.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ListAddItemByDateEx (

nPlayer as Integer,

strPathname as String,

nYear as Long,

nMonth as Long,

nDay as Long,

nHour as Long,

nMinute as Long,

nSecond as Long,

nStartPos as Long,

nEndPos as Long,

nLoopCount as Long,

nFadeInLength as Long,

nFadeOutLength as Long

) as Long

[C++]

long control.DelayedPlayback.ListAddItemByDateEx (

short nPlayer,

LPCTSTR strPathname,

long nYear,

long nMonth,

long nDay,

long nHour,

long nMinute,

long nSecond,

long nStartPos,

long nEndPos,

long nLoopCount,

long nFadeInLength,

long nFadeOutLength

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the element to add. If this string is left empty, the current sound or video clip loaded into the given player will be added.
nYear | Number representing the year
nMonth | Number representing the month
nDay | Number representing the day of the month
nHour | Number representing the hour of the day
nMinute | Number representing the minute of the hour
nSecond | Number representing the second of the minute
nStartPos | Playback range start position expressed in milliseconds
nEndPos | Playback range end position expressed in milliseconds
nLoopCount | Number of loops applied to the given range
nFadeInLength | Fade-in length expressed in milliseconds
nFadeOutLength | Fade-out length expressed in milliseconds

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the file that will have a delayed playback


DelayedPlayback.ListGetCount method

DelayedPlayback.ListGetCount method

Remarks

Obtains the number of sound files stored inside the list of delayed playbacks.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ListGetCount (

) as enumErrorCodes

[C++]

short control.DelayedPlayback.ListGetCount (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | The number of sound files inside the list of delayed playbacks


DelayedPlayback.ListRemoveAll method

DelayedPlayback.ListRemoveAll method

Remarks

Removes all the files from the list of delayed playbacks.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ListRemoveAll (

) as enumErrorCodes

[C++]

short control.DelayedPlayback.ListRemoveAll (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DelayedPlayback.ListRemoveItem method

DelayedPlayback.ListRemoveItem method

Remarks

Removes the given file from the list of delayed playbacks.

For details about management of delayed playbacks refer to the How to manage delayed playbacks tutorial.

Syntax

[Visual Basic]

control.DelayedPlayback.ListRemovetem (

nFileUniqueID as Long

) as enumErrorCodes

[C++]

short control.DelayedPlayback.ListRemovetem (

long nFileUniqueID

);

Parameter | Description
nFileUniqueID | Number representing the unique identifier of the file as returned by the DelayedPlayback,ListAddItem or DelayedPlayback,ListAddItemEx methods

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Downloader object

Downloader object

The Downloader object, accessible through the control's Downloader property, is internally implemented as a COM interface called IDownloaderDj and allows implementing and managing download of remote files into the local system.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

The Downloader object is implemented through the following properties and methods:

Methods

Create

Destroy

SessionDataSizeGet

SessionStartToFile

SessionStartToMemory

SessionStartToPlayer

SessionStop

SetTimeouts


Downloader.Create method

Downloader.Create method

Remarks

Creates and initializes the downloader.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.Create (

nTimeoutConnectionInMs as Long,

nTimeoutDataInMs as Long

)

[C++]

void control.Downloader.Create (

long nTimeoutConnectionInMs,

long nTimeoutDataInMs

);

Parameter | Description
nTimeoutConnectionInMs | Number representing the connection timeout expressed in milliseconds. By default this timeout is set to 10000 (10 seconds). Set this parameter to -1 for keeping the current default value.
nTimeoutDataInMs | Number representing the data timeout expressed in milliseconds. By default this timeout is set to 0 (no timeout). Set this parameter to -1 for keeping the current default value.

Return value

None


Downloader.Destroy method

Downloader.Destroy method

Remarks

Destroys the downloader and disposes its resources.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.Destroy (

)

[C++]

void control.Downloader.Destroy (

);

Return value

None


Downloader.LastFileExceptionGet method

Downloader.LastFileExceptionGet method

Remarks

Obtains the eventual exception code generated by a file access error during the latest downloading session. The call to this method is indicated when one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer methods returns a negative value (indicating an invalid unique identifier) and the LastError property is set to ERR_DOWNLOADER_REMOTE_FILE_FAILURE or ERR_DOWNLOADER_LOCAL_FILE_FAILURE.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.LastFileExceptionGet (

) as Integer

[C++]

short control.Downloader.LastFileExceptionGet (

);

Return value

Value | Meaning
0 | No error occurred.
1 | An unspecified error occurred.
2 | The file could not be located.
3 | All or part of the path is invalid.
4 | The permitted number of open files was exceeded.
5 | The file could not be accessed.
6 | There was an attempt to use an invalid file handle.
7 | The current working directory cannot be removed.
8 | There are no more directory entries.
9 | There was an error trying to set the file pointer.
10 | There was a hardware error.
11 | SHARE.EXE was not loaded, or a shared region was locked.
12 | There was an attempt to lock a region that was already locked.
13 | The disk is full.
14 | The end of file was reached.


Downloader.SessionDataSizeGet method

Downloader.SessionDataSizeGet method

Remarks

Obtains the size in bytes of the remote file pointed by the given URL.

This method can be used to determine the size of the memory buffer needed to perform a memory-based downloading of a remote file through the Downloader.SessionStartToMemory method.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.SessionDataSizeGet (

strURL as String,

strUsername as String,

strPassword as String,

nDataSize as Long,

nSdkError as Long,

pBufferExtendedError as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.Downloader.SessionDataSizeGet (

LPCTSTR strURL,

LPCTSTR strUsername,

LPCTSTR strPassword,

long *nDataSize,

long *nSdkError,

const VARIANT FAR& pBufferExtendedError,

long *nBufferLen

);

Parameter

Description

strURL

String containing the URL pointing to the remote media file to download. Accepted Internet protocols for the passed URL must be of type HTTP or FTP.

strUsername

String containing the username for accessing the server. Leave the string empty if the directory containing the remote file is not username protected.

strPassword

String containing the password for accessing the server. Leave the string empty if the directory containing the remote file is not password protected.

nDataSize

Reference that, on return from the method call, will contain the size in bytes of the remote file.

nSdkError

Reference that, on return from the method call, and in case of error will contain the eventual error code defined by the Windows SDK.

In case the error code should be ERROR_INTERNET_EXTENDED_ERROR (12003), this would mean that an extended error was returned from the server. This is typically a string or buffer containing a verbose error message; the string containing the message is provided back to the caller through the memory buffer pointed by the pBufferExtendedError parameter.

pBufferExtendedError

Variant parameter containing the pointer to the memory buffer where an eventual extended error message will be stored: when returning from the method call, the buffer will contain a string in Unicode characters.

This buffer must be previously allocated by the caller and when the buffer is no more needed, its deallocation is responsibility of the caller.

nBufferLen

Reference containing the length in bytes of the given buffer: it's recommended setting a buffer with a minimal size of 1024 bytes.

When returning from the call to this method, in case of error and if the nSdkError parameter should contain ERROR_INTERNET_EXTENDED_ERROR (12003), this parameter will contain the exact size in characters of the extended error string stored inside the buffer pointed by the pBufferExtendedError parameter.

Return value

Value

Meaning

enumErrorCodes.NOERROR (0)

The method call was successful.

Negative value

An error occurred: see the LastError property for further error details or for a list of the possible error values.

In case of error the nSdkError and pBufferExtendedError parameters may contain further information about the nature of the error.


Downloader.SessionStartToFile method

Downloader.SessionStartToFile method

Remarks

Starts a download session of a remote file pointed by a URL and stores the downloaded file inside a given pathname using the same filename of the remote file.

A successful call to this method will fire the following sequence of events:

- the DownloaderSessionStarted event

- a sequence of DownloaderSessionProgress events informing about the download advancement in percentage

- the DownloaderSessionCompleted event

In case the connection to the remote server or the access to the remote file should fail, the DownloaderSessionFailed would be invoked.

In case the connection should be stopped by the user through a call to the Downloader.SessionStop method, the DownloaderSessionStopped event would be generated.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.SessionStartToFile (

strURL as String,

strUsername as String,

strPassword as String,

strDestinationPath as String,

bDisableCache as enumBoolean

) as Long

[C++]

long control.Downloader.SessionStartToFile (

LPCTSTR strURL,

LPCTSTR strUsername,

LPCTSTR strPassword,

LPCTSTR strDestinationPath,

short bDisableCache

);

Parameter

Description

strURL

String containing the URL pointing to the remote media file to download. Accepted Internet protocols for the passed URL must be of type HTTP or FTP.

strUsername

String containing the username for accessing the server. Leave the string empty if the directory containing the remote file is not username protected.

strPassword

String containing the password for accessing the server. Leave the string empty if the directory containing the remote file is not password protected.

strDestinationPath

String containing the path on the local system where the downloaded file will be stored: the path must not contain the filename, indeed the same filename of the remote file will be used for creating the local file copy.

bDisableCache

Flag for determining if the usage of the Internet cache must be disabled or not.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | If the file to download is already inside the Internet cache, allows taking the cached file.
BOOL_TRUE | 1 | Never use an eventual cached file, always take it from the remote server.

Return value

Value

Meaning

Value >= 0

The method call was successful and the returned value is the unique identifier of the download session.

Negative value

An error occurred: see the LastError property for error details or for a list of the possible error values.

In case the error code should be ERR_DOWNLOADER_REMOTE_FILE_FAILURE or ERR_DOWNLOADER_LOCAL_FILE_FAILURE the Downloader.LastFileExceptionGet method would provide the nature of the error which may assume one of the following values:

Value | Meaning
1 | An unspecified error occurred.
2 | The file could not be located.
3 | All or part of the path is invalid.
4 | The permitted number of open files was exceeded.
5 | The file could not be accessed.
6 | There was an attempt to use an invalid file handle.
7 | The current working directory cannot be removed.
8 | There are no more directory entries.
9 | There was an error trying to set the file pointer.
10 | There was a hardware error.
11 | SHARE.EXE was not loaded, or a shared region was locked.
12 | There was an attempt to lock a region that was already locked.
13 | The disk is full.
14 | The end of file was reached.


Downloader.SessionStartToMemory method

Downloader.SessionStartToMemory method

Remarks

Starts a download session of a remote file pointed by a URL and stores the downloaded file inside a given memory buffer.

The size of the memory buffer needed to store the full remote file can be obtained through the Downloader.SessionDataSizeGet method.

A successful call to this method will fire the following sequence of events:

- the DownloaderSessionStarted event

- a sequence of DownloaderSessionProgress events informing about the download advancement in percentage

- the DownloaderSessionCompleted event

In case the connection to the remote server or the access to the remote file should fail, the DownloaderSessionFailed would be invoked.

In case the connection should be stopped by the user through a call to the Downloader.SessionStop method, the DownloaderSessionStopped event would be generated.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.SessionStartToMemory (

strURL as String,

strUsername as String,

strPassword as String,

pBuffer as Variant,

nBufferLen as Long,

bDisableCache as enumBoolean

) as Long

[C++]

long control.Downloader.SessionStartToMemory (

LPCTSTR strURL,

LPCTSTR strUsername,

LPCTSTR strPassword,

const VARIANT FAR& pBuffer,

long nBufferLen,

short bDisableCache

);

Parameter

Description

strURL

String containing the URL pointing to the remote media file to download. Accepted Internet protocols for the passed URL must be of type HTTP or FTP.

strUsername

String containing the username for accessing the server. Leave the string empty if the directory containing the remote file is not username protected.

strPassword

String containing the password for accessing the server. Leave the string empty if the directory containing the remote file is not password protected.

pBuffer

Variant parameter containing the pointer to the memory buffer where contents of the downloaded file will be stored.

The buffer must be previously allocated by the caller using the size obtained through a previous call to the Downloader.SessionDataSizeGet method.

When the buffer is no more needed, its deallocation is responsibility of the caller.

nBufferLen

Length in bytes of the given buffer.

bDisableCache

Flag for determining if the usage of the Internet cache must be disabled or not.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | If the file to download is already inside the Internet cache, allows taking the cached file.
BOOL_TRUE | 1 | Never use an eventual cached file, always take it from the remote server.

Return value

Value

Meaning

Value >= 0

The method call was successful and the returned value is the unique identifier of the download session.

Negative value

An error occurred: see the LastError property for error details or for a list of the possible error values.

In case the error code should be ERR_DOWNLOADER_REMOTE_FILE_FAILURE or ERR_DOWNLOADER_LOCAL_FILE_FAILURE the Downloader.LastFileExceptionGet method would provide the nature of the error which may assume one of the following values:

Value | Meaning
1 | An unspecified error occurred.
2 | The file could not be located.
3 | All or part of the path is invalid.
4 | The permitted number of open files was exceeded.
5 | The file could not be accessed.
6 | There was an attempt to use an invalid file handle.
7 | The current working directory cannot be removed.
8 | There are no more directory entries.
9 | There was an error trying to set the file pointer.
10 | There was a hardware error.
11 | SHARE.EXE was not loaded, or a shared region was locked.
12 | There was an attempt to lock a region that was already locked.
13 | The disk is full.
14 | The end of file was reached.


Downloader.SessionStartToPlayer method

Downloader.SessionStartToPlayer method

Remarks

Starts a download session of a remote media file pointed by a URL and, once the download is completed, automatically loads it into the given player.

A successful call to this method will fire the following sequence of events:

- the DownloaderSessionStarted event

- a sequence of DownloaderSessionProgress events informing about the download advancement in percentage

- the DownloaderSessionCompleted event

In case the remote file should be of a supported format and the automatic loading should succeed, the SoundLoaded event would be invoked.

In case the remote file should be of an unsupported format and the automatic loading should fail, the DownloaderSessionInvalidFile event would be invoked.

In case the connection to the remote server or the access to the remote file should fail, the DownloaderSessionFailed would be invoked.

In case the connection should be stopped by the user through a call to the Downloader.SessionStop method, the DownloaderSessionStopped event would be generated.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.SessionStartToPlayer (

nPlayer as Integer,

strURL as String,

strUsername as String,

strPassword as String,

nMediaType as enumMediaTypes,

strDecryptionKey as String,

bDisableCache as enumBoolean

) as Long

[C++]

long control.Downloader.SessionStartToPlayer (

short nPlayer,

LPCTSTR strURL,

LPCTSTR strUsername,

LPCTSTR strPassword,

short nMediaType,

LPCTSTR strDecryptionKey,

short bDisableCache

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the sound.

strURL

String containing the URL pointing to the remote media file to download. Accepted Internet protocols for the passed URL must be of type HTTP or FTP.

strUsername

String containing the username for accessing the server. Leave the string empty if the directory containing the remote file is not username protected.

strPassword

String containing the password for accessing the server. Leave the string empty if the directory containing the remote file is not password protected.

nMediaType

Media type.

Supported values are the following:

Mnemonic constant | Value | Meaning
MEDIA_TYPE_AUDIO | 0 | The requested media is an audio file. Accepted audio formats are the same supported by the LoadSound method. In case the remote file should have been encrypted through the CryptSound™ application, the decryption key can be specified through the strDecryptionKey parameter below.
MEDIA_TYPE_VIDEO | 1 | The requested media is a video file. Once the download session is completed the behaviour is the same as invoking the VideoPlayer.Load method.

strDecryptionKey

String containing the decryption key for audio encrypted files.

If the audio file is not encrypted leave this string empty.

This parameter is ignored when the nMediaType parameter is set to MEDIA_TYPE_VIDEO.

bDisableCache

Flag for determining if the usage of the Internet cache must be disabled or not.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | If the file to download is already inside the Internet cache, allows taking the cached file.
BOOL_TRUE | 1 | Never use an eventual cached file, always take it from the remote server.

Return value

Value

Meaning

Value >= 0

The method call was successful and the returned value is the unique identifier of the download session.

Negative value

An error occurred: see the LastError property for error details or for a list of the possible error values.

In case the error code should be ERR_DOWNLOADER_REMOTE_FILE_FAILURE or ERR_DOWNLOADER_LOCAL_FILE_FAILURE the Downloader.LastFileExceptionGet method would provide the nature of the error which may assume one of the following values:

Value | Meaning
1 | An unspecified error occurred.
2 | The file could not be located.
3 | All or part of the path is invalid.
4 | The permitted number of open files was exceeded.
5 | The file could not be accessed.
6 | There was an attempt to use an invalid file handle.
7 | The current working directory cannot be removed.
8 | There are no more directory entries.
9 | There was an error trying to set the file pointer.
10 | There was a hardware error.
11 | SHARE.EXE was not loaded, or a shared region was locked.
12 | There was an attempt to lock a region that was already locked.
13 | The disk is full.
14 | The end of file was reached.


Downloader.SessionStop method

Downloader.SessionStop method

Remarks

Stops a download session previously started by a call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer methods.

A successful call to this method will fire the DownloaderSessionStopped event.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.SessionStop (

nDllSessionUniqueId as Long

) as enumErrorCodes

[C++]

short control.Downloader.SessionStop (

long nDllSessionUniqueId

);

Parameter | Description
nDllSessionUniqueId | The unique identifier of the download session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


Downloader.SetTimeouts method

Downloader.SetTimeouts method

Remarks

Modify timeouts for the downloader.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

control.Downloader.SetTimeouts (

nTimeoutConnectionInMs as Long,

nTimeoutDataInMs as Long

)

[C++]

void control.Downloader.SetTimeouts (

long nTimeoutConnectionInMs,

long nTimeoutDataInMs

);

Parameter | Description
nTimeoutConnectionInMs | Number representing the connection timeout expressed in milliseconds. Set this parameter to -1 for keeping the current value.
nTimeoutDataInMs | Number representing the data timeout expressed in milliseconds. Set this parameter to -1 for keeping the current value. Set this parameter to 0 for disabling the data timeout.

Return value

None


Effects object

Effects object

The Effects object, accessible through the control's Effects property, is internally implemented as a COM interface called IEffectsDj and allows applying and managing special effects to sounds loaded into a player.

See the How to apply special effects to a playing sound section for further details.

The Effects object is implemented through the following properties and methods:

Methods

AutoWahApply

AutoWahIsApplied

AutoWahReset

BassBoostApply

BassBoostIsApplied

BassBoostReset

ChannelsRemapApply

ChannelsRemapIsApplied

ChannelsRemapReset

ChorusApply

ChorusIsApplied

ChorusReset

CompressorApply

CompressorIsApplied

CompressorReset

DcOffsetRemovalEnable

DcOffsetRemovalIsEnabled

DirectXEffectApply

DirectXEffectIsApplied

DirectXEffectReset

DirectXEffectParamsGet

DirectXEffectParamsSet

DistortionApply

DistortionIsApplied

DistortionReset

EchoApply

EchoIsApplied

EchoReset

EqualizerEnable

EqualizerIsEnabled

EqualizerBandAdd

EqualizerBandGainSet

EqualizerBandCountGet

EqualizerBandFrequencyGet

EqualizerBandParamsGet

EqualizerBandParamsSet

EqualizerBandRemove

EqualizerLoadFromFile

EqualizerLoadPresets

EqualizerReset

EqualizerSaveToFile

FilterApply

FilterIsApplied

FilterReset

FilterVocalRemoverApply

FilterVocalRemoverIsApplied

FilterVocalRemoverReset

FreeverbApply

FreeverbIsApplied

FreeverbReset

MPXEnable

MPXIsEnabled

MPXInvertChannels

MPXSetVocalAttenuation

NormalizationEnable

NormalizationIsEnabled

PhaserApply

PhaserIsApplied

PhaserReset

PlaybackPitchGet

PlaybackPitchSet

PlaybackRateGet

PlaybackRateSet

PlaybackTempoGet

PlaybackTempoSet

PlaybackRateRatioGet

PreAmplifierEnable

PreAmplifierIsEnabled

PreAmplifierValueGet

PreAmplifierValueSet

PreAmplifierSpeakerValueGet

PreAmplifierSpeakerValueSet

SoundDirectionEnable

SoundDirectionIsEnabled

SoundDirectionGet

SoundDirectionSet


Effects.AutoWahApply method

Effects.AutoWahApply method

Remarks

Applies an AutoWah effect on the playing song. This DSP effect can be reset through the Effects.AutoWahReset method.

The effect implements the AutoWah by using 4-stage phaser effect which moves a peak in the frequency response up and down the frequency spectrum by amplitude of input signal.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.AutoWahApply (

nPlayer as Integer,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fRate as Single,

fRange as Single,

fFrequency as Single,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.AutoWahApply (

short nPlayer,

short nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fRate,

float fRange,

float fFrequency,

short nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nAffectedChannel

Numeric value that determines the combination of affected channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
CHANNEL_MASK_0 | 1 (0x01) | Channel 0 or left channel
CHANNEL_MASK_1 | 2 (0x02) | Channel 1 or right channel
CHANNEL_MASK_2 | 4 (0x04) | Channel 2
CHANNEL_MASK_3 | 8 (0x08) | Channel 3
CHANNEL_MASK_4 | 16 (0x10) | Channel 4
CHANNEL_MASK_5 | 32 (0x20) | Channel 5
CHANNEL_MASK_6 | 64 (0x40) | Channel 6
CHANNEL_MASK_7 | 128 (0x80) | Channel 7
CHANNEL_MASK_LEFTS | 85 (0x55) | All left channels
CHANNEL_MASK_RIGHTS | 170 (0xAA) | All right channels
CHANNEL_MASK_ALL | 255 (0xFF) | All available channels

fDryMix

Numeric value representing the Dry (unaffected) signal mix.

Supported values are in the range from -2 to +2.

fWetMix

Numeric value representing the Wet (affected) signal mix.

Supported values are in the range from -2 to +2.

fFeedback

Numeric value representing the output signal to feed back into input.

Supported values are in the range from -1 to +1.

fRate

Numeric value representing the rate of sweep expressed in cycles per second.

Supported values are in the range from 0 to 10.

fRange

Numeric value representing the sweep range expressed in octaves.

Supported values are in the range from 0 to 10.

fFrequency

Numeric value representing the base frequency of sweep range.

Supported values are in the range from 0 to 1000.

nPriority

Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

The fDryMix is the volume of input signal & the fWetMix is the volume of delayed signal. The fFeedback sets feedback of AutoWah(phaser). The fRate and fRange control how fast and far the frequency notches move. The fRate is the rate of sweep in cycles per second, fRange is the width of sweep in octaves. And the the fFrequency is the base frequency of sweep.

Below some sample:

Effect type | fDryMix | fWetMix | fFeedback | fRate | fRange | fFrequency
Slow Auto Wah | 0.500 | 1.500 | 0.5 | 2.0 | 4.3 | 50.0
Fast Auto Wah | 0.500 | 1.500 | 0.5 | 5.0 | 5.3 | 50.0
Hi Fast Auto Wah | 0.500 | 1.500 | 0.5 | 5.0 | 4.3 | 500.0

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.AutoWahIsApplied method

Effects.AutoWahIsApplied method

Remarks

Verifies if the AutoWah effect has been applied to the given player through the Effects.AutoWahApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.AutoWahIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.AutoWahIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the effect is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The effect has not been applied
BOOL_TRUE | 1 | The effect has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.AutoWahReset method

Effects.AutoWahReset method

Remarks

Resets the AutoWah effect previously set through a call to the Effects.AutoWahApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.AutoWahReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.AutoWahReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.BassBoostApply method

Effects.BassBoostApply method

Remarks

Applies a DSP effect for boosting bass levels on the playing song. This DSP effect can be reset through the Effects.BassBoostReset method.

When this kind of filter is activated on any of the players instanced by the control, eventual custom DSPs must be set to work with floating point samples through the CustomDSP.UseFloatSamples method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.BassBoostApply (

nPlayer as Integer,

nFrequencyInHz as Long,

fBoostLevelIndB as Single,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.BassBoostApply (

short nPlayer,

long nFrequencyInHz,

float fBoostLevelIndB,

short nPriority

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nFrequencyInHz | Numeric value representing the frequency expressed in Hz. Accepted values range from 0 to 1000.
fBoostLevelIndB | Numeric value representing the Boost level expressed in dB. Accepted values range from 0 to 36.
nPriority | Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.BassBoostIsApplied method

Effects.BassBoostIsApplied method

Remarks

Verifies if the bass boost DSP has been applied to the given player through the Effects.BassBoostApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.BassBoostIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.BassBoostIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the DSP is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The DSP has not been applied
BOOL_TRUE | 1 | The DSP has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.BassBoostReset method

Effects.BassBoostReset method

Remarks

Resets the bass boost DSP previously set through a call to the Effects.BassBoostApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.BassBoostReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.BassBoostReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.ChannelsRemapApply method

Effects.ChannelsRemapApply method

Remarks

Applies a remapping or swapping or mixing of audio channels of the song loaded into the given player. This effect can be reset through the Effects.ChannelsRemapReset method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.ChannelsRemapApply (

nPlayer as Integer,

mapChans as Long,

nChannelsToMap as Integer

) as enumErrorCodes

[C++]

short control.Effects.ChannelsRemapApply (

short nPlayer,

long *mapChans,

short nChannelsToMap

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

mapChans

The map of available channels, can be a combination of the following values:

Mnemonic constant | Value | Meaning
REMAP_CHANNEL_SILENT | 0 | Silence the channel
REMAP_CHANNEL_0 | 1 (0x01) | Channel 0 or left channel
REMAP_CHANNEL_1 | 2 (0x02) | Channel 1 or right channel
REMAP_CHANNEL_2 | 4 (0x04) | Channel 2
REMAP_CHANNEL_3 | 8 (0x08) | Channel 3
REMAP_CHANNEL_4 | 16 (0x10) | Channel 4
REMAP_CHANNEL_5 | 32 (0x20) | Channel 5
REMAP_CHANNEL_6 | 64 (0x40) | Channel 6
REMAP_CHANNEL_7 | 128 (0x80) | Channel 7

nChannelsToMap

Number of channels covered by the map.

Multi-channel order of each channel is as follows:

· 3 channels left-front, right-front, center.
· 4 channels left-front, right-front, left-rear/side, right-rear/side.
· 5 channels left-front, right-front, center, left-rear/side, right-rear/side.
· 6 channels (5.1) left-front, right-front, center, LFE, left-rear/side, right-rear/side.
· 8 channels (7.1) left-front, right-front, center, LFE, left-rear/side, right-rear/side, left-rear center, right-rear center.

The following snippets show some possible combination.

Swapping of left and right stereo channels:

Visual Basic 6

' define the map of channels

Dim mapChannels(2) As Long

mapChannels(0) = enumRemapChannels.REMAP_CHANNEL_1

mapChannels(1) = enumRemapChannels.REMAP_CHANNEL_0

' apply the new map

Amp3dj1.Effects.ChannelsRemapApply Player_1, VarPtr(mapChannels(0)), 2

Visual C++

// define the map of channels

long mapChannels[2];

mapChannels[0] = REMAP_CHANNEL_1;

mapChannels[1] = REMAP_CHANNEL_0;

// apply the new map

Amp3dj1.GetEffects().ChannelsRemapApply (Player_1, mapChannels, 2);

Mixing of left and right stereo channels:

Visual Basic 6

' define the map of channels

Dim mapChannels(2) As Long

mapChannels(0) = enumRemapChannels.REMAP_CHANNEL_0 Or enumRemapChannels.REMAP_CHANNEL_1

mapChannels(1) = enumRemapChannels.REMAP_CHANNEL_0 Or enumRemapChannels.REMAP_CHANNEL_1

' apply the new map

Amp3dj1.Effects.ChannelsRemapApply Player_1, VarPtr(mapChannels(0)), 2

Visual C++

// define the map of channels

long mapChannels[2];

mapChannels[0] = REMAP_CHANNEL_0 | REMAP_CHANNEL_1;

mapChannels[1] = REMAP_CHANNEL_0 | REMAP_CHANNEL_1;

// apply the new map

Amp3dj1.GetEffects().ChannelsRemapApply (Player_1, mapChannels, 2);

Muting of left channel:

Visual Basic 6

' define the map of channels

Dim mapChannels(2) As Long

mapChannels(0) = enumRemapChannels.REMAP_CHANNEL_SILENT

mapChannels(1) = enumRemapChannels.REMAP_CHANNEL_1

' apply the new map

Amp3dj1.Effects.ChannelsRemapApply Player_1, VarPtr(mapChannels(0)), 2

Visual C++

// define the map of channels

long mapChannels[2];

mapChannels[0] = REMAP_CHANNEL_SILENT;

mapChannels[1] = REMAP_CHANNEL_1;

// apply the new map

Amp3dj1.GetEffects().ChannelsRemapApply (Player_1, mapChannels, 2);

Swapping of front and rear channels on a 4 channels song:

Visual Basic 6

' define the map of channels

Dim mapChannels(4) As Long

mapChannels(0) = enumRemapChannels.REMAP_CHANNEL_2

mapChannels(1) = enumRemapChannels.REMAP_CHANNEL_3

mapChannels(2) = enumRemapChannels.REMAP_CHANNEL_0

mapChannels(3) = enumRemapChannels.REMAP_CHANNEL_1

' apply the new map

Amp3dj1.Effects.ChannelsRemapApply Player_1, VarPtr(mapChannels(0)), 4

Visual C++

// define the map of channels

long mapChannels[4];

mapChannels[0] = REMAP_CHANNEL_2;

mapChannels[1] = REMAP_CHANNEL_3;

mapChannels[2] = REMAP_CHANNEL_0;

mapChannels[3] = REMAP_CHANNEL_1;

// apply the new map

Amp3dj1.GetEffects().ChannelsRemapApply (Player_1, mapChannels, 4);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.ChannelsRemapIsApplied method

Effects.ChannelsRemapIsApplied method

Remarks

Verifies if the channels remapping effect has been applied to the given player through the Effects.ChannelsRemapApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.ChannelsRemapIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.ChannelsRemapIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the effect is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The effect has not been applied
BOOL_TRUE | 1 | The effect has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.ChannelsRemapReset method

Effects.ChannelsRemapReset method

Remarks

Resets the channels remapping effect previously set through a call to the Effects.ChannelsRemapApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.ChannelsRemapReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.ChannelsRemapReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.ChorusApply method

Effects.ChorusApply method

Remarks

Applies a chorus effect on the playing song. This effect can be reset through the Effects.ChorusReset method.

True vintage chorus works the same way as flanging. It mixes a varying delayed signal with the original to produce a large number of harmonically related notches in the frequency response. Chorus uses a longer delay than flanging, so there is a perception of "spaciousness", although the delay is too short to hear as a distinct slap-back echo. There is also little or no feedback, so the effect is more subtle.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.ChorusApply (

nPlayer as Integer,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fMinSweep as Single,

fMaxSweep as Single,

fRate as Single,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.ChorusApply (

short nPlayer,

short nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fMinSweep,

float fMaxSweep,

float fRate,

short nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nAffectedChannel

Numeric value that determines the combination of affected channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
CHANNEL_MASK_0 | 1 (0x01) | Channel 0 or left channel
CHANNEL_MASK_1 | 2 (0x02) | Channel 1 or right channel
CHANNEL_MASK_2 | 4 (0x04) | Channel 2
CHANNEL_MASK_3 | 8 (0x08) | Channel 3
CHANNEL_MASK_4 | 16 (0x10) | Channel 4
CHANNEL_MASK_5 | 32 (0x20) | Channel 5
CHANNEL_MASK_6 | 64 (0x40) | Channel 6
CHANNEL_MASK_7 | 128 (0x80) | Channel 7
CHANNEL_MASK_LEFTS | 85 (0x55) | All left channels
CHANNEL_MASK_RIGHTS | 170 (0xAA) | All right channels
CHANNEL_MASK_ALL | 255 (0xFF) | All available channels

fDryMix

Numeric value representing the Dry (unaffected) signal mix.

Supported values are in the range from -2 to +2.

fWetMix

Numeric value representing the Wet (affected) signal mix.

Supported values are in the range from -2 to +2.

fFeedback

Numeric value representing the output signal to feed back into input.

Supported values are in the range from -1 to +1.

fMinSweep

Numeric value representing the minimum delay expressed in milliseconds.

Supported values are in the range from 0 to 6000.

fMaxSweep

Numeric value representing the maximum delay expressed in milliseconds.

Supported values are in the range from 0 to 6000.

fRate

Numeric value representing the rate of delay change in milliseconds per second.

Supported values are in the range from 0 to 1000.

nPriority

Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

The fDryMix is the volume of input signal and the fWetMix is the volume of delayed signal. The fFeedback sets feedback of chorus. The fRate, fMinSweep and fMaxSweep parameters control how fast and far the frequency notches move. The fRate is the rate of delay change in milliseconds per second, fMaxSweep-fMinSweep is the range or width of sweep in milliseconds.

Below some sample:

Effect type | fDryMix | fWetMix | fFeedback | fMinSweep | fMaxSweep | fRate
Flanger | 1.0 | 0.35 | 0.5 | 1.0 | 5.0 | 1.0
Exaggerated chorus leads to multiple pitch shifted voices | 0.7 | 0.25 | 0.5 | 1.0 | 200.0 | 50.0
Motorcycle | 0.9 | 0.45 | 0.5 | 1.0 | 100.0 | 25.0
Devil | 0.9 | 0.35 | 0.5 | 1.0 | 50.0 | 200.0
Who say that there are not many voices? | 0.9 | 0.35 | 0.5 | 1.0 | 400.0 | 200.0
Back chipmunk | 0.9 | -0.2 | 0.5 | 1.0 | 400.0 | 400.0
Water | 0.9 | -0.4 | 0.5 | 1.0 | 2.0 | 1.0
This is the airplane | 0.3 | 0.4 | 0.5 | 1.0 | 10.0 | 5.0

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.ChorusIsApplied method

Effects.ChorusIsApplied method

Remarks

Verifies if the chorus effect has been applied to the given player through the Effects.ChorusApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.ChorusIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.ChorusIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the effect is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The effect has not been applied
BOOL_TRUE | 1 | The effect has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.ChorusReset method

Effects.ChorusReset method

Remarks

Resets the chorus effect previously set through a call to the Effects.ChorusApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.ChorusReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.ChorusReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.CompressorApply method

Effects.CompressorApply method

Remarks

Applies a compressor effect on the playing song. This effect can be reset through the Effects.CompressorReset method.

Compressors are commonly used in recording to control the level, by making loud passages quieter, and quiet passages louder. This is useful in allowing a vocalist to sing quiet and loud for different emphasis, and always be heard clearly in the mix. Compression is generally applied to guitar to give clean sustain, where the start of a note is "squashed" with the gain automatically increased as the not fades away. Compressors take a short time to react to a picked note, and it can be difficult to find settings that react quickly enough to the volume change without killing the natural attack sound of your guitar.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.CompressorApply (

nPlayer as Integer,

nAffectedChannel as enumChannelMasks,

fGain as Single,

fThreshold as Single,

fRatio as Single,

fAttack as Single,

fRelease as Single,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.CompressorApply (

short nPlayer,

short nAffectedChannel,

float fGain,

float fThreshold,

float fRatio,

float fAttack,

float fRelease,

short nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nAffectedChannel

Numeric value that determines the combination of affected channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
CHANNEL_MASK_0 | 1 (0x01) | Channel 0 or left channel
CHANNEL_MASK_1 | 2 (0x02) | Channel 1 or right channel
CHANNEL_MASK_2 | 4 (0x04) | Channel 2
CHANNEL_MASK_3 | 8 (0x08) | Channel 3
CHANNEL_MASK_4 | 16 (0x10) | Channel 4
CHANNEL_MASK_5 | 32 (0x20) | Channel 5
CHANNEL_MASK_6 | 64 (0x40) | Channel 6
CHANNEL_MASK_7 | 128 (0x80) | Channel 7
CHANNEL_MASK_LEFTS | 85 (0x55) | All left channels
CHANNEL_MASK_RIGHTS | 170 (0xAA) | All right channels
CHANNEL_MASK_ALL | 255 (0xFF) | All available channels

fGain

Numeric value representing the output gain of signal after compression expressed in dB.

Supported values are in the range from -60 to +60. The default value is 0 dB.

fThreshold

Numeric value representing the point at which compression begins expressed in dB.

Supported values are in the range from -60 to 0. The default value is -15 dB.

fRatio

Numeric value representing the compression ratio.

Supported values start from 1. The default value is 3, which means 3:1 compression.

fAttack

Numeric value representing the time before compression reaches its full value expressed in milliseconds.

Supported values are in the range from 0.01 to 1000. The default value is 10 ms.

fRelease

Numeric value representing the speed, expressed in milliseconds, at which compression is stopped after input drops below fThreshold.

Supported values are in the range from 0.01 to 5000. The default value is 200 ms.

nPriority

Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.CompressorIsApplied method

Effects.CompressorIsApplied method

Remarks

Verifies if the compressor effect has been applied to the given player through the Effects.CompressorApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.CompressorIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.CompressorIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the effect is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The effect has not been applied
BOOL_TRUE | 1 | The effect has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.CompressorReset method

Effects.CompressorReset method

Remarks

Resets the compressor effect previously set through a call to the Effects.CompressorApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.CompressorReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.CompressorReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.DcOffsetRemovalEnable method

Effects.DcOffsetRemovalEnable method

Remarks

Enables/disables real-time DC offset removal of songs in playback.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DcOffsetRemovalEnable (

nPlayer as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.DcOffsetRemovalEnable (

short nPlayer,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value that specifies if DC offset removal must be enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Disables DC Offset removal
BOOL_TRUE | 1 | Enables DC Offset removal

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.DcOffsetRemovalIsEnabled method

Effects.DcOffsetRemovalIsEnabled method

Remarks

Verifies if real-time DC offset removal effect has been enabled on the given player through the Effects.DcOffsetRemovalEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DcOffsetRemovalIsEnabled (

nPlayer as Integer,

bEnabled as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.DcOffsetRemovalIsEnabled (

short nPlayer,

long *bEnabled

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnabled

Reference that, on return from the method call, will contain the boolean value specifying if the effect is currently enabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Real-time DC offset removal is not enabled
BOOL_TRUE | 1 | Real-time DC offset removal is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.DirectXEffectApply method

Effects.DirectXEffectApply method

Remarks

Applies a specific DMO (DirectX Media Object) effect to the playing sound. Parameters related to the chosen effect can be retrieved through the Effects.DirectXEffectParamsGet method and modified through the Effects.DirectXEffectParamsSet method.

The same DMO effect can be removed through the Effects.DirectXEffectReset method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Avail method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DirectXEffectApply (

nPlayer as Integer,

nEffect as enumDirectXEffects,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.DirectXEffectApply (

short nPlayer,

short nEffect,

short nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nEffect

Numeric value that determines the effect to apply.

Supported values are the following:

Mnemonic constant | Value | Meaning
DX_CHORUS | 0 | Chorus
DX_COMPRESSOR | 1 | Compressor
DX_DISTORTION | 2 | Distortion
DX_ECHO | 3 | Echo
DX_FLANGER | 4 | Flanger
DX_GARGLE | 5 | Gargle
DX_I3DL2REVERB | 6 | I3DL2 environmental reverb
DX_REVERB | 8 | Wave reverb

nPriority

Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

Return value

Value | Meaning
enumErrorCodes.ERR_NOERROR (0) | The call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


Effects.DirectXEffectIsApplied method

Effects.DirectXEffectIsApplied method

Remarks

Verifies if the given DMO effect has been applied to the given player through the Effects.DirectXEffectApply method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Avail method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DirectXEffectIsApplied (

nPlayer as Integer,

nEffect as enumDirectXEffects,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.DirectXEffectIsApplied (

short nPlayer,

short nEffect,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nEffect

Numeric value that determines the effect to retrieve.

Supported values are the following:

Mnemonic constant | Value | Meaning
DX_CHORUS | 0 | Chorus
DX_COMPRESSOR | 1 | Compressor
DX_DISTORTION | 2 | Distortion
DX_ECHO | 3 | Echo
DX_FLANGER | 4 | Flanger
DX_GARGLE | 5 | Gargle
DX_I3DL2REVERB | 6 | I3DL2 environmental reverb
DX_REVERB | 8 | Reverb

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the given effect is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The given effect has not been applied
BOOL_TRUE | 1 | The given effect has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.DirectXEffectParamsGet method

Effects.DirectXEffectParamsGet method

Remarks

Retrieves parameters related to the chosen effect. These parameters can be changed using the Effects.DirectXEffectParamsSet method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Avail method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DirectXEffectParamsGet (

nPlayer as Integer,

nEffect as enumDirectXEffects,

pParamData as Long

) as enumErrorCodes

[C++]

short control.Effects.DirectXEffectParamsGet (

short nPlayer,

short nEffect,

void *pParamData

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nEffect

Numeric value that determines the effect parameters to retrieve.

Supported values are the following:

Mnemonic constant | Value | Meaning
DX_CHORUS | 0 | Chorus
DX_COMPRESSOR | 1 | Compressor
DX_DISTORTION | 2 | Distortion
DX_ECHO | 3 | Echo
DX_FLANGER | 4 | Flanger
DX_GARGLE | 5 | Gargle
DX_I3DL2REVERB | 6 | I3DL2 environmental reverb
DX_REVERB | 8 | Reverb

pParamData

Address of a structure that receives the effect parameters: the passed structure must be directly related to the chosen effect as in the table below.

NOTE: DirectX related data structures are usually defined inside the Platform SDK dsound.h header file. For Visual Basic users convenience, we have provided a DirectSound.bas module containing the definitions of these structures and some of the Mnemonic constant definitions that can be used inside your code: this module can be found inside the product Include directory (default C:\Program Files\Active DJ Studio\include).

Effect

Related DirectX structure

DX_CHORUS

The DSFXChorus structure contains parameters for a chorus effect.

typedef struct _DSFXChorus {

FLOAT   fWetDryMix;

FLOAT   fDepth;

FLOAT   fFeedback;

FLOAT   fFrequency;

LONG   lWaveform;

FLOAT   fDelay;

LONG   lPhase;

} DSFXChorus, *LPDSFXChorus;

fWetDryMix

Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXCHORUS_WETDRYMIX_MIN through DSFXCHORUS_WETDRYMIX_MAX (all wet). The default value is 50.

fDepth

Percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Must be in the range from DSFXCHORUS_DEPTH_MIN through DSFXCHORUS_DEPTH_MAX. The default value is 10.

fFeedback

Percentage of output signal to feed back into the effect's input, in the range from DSFXCHORUS_FEEDBACK_MIN to DSFXCHORUS_FEEDBACK_MAX. The default value is 25.

fFrequency

Frequency of the LFO, in the range from DSFXCHORUS_FREQUENCY_MIN to DSFXCHORUS_FREQUENCY_MAX. The default value is 1.1.

lWaveform

Waveform of the LFO. Defined values are DSFXCHORUS_WAVE_TRIANGLE and DSFXCHORUS_WAVE_SIN. By default, the waveform is a sine.

fDelay

Number of milliseconds the input is delayed before it is played back, in the range from DSFXCHORUS_DELAY_MIN to DSFXCHORUS_DELAY_MAX. The default value is 16 ms.

lPhase

Phase differential between left and right LFOs, in the range from DSFXCHORUS_PHASE_MIN through DSFXCHORUS_PHASE_MAX. Possible values are defined as follows.

Value

DSFXCHORUS_PHASE_NEG_180

DSFXCHORUS_PHASE_NEG_90

DSFXCHORUS_PHASE_ZERO

DSFXCHORUS_PHASE_90

DSFXCHORUS_PHASE_180

DX_COMPRESSOR

The DSFXCompressor structure contains parameters for a compression effect.

typedef struct _DSFXCompressor {

FLOAT fGain;

FLOAT fAttack;

FLOAT fRelease;

FLOAT fThreshold;

FLOAT fRatio;

FLOAT fPredelay;

} DSFXCompressor, *LPDSFXCompressor;

fGain

Output gain of signal after compression, in the range from DSFXCOMPRESSOR_GAIN_MIN to DSFXCOMPRESSOR_GAIN_MAX. The default value is 0 dB.

fAttack

Time before compression reaches its full value, in the range from DSFXCOMPRESSOR_ATTACK_MIN to DSFXCOMPRESSOR_ATTACK_MAX. The default value is 10 ms.

fRelease

Speed at which compression is stopped after input drops below fThreshold, in the range from DSFXCOMPRESSOR_RELEASE_MIN to DSFXCOMPRESSOR_RELEASE_MAX. The default value is 200 ms.

fThreshold

Point at which compression begins, in decibels, in the range from DSFXCOMPRESSOR_THRESHOLD_MIN to DSFXCOMPRESSOR_THRESHOLD_MAX. The default value is -20 dB.

fRatio

Compression ratio, in the range from DSFXCOMPRESSOR_RATIO_MIN to DSFXCOMPRESSOR_RATIO_MAX. The default value is 3, which means 3:1 compression.

fPredelay

Time after lThreshold is reached before attack phase is started, in milliseconds, in the range from DSFXCOMPRESSOR_PREDELAY_MIN to DSFXCOMPRESSOR_PREDELAY_MAX. The default value is 4 ms.

DX_DISTORTION

The DSFXDistortion structure contains parameters for a distortion effect.

typedef struct _DSFXDistortion {

FLOAT fGain;

FLOAT fEdge;

FLOAT fPostEQCenterFrequency;

FLOAT fPostEQBandwidth;

FLOAT fPreLowpassCutoff;

} DSFXDistortion, *LPDSFXDistortion;

fGain

Amount of signal change after distortion, in the range from DSFXDISTORTION_GAIN_MIN through DSFXDISTORTION_GAIN_MAX. The default value is -18 dB.

fEdge

Percentage of distortion intensity, in the range in the range from DSFXDISTORTION_EDGE_MIN through DSFXDISTORTION_EDGE_MAX. The default value is 15 percent.

fPostEQCenterFrequency

Center frequency of harmonic content addition, in the range from DSFXDISTORTION_POSTEQCENTERFREQUENCY_MIN through DSFXDISTORTION_POSTEQCENTERFREQUENCY_MAX. The default value is 2400 Hz.

fPostEQBandwidth

Width of frequency band that determines range of harmonic content addition, in the range from DSFXDISTORTION_POSTEQBANDWIDTH_MIN through DSFXDISTORTION_POSTEQBANDWIDTH_MAX. The default value is 2400 Hz.

fPreLowpassCutoff

Filter cutoff for high-frequency harmonics attenuation, in the range from DSFXDISTORTION_PRELOWPASSCUTOFF_MIN through DSFXDISTORTION_PRELOWPASSCUTOFF_MAX. The default value is 8000 Hz.

DX_ECHO

The DSFXEcho structure contains parameters for an echo effect.

typedef struct _DSFXEcho {

FLOAT fWetDryMix;

FLOAT fFeedback;

FLOAT fLeftDelay;

FLOAT fRightDelay;

LONG   lPanDelay;

} DSFXEcho, *LPDSFXEcho;

fWetDryMix

Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXECHO_WETDRYMIX_MIN through DSFXECHO_WETDRYMIX_MAX (all wet). The default value is 50.

fFeedback

Percentage of output fed back into input, in the range from DSFXECHO_FEEDBACK_MIN through DSFXECHO_FEEDBACK_MAX. The default value is 50.

fLeftDelay

Delay for left channel, in milliseconds, in the range from DSFXECHO_LEFTDELAY_MIN through DSFXECHO_LEFTDELAY_MAX. The default value is 500 ms.

fRightDelay

Delay for right channel, in milliseconds, in the range from DSFXECHO_RIGHTDELAY_MIN through DSFXECHO_RIGHTDELAY_MAX. The default value is 500 ms.

lPanDelay

Value that specifies whether to swap left and right delays with each successive echo. The default value is zero, meaning no swap. Possible values are defined as DSFXECHO_PANDELAY_MIN (equivalent to FALSE) and DSFXECHO_PANDELAY_MAX (equivalent to TRUE).

DX_FLANGER

The DSFXFlanger structure contains parameters for a flange effect.

typedef struct _DSFXFlanger {

FLOAT fWetDryMix;

FLOAT fDepth;

FLOAT fFeedback;

FLOAT fFrequency;

LONG   lWaveform;

FLOAT fDelay;

LONG   lPhase;

} DSFXFlanger, *LPDSFXFlanger;

fWetDryMix

Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXFLANGER_WETDRYMIX_MIN through DSFXFLANGER_WETDRYMIX_MAX (all wet). The default value is 50.

fDepth

Percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Must be in the range from DSFXFLANGER_DEPTH_MIN through DSFXFLANGER_DEPTH_MAX. The default value is 100.

fFeedback

Percentage of output signal to feed back into the effect's input, in the range from DSFXFLANGER_FEEDBACK_MIN to DSFXFLANGER_FEEDBACK_MAX. The default value is -50.

fFrequency

Frequency of the LFO, in the range from DSFXFLANGER_FREQUENCY_MIN to DSFXFLANGER_FREQUENCY_MAX. The default value is 0.25.

lWaveform

Waveform of the LFO. By default, the waveform is a sine. Possible values are the following.

- DSFXFLANGER_WAVE_TRIANGLE

- DSFXFLANGER_WAVE_SIN

fDelay

Number of milliseconds the input is delayed before it is played back, in the range from DSFXFLANGER_DELAY_MIN to DSFXFLANGER_DELAY_MAX. The default value is 2 ms.

lPhase

Phase differential between left and right LFOs, in the range from DSFXFLANGER_PHASE_MIN through DSFXFLANGER_PHASE_MAX. Possible values are the following:

- DSFXFLANGER_PHASE_NEG_180

- DSFXFLANGER_PHASE_NEG_90

- DSFXFLANGER_PHASE_ZERO

- DSFXFLANGER_PHASE_90

- DSFXFLANGER_PHASE_180

The default value is DSFXFLANGER_PHASE_ZERO.

DX_GARGLE

The DSFXGargle structure contains parameters for an amplitude modulation effect.

typedef struct _DSFXGargle {

DWORD dwRateHz;

DWORD dwWaveShape;

} DSFXGargle, *LPDSFXGargle;

dwRateHz

Rate of modulation, in Hertz. Must be in the range from DSFXGARGLE_RATEHZ_MIN through DSFXGARGLE_RATEHZ_MAX. The default value is 20.

dwWaveShape

Shape of the modulation wave. The following values are defined:

DSFXGARGLE_WAVE_TRIANGLE

DSFXGARGLE_WAVE_SQUARE

The default value is DSFXGARGLE_WAVE_TRIANGLE.

DX_I3DL2REVERB

The DSFXI3DL2Reverb structure contains parameters for an I3DL2 (Interactive 3D Audio Level 2) reverberation effect.

typedef struct _DSFXI3DL2Reverb {

LONG lRoom;

LONG lRoomHF;

FLOAT flRoomRolloffFactor;

FLOAT flDecayTime;

FLOAT flDecayHFRatio;

LONG lReflections;

FLOAT flReflectionsDelay;

LONG lReverb;

FLOAT flReverbDelay;

FLOAT flDiffusion;

FLOAT flDensity;

FLOAT flHFReference;

} DSFXI3DL2Reverb, *LPDSFXI3DL2Reverb;

lRoom

Attenuation of the room effect, in millibels (mB), in the range from DSFX_I3DL2REVERB_ROOM_MIN to DSFX_I3DL2REVERB_ROOM_MAX. The default value is DSFX_I3DL2REVERB_ROOM_DEFAULT, or -1000 mB.

lRoomHF

Attenuation of the room high-frequency effect, in mB, in the range from DSFX_I3DL2REVERB_ROOMHF_MIN to DSFX_I3DL2REVERB_ROOMHF_MAX. The default value is DSFX_I3DL2REVERB_ROOMHF_DEFAULT, or -100 mB.

flRoomRolloffFactor

Rolloff factor for the reflected signals, in the range from DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MIN to DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MAX. The default value is DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_DEFAULT, or 0.0. The rolloff factor for the direct path is controlled by the DirectSound listener.

flDecayTime

Decay time, in seconds, in the range from DSFX_I3DL2REVERB_DECAYTIME_MIN to DSFX_I3DL2REVERB_DECAYTIME_MAX. The default value is DSFX_I3DL2REVERB_DECAYTIME_DEFAULT, or 1.49 second.

flDecayHFRatio

Ratio of the decay time at high frequencies to the decay time at low frequencies, in the range from DSFX_I3DL2REVERB_DECAYHFRATIO_MIN to DSFX_I3DL2REVERB_DECAYHFRATIO_MAX. The default value is DSFX_I3DL2REVERB_DECAYHFRATIO_DEFAULT, or 0.83.

lReflections

Attenuation of early reflections relative to lRoom, in mB, in the range from DSFX_I3DL2REVERB_REFLECTIONS_MIN to DSFX_I3DL2REVERB_REFLECTIONS_MAX. The default value is DSFX_I3DL2REVERB_REFLECTIONS_DEFAULT, or -2602 mB.

flReflectionsDelay

Delay time of the first reflection relative to the direct path, in seconds, in the range from DSFX_I3DL2REVERB_REFLECTIONSDELAY_MIN to DSFX_I3DL2REVERB_REFLECTIONSDELAY_DEFAULT. The default value is 0.007 seconds.

lReverb

Attenuation of late reverberation relative to lRoom, in mB, in the range -from DSFX_I3DL2REVERB_REVERB_MIN to DSFX_I3DL2REVERB_REVERB_MAX. The default value is DSFX_I3DL2REVERB_REVERB_DEFAULT, or 200 mB.

flReverbDelay

Time limit between the early reflections and the late reverberation relative to the time of the first reflection, in seconds, in the range from DSFX_I3DL2REVERB_REVERBDELAY_MIN to DSFX_I3DL2REVERB_REVERBDELAY_MAX. The default value is DSFX_I3DL2REVERB_REVERBDELAY_DEFAULT, or 0.011 seconds.

flDiffusion

Echo density in the late reverberation decay, in percent, in the range from DSFX_I3DL2REVERB_DIFFUSION_MIN to DSFX_I3DL2REVERB_DIFFUSION_MAX. The default value is DSFX_I3DL2REVERB_DIFFUSION_DEFAULT, or 100.0 percent.

flDensity

Modal density in the late reverberation decay, in percent, in the range from DSFX_I3DL2REVERB_DENSITY_MIN to DSFX_I3DL2REVERB_DENSITY_MAX. The default value is DSFX_I3DL2REVERB_DENSITY_DEFAULT, or 100.0 percent.

flHFReference

Reference high frequency, in hertz, in the range from DSFX_I3DL2REVERB_HFREFERENCE_MIN to DSFX_I3DL2REVERB_HFREFERENCE_MAX. The default value is DSFX_I3DL2REVERB_HFREFERENCE_DEFAULT, or 5000.0 Hz.

DX_PARAMEQ

The DSFXParamEq structure contains parameters for a parametric equalizer effect.

typedef struct _DSFXParamEq {

FLOAT fCenter;

FLOAT fBandwidth;

FLOAT fGain;

} DSFXParamEq, *LPDSFXParamEq;

fCenter

Center frequency, in hertz, in the range from DSFXPARAMEQ_CENTER_MIN to DSFXPARAMEQ_CENTER_MAX. This value cannot exceed one-third of the frequency of the buffer. The default value is 8000.

fBandwidth

Bandwidth, in semitones, in the range from DSFXPARAMEQ_BANDWIDTH_MIN to DSFXPARAMEQ_BANDWIDTH_MAX. The default value is 12.

fGain

Gain, in the range from DSFXPARAMEQ_GAIN_MIN to DSFXPARAMEQ_GAIN_MAX. The default value is 0.

DX_REVERB

The DSFXWavesReverb structure contains parameters for a Waves reverberation effect.

typedef struct _DSFXWavesReverb {

FLOAT fInGain;

FLOAT fReverbMix;

FLOAT fReverbTime;

FLOAT fHighFreqRTRatio;

} DSFXWavesReverb, *LPDSFXWavesReverb;

fInGain

Input gain of signal, in decibels (dB), in the range from DSFX_WAVESREVERB_INGAIN_MIN through DSFX_WAVESREVERB_INGAIN_MAX. The default value is DSFX_WAVESREVERB_INGAIN_DEFAULT, or 0 dB.

fReverbMix

Reverb mix, in dB, in the range from DSFX_WAVESREVERB_REVERBMIX_MIN through DSFX_WAVESREVERB_REVERBMIX_MAX. The default value is DSFX_WAVESREVERB_REVERBMIX_DEFAULT, or 0 dB.

fReverbTime

Reverb time, in milliseconds, in the range from DSFX_WAVESREVERB_REVERBTIME_MIN through DSFX_WAVESREVERB_REVERBTIME_MAX. The default value is DSFX_WAVESREVERB_REVERBTIME_DEFAULT, or 1000.

fHighFreqRTRatio

In the range from DSFX_WAVESREVERB_HIGHFREQRTRATIO_MIN through DSFX_WAVESREVERB_HIGHFREQRTRATIO_MAX. The default value is DSFX_WAVESREVERB_HIGHFREQRTRATIO_DEFAULT, or 0.001.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


Effects.DirectXEffectParamsSet method

Effects.DirectXEffectParamsSet method

Remarks

Sets the parameters related to the chosen effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGet method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Avail method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DirectXEffectParamsSet (

nPlayer as Integer,

nEffect as enumDirectXEffects,

pParamData as Long

) as enumErrorCodes

[C++]

short control.Effects.DirectXEffectParamsSet (

short nPlayer,

short nEffect,

void *pParamData

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nEffect

Numeric value that determines the effect parameters to apply.

Supported values are the following:

Mnemonic constant | Value | Meaning
DX_CHORUS | 0 | Chorus
DX_COMPRESSOR | 1 | Compressor
DX_DISTORTION | 2 | Distortion
DX_ECHO | 3 | Echo
DX_FLANGER | 4 | Flanger
DX_GARGLE | 5 | Gargle
DX_I3DL2REVERB | 6 | I3DL2 environmental reverb
DX_REVERB | 8 | Reverb

pParamData

Address of a structure that contains the effect parameters to apply: the passed structure must be directly related to the chosen effect as in the table below.

NOTE: DirectX related data structures are usually defined inside the Platform SDK dsound.h header file. For Visual Basic users convenience, we have provided a DirectSound.bas module containing the definitions of these structures and some of the Mnemonic constant definitions that can be used inside your code: this module can be found inside the product Include directory (default C:\Program Files\Active DJ Studio\include).

Effect

Related DirectX structure

DX_CHORUS

The DSFXChorus structure contains parameters for a chorus effect.

typedef struct _DSFXChorus {

FLOAT   fWetDryMix;

FLOAT   fDepth;

FLOAT   fFeedback;

FLOAT   fFrequency;

LONG   lWaveform;

FLOAT   fDelay;

LONG   lPhase;

} DSFXChorus, *LPDSFXChorus;

fWetDryMix

Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXCHORUS_WETDRYMIX_MIN through DSFXCHORUS_WETDRYMIX_MAX (all wet). The default value is 50.

fDepth

Percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Must be in the range from DSFXCHORUS_DEPTH_MIN through DSFXCHORUS_DEPTH_MAX. The default value is 10.

fFeedback

Percentage of output signal to feed back into the effect's input, in the range from DSFXCHORUS_FEEDBACK_MIN to DSFXCHORUS_FEEDBACK_MAX. The default value is 25.

fFrequency

Frequency of the LFO, in the range from DSFXCHORUS_FREQUENCY_MIN to DSFXCHORUS_FREQUENCY_MAX. The default value is 1.1.

lWaveform

Waveform of the LFO. Defined values are DSFXCHORUS_WAVE_TRIANGLE and DSFXCHORUS_WAVE_SIN. By default, the waveform is a sine.

fDelay

Number of milliseconds the input is delayed before it is played back, in the range from DSFXCHORUS_DELAY_MIN to DSFXCHORUS_DELAY_MAX. The default value is 16 ms.

lPhase

Phase differential between left and right LFOs, in the range from DSFXCHORUS_PHASE_MIN through DSFXCHORUS_PHASE_MAX. Possible values are defined as follows.

Value

DSFXCHORUS_PHASE_NEG_180

DSFXCHORUS_PHASE_NEG_90

DSFXCHORUS_PHASE_ZERO

DSFXCHORUS_PHASE_90

DSFXCHORUS_PHASE_180

DX_COMPRESSOR

The DSFXCompressor structure contains parameters for a compression effect.

typedef struct _DSFXCompressor {

FLOAT fGain;

FLOAT fAttack;

FLOAT fRelease;

FLOAT fThreshold;

FLOAT fRatio;

FLOAT fPredelay;

} DSFXCompressor, *LPDSFXCompressor;

fGain

Output gain of signal after compression, in the range from DSFXCOMPRESSOR_GAIN_MIN to DSFXCOMPRESSOR_GAIN_MAX. The default value is 0 dB.

fAttack

Time before compression reaches its full value, in the range from DSFXCOMPRESSOR_ATTACK_MIN to DSFXCOMPRESSOR_ATTACK_MAX. The default value is 10 ms.

fRelease

Speed at which compression is stopped after input drops below fThreshold, in the range from DSFXCOMPRESSOR_RELEASE_MIN to DSFXCOMPRESSOR_RELEASE_MAX. The default value is 200 ms.

fThreshold

Point at which compression begins, in decibels, in the range from DSFXCOMPRESSOR_THRESHOLD_MIN to DSFXCOMPRESSOR_THRESHOLD_MAX. The default value is -20 dB.

fRatio

Compression ratio, in the range from DSFXCOMPRESSOR_RATIO_MIN to DSFXCOMPRESSOR_RATIO_MAX. The default value is 3, which means 3:1 compression.

fPredelay

Time after lThreshold is reached before attack phase is started, in milliseconds, in the range from DSFXCOMPRESSOR_PREDELAY_MIN to DSFXCOMPRESSOR_PREDELAY_MAX. The default value is 4 ms.

DX_DISTORTION

The DSFXDistortion structure contains parameters for a distortion effect.

typedef struct _DSFXDistortion {

FLOAT fGain;

FLOAT fEdge;

FLOAT fPostEQCenterFrequency;

FLOAT fPostEQBandwidth;

FLOAT fPreLowpassCutoff;

} DSFXDistortion, *LPDSFXDistortion;

fGain

Amount of signal change after distortion, in the range from DSFXDISTORTION_GAIN_MIN through DSFXDISTORTION_GAIN_MAX. The default value is -18 dB.

fEdge

Percentage of distortion intensity, in the range in the range from DSFXDISTORTION_EDGE_MIN through DSFXDISTORTION_EDGE_MAX. The default value is 15 percent.

fPostEQCenterFrequency

Center frequency of harmonic content addition, in the range from DSFXDISTORTION_POSTEQCENTERFREQUENCY_MIN through DSFXDISTORTION_POSTEQCENTERFREQUENCY_MAX. The default value is 2400 Hz.

fPostEQBandwidth

Width of frequency band that determines range of harmonic content addition, in the range from DSFXDISTORTION_POSTEQBANDWIDTH_MIN through DSFXDISTORTION_POSTEQBANDWIDTH_MAX. The default value is 2400 Hz.

fPreLowpassCutoff

Filter cutoff for high-frequency harmonics attenuation, in the range from DSFXDISTORTION_PRELOWPASSCUTOFF_MIN through DSFXDISTORTION_PRELOWPASSCUTOFF_MAX. The default value is 8000 Hz.

DX_ECHO

The DSFXEcho structure contains parameters for an echo effect.

typedef struct _DSFXEcho {

FLOAT fWetDryMix;

FLOAT fFeedback;

FLOAT fLeftDelay;

FLOAT fRightDelay;

LONG   lPanDelay;

} DSFXEcho, *LPDSFXEcho;

fWetDryMix

Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXECHO_WETDRYMIX_MIN through DSFXECHO_WETDRYMIX_MAX (all wet). The default value is 50.

fFeedback

Percentage of output fed back into input, in the range from DSFXECHO_FEEDBACK_MIN through DSFXECHO_FEEDBACK_MAX. The default value is 50.

fLeftDelay

Delay for left channel, in milliseconds, in the range from DSFXECHO_LEFTDELAY_MIN through DSFXECHO_LEFTDELAY_MAX. The default value is 500 ms.

fRightDelay

Delay for right channel, in milliseconds, in the range from DSFXECHO_RIGHTDELAY_MIN through DSFXECHO_RIGHTDELAY_MAX. The default value is 500 ms.

lPanDelay

Value that specifies whether to swap left and right delays with each successive echo. The default value is zero, meaning no swap. Possible values are defined as DSFXECHO_PANDELAY_MIN (equivalent to FALSE) and DSFXECHO_PANDELAY_MAX (equivalent to TRUE).

DX_FLANGER

The DSFXFlanger structure contains parameters for a flange effect.

typedef struct _DSFXFlanger {

FLOAT fWetDryMix;

FLOAT fDepth;

FLOAT fFeedback;

FLOAT fFrequency;

LONG   lWaveform;

FLOAT fDelay;

LONG   lPhase;

} DSFXFlanger, *LPDSFXFlanger;

fWetDryMix

Ratio of wet (processed) signal to dry (unprocessed) signal. Must be in the range from DSFXFLANGER_WETDRYMIX_MIN through DSFXFLANGER_WETDRYMIX_MAX (all wet). The default value is 50.

fDepth

Percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Must be in the range from DSFXFLANGER_DEPTH_MIN through DSFXFLANGER_DEPTH_MAX. The default value is 100.

fFeedback

Percentage of output signal to feed back into the effect's input, in the range from DSFXFLANGER_FEEDBACK_MIN to DSFXFLANGER_FEEDBACK_MAX. The default value is -50.

fFrequency

Frequency of the LFO, in the range from DSFXFLANGER_FREQUENCY_MIN to DSFXFLANGER_FREQUENCY_MAX. The default value is 0.25.

lWaveform

Waveform of the LFO. By default, the waveform is a sine. Possible values are the following.

- DSFXFLANGER_WAVE_TRIANGLE

- DSFXFLANGER_WAVE_SIN

fDelay

Number of milliseconds the input is delayed before it is played back, in the range from DSFXFLANGER_DELAY_MIN to DSFXFLANGER_DELAY_MAX. The default value is 2 ms.

lPhase

Phase differential between left and right LFOs, in the range from DSFXFLANGER_PHASE_MIN through DSFXFLANGER_PHASE_MAX. Possible values are the following:

- DSFXFLANGER_PHASE_NEG_180

- DSFXFLANGER_PHASE_NEG_90

- DSFXFLANGER_PHASE_ZERO

- DSFXFLANGER_PHASE_90

- DSFXFLANGER_PHASE_180

The default value is DSFXFLANGER_PHASE_ZERO.

DX_GARGLE

The DSFXGargle structure contains parameters for an amplitude modulation effect.

typedef struct _DSFXGargle {

DWORD dwRateHz;

DWORD dwWaveShape;

} DSFXGargle, *LPDSFXGargle;

dwRateHz

Rate of modulation, in Hertz. Must be in the range from DSFXGARGLE_RATEHZ_MIN through DSFXGARGLE_RATEHZ_MAX. The default value is 20.

dwWaveShape

Shape of the modulation wave. The following values are defined:

DSFXGARGLE_WAVE_TRIANGLE

DSFXGARGLE_WAVE_SQUARE

The default value is DSFXGARGLE_WAVE_TRIANGLE.

DX_I3DL2REVERB

The DSFXI3DL2Reverb structure contains parameters for an I3DL2 (Interactive 3D Audio Level 2) reverberation effect.

typedef struct _DSFXI3DL2Reverb {

LONG lRoom;

LONG lRoomHF;

FLOAT flRoomRolloffFactor;

FLOAT flDecayTime;

FLOAT flDecayHFRatio;

LONG lReflections;

FLOAT flReflectionsDelay;

LONG lReverb;

FLOAT flReverbDelay;

FLOAT flDiffusion;

FLOAT flDensity;

FLOAT flHFReference;

} DSFXI3DL2Reverb, *LPDSFXI3DL2Reverb;

lRoom

Attenuation of the room effect, in millibels (mB), in the range from DSFX_I3DL2REVERB_ROOM_MIN to DSFX_I3DL2REVERB_ROOM_MAX. The default value is DSFX_I3DL2REVERB_ROOM_DEFAULT, or -1000 mB.

lRoomHF

Attenuation of the room high-frequency effect, in mB, in the range from DSFX_I3DL2REVERB_ROOMHF_MIN to DSFX_I3DL2REVERB_ROOMHF_MAX. The default value is DSFX_I3DL2REVERB_ROOMHF_DEFAULT, or -100 mB.

flRoomRolloffFactor

Rolloff factor for the reflected signals, in the range from DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MIN to DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MAX. The default value is DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_DEFAULT, or 0.0. The rolloff factor for the direct path is controlled by the DirectSound listener.

flDecayTime

Decay time, in seconds, in the range from DSFX_I3DL2REVERB_DECAYTIME_MIN to DSFX_I3DL2REVERB_DECAYTIME_MAX. The default value is DSFX_I3DL2REVERB_DECAYTIME_DEFAULT, or 1.49 second.

flDecayHFRatio

Ratio of the decay time at high frequencies to the decay time at low frequencies, in the range from DSFX_I3DL2REVERB_DECAYHFRATIO_MIN to DSFX_I3DL2REVERB_DECAYHFRATIO_MAX. The default value is DSFX_I3DL2REVERB_DECAYHFRATIO_DEFAULT, or 0.83.

lReflections

Attenuation of early reflections relative to lRoom, in mB, in the range from DSFX_I3DL2REVERB_REFLECTIONS_MIN to DSFX_I3DL2REVERB_REFLECTIONS_MAX. The default value is DSFX_I3DL2REVERB_REFLECTIONS_DEFAULT, or -2602 mB.

flReflectionsDelay

Delay time of the first reflection relative to the direct path, in seconds, in the range from DSFX_I3DL2REVERB_REFLECTIONSDELAY_MIN to DSFX_I3DL2REVERB_REFLECTIONSDELAY_DEFAULT. The default value is 0.007 seconds.

lReverb

Attenuation of late reverberation relative to lRoom, in mB, in the range -from DSFX_I3DL2REVERB_REVERB_MIN to DSFX_I3DL2REVERB_REVERB_MAX. The default value is DSFX_I3DL2REVERB_REVERB_DEFAULT, or 200 mB.

flReverbDelay

Time limit between the early reflections and the late reverberation relative to the time of the first reflection, in seconds, in the range from DSFX_I3DL2REVERB_REVERBDELAY_MIN to DSFX_I3DL2REVERB_REVERBDELAY_MAX. The default value is DSFX_I3DL2REVERB_REVERBDELAY_DEFAULT, or 0.011 seconds.

flDiffusion

Echo density in the late reverberation decay, in percent, in the range from DSFX_I3DL2REVERB_DIFFUSION_MIN to DSFX_I3DL2REVERB_DIFFUSION_MAX. The default value is DSFX_I3DL2REVERB_DIFFUSION_DEFAULT, or 100.0 percent.

flDensity

Modal density in the late reverberation decay, in percent, in the range from DSFX_I3DL2REVERB_DENSITY_MIN to DSFX_I3DL2REVERB_DENSITY_MAX. The default value is DSFX_I3DL2REVERB_DENSITY_DEFAULT, or 100.0 percent.

flHFReference

Reference high frequency, in hertz, in the range from DSFX_I3DL2REVERB_HFREFERENCE_MIN to DSFX_I3DL2REVERB_HFREFERENCE_MAX. The default value is DSFX_I3DL2REVERB_HFREFERENCE_DEFAULT, or 5000.0 Hz.

DX_PARAMEQ

The DSFXParamEq structure contains parameters for a parametric equalizer effect.

typedef struct _DSFXParamEq {

FLOAT fCenter;

FLOAT fBandwidth;

FLOAT fGain;

} DSFXParamEq, *LPDSFXParamEq;

fCenter

Center frequency, in hertz, in the range from DSFXPARAMEQ_CENTER_MIN to DSFXPARAMEQ_CENTER_MAX. This value cannot exceed one-third of the frequency of the buffer. The default value is 8000.

fBandwidth

Bandwidth, in semitones, in the range from DSFXPARAMEQ_BANDWIDTH_MIN to DSFXPARAMEQ_BANDWIDTH_MAX. The default value is 12.

fGain

Gain, in the range from DSFXPARAMEQ_GAIN_MIN to DSFXPARAMEQ_GAIN_MAX. The default value is 0.

DX_REVERB

The DSFXWavesReverb structure contains parameters for a Waves reverberation effect.

typedef struct _DSFXWavesReverb {

FLOAT fInGain;

FLOAT fReverbMix;

FLOAT fReverbTime;

FLOAT fHighFreqRTRatio;

} DSFXWavesReverb, *LPDSFXWavesReverb;

fInGain

Input gain of signal, in decibels (dB), in the range from DSFX_WAVESREVERB_INGAIN_MIN through DSFX_WAVESREVERB_INGAIN_MAX. The default value is DSFX_WAVESREVERB_INGAIN_DEFAULT, or 0 dB.

fReverbMix

Reverb mix, in dB, in the range from DSFX_WAVESREVERB_REVERBMIX_MIN through DSFX_WAVESREVERB_REVERBMIX_MAX. The default value is DSFX_WAVESREVERB_REVERBMIX_DEFAULT, or 0 dB.

fReverbTime

Reverb time, in milliseconds, in the range from DSFX_WAVESREVERB_REVERBTIME_MIN through DSFX_WAVESREVERB_REVERBTIME_MAX. The default value is DSFX_WAVESREVERB_REVERBTIME_DEFAULT, or 1000.

fHighFreqRTRatio

In the range from DSFX_WAVESREVERB_HIGHFREQRTRATIO_MIN through DSFX_WAVESREVERB_HIGHFREQRTRATIO_MAX. The default value is DSFX_WAVESREVERB_HIGHFREQRTRATIO_DEFAULT, or 0.001.

Return value

Value | Meaning
enumErrorCodes.ERR_NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


Effects.DirectXEffectReset method

Effects.DirectXEffectReset method

Remarks

Removes a specific DMO (DirectX Media Object) effect, previously applied through the Effects.DirectXEffectApply method, from the playing sound.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DirectXEffectReset (

nPlayer as Integer,

nEffect as enumDirectXEffects

) as enumErrorCodes

[C++]

short control.Effects.DirectXEffectReset (

short nPlayer,

short nEffect

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nEffect

Numeric value that determines the effect to remove.

Supported values are the following:

Mnemonic constant | Value | Meaning
DX_CHORUS | 0 | Chorus
DX_COMPRESSOR | 1 | Compressor
DX_DISTORTION | 2 | Distortion
DX_ECHO | 3 | Echo
DX_FLANGER | 4 | Flanger
DX_GARGLE | 5 | Gargle
DX_I3DL2REVERB | 6 | I3DL2 environmental reverb
DX_REVERB | 8 | Wave reverb

Return value

Value | Meaning
enumErrorCodes.ERR_NOERROR (0) | The call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


Effects.DistortionApply method

Effects.DistortionApply method

Remarks

Applies a distortion effect on the playing song. This effect can be reset through the Effects.DistortionReset method.

Similar to Pre/Post Gain & Drive controls on amps. They were first introduced as a trick to added color to a guitar's tone. Usually produced back then by turning the amp all the way up, or slightly pulling out a tube from its socket. These tones are now today referred to as Overdrives. Today, there are an almost infinite variety of these effects, and they range in 3 classes: Distortions, Fuzz, and Overdrive. One common feature to mostly all of these types of pedals is a volume and drive (also noted as distortion, fuzz, gain, ...etc.). Overdrives are usually a sustain and volume boosting pedal. Used by more traditional rock and country bands. Next are the Distortions, which range from punk style to death metal screams. They are similar to Overdrives, but have more buzzing quality to them. Finally, there are the Fuzzes which are more distorted than distortions, but are more mellow and compressed sounding. Many pedals can be confused within these names, and some may be named other than what they are. Towards the end of this era, the back-to-back diode pair became popular as a technique to provide soft clipping (with germanium diodes) and hard clipping (with silicon diodes). Today, overdrive effects usually means soft clipping, where gain is reduced beyond the clipping point, while distortion usually means hard clipping, where the level is fixed beyond the clipping point. Distortion is a little harder sound, good for rock, while overdrive gives a more natural sound.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DistortionApply (

nPlayer as Integer,

nAffectedChannel as enumChannelMasks,

fDrive as Single,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fVolume as Single,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.DistortionApply (

short nPlayer,

short nAffectedChannel,

float fDrive,

float fDryMix,

float fWetMix,

float fFeedback,

float fVolume,

short nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nAffectedChannel

Numeric value that determines the combination of affected channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
CHANNEL_MASK_0 | 1 (0x01) | Channel 0 or left channel
CHANNEL_MASK_1 | 2 (0x02) | Channel 1 or right channel
CHANNEL_MASK_2 | 4 (0x04) | Channel 2
CHANNEL_MASK_3 | 8 (0x08) | Channel 3
CHANNEL_MASK_4 | 16 (0x10) | Channel 4
CHANNEL_MASK_5 | 32 (0x20) | Channel 5
CHANNEL_MASK_6 | 64 (0x40) | Channel 6
CHANNEL_MASK_7 | 128 (0x80) | Channel 7
CHANNEL_MASK_LEFTS | 85 (0x55) | All left channels
CHANNEL_MASK_RIGHTS | 170 (0xAA) | All right channels
CHANNEL_MASK_ALL | 255 (0xFF) | All available channels

fDrive

Numeric value representing the distortion drive.

Supported values are in the range from 0 to 5.

fDryMix

Numeric value representing the Dry (unaffected) signal mix.

Supported values are in the range from -5 to +5.

fWetMix

Numeric value representing the Wet (affected) signal mix.

Supported values are in the range from -5 to +5.

fFeedback

Numeric value representing the output signal to feed back into input.

Supported values are in the range from -1 to +1.

fVolume

Numeric value representing the distortion volume.

Supported values are in the range from 0 to 2.

nPriority

Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

The fDrive controls the amount of overdrive. The fVolume to balance the effect volume with the bypassed level. It can also be used to boost the signal for solos. The fDryMix is the volume of input signal and the fWetMix is the volume of distorted signal. The fFeedback sets feedback of distortion.

Below some sample:

Effect type | fDrive | fDryMix | fWetMix | fFeedback | fVolume
Hard Distortion | 1.0 | 0.0 | 1.0 | 0.0 | 1.0
Very Hard Distortion | 5.0 | 0.0 | 1.0 | 0.1 | 1.0
Medium Distortion | 0.2 | 1.0 | 1.0 | 0.1 | 1.0
Soft Distortion | 0.0 | -2.95 | -0.05 | -0.18 | 0.25

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.DistortionIsApplied method

Effects.DistortionIsApplied method

Remarks

Verifies if the distortion effect has been applied to the given player through the Effects.DistortionApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DistortionIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.DistortionIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the effect is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The effect has not been applied
BOOL_TRUE | 1 | The effect has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.DistortionReset method

Effects.DistortionReset method

Remarks

Resets the distortion effect previously set through a call to the Effects.DistortionApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.DistortionReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.DistortionReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.EchoApply method

Effects.EchoApply method

Remarks

Applies an echo effect on the playing song. This effect can be reset through the Effects.EchoReset method.

This is an echo effect that replays what you have played one or more times after a period of time. It's something like the echoes you might hear shouting against a canyon wall. For reverb effect enable feedback.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EchoApply (

nPlayer as Integer,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fDelay as Single,

bStereo as enumBoolean,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.EchoApply (

short nPlayer,

short nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fDelay,

short bStereo,

short nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nAffectedChannel

Numeric value that determines the combination of affected channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
CHANNEL_MASK_0 | 1 (0x01) | Channel 0 or left channel
CHANNEL_MASK_1 | 2 (0x02) | Channel 1 or right channel
CHANNEL_MASK_2 | 4 (0x04) | Channel 2
CHANNEL_MASK_3 | 8 (0x08) | Channel 3
CHANNEL_MASK_4 | 16 (0x10) | Channel 4
CHANNEL_MASK_5 | 32 (0x20) | Channel 5
CHANNEL_MASK_6 | 64 (0x40) | Channel 6
CHANNEL_MASK_7 | 128 (0x80) | Channel 7
CHANNEL_MASK_LEFTS | 85 (0x55) | All left channels
CHANNEL_MASK_RIGHTS | 170 (0xAA) | All right channels
CHANNEL_MASK_ALL | 255 (0xFF) | All available channels

fDryMix

Numeric value representing the Dry (unaffected) signal mix.

Supported values are in the range from -2 to +2.

fWetMix

Numeric value representing the Wet (affected) signal mix.

Supported values are in the range from -2 to +2.

fDelay

Numeric value representing the delay expressed in seconds.

Supported values are in the range from -1 to +1.

bStereo

Boolean value, only allowed with even number of channels, instructs the effect to affect both stereo channels or only single channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Affect single channels only
BOOL_TRUE | 1 | Affect both stereo channels

nPriority

Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

The fDryMix is the volume of input signal and the fWetMix is the volume of delayed signal. The fDelay is the delay time in sec. The fFeedback sets how much delay is feed back to the input (for repeating delays). If bStereo is enabled and a stream has an even number of channels then, each even channels will be echoed to each other.

Below some sample:

 | fDryMix | fWetMix | fFeedback | fDelay
Small Echo | 0.999 | 0.999 | 0.0 | 0.20
Many Echoes | 0.999 | 0.999 | 0.7 | 0.50
Reverse Echoes | 0.999 | 0.999 | -0.7 | 0.80
Robotic Voice | 0.500 | 0.800 | 0.5 | 0.10

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.EchoIsApplied method

Effects.EchoIsApplied method

Remarks

Verifies if the echo effect has been applied to the given player through the Effects.EchoApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EchoIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.EchoIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the effect is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The effect has not been applied
BOOL_TRUE | 1 | The effect has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.EchoReset method

Effects.EchoReset method

Remarks

Resets the echo effect previously set through a call to the Effects.EchoApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EchoReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.EchoReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.EqualizerBandAdd method

Effects.EqualizerBandAdd method

Remarks

Adds a new band to the equalizer.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerBandAdd (

nPlayer as Integer,

fFrequency as Single,

fBandWidth as Single,

fGain as Single

) as enumErrorCodes

[C++]

short control.Effects.EqualizerBandAdd (

short nPlayer,

float fFrequency,

float fBandWidth,

float fGain

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

fFrequency

Center frequency of the band expressed in Hertz. Accepted values can be in the range from 1 to 16000 Hz.

A band's frequency cannot exceed one-third of the frequency of the sound under editing so, if you have loaded a sound with a frequency of 44100 Hz, the maximum allowed band's frequency will be 14700 Hz (14700 * 3 = 44100); in order to reach a band's frequency of 16000 Hz, you must load sounds whose frequency is at least 48000 Hz.

If a band for this specific frequency should already exist, it would be automatically replaced.

fBandWidth

Width of the band expressed in semi-tones

fGain

Gain of the band expressed in dB. Typical values are in the range from -15 to 15 dB but you can also enter values outside of this range.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerBandCountGet method

Effects.EqualizerBandCountGet method

Remarks

Obtains the number of bands currently available inside the equalizer.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerBandCountGet (

nPlayer as Integer,

nCount as Integer

) as enumErrorCodes

[C++]

short control.Effects.EqualizerBandCountGet (

short nPlayer,

short *nCount

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nCount | Reference that, on return from the method call, will contain the number of bands available inside the equalizer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerBandFrequencyGet method

Effects.EqualizerBandFrequencyGet method

Remarks

Obtains the frequency of a given equalizer's band.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerBandFrequencyGet (

nPlayer as Integer,

nIndex as Long,

fFrequency as Single

) as Single

[C++]

float control.Effects.EqualizerBandFrequencyGet (

short nPlayer,

long nIndex,

float *fFrequency

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndex | Zero-based index of the equalizer's band
fFrequency | Reference that, on return from the method call, will contain the current frequency, expressed in Hertz, of the given band

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerBandGainSet method

Effects.EqualizerBandGainSet method

Remarks

Modifies the gain of a given band of the equalizer.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerBandGainSet (

nPlayer as Integer,

fFrequency as Single,

fGain as Single

) as Single

[C++]

float control.Effects.EqualizerBandGainSet (

short nPlayer,

float fFrequency,

float fGain

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fFrequency | Frequency of the band expressed in Hertz
fGain | Gain of the band expressed in dB. Typical values are in the range from -15 to 15 dB but you can also enter values outside of this range.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerBandParamsGet method

Effects.EqualizerBandParamsGet method

Remarks

Obtains parameters related to a given band of the equalizer.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerBandParamsGet (

nPlayer as Integer,

fFrequency as Single,

fBandWidth as Single,

fGain as Single

) as Single

[C++]

float control.Effects.EqualizerBandParamsGet (

short nPlayer,

float fFrequency,

float *fBandWidth,

float *fGain

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fFrequency | Center frequency of the band expressed in Hertz
fBandWidth | Reference that, on return from the method call, will contain the width of the band expressed in semi-tones
fGain | Reference that, on return from the method call, will contain the gain of the band expressed in dB

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerBandParamsSet method

Effects.EqualizerBandParamsSet method

Remarks

Sets parameters related to a given band of the equalizer.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerBandParamsSet (

nPlayer as Integer,

fFrequency as Single,

fBandWidth as Single,

fGain as Single

) as Single

[C++]

float control.Effects.EqualizerBandParamsSet (

short nPlayer,

float fFrequency,

float fBandWidth,

float fGain

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fFrequency | Center frequency of the band expressed in Hertz
fBandWidth | Width of the band expressed in semi-tones
fGain | Gain of the band expressed in dB. Typical values are in the range from -15 to 15 dB but you can also enter values outside of this range.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerBandRemove method

Effects.EqualizerBandRemove method

Remarks

Removes the band related to a given frequency from the equalizer.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerBandRemove (

nPlayer as Integer,

fFrequency as Single

) as Single

[C++]

float control.Effects.EqualizerBandRemove (

short nPlayer,

float fFrequency

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fFrequency | Frequency, expressed in Hertz, of the band to remove from the equalizer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerEnable method

Effects.EqualizerEnable method

Remarks

Enables/disables the equalizer.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerEnable (

nPlayer as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.EqualizerEnable (

short nPlayer,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value that specifies if the equalizer must be enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Disable the equalizer
BOOL_TRUE | 1 | Enable the equalizer

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerIsEnabled method

Effects.EqualizerIsEnabled method

Remarks

Verifies if the equalizer has been enabled on the given player through the Effects.EqualizerEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerIsEnabled (

nPlayer as Integer,

bEnabled as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.EqualizerIsEnabled (

short nPlayer,

long *bEnabled

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnabled

Reference that, on return from the method call, will contain the boolean value specifying if the equalizer is currently enabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Equalizer is not enabled
BOOL_TRUE | 1 | Equalizer is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.EqualizerLoadFromFile method

Effects.EqualizerLoadFromFile method

Remarks

Loads from an EDJ file settings to apply to the equalizer.

EDJ files are in XML format and contain settings for defining a pool of pre-defined equalizer bands: EDJ files can be created through your own code or through a call to the Effects.EqualizerSaveToFile method.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerLoadFromFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.Effects.EqualizerLoadFromFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the source EDJ file

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerLoadPresets method

Effects.EqualizerLoadPresets method

Remarks

Loads a WinAmp™ preset into the equalizer.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerLoadPresets (

nPlayer as Integer,

nPreset as enumEqualizerPresets

) as enumErrorCodes

[C++]

short control.Effects.EqualizerLoadPresets (

short nPlayer,

short nPreset

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nPreset

Preset identifier.

Supported values are the following:

Mnemonic constant | Value | Meaning
EQU_PRESET_WINAMP_CLASSICAL | 0 | Classical
EQU_PRESET_WINAMP_CLUB | 1 | Club
EQU_PRESET_WINAMP_DANCE | 2 | Dance
EQU_PRESET_WINAMP_FULL_BASS | 3 | Full bass
EQU_PRESET_WINAMP_FULL_BASS_TREBLE | 4 | Full bass and treble
EQU_PRESET_WINAMP_FULL_TREBLE | 5 | Full treble
EQU_PRESET_WINAMP_LAPTOP_SPEAKERS | 6 | Laptop speakers
EQU_PRESET_WINAMP_LARGE_HALL | 7 | Large hall
EQU_PRESET_WINAMP_LIVE | 8 | Live
EQU_PRESET_WINAMP_PARTY | 9 | Party
EQU_PRESET_WINAMP_POP | 10 | Pop
EQU_PRESET_WINAMP_REGGAE | 11 | Reggae
EQU_PRESET_WINAMP_ROCK | 12 | Rock
EQU_PRESET_WINAMP_SKA | 13 | Ska
EQU_PRESET_WINAMP_SOFT | 14 | Soft
EQU_PRESET_WINAMP_SOFT_ROCK | 15 | Soft rock
EQU_PRESET_WINAMP_TECHNO | 16 | Techno

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerReset method

Effects.EqualizerReset method

Remarks

Resets all of the bands available inside the equalizer to gain 0.

If you should simply need to disable the equalizer use the Effects.EqualizerEnable method with bEnable parameter set to BOOL_FALSE.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.EqualizerReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | Absolute pathname of the destination EDJ file

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.EqualizerSaveToFile method

Effects.EqualizerSaveToFile method

Remarks

Saves current settings of the equalizer into an EDJ file.

EDJ files are in XML format and contain settings for defining a set of pre-defined equalizer bands: EDJ files can be loaded at a later time into the control's equalizer through a call to the Effects.EqualizerLoadFromFile method.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.EqualizerSaveToFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.Effects.EqualizerSaveToFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the destination EDJ file

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.FilterApply method

Effects.FilterApply method

Remarks

Applies a filter effect to the given player. An existing filter can be reset through the Effects.FilterReset method.

When a filter is activated on any of the players instanced by the control, eventual custom DSPs must be set to work with floating point samples through the CustomDSP.UseFloatSamples method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FilterApply (

nPlayer as Integer,

nFilterName as enumFilterNames,

nFilterType as enumFilterTypes,

fFrequency1 as Single,

fFrequency2 as Single,

fGain as Single,

fTransitionTime as Single

) as enumErrorCodes

[C++]

short control.Effects.FilterApply (

short nPlayer,

short nFilterName,

short nFilterType,

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nFilterName

Numeric value representing the filter name.

Supported values are the following:

Mnemonic constant | Value | Meaning
FILTER_NAME_BESSEL | 0 | Bessel IIR Filter
FILTER_NAME_BUTTERWORTH | 1 | Butterworth IIR Filter
FILTER_NAME_HAMMING | 2 | Hamming FIR Filter
FILTER_NAME_HANNING | 3 | Hanning FIR Filter
FILTER_NAME_BLACKMAN | 4 | Blackman FIR Filter
FILTER_NAME_RECTANGULAR | 5 | Rectangular FIR Filter
FILTER_NAME_KAISER | 6 | Kaiser FIR Filter

nFilterType

Numeric value representing the filter type.

Supported values are the following:

Mnemonic constant | Value | Meaning
FILTER_TYPE_LOW_PASS | 0 | Low Pass Filter
FILTER_TYPE_HIGH_PASS | 1 | High Pass Filter
FILTER_TYPE_BAND_PASS | 2 | Band Pass Filter
FILTER_TYPE_BAND_STOP | 3 | Stop Band Filter

fFrequency1

First corner frequency, expressed in Hertz.

For Low Pass and High Pass filters, this parameter represents the cut-off frequency.

For Band Pass and Band Stop filters, this parameter represents the low frequency cut.

The value of this parameter must be higher than 0 and smaller than half the frequency of the sound being played; the frequency of the sound being played can be obtained through the GetFrequency method.

fFrequency2

Second corner frequency, expressed in Hertz.

For Low Pass and High Pass filters, this parameter is ignored and can be set to 0.

For Band Pass and Band Stop filters, this parameter represents the high frequency cut and its value must be higher than 0, higher than the value of the fFrequency1 parameter and smaller than half the frequency of the sound being played; the frequency of the sound being played can be obtained through the GetFrequency method.

fGain

Gain applied to the filter, expressed in percentage: typically this parameter should be set to 100 which leaves the original sound level unchanged during filtering; values under 100 reduce the sound level while values above 100 amplify the sound level.

This parameter is ignored by IIR filters like Bessel and Butterworth.

fTransitionTime

Transition time, expressed in milliseconds, describes how quickly a filter transitions from a pass band to a stop band, or vice versa.

The minimum accepted value is 201 milliseconds.

This parameter is ignored by IIR filters like Bessel and Butterworth.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.FilterIsApplied method

Effects.FilterIsApplied method

Remarks

Verifies if a filter has been applied to the given player through the Effects.FilterApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FilterIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.FilterIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the filter is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | he filter has not been applied
BOOL_TRUE | 1 | The filter has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.FilterReset method

Effects.FilterReset method

Remarks

Resets a filter previously set through a call to the Effects.FilterApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FilterReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.FilterReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.FilterVocalRemoverApply method

Effects.FilterVocalRemoverApply method

Remarks

Applies a filter that removes the main component of the lead vocal from the playing song. An existing filter can be reset through the Effects.FilterVocalRemoverReset method.

When this kind of filter is activated on any of the players instanced by the control, eventual custom DSPs must be set to work with floating point samples through the CustomDSP.UseFloatSamples method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FilterVocalRemoverApply (

nPlayer as Integer,

nVoiceAttenuation as Integer,

nSoundGain as Integer,

nCutoffFrequency as Long

) as enumErrorCodes

[C++]

short control.Effects.FilterVocalRemoverApply (

short nPlayer,

short nVoiceAttenuation,

short nSoundGain,

long nCutoffFrequency

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nVoiceAttenuation | Numeric value representing the voice attenuation factor expressed in percentage. This parameter can assume values from 0 to 100 where 0 means that no attenuation is performed on the lead vocal while 100 means that the lead vocal is totally attenuated: a background reverb of the lead voice could be still heard because, trying to remove this reverb, could cause the song to be attenuated in other components that need to remain as they are.
nSoundGain | Numeric value representing the gain applied to the filtered sound expressed in percentage. Typically this parameter should be set to 100 which leaves the original sound level unchanged during filtering; values under 100 reduce the sound level while values above 100 amplify the sound level.
nCutoffFrequency | Numeric value representing the cutoff frequency, expressed in Hz, under which the algorithm is not applied. For obtaining best results, typically this parameter should be set to values around 200.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.FilterVocalRemoverIsApplied method

Effects.FilterVocalRemoverIsApplied method

Remarks

Verifies if the vocal remover filter has been applied to the given player through the Effects.FilterVocalRemoverApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FilterVocalRemoverIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.FilterVocalRemoverIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the filter is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The filter has not been applied
BOOL_TRUE | 1 | The filter has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.FilterVocalRemoverReset method

Effects.FilterVocalRemoverReset method

Remarks

Resets the vocal remover filter previously set through a call to the Effects.FilterVocalRemoverApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FilterVocalRemoverReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.FilterVocalRemoverReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.FreeverbApply method_2

Effects.FreeverbApply method

Remarks

Applies a specific reverberation effect on the playing song. This DSP effect can be reset through the Effects.FreeverbReset method.

Reverb adds reverberation (rapid, modified repetitions blended with the original sound that gives an impression of ambience). The Reverb effect is based on the original "freeverb" algorithm. Adding reverberation is sometimes desirable for concert halls that are too small or contain so many people that the hall's natural reverberance is diminished. Applying a small amount of stereo reverb to an untreated mono signal duplicated into a two-channel stereo track will usually make it sound more natural.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FreeverbApply (

nPlayer as Integer,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fRoomSize as Single,

fDamp as Single,

fWidth as Single,

nReserved as Long,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.FreeverbApply (

short nPlayer,

short nAffectedChannel,

float fDryMix,

float fWetMix,

float fRoomSize,

float fDamp,

float fWidth,

long nReserved,

short nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nAffectedChannel

Numeric value that determines the combination of affected channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
CHANNEL_MASK_0 | 1 (0x01) | Channel 0 or left channel
CHANNEL_MASK_1 | 2 (0x02) | Channel 1 or right channel
CHANNEL_MASK_2 | 4 (0x04) | Channel 2
CHANNEL_MASK_3 | 8 (0x08) | Channel 3
CHANNEL_MASK_4 | 16 (0x10) | Channel 4
CHANNEL_MASK_5 | 32 (0x20) | Channel 5
CHANNEL_MASK_6 | 64 (0x40) | Channel 6
CHANNEL_MASK_7 | 128 (0x80) | Channel 7
CHANNEL_MASK_LEFTS | 85 (0x55) | All left channels
CHANNEL_MASK_RIGHTS | 170 (0xAA) | All right channels
CHANNEL_MASK_ALL | 255 (0xFF) | All available channels

fDryMix

Numeric value representing the Dry (unaffected) signal mix.

Supported values are in the range from 0 to 1. The default value is 0.

fWetMix

Numeric value representing the Wet (affected) signal mix.

Supported values are in the range from 0 to 3. The default value is 1.0.

fRoomSize

Numeric value representing the room size.

Supported values are in the range from 0 to 1. The default value is 0.5.

fDamp

Numeric value representing the damping.

Supported values are in the range from 0 to 1. The default value is 0.5.

fWidth

Numeric value representing the stereo width.

Supported values are in the range from 0 to 1. The default value is 1.0.

nReserved

Reserved for future uses should be set to 0.

nPriority

Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.FreeverbIsApplied method

Effects.FreeverbIsApplied method

Remarks

Verifies if the "freeverb" reverberation effect has been applied to the given player through the Effects.FreeverbApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FreeverbIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.FreeverbIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the filter is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The filter has not been applied
BOOL_TRUE | 1 | The filter has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.FreeverbReset method

Effects.FreeverbReset method

Remarks

Resets the the "freeverb" reverberation effect previously set through a call to the Effects.FreeverbApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.FreeverbReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.FreeverbReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.MPXEnable method

Effects.MPXEnable method

Remarks

Enables/disables the application of the MPX (Multiplex) DSP effect on the playing sound. A sound must be already loaded inside the given player before applying this method.

Multiplex is a type of Karaoke software that has specially formatted left and right channels to make multiplex features available. To be formatted for multiplex use, a disc must have the vocals coded to the right channel and the music to the left channel. When you enable the use of the MPX DSP, the control will attenuate/remove the right channel (vocals) and split the left channel (music) to both sides. Attenuation removal of the vocal channel can be fine-tuned using the Effects.MPXSetVocalAttenuation method.

With some special MPX file there may be the need to invert channels management: this can be done using the Effects.MPXInvertChannels method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.MPXEnable (

nPlayer as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.MPXEnable (

short nPlayer,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value that specifies if the control must apply or not the MPX DSP.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | MPX DSP is disabled
BOOL_TRUE | 1 | MPX DSP is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.MPXIsEnabled method

Effects.MPXIsEnabled method

Remarks

Verifies if the MPX DSP effect has been enabled on the given player through the Effects.MPXEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.MPXIsEnabled (

nPlayer as Integer,

bEnabled as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.MPXIsEnabled (

short nPlayer,

long *bEnabled

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnabled

Reference that, on return from the method call, will contain the boolean value specifying if the MPX DSP effect is currently enabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The MPX DSP effect is not enabled
BOOL_TRUE | 1 | The MPX DSP effect is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.MPXInvertChannels method

Effects.MPXInvertChannels method

Remarks

Inverts channels management of MPX files. Normal MPX files have the vocals coded to the right channel and the music to the left channel: in some very special case channels may result inverted inside the file so this method allows managing the different situation.

See the Effects.MPXEnable method for details about management of MPX files.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.MPXInvertChannels (

nPlayer as Integer,

bInvertChannels as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.MPXInvertChannels (

short nPlayer,

short bInvertChannels

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bInvertChannels

Boolean value specifying if management of channels of MPX files must be inverted

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | MPX channels are not inverted
BOOL_TRUE | 1 | MPX channels are inverted so the vocals are coded on the left channel and music is coded on the right channel.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.MPXSetVocalAttenuation method

Effects.MPXSetVocalAttenuation method

Remarks

Sets the percentage of attenuation applied to the right channel of the original MPX file. This method call has no effect until the MPX DSP effect is enabled by a call to the Effects.MPXEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.MPXSetVocalAttenuation (

nPlayer as Integer,

nAttenuation as Integer

) as enumErrorCodes

[C++]

short control.Effects.MPXSetVocalAttenuation (

short nPlayer,

short nAttenuation

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nAttenuation | Attenuation value expressed in percentage. If set to 100 no voice will be heard while if set to 0 the full voice will be heard.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.NormalizationEnable method

Effects.NormalizationEnable method

Remarks

Enables/disables real-time normalization of songs during playback. For obtaining good results, in order to apply normalization the control will perform detection of the highest peak during the loading phase (started by one of the many methods having the "Load" prefix like LoadSound or LoadSoundFromMemory with the exception of the LoadInternetStream method) so it will need to read the overall sound file: for this reason, when normalization is enabled, it's highly recommended that you avoid loading files stored inside a network disk.

Normalization doesn't immediately apply to already loaded sound files but takes effect only after the first call to the LoadSound or LoadSoundFromMemory methods.

Normalization is not supported in the following cases:

· Internet streams loaded through the LoadInternetStream method
· audio files loaded through the LoadSoundFast method
· video clips loaded through DirectShow
· on the output of a stream mixer

When normalization is enabled on any of the players instanced by the control, eventual custom DSPs must be set to work with floating point samples through the CustomDSP.UseFloatSamples method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.NormalizationEnable (

nPlayer as Integer,

bEnable as enumBoolean,

fTargetLevelPerc as Single,

fBelowLevelPerc as Single,

fAboveLevelPerc as Single

) as enumErrorCodes

[C++]

short control.Effects.NormalizationEnable (

short nPlayer,

short bEnable,

float fTargetLevelPerc,

float fBelowLevelPerc,

float fAboveLevelPerc

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value that specifies if normalization must be enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Disables normalization
BOOL_TRUE | 1 | Enables normalization.

fTargetLevelPerc

Target peak level expressed in percentage.Typical values are 98% (-0.17 dB) or 100% (0 dB).

fBelowLevelPerc

Defines the lower peak level value, expressed in percentage, of the range where normalization effect will not be applied. Set this value to 100 if you want to apply normalization on all peak levels.

fAboveLevelPerc

Defines the higher peak level value, expressed in percentage, of the range where normalization effect will not be applied. Set this value to 100 if you want to apply normalization on all peak levels.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.NormalizationIsEnabled method

Effects.NormalizationIsEnabled method

Remarks

Verifies if the real-time normalization has been enabled on the given player through the Effects.NormalizationEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.NormalizationIsEnabled (

nPlayer as Integer,

bEnabled as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.NormalizationIsEnabled (

short nPlayer,

long *bEnabled

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnabled

Reference that, on return from the method call, will contain the boolean value specifying if real-time normalization is currently enabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Real-time normalization is not enabled
BOOL_TRUE | 1 | Real-time normalization is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PhaserApply method

Effects.PhaserApply method

Remarks

Applies a phaser effect on the playing song. This DSP effect can be reset through the Effects.PhaserReset method.

Phasers use an internal low frequency oscillator to automatically move notches in the frequency response up and down the frequency spectrum. An important difference between phasing and flanging is that phasers space these notches evenly across the frequency spectrum, while the notches in flanging and chorus are harmonically (musically) related. You don't hear the notches as such (because they are the frequencies that are removed). What you hear is the resulting frequency peaks between these notches. Phasing works by mixing the original signal with one that is phase shifted over the frequency spectrum. For example, a four stage phaser signal (such as this) could be from 0 degrees at 100Hz, shifted to 720 degrees at 5Khz (these extremes are not quite possible practically, but are near enough to explain the effect). This is how the term phase shifter comes about. A 4 stage phaser has 2 notches with bass response, a central peak, and treble response. By using resonance to enhance the central peak, you can get a sound similar to an automatic wah. Using a phaser with lots of stages and setting the resonance high can give a sound similar to flanging, although they are really quite different.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PhaserApply (

nPlayer as Integer,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fRate as Single,

fRange as Single,

fFrequency as Single,

nPriority as Integer

) as enumErrorCodes

[C++]

short control.Effects.PhaserApply (

short nPlayer,

short nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fRate,

float fRange,

float fFrequency,

short nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nAffectedChannel

Numeric value that determines the combination of affected channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
CHANNEL_MASK_0 | 1 (0x01) | Channel 0 or left channel
CHANNEL_MASK_1 | 2 (0x02) | Channel 1 or right channel
CHANNEL_MASK_2 | 4 (0x04) | Channel 2
CHANNEL_MASK_3 | 8 (0x08) | Channel 3
CHANNEL_MASK_4 | 16 (0x10) | Channel 4
CHANNEL_MASK_5 | 32 (0x20) | Channel 5
CHANNEL_MASK_6 | 64 (0x40) | Channel 6
CHANNEL_MASK_7 | 128 (0x80) | Channel 7
CHANNEL_MASK_LEFTS | 85 (0x55) | All left channels
CHANNEL_MASK_RIGHTS | 170 (0xAA) | All right channels
CHANNEL_MASK_ALL | 255 (0xFF) | All available channels

fDryMix

Numeric value representing the Dry (unaffected) signal mix.

Supported values are in the range from -2 to +2.

fWetMix

Numeric value representing the Wet (affected) signal mix.

Supported values are in the range from -2 to +2.

fFeedback

Numeric value representing the output signal to feed back into input.

Supported values are in the range from -1 to +1.

fRate

Numeric value representing the rate of sweep expressed in cycles per second.

Supported values are in the range from 0 to 10.

fRange

Numeric value representing the sweep range expressed in octaves.

Supported values are in the range from 0 to 10.

fFrequency

Numeric value representing the base frequency of sweep range.

Supported values are in the range from 0 to 1000.

nPriority

Effect's priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added.

The fDryMix is the volume of input signal and the fWetMix is the volume of delayed signal. The fFeedback sets feedback of phaser. The fRate and fRange parameters control how fast and far the frequency notches move. The fRate is the rate of sweep in cycles per second, fRange is the width of sweep in octaves. And the the fFrequency is the base frequency of sweep.

Below some sample:

Effect type | fDryMix | fWetMix | fFeedback | fRate | fRange | fFrequency
Phase shift | 0.999 | 0.999 | 0.0 | 1.0 | 4.0 | 100.0
Slow invert phase shift with feedback | 0.999 | -0.999 | -0.6 | 0.2 | 6.0 | 100.0
Basic phase | 0.999 | 0.999 | 0.0 | 1.0 | 4.3 | 50.0
Phase w/ FB | 0.999 | 0.999 | 0.6 | 1.0 | 4.0 | 40.0
Med. phase | 0.999 | 0.999 | 0.0 | 1.0 | 7.0 | 100.0
Fast phase | 0.999 | 0.999 | 0.0 | 1.0 | 7.0 | 400.0
Invert w/ invert FB | 0.999 | -0.999 | -0.2 | 1.0 | 7.0 | 200.0
Tremolo Wah | 0.999 | 0.999 | 0.6 | 1.0 | 4.0 | 60.0

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PhaserIsApplied method

Effects.PhaserIsApplied method

Remarks

Verifies if the phaser effect has been applied to the given player through the Effects.PhaserApply method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PhaserIsApplied (

nPlayer as Integer,

bApplied as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.PhaserIsApplied (

short nPlayer,

long *bApplied

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bApplied

Reference that, on return from the method call, will contain the boolean value specifying if the effect is currently applied.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | The effect has not been applied
BOOL_TRUE | 1 | The effect has been applied

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PhaserReset method

Effects.PhaserReset method

Remarks

Resets the phaser effect previously set through a call to the Effects.PhaserApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PhaserReset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Effects.PhaserReset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PlaybackPitchGet method

Effects.PlaybackPitchGet method

Remarks

Obtains the sound pitch or key. The pitch can be modified through the Effects.PlaybackPitchSet method.

Further details about songs mixing can be found inside the How to mix your songs section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PlaybackPitchGet (

nPlayer as Integer,

fPitch as Single

) as enumErrorCodes

[C++]

short control.Effects.PlaybackPitchGet (

short nPlayer,

float *fPitch

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fPitch | Reference that, on return from the method call, will contain the Pitch variation expressed in semitones; supported values are from -50 to 50.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PlaybackPitchSet method

Effects.PlaybackPitchSet method

Remarks

Changes the sound pitch or key, without affecting the sound tempo or playback rate: after a successful call to this method the duration of the song is not altered. The current pitch can be obtained through the Effects.PlaybackPitchGet method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

When dealing with video clips, calls to this method will have no effect if the video clip has not been loaded with the VideoPlayer.LoadForTempoChange, VideoPlayer.LoadFromMemoryForTempoChange, VideoPlayer.LoadFromMemorySyncForTempoChange or VideoPlayer.LoadSyncForTempoChange methods.

Further details about songs mixing can be found inside the How to mix your songs section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PlaybackPitchSet (

nPlayer as Integer,

fPitch as Single

) as enumErrorCodes

[C++]

short control.Effects.PlaybackPitchSet (

short nPlayer,

float fPitch

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fPitch | The Pitch variation expressed in semitones; supported values are from -50 to 50. Setting this parameter to 0 will set the original sound pitch value.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PlaybackRateGet method

Effects.PlaybackRateGet method

Remarks

Obtains the current playback rate percentage for the given player. The playback rate percentage can be modified calling the Effects.PlaybackRateSet method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

Further details about songs mixing can be found inside the How to mix your songs section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PlaybackRateGet (

nPlayer as Integer,

fRatePerc as single

) as enumErrorCodes

[C++]

short control.Effects.PlaybackRateGet (

short nPlayer,

float *fRatePerc

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fRatePerc | Reference that, on return from the method call, will contain the Sample Rate variation expressed in percentage; supported values are from -90 to 90.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PlaybackRateSet method

Effects.PlaybackRateSet method

Remarks

Changes both the sound tempo and pitch, as if an LP disc was played at wrong RPM rate. The use of this method will speed up the sound playback and voices will result altered; if you don't want to alter voices, use the Effects.PlaybackTempoSet method. The current rate percentage can be obtained through the Effects.PlaybackRateGet method. The current effective playback rate ratio, that may be also affected by the Effects.PlaybackTempoSet method, can be obtained through the Effects.PlaybackRateRatioGet method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

When dealing with video clips, calls to this method will have no effect if the video clip has not been loaded with the VideoPlayer.LoadForTempoChange, VideoPlayer.LoadFromMemoryForTempoChange, VideoPlayer.LoadFromMemorySyncForTempoChange or VideoPlayer.LoadSyncForTempoChange methods.

After a successful call to this method, the duration of the song will change: the new duration, expressed in seconds, is notified through the SoundDurationChanged event. The new duration can also be obtained through the SoundDurationGet and SoundDurationStringGet methods by setting the bKeepCountOfRateChange parameter to "BOOL_TRUE".

Further details about songs mixing can be found inside the How to mix your songs section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PlaybackRateSet (

nPlayer as Integer,

fRatePerc as single

) as enumErrorCodes

[C++]

short control.Effects.PlaybackRateSet (

short nPlayer,

float fRatePerc

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fRatePerc | The Sample Rate variation expressed in percentage; supported values are from -90 to 90. Setting this parameter to 0 will set the original sound sample rate value.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PlaybackRateRatioGet method

Effects.PlaybackRateRatioGet method

Remarks

Obtains the current ratio for playback rate of the given player.

When playback is performed at normal speed, its ratio is 1.0; after changing the playback speed through the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods, the playback speed is altered and this method allows to know which is the updated rate ratio. For example, if the playback rate should be incremented by 20%, the reported playback rate ratio would be 1.2 while, if the playback rate should be reduced by 30%, the reported playback rate ratio would be 0.7.

Syntax

[Visual Basic]

control.Effects.PlaybackRateRatioGet (

nPlayer as Integer,

fRatio as Single

) as enumErrorCodes

[C++]

short control.Effects.PlaybackRateRatioGet (

short nPlayer,

float *fRatio

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player whose information must be retrieved
fRatio | Reference that, on return from the method call, will contain the current rate ratio.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PlaybackTempoGet method

Effects.PlaybackTempoGet method

Remarks

Retrieves the current Tempo percentage for the given player. The Tempo percentage can be modified calling the Effects.PlaybackTempoSet method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

Further details about songs mixing can be found inside the How to mix your songs section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PlaybackTempoGet (

nPlayer as Integer,

fTempoPerc as single

) as enumErrorCodes

[C++]

short control.Effects.PlaybackTempoGet (

short nPlayer,

float *fTempoPerc

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fTempoPerc | Reference that, on return from the method call, will contain the Tempo variation expressed in percentage; supported values are from -90 to 90.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PlaybackTempoSet method

Effects.PlaybackTempoSet method

Remarks

Changes the sound to play at faster or slower speed than original, without affecting the sound pitch so voices won't result altered. The current tempo percentage can be obtained through the Effects.PlaybackTempoGet method. The current effective playback rate ratio, that may be also affected by the Effects.PlaybackRateSet method, can be obtained through the Effects.PlaybackRateRatioGet method.

This method doesn't work with sounds with more than 2 channels (5.1 or 7.1) or if the EnableMixingFeatures property has been set to BOOL_FALSE.

When dealing with video clips, calls to this method will have no effect if the video clip has not been loaded with the VideoPlayer.LoadForTempoChange, VideoPlayer.LoadFromMemoryForTempoChange, VideoPlayer.LoadFromMemorySyncForTempoChange or VideoPlayer.LoadSyncForTempoChange methods.

After a successful call to this method, the duration of the song will change: the new duration, expressed in seconds, is notified through the SoundDurationChanged event. The new duration can also be obtained through the SoundDurationGet and SoundDurationStringGet methods by setting the bKeepCountOfRateChange parameter to "BOOL_TRUE".

Further details about songs mixing can be found inside the How to mix your songs section.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PlaybackTempoSet (

nPlayer as Integer,

fTempoPerc as single

) as enumErrorCodes

[C++]

short control.Effects.PlaybackTempoSet (

short nPlayer,

float fTempoPerc

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fTempoPerc | The Tempo variation expressed in percentage; supported values are from -90 to 90. Setting this parameter to 0 will set the original sound tempo value. Usually best mixing results are obtained with values from -15 to 15.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PreAmplifierEnable method

Effects.PreAmplifierEnable method

Remarks

Enables/disables pre-amplification of the loaded sound.

For stereo and mono sounds the current pre-amplification value can be obtained through the Effects.PreAmplifierValueGet method and changed through the Effects.PreAmplifierValueSet method.

For multi-channel songs like 5.1 or 7.1 the current pre-amplification value assigned to each speaker can be obtained through the Effects.PreAmplifierSpeakerValueGet method and changed through the Effects.PreAmplifierSpeakerValueSet method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PreAmplifierEnable (

nPlayer as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.PreAmplifierEnable (

short nPlayer,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value indicating if pre-amplification is enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Disables pre-amplification
BOOL_TRUE | 1 | Enables pre-amplification

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PreAmplifierIsEnabled method

Effects.PreAmplifierIsEnabled method

Remarks

Verifies if the preamplifier has been enabled on the given player through the Effects.PreAmplifierEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PreAmplifierIsEnabled (

nPlayer as Integer,

bEnabled as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.PreAmplifierIsEnabled (

short nPlayer,

long *bEnabled

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnabled

Reference that, on return from the method call, will contain the boolean value specifying if preamplifier is currently enabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Preamplifier is not enabled
BOOL_TRUE | 1 | Preamplifier is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PreAmplifierSpeakerValueGet method

Effects.PreAmplifierSpeakerValueGet method

Remarks

Gets the current preamplifier's amplification value related to a specific speaker (only for multi-channel songs like 5.1 or 7.1). The current value can be modified through the Effects.PreAmplifierSpeakerValueSet method.

Pre-amplification is applied only if enabled through a previous call to the Effects.PreAmplifierEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PreAmplifierSpeakerValueGet (

nPlayer as Integer,

nSpeaker as enumSpeakers

fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.Effects.PreAmplifierSpeakerValueGet (

short nPlayer,

short nSpeaker,

float *fValue,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSpeaker

The output speaker assigned to the given player.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
SPEAKER_FRONT | 0 | Front speakers (Stereo)
SPEAKER_REAR | 1 | Rear speakers (Stereo)
SPEAKER_CENTER_LFE | 2 | Center speakers (Stereo)
SPEAKER_REAR_CENTER | 3 | Rear center speakers (Stereo)
SPEAKER_FRONT_LEFT | 4 | Front-left speaker (Mono)
SPEAKER_FRONT_RIGHT | 5 | Front-right speaker (Mono)
SPEAKER_REAR_LEFT | 6 | Rear-left speaker (Mono)
SPEAKER_REAR_RIGHT | 7 | Rear-right speaker (Mono)
SPEAKER_CENTER | 8 | Center speaker (Mono)
SPEAKER_LFE | 9 | LFE or Subwoofer speaker (Mono)
SPEAKER_REAR_CENTER_LEFT | 10 | Rear Center Left speaker (Mono)
SPEAKER_REAR_CENTER_RIGHT | 11 | Rear Center Right speaker (Mono)

Below you can see the positioning of the Stereo speakers on a wide 7.1 configuration (the reported blue numbers corresponds to the Numeric value of the parameter)

and below you can see the positioning of the Mono speakers on the same wide 7.1 configuration

fValue

Reference that, on return from the method call, will contain the amplification value expressed in the unit specified by the nScaleType parameter.

nScaleType

The amplification scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Returned amplification, expressed in percentage, is based upon a linear scale: - value 0.0 mutes the playing sound - values higher than 0.0 and smaller than 100.0 attenuate the playing sound - value 100.0 keeps sound level unchanged - values higher than 100.0 amplify the playing sound
SCALE_LOG | 1 | Returned amplification, expressed in dB, is based upon a logarithmic scale: - value -100.0 mutes the playing sound - values higher than -100.0 and smaller than 0.0 attenuate the playing sound - value 0.0 keeps sound level unchanged - values higher than 0.0 amplify the playing sound The actual applied formula for converting a linear volume into a logarithmic volume is the following: VolumeInDB = 20 * log10 (VolumeLinear/100) The C syntax for converting a logarithmic volume into a linear volume is the following: VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PreAmplifierSpeakerValueSet method

Effects.PreAmplifierSpeakerValueSet method

Remarks

Modifies the preamplifier's amplification value related to a specific speaker (only for multi-channel songs like 5.1 or 7.1). The current value can be obtained through the Effects.PreAmplifierSpeakerValueGet method.

Pre-amplification is applied only if enabled through a previous call to the Effects.PreAmplifierEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PreAmplifierSpeakerValueSet (

nPlayer as Integer,

nSpeaker as enumSpeakers

fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.Effects.PreAmplifierSpeakerValueSet (

short nPlayer,

short nSpeaker,

float fValue,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSpeaker

The output speaker assigned to the given player.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
SPEAKER_FRONT | 0 | Front speakers (Stereo)
SPEAKER_REAR | 1 | Rear speakers (Stereo)
SPEAKER_CENTER_LFE | 2 | Center speakers (Stereo)
SPEAKER_REAR_CENTER | 3 | Rear center speakers (Stereo)
SPEAKER_FRONT_LEFT | 4 | Front-left speaker (Mono)
SPEAKER_FRONT_RIGHT | 5 | Front-right speaker (Mono)
SPEAKER_REAR_LEFT | 6 | Rear-left speaker (Mono)
SPEAKER_REAR_RIGHT | 7 | Rear-right speaker (Mono)
SPEAKER_CENTER | 8 | Center speaker (Mono)
SPEAKER_LFE | 9 | LFE or Subwoofer speaker (Mono)
SPEAKER_REAR_CENTER_LEFT | 10 | Rear Center Left speaker (Mono)
SPEAKER_REAR_CENTER_RIGHT | 11 | Rear Center Right speaker (Mono)

Below you can see the positioning of the Stereo speakers on a wide 7.1 configuration (the reported blue numbers corresponds to the Numeric value of the parameter)

and below you can see the positioning of the Mono speakers on the same wide 7.1 configuration

fValue

The new amplification value expressed in the unit specified by the nScaleType parameter.

nScaleType

The amplification scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Amplification, expressed in percentage, is based upon a linear scale: - value 0.0 mutes the playing sound - values higher than 0.0 and smaller than 100.0 attenuate the playing sound - value 100.0 keeps sound level unchanged - values higher than 100.0 amplify the playing sound
SCALE_LOG | 1 | Amplification, expressed in dB, is based upon a logarithmic scale: - value -100.0 mutes the playing sound - values higher than -100.0 and smaller than 0.0 attenuate the playing sound - value 0.0 keeps sound level unchanged - values higher than 0.0 amplify the playing sound The actual applied formula for converting a linear volume into a logarithmic volume is the following: VolumeInDB = 20 * log10 (VolumeLinear/100) The C syntax for converting a logarithmic volume into a linear volume is the following: VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PreAmplifierValueGet method

Effects.PreAmplifierValueGet method

Remarks

Obtains the current pre-amplifier's amplification value (for stereo and mono sounds). The current value can be modified through the Effects.PreAmplifierValueSet method.

Pre-amplification is applied only if enabled through a previous call to the Effects.PreAmplifierEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PreAmplifierValueGet (

nPlayer as Integer,

fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.Effects.PreAmplifierValueGet (

short nPlayer,

float *fValue,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

fValue

Reference that, on return from the method call, will contain the amplification value expressed in the unit specified by the nScaleType parameter.

nScaleType

The amplification scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Returned amplification, expressed in percentage, is based upon a linear scale: - value 0.0 mutes the playing sound - values higher than 0.0 and smaller than 100.0 attenuate the playing sound - value 100.0 keeps sound level unchanged - values higher than 100.0 amplify the playing sound
SCALE_LOG | 1 | Returned amplification, expressed in dB, is based upon a logarithmic scale: - value -100.0 mutes the playing sound - values higher than -100.0 and smaller than 0.0 attenuate the playing sound - value 0.0 keeps sound level unchanged - values higher than 0.0 amplify the playing sound The actual applied formula for converting a linear volume into a logarithmic volume is the following: VolumeInDB = 20 * log10 (VolumeLinear/100) The C syntax for converting a logarithmic volume into a linear volume is the following: VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.PreAmplifierValueSet method

Effects.PreAmplifierValueSet method

Remarks

Modifies the current pre-amplifier's amplification value (for stereo and mono sounds). The current value can be obtained through the Effects.PreAmplifierValueGet method.

Pre-amplification is applied only if enabled through a previous call to the Effects.PreAmplifierEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.PreAmplifierValueSet (

nPlayer as Integer,

fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.Effects.PreAmplifierValueSet (

short nPlayer,

float fValue,

short nScaleType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

fValue

Amplification value expressed in the unit specified by the nScaleType parameter

nScaleType

The amplification scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | Amplification, expressed in percentage, is based upon a linear scale: - value 0.0 mutes the playing sound - values higher than 0.0 and smaller than 100.0 attenuate the playing sound - value 100.0 keeps sound level unchanged - values higher than 100.0 amplify the playing sound
SCALE_LOG | 1 | Amplification, expressed in dB, is based upon a logarithmic scale: - value -100.0 mutes the playing sound - values higher than -100.0 and smaller than 0.0 attenuate the playing sound - value 0.0 keeps sound level unchanged - values higher than 0.0 amplify the playing sound The actual applied formula for converting a linear volume into a logarithmic volume is the following: VolumeInDB = 20 * log10 (VolumeLinear/100) The C syntax for converting a logarithmic volume into a linear volume is the following: VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.SoundDirectionEnable method

Effects.SoundDirectionEnable method

Remarks

Enables/disables the possibility to play the loaded song in reverse through future calls to the Effects.SoundDirectionSet method.

This method will have effect only for the following audio formats: MP1, MP2, MP3, MP4, AIFF, AAC, M4A, AC3, WavPack, ALAC, WAV, OGG Vorbis, WMA, ASF, WMV, FLAC, Speex, Musepack and Monkey's Audio (APE).

Other audio formats, including video clips managed by DirectShow, Internet streams loaded through the LoadInternetStream method and audio queues created through the StreamQueueCreate method, don't come with support for reverse playback.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.SoundDirectionEnable (

nPlayer as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.SoundDirectionEnable (

short nPlayer,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnable

Boolean value indicating if the control needs to resample the stream for reverse playback support.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Disables reversed sound creation
BOOL_TRUE | 1 | Enables reversed sound creation

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.SoundDirectionGet method

Effects.SoundDirectionGet method

Remarks

Obtains the current sound's playback direction. The playback direction can be modified through the Effects.SoundDirectionSet method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.SoundDirectionGet (

nPlayer as Integer,

nDirection as enumSoundDirections

) as enumSoundDirections

[C++]

short control.Effects.SoundDirectionGet (

short nPlayer,

long *nDirection

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nDirection

Reference that, on return from the method call, will contain the current playback direction.

Supported values are the following:

Mnemonic constant | Value | Meaning
DIRECTION_FORWARD | 0 | Sound is played in normal forward direction
DIRECTION_REVERSE | 1 | Sound is played in reverse direction

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.SoundDirectionIsEnabled method

Effects.SoundDirectionIsEnabled method

Remarks

Verifies if the possibility to play the loaded song in reverse has been enabled on the given player through the Effects.SoundDirectionEnable method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.SoundDirectionIsEnabled (

nPlayer as Integer,

bEnabled as enumBoolean

) as enumErrorCodes

[C++]

short control.Effects.SoundDirectionIsEnabled (

short nPlayer,

long *bEnabled

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bEnabled

Reference that, on return from the method call, will contain the boolean value specifying if reverse playback is currently enabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Reverse playback is not enabled
BOOL_TRUE | 1 | Reverse playback is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Effects.SoundDirectionSet method

Effects.SoundDirectionSet method

Remarks

Sets the sound's playback direction. This method doesn't have any effect if reversed sound management has not been enabled by a previously call to the Effects.SoundDirectionEnable method.

The current playback direction can be obtained through the Effects.SoundDirectionGet method.

It's important to note that calling one of the following methods will force the setting of the forward direction of the playing sound: StopSound, RewindSound and ForwardSound.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

control.Effects.SoundDirectionSet (

nPlayer as Integer,

nDirection as Integer

) as enumSoundDirections

[C++]

short control.Effects.SoundDirectionSet (

short nPlayer,

short nDirection

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nDirection

The current playback direction.

Supported values are the following:

Mnemonic constant | Value | Meaning
DIRECTION_FORWARD | 0 | Sound is played in normal forward direction
DIRECTION_REVERSE | 1 | Sound is played in reverse direction

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


Fader object

Fader object

The Fader object, accessible through the control's Fader property, is internally implemented as a COM interface called IFader and contains information needed to operate the embedded Automatic Fader.

It can be used at Run-time in order to create and operate the embedded Fader and to access its Display property. For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

The Fader object is implemented through the following methods and properties:

Methods

Init

Exit

FadeInTargetVolumeGet

FadeInTargetVolumeSet

FadeInVolumeCurveSet

FadeInVolumeCurveSetEx

FadeOutVolumeCurveSet

FadeOutVolumeCurveSetEx

PlayListUseSingle

StartManualFading

Stop

Properties

FadeInEnabled

FadeOutEnabled

FadeStartFromEnd

FadeOutLength

FadeInLength

FadeInSeekPos

FadeInDelayFromMixStart

FadeOutDelayFromMixStart

FadeOutMode

Display

TotalMixingTime

CheckItemsDurationOnStart

The following code snippets show how to initialise and change settings for this object in your code. These examples assume that you have placed a control named MyPlayer on a form or dialog and that you want to change a couple of Fader settings (fade-in duration set to 3000 milliseconds and fade-out duration set to 4000 milliseconds).

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Microsoft Visual Basic (5.0 and 6.0)

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual J#.NET

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Properties and methods of the control are accessible through the control wrapper class CAmp3dj contained inside the amp3dj.cpp and amp3dj.h files: these wrapper files are automatically generated when you insert the control inside your project so, in order to access the wrapper functions, you will have to insert the following line of code somewhere in your code.

#include "amp3dj.h"

The Fader object is defined by the control wrapper class CFader contained inside the fader.cpp and fader.h files: also these wrapper files are automatically generated when you insert the control inside your project so, in order to access this object, you will have to insert the following line of code somewhere in your code.

#include "fader.h"

Here follows the code needed to perform the requested operation of initialising the Fader object and changing some of its properties.

// declare a Fader object

CFader fader;

// init the object with the control's Fader reference

fader = MyPlayer.GetFader ();

// initialise the Fader on player 0 and player 1

fader.Init (FADE_SINGLE, 0, 1);

// set the fade-in and fade-out duration

fader.SetFadeInLength (3000);

fader.SetFadeOutLength (4000);

As you can see the access to the Fader properties FadeInLength and FadeOutLength are wrapped by the SetFadeInLength and SetFadeOutLength functions declared inside the wrapper class CFader.

Note that the use of the FADE_SINGLE enumerated type requires to add the following include to your code:

#include "AdjMmsEngDef.h"

Microsoft Visual Basic (5.0 and 6.0)

Here follows the code needed to perform the requested operations

' initialise the Fader

MyPlayer.Fader.Init 0, 0, 1

' set the fade-in and fade-out duration

MyPlayer.Fader.FadeInLength = 3000

MyPlayer.Fader.FadeOutLength = 4000

Microsoft Visual Basic.NET

Here follows the code needed to perform the requested operations

' initialise the Fader on player 0 and player 1

MyPlayer.Fader.Init (enumFadeTypes.FADE_SINGLE, 0, 1)

' set the fade-in and fade-out duration

MyPlayer.Fader.FadeInLength = 3000

MyPlayer.Fader.FadeOutLength = 4000

Microsoft Visual C#.NET

Here follows the code needed to perform the requested operations

// initialise the Fader on player 0 and player 1

MyPlayer.Fader.Init (enumFadeTypes.FADE_SINGLE, 0, 1);

// set the fade-in and fade-out duration

MyPlayer.Fader.FadeInLength = 3000;

MyPlayer.Fader.FadeOutLength = 4000;

Microsoft Visual J#.NET

Here follows the code needed to perform the requested operations

// initialise the Fader

MyPlayer.get_Fader().Init (AMP3DJLib.enumFadeTypes.FADE_SINGLE, (short) 0, (short) 1);

// set the fade-in and fade-out duration

MyPlayer.get_Fader().set_FadeInLength (3000);

MyPlayer.get_Fader().set_FadeOutLength (4000);

As you can see, in J#.NET the access to the control properties is made through the use of wrapper functions (automatically generated when you insert the control inside your project) with the "get_" and "set_" prefixes. Intellisense will help you finding the right wrapper function.


Fader.CheckItemsDurationOnStart property

Fader.CheckItemsDurationOnStart property

Type

BOOL for Visual C++

boolean for Visual Basic

Syntax

object.Fader.CheckItemsDurationOnStart [=boolean]

Remarks

Boolean value that determines the need to check if the playlist contains at least two songs longer than the total mixing time.

When the fader is started through a call to the Fader.StartManualFading method, by default the multimedia engine will check the availability of at least two songs or video clips having a duration longer than the total mixing time: without this availability the multimedia engine will return error ERR_CANNOT_FADE_SMALL_SONGS (-45).

When dealing with playlists without information about the duration of each song and/or video clip (feature available only when dealing with PLS and PDJ playlist formats) you can disable this check by setting the property to "False" so the manual fade will in any case occur. In any case, be very careful in setting this property to "True" until you are not manually checking that the duration of added songs and/or video clips is compatible with the total mixing time because the fader may miss the next fade if the end of the song and/or video clip is reached before the predisposed mixing point.

See also

Fader COM object.

Fader property

How to use the Automatic Fader section.


Fader.Display property (RO)

Fader.Display property (RO)

Return to chapter overview
Type | CDisplay for Visual C++ AMP3DJLib.Fader.Display for Visual Basic This property is Read-only
Syntax | object.Fader.Display [=AMP3DJLib.Fader.Display]
Remarks | The Display object for the embedded Automatic Fader object. This property encapsulates the functionality of the Fader.Display object and the IDisplay COM interface. For details about using the Automatic Fader refer to the How to use the Automatic Fader section


Fader.FadeInDelayFromMixStart property

Fader.FadeInDelayFromMixStart property

Type | long for Visual C++ long for Visual Basic
Syntax | object.Fader.FadeInDelayFromMixStart [=long]
Remarks | Expressed in milliseconds, determines the delay applied for the fade-in.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.FadeInEnabled property

Fader.FadeInEnabled property

Type | BOOL for Visual C++ boolean for Visual Basic
Syntax | object.Fader.FadeInEnabled [=boolean]
Remarks | Boolean value that determines if the fade-in is enabled: when disabled, the volume of the song fading-in will increase immediately to its maximum.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.FadeInLength property

Fader.FadeInLength property

Type | long for Visual C++ long for Visual Basic
Syntax | object.Fader.FadeInLength [=long]
Remarks | Expressed in milliseconds, determines the time required by the song fading-in to slide the volume to its maximum.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.FadeInSeekPos property

Fader.FadeInSeekPos property

Type | long for Visual C++ long for Visual Basic
Syntax | object.Fader.FadeInSeekPos [=long]
Remarks | Expressed in milliseconds, determines the initial position of the song fading-in. If the song that will fade-in is currently in "paused" state and if the nFadeType parameter of the Fader.Init method was set to FADE_SINGLE, the value of this property is ignored and the actual position is taken: during a manual mix this allows precise positioning of the song that will fade-in. This property can be set to -1 if no seek is needed at the beginning of playback.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.FadeOutDelayFromMixStart property

Fader.FadeOutDelayFromMixStart property

Type | long for Visual C++ long for Visual Basic
Syntax | object.Fader.FadeOutDelayFromMixStart [=long]
Remarks | Expressed in milliseconds, determines the delay applied for the fade-out.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.FadeOutEnabled property

Fader.FadeOutEnabled property

Type | BOOL for Visual C++ boolean for Visual Basic
Syntax | object.Fader.FadeOutEnabled [=boolean]
Remarks | Boolean value that determines if the fade-out is enabled: when disabled, the volume of the song fading-out will decrease immediately to its minimum.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.FadeOutLength property

Fader.FadeOutLength property

Type | long for Visual C++ long for Visual Basic
Syntax | object.Fader.FadeOutLength [=long]
Remarks | Expressed in milliseconds, determines the time required by the song fading-out to slide the volume to its minimum.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.FadeOutMode property

Fader.FadeOutMode property

Type

short for Visual C++

enumFadeOutModes for Visual Basic

Syntax

object.Fader.FadeOutMode [=Integer]

Remarks

Determines how to perform the fade-out process.

Supported values are the following:

Mnemonic constant | Value | Meaning
FADEOUT_LINEAR (default) | 0 | Based upon a Time/Volume combination, performs a linear volume sliding to its minimum.
FADEOUT_BREAKDOWN | 1 | Based upon a Time/Playback-rate combination, performs a "Breakdown effect" that simulates the switch off of the deck rotor engine

See also

Fader COM object.

Fader property

How to use the Automatic Fader section.


Fader.FadeStartFromEnd property

Fader.FadeStartFromEnd property

Type | long for Visual C++ long for Visual Basic
Syntax | object.Fader.FadeStartFromEnd [=long]
Remarks | Expressed in milliseconds, determines when the fader will automatically start the cross-fading during the playback of the song that must fade-out.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.TotalMixingTime property (RO)

Fader.TotalMixingTime property (RO)

Return to chapter overview
Type | long for Visual C++ long for Visual Basic This property is read-only
Syntax | object.Fader.TotalMixingTime [=long]
Remarks | Expressed in milliseconds, retrieves the total time required to perform a complete cross-fading.
See also | Fader COM object. Fader property How to use the Automatic Fader section.


Fader.Exit method

Fader.Exit method

Remarks

Disables the embedded Automatic Fader previously created and enabled through a call to the Fader.Init method.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

controlFader.Exit (

)

[C++]

void control.Fader.Exit (

);

Return value

None


Fader.FadeInTargetVolumeGet method

Fader.FadeInTargetVolumeGet method

Remarks

Obtains the volume target level applied to player fading-in. The target volume level can be modified using the Fader.FadeInTargetVolumeSet method.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.FadeInTargetVolumeGet (

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.Fader.FadeInTargetVolumeGet (

short nScaleType

);

Parameter

Description

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The returned volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The current target level (the meaning of the passed value depends upon the nScaleType parameter).


Fader.FadeInTargetVolumeSet method

Fader.FadeInTargetVolumeSet method

Remarks

Sets the volume target level applied to player fading-in. The current target level can be obtained through the Fader.FadeInTargetVolumeGet method.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.FadeInTargetVolumeSet (

fTargetVolume as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C++]

short control.Fader.FadeInTargetVolumeSet (

float fTargetVolume,

short nScaleType

);

Parameter

Description

fTargetVolume

Number representing the volume target level (the meaning of the passed value depends upon the nScaleType parameter).

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The returned volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The returned volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Fader.FadeInVolumeCurveSet method

Fader.FadeInVolumeCurveSet method

Remarks

Sets the volume curve for fade-in operations.

This setting is lost after invoking the Fader.Exit method so you should call again this method after a new eventual call to the Fader.Init method.

Syntax

[Visual Basic]

control.Fader.FadeInVolumeCurveSet (

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.Fader.FadeInVolumeCurveSet (

short nCurveType,

long nDesignerUniqueId

);

Parameter

Description

nCurveType

Type of curve applied to the volume sliding.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

If you don't want to display the custom curve designer on your user interface but you know the exact position of the control points to set, you can use the Fader.FadeInVolumeCurveSetEx method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


Fader.FadeInVolumeCurveSetEx method

Fader.FadeInVolumeCurveSetEx method

Remarks

Sets the volume curve for fade-in operations.

This setting is lost after invoking the Fader.Exit method so you should call again this method after a new eventual call to the Fader.Init method.

Syntax

[Visual Basic]

control.Fader.FadeInVolumeCurveSetEx (

nCurveType as enumVolumeCurves,

nLeftX as Integer,

nLeftY as Integer,

nRightX as Integer,

nRightY as Integer

) as enumErrorCodes

[C++]

short control.Fader.FadeInVolumeCurveSetEx (

short nCurveType,

short nLeftX,

short nLeftY,

short nRightX,

short nRightY

);

Parameter

Description

nCurveType

Type of curve applied to the volume sliding.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nLeftX

The horizontal position, expressed in percentage of the custom curve designer's area, of the left control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nLeftY

The vertical position, expressed in percentage of the custom curve designer's area, of the left control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nRightX

The horizontal position, expressed in percentage of the custom curve designer's area, of the right control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nRightY

The vertical position, expressed in percentage of the custom curve designer's area, of the right control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

(*) The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


Fader.FadeOutVolumeCurveSet method

Fader.FadeOutVolumeCurveSet method

Remarks

Sets the volume curve for fade-out operations.

This setting is lost after invoking the Fader.Exit method so you should call again this method after a new eventual call to the Fader.Init method.

Syntax

[Visual Basic]

control.Fader.FadeOutVolumeCurveSet (

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.Fader.FadeOutVolumeCurveSet (

short nCurveType,

long nDesignerUniqueId

);

Parameter

Description

nCurveType

Type of curve applied to the volume sliding.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

If you don't want to display the custom curve designer on your user interface but you know the exact position of the control points to set, you can use the Fader.FadeOutVolumeCurveSetEx method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


Fader.FadeOutVolumeCurveSetEx method

Fader.FadeOutVolumeCurveSetEx method

Remarks

Sets the volume curve for fade-out operations.

This setting is lost after invoking the Fader.Exit method so you should call again this method after a new eventual call to the Fader.Init method.

Syntax

[Visual Basic]

control.Fader.FadeOutVolumeCurveSetEx (

nCurveType as enumVolumeCurves,

nLeftX as Integer,

nLeftY as Integer,

nRightX as Integer,

nRightY as Integer

) as enumErrorCodes

[C++]

short control.Fader.FadeOutVolumeCurveSetEx (

short nCurveType,

short nLeftX,

short nLeftY,

short nRightX,

short nRightY

);

Parameter

Description

nCurveType

Type of curve applied to the volume sliding.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nLeftX

The horizontal position, expressed in percentage of the custom curve designer's area, of the left control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nLeftY

The vertical position, expressed in percentage of the custom curve designer's area, of the left control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nRightX

The horizontal position, expressed in percentage of the custom curve designer's area, of the right control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

nRightY

The vertical position, expressed in percentage of the custom curve designer's area, of the right control point (*). This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

(*) The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


Fader.Init method

Fader.Init method

Remarks

Initialises and enables the embedded Automatic Fader object: once created, the Automatic Fader can be disabled calling the Fader.Exit method.

Note that you can have only one single instance of the Automatic Fader for each instance of the control.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.Init (

nFadeType as enumFadeTypes,

nIndexPlayerA as Integer,

nIndexPlayerB as Integer

) as enumErrorCodes

[C++]

short control.Fader.Init (

short nFadeType,

short nIndexPlayerA,

short nIndexPlayerB

);

Parameter

Description

nFadeType

The automatic fading type.

Supported values are the following:

Mnemonic value | Value | Meaning
FADE_SINGLE | 0 | The cross-fading between the two involved players is performed through the respective loaded songs. Use the Fader.StartManualFading method in order to start the first fading operation.
FADE_PLAYLIST | 1 | The cross-fading between the two involved players is performed getting sound files from their respective loaded playlists: it's mandatory that each involved player has a loaded playlist. Use the Fader.StartManualFading method in order to start the first fading operation.
FADE_SINGLE_PLAYLIST | 2 | The cross-fading between the two involved players is performed getting sound files from one single playlist loaded inside one of the two players; the player owning the playlist to execute is determined through a call to the Fader.PlayListUseSingle. Use the Fader.StartManualFading method in order to start the first fading operation.

nIndexPlayerA

Number representing the zero-based index of the first involved player

nIndexPlayerB

Number representing the zero-based index of the second involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Fader.PlayListUseSingle method

Fader.PlayListUseSingle method

Remarks

Instructs the fader to mix sounds coming from the single playlist taken from the given player.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.PlayListUseSingle (

nIndexPlayer as Integer

) as enumErrorCodes

[C++]

short control.Fader.PlayListUseSingle (

short nIndexPlayer

);

Parameter | Description
nIndexPlayer | Number representing the zero-based index of the player whose playlist will be used in order to perform automatic fading operations between the two players set inside the Fader.Init method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Fader.StartManualFading method

Fader.StartManualFading method

Remarks

Manually starts the cross-fading procedure on the Automatic Fader without waiting to reach the trigger set through the Fader.FadeStartFromEnd property. A started cross-fading procedure can be stopped through the Fader.Stop method.

This method requires a previous call to the Fader.Init method and that the two involved players have a loaded song.

When the embedded fader is executing a playlist predisposed to work with volume automation, calling this method during the volume sliding, automatically started by the volume automation procedure, will fail reporting back the ERR_PLAYER_BUSY error: you can know if a volume sliding is still occurring on one of the involved players by querying the StreamVolumeIsSliding method on both players.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.StartManualFading (

) as enumErrorCodes

[C++]

short control.Fader.StartManualFading (

);

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Fader.Stop method

Fader.Stop method

Remarks

Stops the embedded Automatic Fader previously started through the Fader.StartManualFading method.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

controlFader.Stop (

)

[C++]

void control.Fader.Stop (

);

Return value

None


Fader.Display object

Fader.Display object

The Display object, accessible through the control's Fader.Display property, is internally implemented as a COM interface called IDisplay and contains information needed to operate the Display used by the embedded Automatic Fader.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

The Fader Display object is implemented through the following methods and properties:

Methods

Create

Show

SetHwnd

SetBackPictureFromFile

SetBackPictureFromHandle

Properties

ColorSongFadingOut

ColorSongFadingIn

ColorLineMixPoint

ColorLineSongEnd

ColorBackground

WidthSongLines

WidthReferenceLines

The following code snippets show how to initialise and change settings for this object in your code. These examples assume that you have placed a control named MyPlayer on a form or dialog and that you want to change a couple of settings for the Automatic Fader Display (the color of the lines representing the fading songs).

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Microsoft Visual Basic (5.0 and 6.0)

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual J#.NET

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Properties and methods of the control are accessible through the control wrapper class CAmp3dj contained inside the amp3dj.cpp and amp3dj.h files: these wrapper files are automatically generated when you insert the control inside your project so, in order to access the wrapper functions, you will have to insert the following line of code somewhere in your code.

#include "amp3dj.h"

The Fader object and its relative Display object are respectively defined by the control wrapper classes CFader (contained inside the fader.cpp and fader.h files) and CDisplay (contained inside the display.cpp and display.h files) : also these wrapper files are automatically generated when you insert the control inside your project so, in order to access these objects, you will have to insert the following lines of code somewhere in your code.

#include "fader.h"

#include "display.h"

Here follows the code needed to perform the requested operation of initialising the Fader object and changing some of its properties.

// declare a Fader object and initialize it with the control's Fader reference

CFader fader = MyPlayer.GetFader ();

// initialise the Fader on player 0 and player 1

fader.Init (FADE_SINGLE, 0, 1);

// declare and obtain the Display object for the Fader

CDisplay display = fader.GetDisplay ();

// create the Display over an existing control identified by the IDC_GRAPHIC id

display.Create ((OLE_HANDLE) GetDlgItem (IDC_PICTURE)->GetSafeHwnd ());

// set the Blue color for the line representing the song fading-out

display.SetColorSongFadingOut (RGB (0, 0, 255));

// set the Yellow color for the line representing the song fading-in

display.SetColorSongFadingIn (RGB (255, 255, 0));

As you can see the access to the Fader properties FadeInLength and FadeOutLength are wrapped by the SetFadeInLength and SetFadeOutLength functions declared inside the wrapper class CFader.

Note that the use of the FADE_SINGLE enumerated type requires to add the following include to your code:

#include "AdjMmsEngDef.h"

Microsoft Visual Basic (5.0 and 6.0)

Here follows the code needed to perform the requested operations

' initialise the Fader

MyPlayer.Fader.Init FADE_SINGLE, 0, 1

' create the Display and show it over an existing Picture control

MyPlayer.Fader.Display.Create Picture1.hWnd

MyPlayer.Fader.Display.Show BOOL_TRUE

' set the Blue color for the line representing the song fading-out

MyPlayer.Fader.Display.ColorSongFadingOut = RGB(0, 0, 255)

' set the Yellow color for the line representing the song fading-in

MyPlayer.Fader.Display.ColorSongFadingIn = RGB(255, 255, 0)

Microsoft Visual Basic.NET

Here follows the code needed to perform the requested operations

' initialise the Fader

MyPlayer.Fader.Init(AMP3DJLib.enumFadeTypes.FADE_SINGLE, 0, 1)

' create the Display and show it over an existing Picture control

MyPlayer.Fader.Display.Create(PictureBox1.Handle.ToInt32())

MyPlayer.Fader.Display.Show(AMP3DJLib.enumBoolean.BOOL_TRUE)

' set the Blue color for the line representing the song fading-out

MyPlayer.Fader.Display.ColorSongFadingOut = Convert.ToUInt32(RGB(0, 0, 255))

' set the Yellow color for the line representing the song fading-in

MyPlayer.Fader.Display.ColorSongFadingIn = Convert.ToUInt32(RGB(255, 255, 0))

Microsoft Visual C#.NET

Here follows the code needed to perform the requested operations

// initialise the Fader

MyPlayer.Fader.Init(AMP3DJLib.enumFadeTypes.FADE_SINGLE, 0, 1);

// create the Display and show it over an existing Picture control

MyPlayer.Fader.Display.Create(pictureBox1.Handle.ToInt32());

MyPlayer.Fader.Display.Show (enumBoolean.BOOL_TRUE);

// set the Blue color for the line representing the song fading-out

MyPlayer.Fader.Display.ColorSongFadingOut = Convert.ToUInt32 (ColorTranslator.ToWin32(Color.Blue));

// set the Yellow color for the line representing the song fading-in

MyPlayer.Fader.Display.ColorSongFadingIn = Convert.ToUInt32 (ColorTranslator.ToWin32(Color.Yellow));

Microsoft Visual J#.NET

Here follows the code needed to perform the requested operations

// initialise the Fader

MyPlayer.get_Fader().Init(AMP3DJLib.enumFadeTypes.FADE_SINGLE, (short) 0, (short) 1);

// create the Display and show it over an existing Picture control

MyPlayer.get_Fader().get_Display().Create(pictureBox1.get_Handle().ToInt32());

MyPlayer.get_Fader().get_Display().Show (AMP3DJLib.enumBoolean.BOOL_TRUE);

// set the Blue color for the line representing the song fading-out

System.UInt32 colorBlue = (System.UInt32) ColorTranslator.ToWin32 (Color.get_Blue ());

MyPlayer.get_Fader().get_Display().set_ColorSongFadingOut (colorBlue);

// set the Yellow color for the line representing the song fading-in

System.UInt32 colorYellow = (System.UInt32) ColorTranslator.ToWin32 (Color.get_Yellow ());

MyPlayer.get_Fader().get_Display().set_ColorSongFadingIn (colorYellow);

As you can see, in J#.NET the access to the control properties is made through the use of wrapper functions (automatically generated when you insert the control inside your project) with the "get_" and "set_" prefixes. Intellisense will help you finding the right wrapper function.


Fader.Display.ColorBackground property

Fader.Display.ColorBackground property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Fader.Display.ColorBackground [=long]
Remarks | Determines the color used to render the Display background.
See also | Fader.Display COM object. Fader.Display property How to use the Automatic Fader section.


Fader.Display.ColorLineMixPoint property

Fader.Display.ColorLineMixPoint property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Fader.Display.ColorLineMixPoint [=long]
Remarks | Determines the color used to render the line representing the Mix point.
See also | Fader.Display COM object. Fader.Display property How to use the Automatic Fader section.


Fader.Display.ColorLineSongEnd property

Fader.Display.ColorLineSongEnd property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Fader.Display.ColorLineSongEnd [=long]
Remarks | Determines the color used to render the line representing the end of the song fading-out.
See also | Fader.Display COM object. Fader.Display property How to use the Automatic Fader section.


Fader.Display.ColorSongFadingIn property

Fader.Display.ColorSongFadingIn property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Fader.Display.ColorSongFadingIn [=long]
Remarks | Determines the color of the line representing the song fading-in.
See also | Fader.Display COM object. Fader.Display property How to use the Automatic Fader section.


Fader.Display.ColorSongFadingOut property

Fader.Display.ColorSongFadingOut property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Fader.Display.ColorSongFadingOut [=long]
Remarks | Determines the color of the line representing the song fading-out.
See also | Fader.Display COM object. Fader.Display property How to use the Automatic Fader section.


Fader.Display.WidthReferenceLines property

Fader.Display.WidthReferenceLines property

Type | short for Visual C++ integer for Visual Basic
Syntax | object.Fader.Display.WidthReferenceLines [=integer]
Remarks | Determines the width in pixels of the reference lines.
See also | Fader.Display COM object. Fader.Display property How to use the Automatic Fader section.


Fader.Display.WidthSongLines property

Fader.Display.WidthSongLines property

Type | short for Visual C++ integer for Visual Basic
Syntax | object.Fader.Display.WidthSongLines [=integer]
Remarks | Determines the width in pixels of the song lines.
See also | Fader.Display COM object. Fader.Display property How to use the Automatic Fader section.


Fader.Display.Create method

Fader.Display.Create method

Remarks

Creates the Fader.Display object: once created, the Display will stay active until the termination of the container application: being a graphical object, the Display needs to be associated to an existing window that will be used as a surface for the graphic rendering: this window can be changed at a later time through the Fader.Display.SetHwnd method.

Once created, by default the Display is still not visible: you must make a call to the Fader.Display.Show method in order to display it.

For details about using Display object refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.Display.Create (

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Fader.Display.Create (

OLE_HANDLE hWndTarget

);

Parameter | Description
hWndTarget | Handle of the window whose surface will be used in order to render the Display graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Fader.Display.SetBackPictureFromFile method

Fader.Display.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.Display.SetBackPictureFromFile (

strPathname as String

) as enumErrorCodes

[C++]

short control.Fader.Display.SetBackPictureFromFile (

LPCTSTR strPathname

);

Parameter | Description
strPathname | Absolute pathname of the picture file to load. Accepted graphic formats are BMP, JPEG, GIF, TIFF and PNG. An empty pathname will reset an eventual picture set through a previous call to this method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Fader.Display.SetBackPictureFromHandle method

Fader.Display.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle (HBITMAP).

For details about using the Automatic Fader refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.Display.SetBackPictureFromHandle (

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Fader.Display.SetBackPictureFromHandle (

OLE_HANDLE hBitmap

);

Parameter | Description
hBitmap | Handle of the bitmap to apply. If this parameter is set to 0 an eventual picture set through a previous call to this method will be reset.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Fader.Display.SetHwnd method

Fader.Display.SetHwnd method

Remarks

Changes the HWND of the window used as a surface for the graphic rendering.

For further details about using the Fader Display object refer to the Fader.Display object section.

For details about using Display object refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.Display.SetHwnd (

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Fader.Display.SetHwnd (

OLE_HANDLE hWndTarget

);

Parameter | Description
hWndTarget | Handle of the window whose surface will be used in order to render the Fader Display graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Fader.Display.Show method

Fader.Display.Show method

Remarks

Shows/hides the Fader Display object. This method has no effect without a previous call to the Fader.Display.Create method.

For details about using Display object refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

control.Fader.Display.Show (

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.Fader.Display.Show (

short bShow

);

Parameter

Description

bShow

Boolean value that specifies to the player if it must show/hide the Fader Display.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the Fader Display graphics
BOOL_TRUE | 1 | Shows the Fader Display graphics

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager object

GraphicBarsManager object

The GraphicBarsManager object, accessible through the control's GraphicBarsManager property, is internally implemented as a COM interface called IGraphicBarsManager and contains information needed to render custom graphic bars like VU-Meters bars, Spectrum bars and Progress bars.

It can be used at Run-time in order to create various graphic bars and to change their graphical settings. For details about using graphic bars refer to the How to perform custom feedbacks rendering using graphic bars section.

The GraphicBarsManager object is implemented through the following methods:

Methods

Create

Destroy

GetGraphicalSettings

GetGraphicalSettingsParam

GetRange

GetValue

Move

Refresh

SetFlatBorder

SetGraphicalSettings

SetGraphicalSettingsParam

SetRange

SetValue

Show

Data structures

GRAPHIC_BAR_SETTINGS

Samples of use of the GraphicBarsManager object in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- Feedbacks

- TestEqualizer

- TestVideoPlayer


GraphicBarsManager.Create method

GraphicBarsManager.Create method

Remarks

Creates a new instance of the GraphicBarsManager object on the given parent window.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.Create (

hWndParent as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as OLE_HANDLE

[C++]

OLE_HANDLE control.GraphicBarsManager.Create (

OLE_HANDLE hWndParent,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Other values | Handle (HWND) of the new graphic bar


GraphicBarsManager.Destroy method

GraphicBarsManager.Destroy method

Remarks

Destroys an existing graphic bar control.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.Destroy (

hWndGraphicBar as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.Destroy (

OLE_HANDLE hWndGraphicBar

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager.GetGraphicalSettings method

GraphicBarsManager.GetGraphicalSettings method

Remarks

Retrieves the current graphical settings for the given graphic bar. Settings can be modified through the GraphicBarsManager.SetGraphicalSettings method.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.GetGraphicalSettings (

hWndGraphicBar as OLE_HANDLE,

pParamData as Long

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.GetGraphicalSettings (

OLE_HANDLE hWndGraphicBar,

void *pParamData

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
pParamData | Address of a structure of type GRAPHIC_BAR_SETTINGS that receives in output graphical settings of the graphic bar.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


GraphicBarsManager.GetGraphicalSettingsParam method

GraphicBarsManager.GetGraphicalSettingsParam method

Remarks

Retrieves one of the current graphical settings for the given graphic bar. Single settings can be modified through the GraphicBarsManager.SetGraphicalSettingsParam method.

This method is an alternative to the GraphicBarsManager.GetGraphicalSettings method and it's provided with the purpose of allowing single settings retrieval when dealing with languages like JavaScript where data structures are not easy to implement.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.GetGraphicalSettingsParam (

hWndGraphicBar as OLE_HANDLE,

nParam as short

) as String

[C++]

BSTR control.GraphicBarsManager.GetGraphicalSettingsParam (

OLE_HANDLE hWndGraphicBar,

short nParam

);

Parameter

Description

hWndGraphicBar

Handle of the control returned by a previous call to the GraphicBarsManager.Create method

nParam

Numeric identifier of the requested parameter.

Supported values are the following:

Numeric value | Meaning
0 | nOrientation member of the GRAPHIC_BAR_SETTINGS data structure
1 | bAppearance3d member of the GRAPHIC_BAR_SETTINGS data structure
2 | bSmoothing member of the GRAPHIC_BAR_SETTINGS data structure
3 | bAutomaticDrop member of the GRAPHIC_BAR_SETTINGS data structure
4 | bSmoothing member of the GRAPHIC_BAR_SETTINGS data structure
5 | colorStart member of the GRAPHIC_BAR_SETTINGS data structure
6 | colorEnd member of the GRAPHIC_BAR_SETTINGS data structure
7 | nShape member of the GRAPHIC_BAR_SETTINGS data structure

Return value

Value | Meaning
Empty string | An error occurred: see the LastError property for further error details or for a list of the possible error values.
Valid string | String containing the value of the requested parameter.


GraphicBarsManager.GetRange method

GraphicBarsManager.GetRange method

Remarks

Obtains the range of values accepted by the graphic bar. The current range can be modified through the GraphicBarsManager.SetRange method.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.GetRange (

hWndGraphicBar as OLE_HANDLE,

nMinValue as Long,

nMaxValue as Long

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.GetRange (

OLE_HANDLE hWndGraphicBar,

long* nMinValue,

long* nMaxValue

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
nMinValue | Reference to Min value
nMaxValue | Reference to Max value

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager.GetValue method

GraphicBarsManager.GetValue method

Remarks

Obtains the current value set into the graphic bar. The current value can be modified through the GraphicBarsManager.SetValue method.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.GetValue (

hWndGraphicBar as OLE_HANDLE,

nValue as Long

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.GetValue (

OLE_HANDLE hWndGraphicBar,

long* nValue

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
nValue | Reference to the current value

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager.Move method

GraphicBarsManager.Move method

Remarks

Moves or resizes an existing graphic bar control.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.Move (

hWndGraphicBar as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.Move (

OLE_HANDLE hWndGraphicBar,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
nLeft | Left position of the window, expressed in parent's client coordinates (pixels)
nTop | Top position of the window, expressed in parent's client coordinates (pixels)
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager.Refresh method

GraphicBarsManager.Refresh method

Remarks

Refreshes an existing graphic bar control.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.Refresh (

hWndGraphicBar as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.Refresh (

OLE_HANDLE hWndGraphicBar

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager.SetFlatBorder method

GraphicBarsManager.SetFlatBorder method

Remarks

Sets parameters for the flat border surrounding the graphic bar. This method is ignored if the border of the graphic bar has been set to 3D mode by setting the bAppearance3d parameter of the GRAPHIC_BAR_SETTINGS structure to "True".

In the graphics below you can see the flat border having a width set to two pixels and the color set to green.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.SetFlatBorder (

hWndGraphicBar as OLE_HANDLE,

nWidth as Integer,

color as OLE_COLOR

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.SetFlatBorder (

OLE_HANDLE hWndGraphicBar,

short nWidth,

OLE_COLOR color

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
nWidth | Width of the border expressed in pixels
color | Color of the border

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager.SetGraphicalSettings method

GraphicBarsManager.SetGraphicalSettings method

Remarks

Modifies the graphical settings for the given graphic bar. Current settings can be obtained through the GraphicBarsManager.GetGraphicalSettings method.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.SetGraphicalSettings (

hWndGraphicBar as OLE_HANDLE,

pParamData as Long

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.SetGraphicalSettings (

OLE_HANDLE hWndGraphicBar,

void *pParamData

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
pParamData | Address of a structure of type GRAPHIC_BAR_SETTINGS containing graphical settings of the graphic bar.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


GraphicBarsManager.SetGraphicalSettingsParam method

GraphicBarsManager.SetGraphicalSettingsParam method

Remarks

Sets one of the graphical settings for the given graphic bar. Value of single settings can be obtained through the GraphicBarsManager.GetGraphicalSettingsParam method.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.SetGraphicalSettings (

hWndGraphicBar as OLE_HANDLE,

pParamData as Long,

strValue as String

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.SetGraphicalSettings (

OLE_HANDLE hWndGraphicBar,

void *pParamData,

LPCTSTR strValue

);

Parameter

Description

hWndGraphicBar

Handle of the control returned by a previous call to the GraphicBarsManager.Create method

nParam

Numeric identifier of the requested parameter.

Supported values are the following:

Numeric value | Meaning
0 | nOrientation member of the GRAPHIC_BAR_SETTINGS data structure
1 | bAppearance3d member of the GRAPHIC_BAR_SETTINGS data structure
2 | bSmoothing member of the GRAPHIC_BAR_SETTINGS data structure
3 | bAutomaticDrop member of the GRAPHIC_BAR_SETTINGS data structure
4 | bSmoothing member of the GRAPHIC_BAR_SETTINGS data structure
5 | colorStart member of the GRAPHIC_BAR_SETTINGS data structure
6 | colorEnd member of the GRAPHIC_BAR_SETTINGS data structure
7 | nShape member of the GRAPHIC_BAR_SETTINGS data structure

strValue

String representing the numerical value to set: the multimedia engine will manage converting the string into the corresponding numerical value.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


GraphicBarsManager.SetRange method

GraphicBarsManager.SetRange method

Remarks

Sets the range of values accepted by the graphic bar. The current range can be obtained through the GraphicBarsManager.GetRange method.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.SetRange (

hWndGraphicBar as OLE_HANDLE,

nMinValue as Long,

nMaxValue as Long

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.SetRange (

OLE_HANDLE hWndGraphicBar,

long nMinValue,

long nMaxValue

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
nMinValue | Min value
nMaxValue | Max value

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager.SetValue method

GraphicBarsManager.SetValue method

Remarks

Sets a new value into the graphic bar. The current value can be obtained through the GraphicBarsManager.GetValue method.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.SetValue (

hWndGraphicBar as OLE_HANDLE,

nValue as Long

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.SetValue (

OLE_HANDLE hWndGraphicBar,

long nValue

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
nValue | New value

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GraphicBarsManager.Show method

GraphicBarsManager.Show method

Remarks

Shows/hides an existing graphic bar control.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

control.GraphicBarsManager.Show (

hWndGraphicBar as OLE_HANDLE,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.GraphicBarsManager.Show (

OLE_HANDLE hWndGraphicBar,

short bShow

);

Parameter

Description

hWndGraphicBar

Handle of the control returned by a previous call to the GraphicBarsManager.Create method

bShow

Boolean value that specifies if it must show/hide the given graphic bar control.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Hides the graphic bar window
BOOL_TRUE | Shows the graphic bar window

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


GRAPHIC_BAR_SETTINGS structure

GRAPHIC_BAR_SETTINGS structure

The GRAPHIC_BAR_SETTINGS class describes the graphical settings applied to a specific graphic bar. The current settings can be retrieved through the GraphicBarManager.GetGraphicalSettings method and modified through the GraphicBarManager.SetGraphicalSettings method.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsManager object.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

Visual C++ definition

typedef struct

{

 long       nOrientation;

 short       bAppearance3d;

 short       bSmoothing;

 short       bAutomaticDrop;

 OLE_COLOR   colorStart;

 OLE_COLOR   colorEnd;

 OLE_COLOR   colorBackground;

 long       nShape;

} GRAPHIC_BAR_SETTINGS;

Visual Basic definition

Public Type GRAPHIC_BAR_SETTINGS

nOrientation As enumGraphicBarOrientations

bAppearance3d As Boolean

bSmoothing As Boolean

bAutomaticDrop As Boolean

colorStart As OLE_COLOR

colorEnd As OLE_COLOR

colorBackground As OLE_COLOR

nShape As enumGraphicBarShapes

End Type

Member

Description

nOrientation

Graphic bar orientation.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_BAR_ORIENT_VERTICAL | 0 | The graphic bar is oriented vertically as seen in the image below:
GRAPHIC_BAR_ORIENT_HORIZONTAL (default) | 1 | The graphic bar is oriented horizontally as seen in the image below:

bAppearance3d

Boolean value that specifies if the graphic bar is displayed with 3D borders.

Supported values are the following:

Value | Meaning
False (default) | Doesn't display 3D borders
True | Displays 3D borders

bSmoothing

Smoothing flag.

Supported values are the following:

Value | Meaning
False (default) | The graphic bar will not be smoothed as seen on the image below:
True | The graphic bar will be smoothed as seen on the image below:

bAutomaticDrop

Automatic drop flag: this feature allows decreasing the displayed value to 0 with a certain delay as seen on certain hardware based VU-meters when no input sound is available.

Supported values are the following:

Value | Meaning
False (default) | The displayed level will not drop automatically, allowing a smoother decrease
True | The displayed level will drop automatically, allowing an immediate decrease

colorStart

The color starting the gradient rendering (default is set to light Green)

colorEnd

The color ending the gradient rendering. Use the same value of the colorStart member if you want a single color graphic bar. (default is set to light Red)

colorBackground

The color used as a background (default is set to Black)

nShape

Graphic bar orientation.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_BAR_SHAPE_RECT (default) | 0 | The gradient will have a rectangular shape:
GRAPHIC_BAR_SHAPE_ROUND_RECT | 1 | The gradient will have a rounded rectangle shape:
GRAPHIC_BAR_SHAPE_ELLIPSE | 2 | The gradient will have an elliptic shape:


MediaFileDecoder object

MediaFileDecoder object

The MediaFileDecoder object, accessible through the control's MediaFileDecoder property, is internally implemented as a COM interface called IMediaFileDecoder and allows decoding the audio track of various types of media files.

For details about management of media files decoding, refer to the How to decode media files tutorial.

The MediaFileDecoder object is implemented through the following properties and methods:

Methods

Initialize

FileClose

FileChunkLengthGet

FileDataGet

FileDurationGet

FileOpen

FileOpenRaw

FileInfoGet

FileLengthGet

FilePositionGet

FilePositionSet


MediaFileDecoder.FileChunkLengthGet method

MediaFileDecoder.FileChunkLengthGet method

Remarks

Obtains the length of a portion of the decoded media file.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileLengthGet (

nStartPosition as Long,

nEndPosition as Long,

nLength as Long

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileLengthGet (

long nStartPosition,

long nEndPosition,

long *nLength

);

Parameter | Description
nStartPosition | Start position expressed in milliseconds
nEndPosition | End position expressed in milliseconds
nLength | Reference that, on return from the method call, will contain the length in bytes of the given portion of decoded media file.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FileClose method

MediaFileDecoder.FileClose method

Remarks

Closes a media file previously opened through the MediaFileDecoder.FileOpen or MediaFileDecoder.FileOpenRaw methods.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileClose (

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileClose (

);

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FileDataGet method

MediaFileDecoder.FileDataGet method

Remarks

Reads a chunk of sound data from the decoded media file into a memory buffer. Each call to this method will automatically increment the position internal to the decoded file allowing to read the full audio track without the need to reposition the reader.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileDataGet (

pBuffer as Variant,

nBufferLen as Long,

nDataType as enumDataTypes,

nBytesRead as Long

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileDataGet (

const VARIANT FAR& pBuffer,

long nBufferLen,

short nDataType,

long *nBytesRead

);

Parameter

Description

pBuffer

Variant variable containing the pointer to the buffer to receive the data

nBufferLen

Length in bytes of the given buffer

nDataType

Establishes how data read should be returned.

Supported values are the following:

Mnemonic constant | Value | Meaning
DATA_TYPE_NATIVE | 0 | Sound data is read using the same bits per sample of the decoded file.
DATA_TYPE_FLOAT | 1 | Sound data is read in floating point.

nBytesRead

Reference that, on return from the method call, will contain the number of bytes effectively read.

This parameter will usually return the same number of bytes set into the nBufferLen parameter: if the returned value should be smaller than the nBufferLen parameter or should be 0, this would mean that the end of the audio track has been reached.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FileDurationGet method

MediaFileDecoder.FileDurationGet method

Remarks

Obtains the duration of the decoded media file.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileDurationGet (

nDuration as Long

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileDurationGet (

long *nDuration

);

Parameter | Description
nDuration | Reference that, on return from the method call, will contain the duration in milliseconds of the decoded media file.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FileInfoGet method

MediaFileDecoder.FileInfoGet method

Remarks

Obtains information about the decoded media file.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileInfoGet (

nFrequency as Long,

nChannels as Long,

nEncodeMode as enumRAWEncodeModes

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileInfoGet (

long *nFrequency,

long *nChannels,

long *nEncodeMode

);

Parameter

Description

nFrequency

Reference that, on return from the method call, will contain the sample rate of the decoded file

nChannels

Reference that, on return from the method call, will contain the number of channels of the decoded file

nEncodeMode

Reference that, on return from the method call, will contain the encode mode (bit depth) used to internally store the decoded and uncompressed file: for RAW sound files, in most cases it may not reflect the original encode mode of the source file.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
RAW_ENCODE_PCM_U8 | 0 | PCM 8 bits Unsigned
RAW_ENCODE_PCM_S16 | 2 | PCM 16 bits Signed
RAW_ENCODE_FLOAT32 | 5 | 32 bits floating point

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FileLengthGet method

MediaFileDecoder.FileLengthGet method

Remarks

Obtains the length of the decoded media file.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileLengthGet (

nLength as Long

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileLengthGet (

long *nLength

);

Parameter | Description
nLength | Reference that, on return from the method call, will contain the length in bytes of the decoded media file.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FileOpen method

MediaFileDecoder.FileOpen method

Remarks

Opens a media file with the purpose of decoding the audio track.

Supported media files can be separated in 3 main categories:

· Media files supported natively :

- AAC | - M4A | - PAF
- AC3 | - MOD Music | - PVF
- AIFF | - Monkey's Audio (APE) | - Speex
- ALAC | - MP3, MP2, MP1 | - SVX
- AU | - MP4 | - VOC
- CAF (1) | - Musepack | - W64
- CD tracks | - NIST | - WAV (2)
- FLAC | - OGG Vorbis | - WavPack
- IRCAM | - OPUS | - WMA and WMV (3)

(1) Support for PCM 8/16/24/32 bits, PCM 32 bits floating point, G711 U-LAW, G711 A-LAW

(2) Support for uncompressed PCM and compressed formats whose ACM codec is installed inside the system

(3) Require the availability of Windows Media Player modules on the target PC

· Media files supported by Windows Media Foundation (only under Windows Vista and higher versions)
· Media files supported by available DirectShow codecs

For audio files stored in RAW format use the MediaFileDecoder.FileOpenRaw method.

The opening and decoding of huge sized files can be canceled through the MediaFileDecoder.FileOpenCancel method.

An opened file can be closed through the MediaFileDecoder.FileClose method.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileOpen (

strPathname as String

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileOpen (

LPCTSTR strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the media file to load.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The media file has been decoded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FileOpenRaw method

MediaFileDecoder.FileOpenRaw method

Remarks

Opens and decodes the specified file in RAW format.

An opened file can be closed through the MediaFileDecoder.FileClose method.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileOpenRaw (

strPathname as String,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as enumBoolean,

nFrequency as Long,

nChannels as Long

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileOpenRaw (

LPCTSTR strPathname,

short nEncodeMode,

short bIsBigEndian,

long nFrequency,

long nChannels

);

Parameter

Description

strPathname

String containing the absolute pathname of the media file to load.

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
RAW_ENCODE_PCM_U8 | 0 | RAW PCM 8 bits Unsigned
RAW_ENCODE_PCM_S8 | 1 | RAW PCM 8 bits Signed
RAW_ENCODE_PCM_S16 | 2 | RAW PCM 16 bits Signed
RAW_ENCODE_PCM_S24 | 3 | RAW PCM 24 bits Signed
RAW_ENCODE_PCM_S32 | 4 | RAW PCM 32 bits Signed
RAW_ENCODE_FLOAT32 | 5 | RAW 32 bits floating point
RAW_ENCODE_G711_ULAW | 6 | RAW G711 U-LAW
RAW_ENCODE_G711_ALAW | 7 | RAW G711 A-LAW
RAW_ENCODE_GSM_610 | 8 | RAW GSM 6.10
RAW_ENCODE_DIALOGIC_VOX | 9 | RAW Dialogic ADPCM VOX

bIsBigEndian

Boolean flag that specifies if bits order inside the RAW file are little-endian or big-endian

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | The RAW file is encoded using little-endian
BOOL_TRUE | The RAW file is encoded using big-endian

nFrequency

Sample rate of the RAW file (e.g. 44100)

nChannels

Number of channels of the RAW file: 1 for Mono or 2 for Stereo

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The audio file has been decoded successfully.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FileOpenCancel method

MediaFileDecoder.FileOpenCancel method

Remarks

Aborts the opening and decoding of a media file started through the MediaFileDecoder.FileOpen method.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FileOpenCancel (

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FileOpenCancel (

);

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FilePositionGet method

MediaFileDecoder.FilePositionGet method

Remarks

Obtains the current position set into the decoded media file. The current position can be modified through the MediaFileDecoder.FilePositionSet method.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FilePositionGet (

nPosition as Long,

nPositionUnit as enumDecodePositionUnit

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FilePositionGet (

long *nPosition,

short nPositionUnit

);

Parameter

Description

nPosition

Reference that, on return from the method call, will contain the position expressed in the same unit set into the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for determining the nPosition parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
DECODE_POS_UNIT_MS | 0 | The nPosition parameter is expressed in milliseconds
DECODE_POS_UNIT_BYTES | 1 | The nPosition parameter is expressed in bytes
DECODE_POS_UNIT_PERCENTAGE | 2 | The nPosition parameter is expressed in percentage

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.FilePositionSet method

MediaFileDecoder.FilePositionSet method

Remarks

Modifies the position within the decoded media file. The current position can be obtained through the MediaFileDecoder.FilePositionGet method.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.FilePositionSet (

nPosition as Long,

nPositionUnit as enumDecodePositionUnit

) as enumErrorCodes

[C++]

short control.MediaFileDecoder.FilePositionSet (

long nPosition,

short nPositionUnit

);

Parameter

Description

nPosition

The position to reach expressed in the same unit set into the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for determining the nPosition parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
DECODE_POS_UNIT_MS | 0 | The nPosition parameter is expressed in milliseconds
DECODE_POS_UNIT_BYTES | 1 | The nPosition parameter is expressed in bytes
DECODE_POS_UNIT_PERCENTAGE | 2 | The nPosition parameter is expressed in percentage

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MediaFileDecoder.Initialize method

MediaFileDecoder.Initialize method

Remarks

Initializes the media file decoder. The call to this method is mandatory before calling any other method of the MediaFileDecoder object.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

control.MediaFileDecoder.Initialize (

)

[C++]

void control.MediaFileDecoder.Initialize (

);

Return value

None


MIDI object

MIDI object

The MIDI object, accessible through the control's MIDI property, is internally implemented as a COM interface called IMIDI and contains methods needed to manage MIDI protocol, MIDI files and MIDI input devices.

The MIDI object is implemented through the following methods:

Methods

BpmGet

BpmSet

ChannelsGet

ChannelsSet

DecayModeSet

KeyboardCreate

KeyboardDestroy

KeyboardGraphicalSettingsGet

KeyboardGraphicalSettingsSet

KeyboardMove

KeyboardNote

KeyboardRangeSet

KeyboardRefresh

KeyboardShow

InputDevicesCountGet

InputDevicesEnum

InputDevicesInfoGet

InputDevicesStart

InputDevicesStartOnPlayer

InputDevicesStop

MarkersEnableNotifications

MarkersEnum

MarkersEnumItemGet

PulsesPerQuarterNoteGet

SeekToPosition

SoundDurationGet

SoundFontApply

SoundFontDefaultConfigGet

SoundFontDefaultGet

SoundFontDefaultSet

SoundFontFree

SoundFontInit

SoundFontInfoNumGet

SoundFontInfoStringGet

SoundFontsInStreamEnum

SoundFontsInStreamItemGet

SoundFontListApply

SoundFontListApplyAsDefault

SoundFontListItemAdd

SoundFontListItemCountGet

SoundFontListItemRemove

SoundFontListItemUniqueIdGet

SoundFontLoad

SoundFontPresetDescGet

SoundFontUnload

SoundFontVolumeGet

SoundFontVolumeSet

SoundPositionGet

StreamEventApply

StreamEventValueGet

StreamEventsEnableNotifications

StreamEventsEnum

StreamEventsEnumFromRange

StreamEventsEnumItemGet

StreamEventsListApply

StreamEventsListItemAdd

StreamEventsListItemCountGet

StreamEventsListItemGet

StreamEventsListItemModify

StreamEventsListItemRemove

StreamEventsListItemUniqueIdGet

StreamEventsRawApply

StreamPreloadSamples

StreamStart

StreamStop

TempoPercGet

TempoPercSet

TrackCountGet

TrackTagsEnum

TrackTagsItemGet

TrackVolumeGet

TrackVolumeSet

TriggerAdd

TriggerSetPos

VoicesDefaultGet

VoicesDefaultSet

VoicesGet

VoicesSet

Data structures

MIDI_KEYBOARD_SETTINGS

Further information about management of MIDI protocol can be found inside the How to deal with MIDI protocol tutorial.

Samples of management of MIDI protocol in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- MidiPlayer

- MidiSynthesizer


MIDI.BPMGet method

MIDI.BPMGet method

Remarks

Obtains the current BPM (Beats Per Minute) of the playing MIDI stream. The current BPM can be changed through a call to the MIDI.BPMSet method and is also affected by calls to the MIDI.TempoPercSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.BPMGet (

nPlayer as Integer,

fBPM as Single

) as enumErrorCodes

[C++]

short control.MIDI.BPMGet (

short nPlayer,

float *fBPM

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fBPM | Reference that, on return from the method call, will contain the BPM of the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.BPMSet method

MIDI.BPMSet method

Remarks

Modifies the current BPM (Beats Per Minute) of the playing MIDI stream. The current BPM can be obtained through the MIDI.BPMGet method. By modifying the BPM of the playing MIDI stream, the tempo of the stream will be affected accordingly.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.BPMSet (

nPlayer as Integer,

fBPM as Single

) as enumErrorCodes

[C++]

short control.MIDI.BPMSet (

short nPlayer,

float fBPM

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fBPM | The new BPM to set on the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.ChannelsGet method

MIDI.ChannelsGet method

Remarks

Obtains the number of channels inside the loaded MIDI stream. The current number of channels can be changed through a call to the MIDI.ChannelsSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.ChannelsGet (

nPlayer as Integer,

nChannels as Integer

) as enumErrorCodes

[C++]

short control.MIDI.ChannelsGet (

short nPlayer,

short *nChannels

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nChannels | Reference that, on return from the method call, will contain the number of channels inside the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.ChannelsSet method

MIDI.ChannelsSet method

Remarks

Sets the number of channels inside the loaded MIDI stream. The current number of channels can be retrieved through a call to the MIDI.ChannelsGet method.

Eventual new channels will be, by default, melodic. If the new number of channels should be smaller than the original one, any notes playing on removed channels will be stopped.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.ChannelsSet (

nPlayer as Integer,

nChannels as Integer

) as enumErrorCodes

[C++]

short control.MIDI.ChannelsSet (

short nPlayer,

short nChannels

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nChannels | The number of channels inside the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.DecayModeSet method

MIDI.DecayModeSet method

Remarks

Specifies how the sound will decay at the end of playback or when a position's seek operation is performed.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.DecayModeSet (

nPlayer as Integer,

bLetDecayOnEnd as enumBoolean,

bLetDecayOnSeek as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.DecayModeSet (

short nPlayer,

short bLetDecayOnEnd,

short bLetDecayOnSeek

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bLetDecayOnEnd

Boolean value that specifies if the sound will decay naturally or will be stopped abruptly when the sound playback is completed.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The sound will be stopped abruptly when the sound playback is completed.
BOOL_TRUE | 1 | The sound will decay naturally when the sound playback is completed.

bLetDecayOnSeek

Boolean value that specifies if the sound will decay naturally or will be stopped abruptly when the sound position is changed through the SeekSound method. If needed, this setting can be overridden by performing the change of playback position through the MIDI.SeekToPosition method and by setting its bLetDecay parameter accordingly.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The sound will be stopped abruptly when the playback position is modified.
BOOL_TRUE | 1 | The sound will decay naturally when the playback position is modified.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.InputDevicesCountGet method

MIDI.InputDevicesCountGet method

Remarks

Reports the number of MIDI input devices installed inside the system and enumerated through a previous call to the MIDI.InputDevicesEnum method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.InputDevicesCountGet (

nCount as Integer

) as enumErrorCodes

[C++]

short control.MIDI.InputDevicesCountGet (

short *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the number of detected MIDI input devices.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.InputDevicesEnum method

MIDI.InputDevicesEnum method

Remarks

Enumerates MIDI input devices installed inside the system.

Information about each detected MIDI input device can be obtained through the MIDI.InputDevicesInfoGet method.

Before being used for detecting incoming MIDI events, each MIDI input device must be started through the MIDI.InputDevicesStart method or through the MIDI.InputDevicesStartOnPlayer method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.InputDevicesEnum (

nCount as Integer

) as enumErrorCodes

[C++]

short control.MIDI.InputDevicesEnum (

short *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the number of detected MIDI input devices.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.InputDevicesInfoGet method

MIDI.InputDevicesInfoGet method

Remarks

After completing the enumeration, started through the MIDI.InputDevicesEnum method, of MIDI input devices installed inside the system, allows retrieving information about a specific MIDI input device.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.InputDevicesInfoGet (

nDeviceIndex as Integer,

nManufacturerId as Long,

nProductId as Long,

bIsEnabled as enumBoolean,

bIsStarted as enumBoolean

) as String

[C++]

BSTR control.MIDI.InputDevicesInfoGet (

short nDeviceIndex,

long *nManufacturerId,

long *nProductId,

long *bIsEnabled,

long *bIsStarted

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the MIDI input device. The number of available MIDI input devices installed inside the system can be obtained directly through the MIDI.InputDevicesEnum method or, after having performed the enumeration, through the MIDI.InputDevicesCountGet method.

nManufacturerId

Reference that, on return from the method call, will contain the number representing the manufacturer identifier for the MIDI device. The list of known identifiers can be found inside the MSDN website

nProductId

Reference that, on return from the method call, will contain the number representing the product identifier for the MIDI device. The list of known identifiers can be found inside the MSDN website

bIsEnabled

Reference that, on return from the method call, will report if the MIDI input device is enabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The MIDI input device is disabled. In this situation a call to the MIDI.InputDevicesStartOnPlayer MIDI.InputDevicesStartOnPlayer method or through the MIDI.InputDevicesStart method will fail.
BOOL_TRUE | 1 | The MIDI input device is enabled.

bIsStarted

Reference that, on return from the method call, will report if the MIDI input device is started.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The MIDI input device has not been started.
BOOL_TRUE | 1 | The MIDI input device has already been started through the MIDI.InputDevicesStartOnPlayer MIDI.InputDevicesStartOnPlayer method or through the MIDI.InputDevicesStart method

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the friendly name of the MIDI input device


MIDI.InputDevicesStart method

MIDI.InputDevicesStart method

Remarks

After having enumerated, through a call to the MIDI.InputDevicesEnum method, the list of available MIDI input devices installed inside the system, starts a MIDI input device and sets a callback for receiving raw MIDI events from the MIDI input channel.

If incoming MIDI events should be sent and played directly through a player instanced by the control, it would be recommended using the MIDI.InputDevicesStartOnPlayer method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.InputDevicesStart (

nDeviceIndex as Integer,

pCallback as Long,

nUserData as Long

) as enumErrorCodes

[C++]

short control.MIDI.InputDevicesStart (

short nDeviceIndex,

long pCallback,

long nUserData

);

\

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the MIDI input device. The number of available MIDI input devices installed inside the system can be obtained directly to the MIDI.InputDevicesEnum method or, after having performed the enumeration, through the MIDI.InputDevicesCountGet method.

pCallback

Pointer to the callback function that will receive raw MIDI events from the MIDI input channel. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

A callback function is defined like this:

[Visual Basic ]

Public Sub MyMidiCallback(

ByVal bufferRawEvents As Long,

ByVal bufferLength As Long,

ByVal nUserData As Long

)

[Visual C++]

void MyMidiCallback (

void *bufferRawEvents,

DWORD bufferLength,

DWORD nUserData

);

where

bufferRawEvents | Pointer to the buffer containing raw MIDI events:
bufferLength | The length in bytes of the buffer above
nUserData | User specific data

nUserData

User data to pass to the callback

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.InputDevicesStartOnPlayer method

MIDI.InputDevicesStartOnPlayer method

Remarks

After having enumerated, through a call to the MIDI.InputDevicesEnum method, the list of available MIDI input devices installed inside the system, starts a MIDI input device and send incoming MIDI events directly to the MIDI stream loaded inside a player instanced by the component.

If incoming MIDI events should be managed without the need of immediate playback it would be recommended using the MIDI.InputDevicesStart method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.InputDevicesStartOnPlayer (

nDeviceIndex as Integer,

nPlayer as Integer

) as BSTR

[C++]

BSTR control.MIDI.InputDevicesStartOnPlayer (

short nDeviceIndex,

short nPlayer

);

\

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the MIDI input device. The number of available MIDI input devices installed inside the system can be obtained directly to the MIDI.InputDevicesEnum method or, after having performed the enumeration, through the MIDI.InputDevicesCountGet method.
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.InputDevicesStop method

MIDI.InputDevicesStop method

Remarks

Stops a MIDI input device previously started through the MIDI.InputDevicesStartOnPlayer method or through the MIDI.InputDevicesStart method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.InputDevicesStop (

nDeviceIndex as Integer

) as BSTR

[C++]

BSTR control.MIDI.InputDevicesStop (

short nDeviceIndex

);

\

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the MIDI input device. The number of available MIDI input devices installed inside the system can be obtained directly to the MIDI.InputDevicesEnum method or, after having performed the enumeration, through the MIDI.InputDevicesCountGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.KeyboardCreate method

MIDI.KeyboardCreate method

Remarks

Creates a new virtual piano keyboard on the given parent window.

Notes played on the virtual piano, through the left button of the mouse, will be directly sent to the MIDI stream in playback on the given player.

Keys pressure/release can be simulated through the MIDI.KeyboardNote method, for example for displaying a note played through an external physical MIDI keyboard attached to one of the MIDI input channels.

The container application is notified each time a key on the virtual keyboard is pressed or released through the MidiKeyboardNotification event.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardCreate (

nPlayer as Integer,

hWndParent as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long,

nLowNote as Integer,

nHighNote as Integer,

bSendEventNotif as enumBoolean,

nOrientation as enumMidiKeyboardOrientations

) as OLE_HANDLE

[C++]

OLE_HANDLE control.MIDI.KeyboardCreate (

short nPlayer,

OLE_HANDLE hWndParent,

long nLeft,

long nTop,

long nWidth,

long nHeight,

short nLowNote,

short nHighNote,

short bSendEventNotif,

short nOrientation

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

hWndParent

Handle of the parent window, usually the container form.

nLeft

Left position of the keyboard window, expressed in client coordinates (pixels) of hWndParent

nTop

Top position of the keyboard window, expressed in client coordinates (pixels) of hWndParent

nWidth

Width of the keyboard window, expressed in pixels

nHeight

Height of the keyboard window, expressed in pixels

nLowNote

Lower note displayed on the virtual piano keyboard. Can be a value between 0 and 127 but must always be a natural note (white key).

nHighNote

Higher note displayed on the virtual piano keyboard. Can be a value between 2 and 127 but must always be a natural note (white key).

bSendEventNotif

Boolean flag that specifies if the container application must be notified about the notes played on the keyboard through the MidiStreamEventNotification event.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The MidiStreamEventNotification event is not generated for notes played on the piano keyboard.
BOOL_TRUE | 1 | The MidiStreamEventNotification event is generated for notes played on the piano keyboard.

nOrientation

Orientation of the piano keyboard.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_KEYB_ORIENT_HORIZONTAL | 0 | The piano keyboard orientation is horizontal as in the picture below
MIDI_KEYB_ORIENT_VERTICAL_LEFT | 1 | The piano keyboard orientation is left vertical as in the picture below
MIDI_KEYB_ORIENT_VERTICAL_RIGHT | 2 | The piano keyboard orientation is right vertical as in the picture below

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Other values | Handle (HWND) of the new virtual piano keyboard


MIDI.KeyboardDestroy method

MIDI.KeyboardDestroy method

Remarks

Destroys an existing virtual piano keyboard.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardDestroy (

hWndKeyboard as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.MIDI.KeyboardDestroy (

OLE_HANDLE hWndKeyboard

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.KeyboardGraphicalSettingsGet method

MIDI.KeyboardGraphicalSettingsGet method

Remarks

Retrieves the current graphical settings for the given virtual piano keyboard. Settings can be modified through the MIDI.KeyboardGraphicalSettingsSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardGraphicalSettingsGet (

hWndKeyboard as OLE_HANDLE,

pParamData as Long

) as enumErrorCodes

[C++]

short control.MIDI.KeyboardGraphicalSettingsGet (

OLE_HANDLE hWndKeyboard,

void *pParamData

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method
pParamData | Address of a structure of type MIDI_KEYBOARD_SETTINGS that receives in output graphical settings of the keyboard.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MIDI.KeyboardGraphicalSettingsSet method

MIDI.KeyboardGraphicalSettingsSet method

Remarks

Modifies graphical settings for the given virtual piano keyboard. Current settings can be modified through the MIDI.KeyboardGraphicalSettingsGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardGraphicalSettingsSet (

hWndKeyboard as OLE_HANDLE,

pParamData as Long

) as enumErrorCodes

[C++]

short control.MIDI.KeyboardGraphicalSettingsSet (

OLE_HANDLE hWndKeyboard,

void *pParamData

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method
pParamData | Address of a structure of type MIDI_KEYBOARD_SETTINGS containing graphical settings of the keyboard.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


MIDI.KeyboardMove method

MIDI.KeyboardMove method

Remarks

Moves or resizes an existing virtual piano keyboard.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardMove (

hWndKeyboard as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.MIDI.KeyboardMove (

OLE_HANDLE hWndKeyboard,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method
nLeft | Left position of the keyboard window, expressed in parent's client coordinates (pixels)
nTop | Top position of the keyboard window, expressed in parent's client coordinates (pixels)
nWidth | Width of the keyboard window, expressed in pixels
nHeight | Height of the keyboard window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.KeyboardNote method

MIDI.KeyboardNote method

Remarks

Acts on the key corresponding to the given note on the virtual piano keyboard. The key pressure can be real, e.g. generating a note on the MIDI stream, or simulated: in this latest case the key on the keyboard results to be pressed but no sound is generated.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardNote (

hWndKeyboard as OLE_HANDLE,

nNote as Long,

nVelocity as Long,

bSimulated as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.KeyboardNote (

OLE_HANDLE hWndKeyboard,

long nNote,

long nVelocity,

short bSimulated

);

Parameter

Description

hWndKeyboard

Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method

nNote

Note to play. Can be a key number from 0 to 127; 60 means middle C

nVelocity

Velocity of the note. 0 means key released while values from 1 to 127 mean pressure.

bSimulated

Boolean flag that specifies if the key pressure is simulated. When the key pressure is simulated, the key will appear pressed on the piano keyboard but no real event will be generated on the MIDI stream in playback, allowing to display a note played through an external physical MIDI keyboard attached to one of the MIDI input channels.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The call to this method will play the requested note on the MIDI stream in playback
BOOL_TRUE | 1 | The call to this method will not play the requested note on the MIDI stream in playback but will display the corresponding key as pressed on the piano keyboard.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.KeyboardRangeSet method

MIDI.KeyboardRangeSet method

Remarks

Modifies the range of key notes on the given virtual piano keyboard.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardRangeSet (

hWndKeyboard as OLE_HANDLE,

nLowNote as Integer,

nHighNote as Integer

) as enumErrorCodes

[C++]

short control.MIDI.KeyboardRangeSet (

OLE_HANDLE hWndKeyboard,

short nLowNote,

short nHighNote

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method
nLowNote | Lower note displayed on the virtual piano keyboard. Can be a value between 0 and 127 but must always be a natural note (white key).
nHighNote | Higher note displayed on the virtual piano keyboard Can be a value between 2 and 127 but must always be a natural note (white key).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.KeyboardRefresh method

MIDI.KeyboardRefresh method

Remarks

Refreshes an existing virtual piano keyboard.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardRefresh (

hWndKeyboard as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.MIDI.KeyboardRefresh (

OLE_HANDLE hWndKeyboard

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.KeyboardShow method

MIDI.KeyboardShow method

Remarks

Shows/hides an existing virtual piano keyboard.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.KeyboardShow (

hWndKeyboard as OLE_HANDLE,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.KeyboardShow (

OLE_HANDLE hWndKeyboard,

short bShow

);

Parameter

Description

hWndKeyboard

Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method

bShow

Boolean value that specifies if it must show/hide the given virtual piano keyboard.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Hides the keyboard
BOOL_TRUE | Shows the keyboard

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.MarkersEnableNotifications method

MIDI.MarkersEnableNotifications method

Remarks

Enables/disables the synchronization of the container application with a specific type of MIDI marker detected inside the loaded MIDI stream during playback.

When synchronization is enabled, the component fires the MidiMarkerNotification event for each specific marker enabled for notification.

Markers can also be enumerated offline, while the MIDI stream is not in playback, through the combination of the MIDI.MarkersEnum and of the MIDI:MarkersEnumItemGet methods.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.MarkersEnableNotifications (

nPlayer as Integer,

nMarkerType as enumMidiMarkerNotifications,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.MarkersEnableNotifications (

short nPlayer,

short nMarkerType,

short bEnable

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMarkerType

The type of MIDI marker.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_NOTIFICATION_LYRIC | 0 | Lyrics (MIDI meta event 5)
MIDI_NOTIFICATION_TEXT | 1 | Text (MIDI meta event 1)
MIDI_NOTIFICATION_MARKER | 2 | Marker (MIDI meta event 6)
MIDI_NOTIFICATION_CUE | 3 | Cue point (MIDI meta event 7)
MIDI_NOTIFICATION_TIME_SIGNATURE | 4 | Time signature (MIDI meta event 88). The reported text is in the form of "a b", where a is the number of sharps, if positive, or flats, if negative, and b signifies major, if 0, or minor, if 1.
MIDI_NOTIFICATION_KEY_SIGNATURE | 5 | Key signature (MIDI meta event 89). The reported text is in the form of "a/b c d", where a is the numerator, b is the denominator, c is the metronome pulse and d is the number of 32nd notes per MIDI quarter-note.
MIDI_NOTIFICATION_COPYRIGHT | 6 | Copyright notice (MIDI meta event 2).
MIDI_NOTIFICATION_TRACK | 7 | Track name (MIDI meta event 3).
MIDI_NOTIFICATION_INSTRUMENT | 8 | Instrument name (MIDI meta event 4).

bEnable

Boolean value that specifies if the finding of the given marker during playback must be notified through the MidiMarkerNotification event.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Notification for the given marker is not enabled.
BOOL_TRUE | 1 | Notification for the given marker is enabled.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.MarkersEnum method

MIDI.MarkersEnum method

Remarks

Enumerates a specific type of marker detected inside the loaded MIDI stream. After completing the enumeration, information about each of the detected markers can be obtained through the MIDI.MarkersEnumItemGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.MarkersEnum (

nPlayer as Integer,

nMarkerType as enumMidiMarkerNotifications,

nCount as Long

) as enumErrorCodes

[C++]

short control.MIDI.MarkersEnum (

short nPlayer,

short nMarkerType,

long *nCount

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMarkerType

Type of marker whose notification for which there is an interest.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_NOTIFICATION_LYRIC | 0 | Lyrics (MIDI meta event 5)
MIDI_NOTIFICATION_TEXT | 1 | Text (MIDI meta event 1)
MIDI_NOTIFICATION_MARKER | 2 | Marker (MIDI meta event 6)
MIDI_NOTIFICATION_CUE | 3 | Cue point (MIDI meta event 7)
MIDI_NOTIFICATION_TIME_SIGNATURE | 4 | Time signature (MIDI meta event 88). The reported text is in the form of "a b", where a is the number of sharps, if positive, or flats, if negative, and b signifies major, if 0, or minor, if 1.
MIDI_NOTIFICATION_KEY_SIGNATURE | 5 | Key signature (MIDI meta event 89). The reported text is in the form of "a/b c d", where a is the numerator, b is the denominator, c is the metronome pulse and d is the number of 32nd notes per MIDI quarter-note.
MIDI_NOTIFICATION_COPYRIGHT | 6 | Copyright notice (MIDI meta event 2).
MIDI_NOTIFICATION_TRACK | 7 | Track name (MIDI meta event 3).
MIDI_NOTIFICATION_INSTRUMENT | 8 | Instrument name (MIDI meta event 4).

nCount

Reference that, on return from the method call, will contain the number of markers of the given type detected inside the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.MarkersEnumItemGet method

MIDI.MarkersEnumItemGet method

Remarks

After completing the enumeration, started through the MIDI.MarkersEnum method, of a specific type of marker detected inside the loaded MIDI stream, allows retrieving information about a specific marker.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.MarkersEnumItemGet (

nPlayer as Integer,

nMarkerType as enumMidiMarkerNotifications,

nMarkerIndex as Long,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits,

nTrack as Integer

) as BSTR

[C++]

BSTR control.MIDI.MarkersEnumItemGet (

short nPlayer,

short nMarkerType,

long nMarkerIndex,

double *fPosition,

short nPositionUnit,

short *nTrack

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMarkerType

Type of marker whose notification for which there is an interest.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_NOTIFICATION_LYRIC | 0 | Lyrics (MIDI meta event 5)
MIDI_NOTIFICATION_TEXT | 1 | Text (MIDI meta event 1)
MIDI_NOTIFICATION_MARKER | 2 | Marker (MIDI meta event 6)
MIDI_NOTIFICATION_CUE | 3 | Cue point (MIDI meta event 7)
MIDI_NOTIFICATION_TIME_SIGNATURE | 4 | Time signature (MIDI meta event 88). The reported text is in the form of "a b", where a is the number of sharps, if positive, or flats, if negative, and b signifies major, if 0, or minor, if 1.
MIDI_NOTIFICATION_KEY_SIGNATURE | 5 | Key signature (MIDI meta event 89). The reported text is in the form of "a/b c d", where a is the numerator, b is the denominator, c is the metronome pulse and d is the number of 32nd notes per MIDI quarter-note.
MIDI_NOTIFICATION_COPYRIGHT | 6 | Copyright notice (MIDI meta event 2).
MIDI_NOTIFICATION_TRACK | 7 | Track name (MIDI meta event 3).
MIDI_NOTIFICATION_INSTRUMENT | 8 | Instrument name (MIDI meta event 4).

nMarkerIndex

Number representing the zero-based index of the marker.

fPosition

Reference that, on return from the method call, will contain the position of the marker expressed in the unit set inside the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for the position value stored inside fPosition parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_POS_UNIT_TICKS | 0 | The value of the fPosition parameter is expressed in MIDI ticks.
MIDI_POS_UNIT_MS | 1 | The value of the fPosition parameter is expressed in milliseconds.
MIDI_POS_UNIT_PERCENTAGE | 2 | The value of the fPosition parameter is expressed in percentage.

nTrack

Reference that, on return from the method call, will contain the number of the MIDI track where the marker was detected. The total number of available MIDI tracks can be obtained through the MIDI:TrackCountGet method.

Return value

Value

Meaning

Empty string

An error occurred (see the LastError property for further error details)

Valid string

String containing the requested marker.

When dealing with markers MIDI_NOTIFICATION_LYRIC or MIDI_NOTIFICATION_TEXT, the returned string may contain the following characters:

· '/' (slash) means that a new line (Line Feed or LF) must be inserted
· '\' (backslash) means that the display containing previous texts must be cleared


MIDI.PulsesPerQuarterNoteGet method

MIDI.PulsesPerQuarterNoteGet method

Remarks

Obtains the number of Pulses Per Quarter Note (also known as "ticks per beat") inside the loaded MIDI stream.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.PulsesPerQuarterNoteGet (

nPlayer as Integer,

fPPQN as Single

) as enumErrorCodes

[C++]

short control.MIDI.PulsesPerQuarterNoteGet (

short nPlayer,

float *fPPQN

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fPPQN | Reference that, on return from the method call, will contain the number of Pulses Per Quarter Note inside the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SeekToPosition method

MIDI.SeekToPosition method

Remarks

Moves the given player to the specified position over the current MIDI song.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SeekToPosition (

nPlayer as Integer,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits,

bPerformDecay as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.SeekToPosition (

short nPlayer,

double fPosition,

short nPositionUnit,

short bPerformDecay

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

fPosition

Number representing the position to reach; its value depends upon the value of the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for the position value stored inside fPosition parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_POS_UNIT_TICKS | 0 | The fPosition parameter is expressed in MIDI ticks
MIDI_POS_UNIT_MS | 1 | The fPosition parameter is expressed in milliseconds. The position is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always move playback to the position on the song as it should be played at its original speed.
MIDI_POS_UNIT_PERCENTAGE | 2 | The fPosition parameter is expressed in percentage

bPerformDecay

Boolean value that specifies if the sound will decay naturally or will be stopped abruptly when the sound position is changed. This setting overrides an eventual setting performed through the MIDI.DecayModeSet method.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The sound will be stopped abruptly when the playback position is modified.
BOOL_TRUE | 1 | The sound will decay naturally when the playback position is modified.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundDurationGet method

MIDI.SoundDurationGet method

Remarks

Obtains the duration of the loaded MIDI stream.

This method keeps count of eventual tempo changes so the reported duration may vary depending upon the current tempo. If you should need retrieving the original duration of the loaded song you should use the SoundDurationGet method by setting the bKeepCountOfRateChange parameter to "BOOL_FALSE".

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundDurationGet (

nPlayer as Integer,

fDuration as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C++]

short control.MIDI.SoundDurationGet (

short nPlayer,

double *fDuration,

short nPositionUnit

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

fDuration

Reference that, on return from the method call, will contain the duration of the loaded MIDI stream; its value depends upon the value of the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for the position value stored inside fDuration parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_POS_UNIT_TICKS | 0 | The fDuration parameter is expressed in MIDI ticks
MIDI_POS_UNIT_MS | 1 | The fDuration parameter is expressed in milliseconds.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontApply method

MIDI.SoundFontApply method

Remarks

Applies a SoundFont, previously initialized through the MIDI.SoundFontInit method, to the MIDI stream loaded inside the given player.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontApply (

nPlayer as Integer,

nUniqueId as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontApply (

short nPlayer,

long nUniqueId

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontDefaultConfigGet method

MIDI.SoundFontDefaultConfigGet method

Remarks

Retrieves the current configuration of the default MIDI SoundFont.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontDefaultConfigGet (

nUniqueId As Long,

nPreset as Long,

nBank as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontDefaultConfigGet (

long *nUniqueId,

long *nPreset,

long *nBank

);

Parameter | Description
nUniqueId | Reference that, on return from the method call, will contain the unique identifier of the default SoundFont
nPreset | Reference that, on return from the method call, will contain the preset number
nBank | Reference that, on return from the method call, will contain the base bank number or the bank number of the individual preset

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontDefaultGet method

MIDI.SoundFontDefaultGet method

Remarks

Obtains the system default MIDI SoundFont. The default SoundFont can be modified through the MIDI.SoundFontDefaultSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontDefaultGet (

) as BSTR

[C++]

BSTR control.MIDI.SoundFontDefaultGet (

);

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the absolute pathname of the system default MIDI SoundFont


MIDI.SoundFontDefaultSet method

MIDI.SoundFontDefaultSet method

Remarks

Modifies the system default MIDI SoundFont. The current default SoundFont can be obtained through the MIDI.SoundFontDefaultGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontDefaultSet (

strPathname as String

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontDefaultSet (

BSTR strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the SoundFont file in SF2 format.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontFree method

MIDI.SoundFontFree method

Remarks

Discards from memory a SoundFont previously initialized through the MIDI.SoundFontInit method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontFree (

nUniqueId as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontFree (

long nUniqueId

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontInfoNumGet method

MIDI.SoundFontInfoNumGet method

Remarks

Obtains a numeric information about the given MIDI SoundFont.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontInfoNumGet (

nUniqueId as Long,

nInfo as enumMidiSoundFontNumInfo,

nValue as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontInfoNumGet (

long nUniqueId,

short nInfo,

long *nValue

);

Parameter

Description

nUniqueId

Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.

This parameter can be set to 0 when the request is related to the system default SoundFont.

nInfo

The type of information that must be retrieved.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_SOUNDFONT_INFO_PRESETS | 0 | The number of presets available inside the SoundFont
MIDI_SOUNDFONT_INFO_SAMPLES_SIZE | 1 | The total size, expressed in bytes, of samples data inside the SoundFont
MIDI_SOUNDFONT_INFO_SAMPLES_LOADED | 2 | The amount of samples data currently loaded

nValue

Reference that, on return from the method call, will contain the requested value

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontInfoStringGet method

MIDI.SoundFontInfoStringGet method

Remarks

Obtains a string information about the given MIDI SoundFont.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontInfoStringGet (

nUniqueId as Long,

nInfo as enumMidiSoundFontStringInfo

) as BSTR

[C++]

BSTR control.MIDI.SoundFontInfoStringGet (

long nUniqueId,

short nInfo

);

Parameter

Description

nUniqueId

Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.

This parameter can be set to 0 when the request is related to the system default SoundFont.

nInfo

The type of information that must be retrieved.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_SOUNDFONT_INFO_NAME | 0 | Friendly name of the SoundFont
MIDI_SOUNDFONT_INFO_COPYRIGHT | 1 | Copyright info
MIDI_SOUNDFONT_INFO_COMMENT | 2 | Comment

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the requested information


MIDI.SoundFontInit method

MIDI.SoundFontInit method

Remarks

Initializes a MIDI SoundFont. After initialization the SoundFont stays in memory until the MIDI.SoundFontFree method is called.

In case the MIDI SoundFont should be stored inside a memory buffer you should use the MIDI.SoundFontInitFromMemory method.

In case the MIDI SoundFont should be stored inside a ZIP file you should use the MIDI.SoundFontInitFromZip method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontInit (

strPathname as String

) as Long

[C++]

long control.MIDI.SoundFontInit (

BSTR strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the SoundFont file in SF2 format.

Return value

Value | Meaning
Value = 0 | An error occurred, check the LastError property value in order to get the error code
Other values | The method call was successful and the returned value is the unique identifier of the SoundFont.


MIDI.SoundFontInitFromMemory method

MIDI.SoundFontInitFromMemory method

Remarks

Initializes a MIDI SoundFont stored inside a memory buffer. After initialization the SoundFont stays in memory until the MIDI.SoundFontFree method is called.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontInitFromMemory (

pBuffer as Variant,

nBufferLen as Long

) as Long

[C++]

long control.MIDI.SoundFontInitFromMemory (

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
pBuffer | Variant parameter containing the pointer to SoundFont data previously loaded in memory.
nBufferLen | Length in bytes of the given buffer

Return value

Value | Meaning
Value = 0 | An error occurred, check the LastError property value in order to get the error code
Other values | The method call was successful and the returned value is the unique identifier of the SoundFont.


MIDI.SoundFontInitFromZip method

MIDI.SoundFontInitFromZip method

Remarks

Initializes a MIDI SoundFont stored inside a ZIP file. After initialization the SoundFont stays in memory until the MIDI.SoundFontFree method is called.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontInitFromZip (

strZipPathname as String,

strPassword as String,

strEntryName as String,

bReserved as enumBoolean

) as Long

[C++]

long control.MIDI.SoundFontInitFromZip (

LPCTSTR strZipPathname,

LPCTSTR strPassword,

LPCTSTR strEntryName,

short bReserved

);

Parameter | Description
strZipPathname | String containing the absolute pathname of the ZIP file to load.
strPassword | String containing the optional password for accessing the requested entry; leave it empty if not needed.
strEntryName | String representing the name of the entry to extract and load.
bReserved | Reserved for future uses

Return value

Value | Meaning
Value = 0 | An error occurred, check the LastError property value in order to get the error code
Other values | The method call was successful and the returned value is the unique identifier of the SoundFont.


MIDI.SoundFontListApply method

MIDI.SoundFontListApply method

Remarks

Applies in one single shot a list of MIDI SoundFonts to the loaded MIDI stream. The list can be cleared and removed from memory through the MIDI.StreamEventsListItemRemove method.

MIDI SoundFonts can be added to the list through the MIDI.SoundFontListItemAdd method or removed through the MIDI.SoundFontListItemRemove method. The total number of SoundFonts added to the list can be obtained through the MIDI.SoundFontListItemCountGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontListApply (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontListApply (

short nPlayer

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontListApplyAsDefault method

MIDI.SoundFontListApplyAsDefault method

Remarks

Applies in one single shot a list of MIDI SoundFonts as system default.

MIDI SoundFonts can be added to the list through the MIDI.SoundFontListItemAdd method or removed through the MIDI.SoundFontListItemRemove method. The total number of SoundFonts added to the list can be obtained through the MIDI.SoundFontListItemCountGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontListApplyAsDefault (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontListApplyAsDefault (

short nPlayer

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontListItemAdd method

MIDI.SoundFontListItemAdd method

Remarks

Adds a MIDI SoundFont to the list of SoundFonts that could be applied in a single shot to the loaded MIDI stream through the MIDI.SoundFontListApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontListItemAdd (

nPlayer as Integer,

nUniqueId As Long,

nPreset as Long,

nBank as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontListItemAdd (

short nPlayer,

long nUniqueId,

long nPreset,

long nBank

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.
nPreset | The preset number
nBank | The bank number

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontListItemCountGet method

MIDI.SoundFontListItemCountGet method

Remarks

Obtains the number of MIDI SoundFonts inside the list that will be applied at a later time through the MIDI.SoundFontListApply method. The unique id of each MIDI SoundFont can be retrieved through the MIDI.SoundFontListItemUniqueIdGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontListItemCountGet (

nPlayer as Integer,

nCount as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontListItemCountGet (

short nPlayer,

long *nCount

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nCount | Reference that, on return from the method call, will contain the number of MIDI SoundFonts inside the list.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontListItemRemove method

MIDI.SoundFontListItemRemove method

Remarks

Removes a MIDI SoundFont from the list of SoundFonts that could be applied in a single shot to the loaded MIDI stream through the MIDI.SoundFontListApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontListItemRemove (

nPlayer as Integer,

nUniqueId As Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontListItemRemove (

short nPlayer,

long nUniqueId

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontListItemUniqueIdGet method

MIDI.SoundFontListItemUniqueIdGet method

Remarks

Obtains the unique identifier of a specific MIDI SoundFont inside the list that will be applied at a later time through the MIDI.SoundFontListApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontListItemUniqueIdGet (

nPlayer as Integer,

nIndex as Long,

nUniqueId as Long,

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontListItemUniqueIdGet (

short nPlayer,

long nIndex,

long *nUniqueId

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndex | Number representing the zero-based index of the MIDI SoundFont inside the list. The total number of MIDI SoundFonts available inside the list can be obtained through the MIDI.SoundFontListItemCountGet method.
nUniqueId | Reference that, on return from the method call, will contain the unique identifier of the requested MIDI SoundFont.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontLoad method

MIDI.SoundFontLoad method

Remarks

Loads in memory presets from a sound font allowing to avoid CPU spikes during playback of MIDI streams. Loaded presets can be unloaded at a later from memory using the MIDI.SoundFontUnload method.

For further details about the use of MIDI protocol see the MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontLoad (

nUniqueId As Long,

nPreset as Long,

nBank as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontLoad (

long nUniqueId,

long nPreset,

long nBank

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.
nPreset | The preset number to load. If this parameter is set to -1, all presets are loaded.
nBank | The bank number to load. If this parameter is set to -1, all banks are loaded.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


MIDI.SoundFontPresetDescGet method

MIDI.SoundFontPresetDescGet method

Remarks

Obtains a the friendly description of a preset available inside the given MIDI SoundFont.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontPresetDescGet (

nUniqueId as Long,

nPreset as Long,

nBank as Long

) as BSTR

[C++]

BSTR control.MIDI.SoundFontPresetDescGet (

long nUniqueId,

long nPreset,

long nBank

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods. This parameter can be set to 0 when the request is related to the system default SoundFont.
nPreset | The preset number which may be in the range from 0 to 127. If this value is set to -1 the information will be related to the first encountered preset
nBank | The bank number. If this value is set to -1 the information will be related to the first encountered bank

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the preset friendly description. The returned string is empty when the preset is not available inside the given SoundFont


MIDI.SoundFontUnload method

MIDI.SoundFontUnload method

Remarks

Unloads from memory presets of a sound font previously loaded through the MIDI.SoundFontLoad method.

For further details about the use of MIDI protocol see the MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontUnload (

nUniqueId As Long,

nPreset as Long,

nBank as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontUnload (

long nUniqueId,

long nPreset,

long nBank

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.
nPreset | The preset number to unload. If this parameter is set to -1, all presets are unloaded.
nBank | The bank number of the individual preset to unload. If this parameter is set to -1, all banks are unloaded.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


MIDI.SoundFontVolumeGet method

MIDI.SoundFontVolumeGet method

Remarks

Obtains the volume level of the given MIDI SoundFont. The current volume level can be modified through the MIDI.SoundFontVolumeSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontVolumeGet (

nUniqueId as Long,

fVolume as Single

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontVolumeGet (

long nUniqueId,

float *fVolume

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.
fVolume | Reference that, on return from the method call, will contain the SoundFont volume expressed in percentage

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontVolumeSet method

MIDI.SoundFontVolumeSet method

Remarks

Modifies the volume level of the given MIDI SoundFont. The current volume level can be obtained through the MIDI.SoundFontVolumeGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontVolumeSet (

nUniqueId as Long,

fVolume as Single

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontVolumeSet (

long nUniqueId,

float fVolume

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the MIDI SoundFont as returned by a previous call to one between the MIDI.SoundFontInit or MIDI.SoundFontInitFromMemory or MIDI.SoundFontInitFromMemory methods.
fVolume | The SoundFont volume expressed in percentage

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontsInStreamEnum method

MIDI.SoundFontsInStreamEnum method

Remarks

Enumerates MIDI SoundFonts available inside the loaded MIDI stream. After completing the enumeration, information about each of the detected MIDI SoundFonts can be obtained through the MIDI.SoundFontsInStreamItemGet method.

The list of detected MIDI SoundFonts stays available in memory until a new enumeration is performed through a call to this same method so a new enumeration always discards the previous list.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontsInStreamEnum (

nPlayer as Integer,

nCount as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontsInStreamEnum (

short nPlayer,

long *nCount

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nCount | Reference that, on return from the method call, will contain the number of MIDI SoundFonts detected inside the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundFontsInStreamItemGet method

MIDI.SoundFontsInStreamItemGet method

Remarks

After completing the enumeration of MIDI SoundFonts, started through the MIDI.SoundFontsInStreamEnum method, available inside the loaded MIDI stream, allows retrieving information about a specific MIDI SoundFont.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundFontsInStreamItemGet (

nPlayer as Integer,

nFontIndex as Long,

nUniqueId As Long,

nPreset as Long,

nBank as Long

) as enumErrorCodes

[C++]

short control.MIDI.SoundFontsInStreamItemGet (

short nPlayer,

long nFontIndex,

long *nUniqueId,

long *nPreset,

long *nBank

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nFontIndex | Number representing the zero-based index of the MIDI SoundFont.
nUniqueId | Reference that, on return from the method call, will contain the unique identifier of the requested SoundFont
nPreset | Reference that, on return from the method call, will contain the preset number
nBank | Reference that, on return from the method call, will contain the base bank number or the bank number of the individual preset

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.SoundPositionGet method

MIDI.SoundPositionGet method

Remarks

Obtains the current position during playback of the MIDI stream.

The current position is calculated respect to the original sound duration and could not represent the effective playback time if a previous playback rate change, performed through a call to MIDI.TempoPercSet and MIDI.BPMSet methods, should occur. If you should need to obtain the effective position in terms of playback time you could use the SoundPositionGet method by setting the bKeepCountOfRateChange parameter to "BOOL_TRUE".

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.SoundPositionGet (

nPlayer as Integer,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C++]

short control.MIDI.SoundPositionGet (

short nPlayer,

double *fPosition,

short nPositionUnit

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

fPosition

Reference that, on return from the method call, will contain the current position; its value depends upon the value of the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for the position value stored inside fPosition parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_POS_UNIT_TICKS | 0 | The fPosition parameter is expressed in MIDI ticks
MIDI_POS_UNIT_MS | 1 | The fPosition parameter is expressed in milliseconds. The position is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always move playback to the position on the song as it should be played at its original speed.
MIDI_POS_UNIT_PERCENTAGE | 2 | The fPosition parameter is expressed in percentage

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventApply method

MIDI.StreamEventApply method

Remarks

Applies a specific single MIDI event to the loaded MIDI stream. The current value of a MIDI event, with the exception of the MIDI_EVENT_NOTE event, can be obtained through the MIDI.StreamEventValueGet method.

If you should need applying multiple events at the same time you could use the MIDI.StreamEventsListApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventApply (

nPlayer as Integer,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Integer,

nMidiParam2 as Integer,

nMidiChannel as Integer,

bSendEventNotif as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventApply (

short nPlayer,

short nMidiEvent,

short nMidiParam1,

short nMidiParam2,

short nMidiChannel,

short bSendEventNotif

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMidiEvent

MIDI event to apply.

Supported values, with related parameters, are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_NOTE | 1 | Presses or releases a key note. nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: velocity; 0 means key released while values from 1 to 127 mean pressure
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument. nMidiParam1: the preset program number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure. nMidiParam1: the pressure level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position. nMidiParam1: the pitch wheel position; can range from 0 to 16383 nMidiParam2: not used
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0). nMidiParam1: the pitch wheel range nMidiParam2: not used
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel. nMidiParam1: if set to 0 melody channels are used, if set to 1 the rhythm channel is used. nMidiParam2: not used
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1). nMidiParam1: fine tuning in cents, can range from 0 to 16383. 0 means a fine tuning of -100, 8192 means normal while 16383 means a fine tuning of +100. nMidiParam2: not used
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2). nMidiParam1: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63. nMidiParam2: not used
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume. nMidiParam1: can range from 0 to 16383 where 0 means silence and 16383 means max volume. nMidiParam2: not used
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0). nMidiParam1: the bank number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1). nMidiParam1: the modulation level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7). nMidiParam1: the volume level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10). nMidiParam1: the pan position from 0 to 128. 0 means left, 64 means middle, 127 means right while 128 sets a random position. nMidiParam2: not used
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11). nMidiParam1: the expression level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64). nMidiParam1: from 0 to 63 the sustain is off while from 64 to 127 the sustain is on. nMidiParam2: not used
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65). nMidiParam1: from 0 to 63 the portamento is off while from 64 to 127 the portamento is on. nMidiParam2: not used
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5). nMidiParam1: the portamento time from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84). nMidiParam1: the key number from 1 to 127; 60 means middle C nMidiParam2: not used
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127) nMidiParam1: 0 means poly while 1 means mono nMidiParam2: not used
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91). nMidiParam1: the reverb level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93). nMidiParam1: the chorus level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h). nMidiParam1: cutoff level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h). nMidiParam1: resonance level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h). nMidiParam1: release time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h). nMidiParam1: attack time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time. nMidiParam1: reverb time in milliseconds. nMidiParam2: not used
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay. nMidiParam1: reverb delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level. nMidiParam1: reverb level; 0 means no reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay. nMidiParam1: chorus delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth. nMidiParam1: chorus depth in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate. nMidiParam1: chorus in 100ths of Hertz. nMidiParam2: not used
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback.. nMidiParam1: the chorus feedback level, can range from 0 to 200. 0 means -100%, 100 means that feedback is off while 200 means +100%. nMidiParam2: not used
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level. nMidiParam1: chorus level; 0 means no chorus, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level. nMidiParam1: chorus reverb level; 0 means no chorus reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: fine tune in cents, can range from 0 to 127. 0 means -100, 64 means normal while 127 means +100.
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63.
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the pan position from 0 to 127. 0 means left, 64 means middle while 127 means right. .
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the reverb level from 0 to 128.
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh) nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the chorus level from 0 to 128.
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: cutoff level from 0 to 127
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: resonance level from 0 to 127
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: level from 0 to 127; 127 means full level.
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67). nMidiParam1: from 0 to 63 the soft pedal is off while from 64 to 127 the soft pedal is on. nMidiParam2: not used
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81). nMidiParam1: tempo in microseconds per quarter note. nMidiParam2: not used
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave. nMidiParam1: tuning change in cents, can range from 0 to 16383. 0 means a tuning of -100, 8192 means normal while 16383 means a tuning of +100. nMidiParam2: note; can range from 0 to 11 where 0 is note C
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth. nMidiParam1: vibrato depth effect in cents (0=none, 128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch. nMidiParam1: pitch effect in semitones (0=-24, 24=none, 48=+24). . nMidiParam2: not used
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff. nMidiParam1: filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600). nMidiParam2: not used
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume. nMidiParam1: volume effect percentage (0=-100, 100=none, 200=+100). nMidiParam2: not used
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5). nMidiParam1: vibrato depth in cents (128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32). nMidiParam1: bank number LSB (0-127). nMidiParam2: not used
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file. nMidiParam1: volume level; 0 means silence, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes. nMidiParam1: amount of transposition in semitones, can range from 0 to 200. 0 means -100, 100 means normal while 200 means +100. nMidiParam2: not used
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used

nMidiParam1

The number representing the first parameter related to the event (see the MIDI events table above for details)

nMidiParam2

The number representing the second parameter related to the event (see the MIDI events table above for details)

nMidiChannel

The MIDI channel on which the event is applied. The current number of channels can be retrieved through a call to the MIDI.ChannelsGet method.

bSendEventNotif

Boolean flag that specifies if the container application must be notified about the applied event through the MidiStreamEventNotification event.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The MidiStreamEventNotification event is not generated after applying the MIDI event.
BOOL_TRUE | 1 | The MidiStreamEventNotification event is generated after applying the MIDI event.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventValueGet method

MIDI.StreamEventValueGet method

Remarks

Obtains the current value of a specific MIDI event inside the loaded MIDI stream. The current value of a MIDI event can be modified through the MIDI.StreamEventApply method.

Obtaining the current value for a MIDI_EVENT_NOTE is not supported because more notes could be applied at the same time: for this purpose you could enumerate notes through the MIDI StreamEventsEnum or MIDI StreamEventsEnumFromRange methods and obtain respective values through the MIDI.StreamEventsEnumItemGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventValueGet (

nPlayer as Integer,

nMidiEvent as enumMidiStreamEvents,

nOptionalKeyNoteValue as Integer

nMidiChannel as Integer,

nCurrValue as Long

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventValueGet (

short nPlayer,

short nMidiEvent,

short nOptionalKeyNoteValue,

short nMidiChannel,

long *nCurrValue

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMidiEvent

The type of MIDI event for which we need to get the current value.

Supported events are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_NOTE | 1 | Presses or releases a key note.
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument.
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure.
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position.
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0).
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel.
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1).
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2).
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume.
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0).
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1).
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7).
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10).
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11).
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64).
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120).
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121).
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123).
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65).
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5).
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84).
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127).
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91).
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93).
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h).
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h).
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h).
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h).
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time.
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay.
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter.
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter.
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level.
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay.
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth.
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate.
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback..
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level.
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level.
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh).
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh).
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh).
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh).
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh).
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh).
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh).
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh).
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67).
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults.
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81).
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave.
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth.
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch.
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff.
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume.
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5).
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32).
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file.
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes.
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method.

nOptionalKeyNoteValue

The number representing the key/note number from 0 to 127 where 60 means middle C This parameter is optional and is ignored for MIDI events different from the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh).
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh).
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh).
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh).
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh)
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh).
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh).
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh).
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave.

nMidiChannel

The MIDI channel on which the event is applied.

nCurrValue

Reference that, on return from the method call, will contain the current value of the MIDI event.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsEnableNotifications method

MIDI.StreamEventsEnableNotifications method

Remarks

Enables/disables the synchronization of the container application with a specific type of MIDI event detected inside the loaded MIDI stream during playback.

When synchronization is enabled, the component fires the MidiStreamEventNotification event for each specific event enabled for notification.

MIDI events can also be enumerated offline, while the MIDI stream is not in playback, through the combination of the MIDI.StreamEventsEnum and MIDI:StreamEventsEnumItemGet methods.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsEnableNotifications (

nPlayer as Integer,

nMidiEvent as enumMidiStreamEvents,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsEnableNotifications (

short nPlayer,

short nMidiEvent,

short bEnable

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMidiEvent

The type of MIDI event.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_ALL | 0 | All types of MIDI events.
MIDI_EVENT_NOTE | 1 | Presses or releases a key note.
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument.
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure.
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position.
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0).
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel.
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1).
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2).
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume.
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0).
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1).
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7).
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10).
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11).
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64).
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120).
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121).
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123).
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65).
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5).
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84).
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127).
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91).
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93).
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h).
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h).
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h).
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h).
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time.
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay.
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter.
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter.
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level.
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay.
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth.
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate.
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback..
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level.
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level.
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh).
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh).
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh).
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh).
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh).
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh).
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh).
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh).
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67).
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults.
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81).
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave.
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth.
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch.
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff.
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume.
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5).
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32).
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file.
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes.
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method.

bEnable

Boolean value that specifies if the finding of the given event during playback must be notified through the MidiStreamEventNotification event.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Notification for the given event is not enabled.
BOOL_TRUE | 1 | Notification for the given event is enabled.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsEnum method

MIDI.StreamEventsEnum method

Remarks

Enumerates a specific type of MIDI event detected inside the loaded MIDI stream. After completing the enumeration, information about each of the detected MIDI events can be obtained through the MIDI.StreamEventsEnumItemGet method. Enumeration of events inside a specific portion of the loaded MIDI stream can be performed through the MIDI.StreamEventsEnumFromRange method.

The list of detected MIDI events stays available in memory until a new enumeration is performed through a call to this same method or through the MIDI.StreamEventsEnumFromRange method so a new enumeration always discards the previous list.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsEnum (

nPlayer as Integer,

nTrack as Integer,

nMidiEvent as enumMidiStreamEvents,

nCount as Long

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsEnum (

short nPlayer,

short nTrack,

short nMidiEvent,

long *nCount

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTrack

Number representing the zero-based index of the MIDI track to scan for events detection. The total number of available MIDI tracks can be obtained through the MIDI:TrackCountGet method.

nMidiEvent

The type of MIDI event.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_ALL | 0 | All types of MIDI events.
MIDI_EVENT_NOTE | 1 | Presses or releases a key note.
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument.
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure.
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position.
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0).
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel.
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1).
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2).
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume.
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0).
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1).
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7).
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10).
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11).
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64).
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120).
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121).
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123).
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65).
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5).
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84).
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127).
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91).
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93).
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h).
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h).
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h).
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h).
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time.
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay.
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter.
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter.
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level.
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay.
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth.
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate.
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback..
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level.
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level.
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh).
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh).
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh).
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh).
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh).
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh).
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh).
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh).
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67).
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults.
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81).
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave.
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth.
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch.
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff.
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume.
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5).
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32).
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file.
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes.
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method.

nCount

Reference that, on return from the method call, will contain the number of events of the given type detected inside the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsEnumFromRange method

MIDI.StreamEventsEnumFromRange method

Remarks

Enumerates a specific type of MIDI event detected inside the given portion of the loaded MIDI stream. After completing the enumeration, information about each of the detected MIDI events can be obtained through the MIDI.StreamEventsEnumItemGet method.

The list of detected MIDI events stays available in memory until a new enumeration is performed through a new call to this same method or through the MIDI.StreamEventsEnum method so a new enumeration always discards the previous list.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsEnumFromRange (

nPlayer as Integer,

nTrack as Integer,

nMidiEvent as enumMidiStreamEvents,

fStartPosition as Double,

fEndPosition as Double,

nPositionUnit as enumMidiPositionUnits,

nCount as Long

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsEnumFromRange (

short nPlayer,

short nTrack,

short nMidiEvent,

double fStartPosition,

double fEndPosition,

short nPositionUnit,

long *nCount

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTrack

Number representing the zero-based index of the MIDI track to scan for events detection. The total number of available MIDI tracks can be obtained through the MIDI:TrackCountGet method.

nMidiEvent

The type of MIDI event.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_ALL | 0 | All types of MIDI events.
MIDI_EVENT_NOTE | 1 | Presses or releases a key note.
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument.
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure.
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position.
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0).
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel.
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1).
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2).
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume.
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0).
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1).
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7).
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10).
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11).
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64).
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120).
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121).
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123).
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65).
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5).
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84).
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127).
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91).
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93).
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h).
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h).
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h).
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h).
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time.
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay.
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter.
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter.
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level.
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay.
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth.
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate.
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback..
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level.
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level.
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh).
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh).
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh).
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh).
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh).
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh).
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh).
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh).
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67).
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults.
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81).
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave.
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth.
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch.
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff.
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume.
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5).
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32).
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file.
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes.
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method.

fStartPosition

Number specifying the start point of the range in the unit specified by the nPositionUnit parameter below.

fEndPosition

Number specifying the end point of the range in the unit specified by the nPositionUnit parameter below.

nPositionUnit

The unit used to specify the fStartPosition and fEndPosition parameters above.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_POS_UNIT_TICKS | 0 | The fPosition parameter is expressed in MIDI ticks
MIDI_POS_UNIT_MS | 1 | The fPosition parameter is expressed in milliseconds.
MIDI_POS_UNIT_PERCENTAGE | 2 | The fPosition parameter is expressed in percentage

nCount

Reference that, on return from the method call, will contain the number of events of the given type detected inside the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsEnumItemGet method

MIDI.StreamEventsEnumItemGet method

Remarks

After completing the enumeration, started through the MIDI.StreamEventsEnum method, of a specific type of event detected inside the loaded MIDI stream, allows retrieving information about a specific event.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsEnumItemGet (

nPlayer as Integer,

nEventIndex as Long,

nMidiChannel as Long,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Integer,

nMidiParam2 as Integer,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsEnumItemGet (

short nPlayer,

long nEventIndex,

long *nMidiChannel,

long *nMidiEvent,

short *nMidiParam1,

short *nMidiParam2,

double *fPosition,

short nPositionUnit

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nEventIndex

Number representing the zero-based index of the event.

nMidiChannel

Reference that, on return from the method call, will contain the channel from which the event was generated. The current number of channels can be retrieved through a call to the MIDI.ChannelsGet method.

nMidiEvent

Reference that, on return from the method call, will contain the type of event.

Supported values, with related parameters, are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_NOTE | 1 | Presses or releases a key note. nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: velocity; 0 means key released while values from 1 to 127 mean pressure
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument. nMidiParam1: the preset program number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure. nMidiParam1: the pressure level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position. nMidiParam1: the pitch wheel position; can range from 0 to 16383 nMidiParam2: not used
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0). nMidiParam1: the pitch wheel range nMidiParam2: not used
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel. nMidiParam1: if set to 0 melody channels are used, if set to 1 the rhythm channel is used. nMidiParam2: not used
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1). nMidiParam1: fine tuning in cents, can range from 0 to 16383. 0 means a fine tuning of -100, 8192 means normal while 16383 means a fine tuning of +100. nMidiParam2: not used
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2). nMidiParam1: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63. nMidiParam2: not used
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume. nMidiParam1: can range from 0 to 16383 where 0 means silence and 16383 means max volume. nMidiParam2: not used
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0). nMidiParam1: the bank number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1). nMidiParam1: the modulation level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7). nMidiParam1: the volume level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10). nMidiParam1: the pan position from 0 to 128. 0 means left, 64 means middle, 127 means right while 128 sets a random position. nMidiParam2: not used
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11). nMidiParam1: the expression level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64). nMidiParam1: from 0 to 63 the sustain is off while from 64 to 127 the sustain is on. nMidiParam2: not used
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65). nMidiParam1: from 0 to 63 the portamento is off while from 64 to 127 the portamento is on. nMidiParam2: not used
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5). nMidiParam1: the portamento time from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84). nMidiParam1: the key number from 1 to 127; 60 means middle C nMidiParam2: not used
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127) nMidiParam1: 0 means poly while 1 means mono nMidiParam2: not used
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91). nMidiParam1: the reverb level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93). nMidiParam1: the chorus level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h). nMidiParam1: cutoff level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h). nMidiParam1: resonance level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h). nMidiParam1: release time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h). nMidiParam1: attack time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time. nMidiParam1: reverb time in milliseconds. nMidiParam2: not used
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay. nMidiParam1: reverb delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level. nMidiParam1: reverb level; 0 means no reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay. nMidiParam1: chorus delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth. nMidiParam1: chorus depth in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate. nMidiParam1: chorus in 100ths of Hertz. nMidiParam2: not used
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback.. nMidiParam1: the chorus feedback level, can range from 0 to 200. 0 means -100%, 100 means that feedback is off while 200 means +100%. nMidiParam2: not used
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level. nMidiParam1: chorus level; 0 means no chorus, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level. nMidiParam1: chorus reverb level; 0 means no chorus reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: fine tune in cents, can range from 0 to 127. 0 means -100, 64 means normal while 127 means +100.
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63.
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the pan position from 0 to 127. 0 means left, 64 means middle while 127 means right. .
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the reverb level from 0 to 128.
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh) nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the chorus level from 0 to 128.
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: cutoff level from 0 to 127
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: resonance level from 0 to 127
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: level from 0 to 127; 127 means full level.
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67). nMidiParam1: from 0 to 63 the soft pedal is off while from 64 to 127 the soft pedal is on. nMidiParam2: not used
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81). nMidiParam1: tempo in microseconds per quarter note. nMidiParam2: not used
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave. nMidiParam1: tuning change in cents, can range from 0 to 16383. 0 means a tuning of -100, 8192 means normal while 16383 means a tuning of +100. nMidiParam2: note; can range from 0 to 11 where 0 is note C
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth. nMidiParam1: vibrato depth effect in cents (0=none, 128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch. nMidiParam1: pitch effect in semitones (0=-24, 24=none, 48=+24). . nMidiParam2: not used
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff. nMidiParam1: filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600). nMidiParam2: not used
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume. nMidiParam1: volume effect percentage (0=-100, 100=none, 200=+100). nMidiParam2: not used
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5). nMidiParam1: vibrato depth in cents (128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32). nMidiParam1: bank number LSB (0-127). nMidiParam2: not used
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file. nMidiParam1: volume level; 0 means silence, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes. nMidiParam1: amount of transposition in semitones, can range from 0 to 200. 0 means -100, 100 means normal while 200 means +100. nMidiParam2: not used
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used

nMidiParam1

Reference that, on return from the method call, will contain the number representing the first parameter related to the event (see the MIDI events table above for details)

nMidiParam2

Reference that, on return from the method call, will contain the number representing the second parameter related to the event (see the MIDI events table above for details)

fPosition

Reference that, on return from the method call, will contain the position of the MIDI event expressed in the unit set inside the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for the position value stored inside fPosition parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_POS_UNIT_TICKS | 0 | The value of the fPosition parameter is expressed in MIDI ticks.
MIDI_POS_UNIT_MS | 1 | The value of the fPosition parameter is expressed in milliseconds.
MIDI_POS_UNIT_PERCENTAGE | 2 | The value of the fPosition parameter is expressed in percentage.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsListApply method

MIDI.StreamEventsListApply method

Remarks

Applies in one single shot a list of MIDI events to the loaded MIDI stream. After being applied, the list of MIDI stays live in memory so it can be applied more than once. The list can be cleared and removed from memory through the MIDI.StreamEventsListItemRemove method.

MIDI events can be added to the list through the MIDI.StreamEventsListItemAdd method. The total number of events added to the list can be obtained through the MIDI.StreamEventsListItemCountGet method.

If you should need applying only one single event you could use the MIDI.StreamEventApply method.

Raw MIDI events stored inside a memory buffer can be applied in one single shot through the MIDI.StreamEventsRawApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsListApply (

nPlayer as Integer,

bSendEventNotif as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsListApply (

short nPlayer,

short bSendEventNotif

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

bSendEventNotif

Boolean flag that specifies if the container application must be notified about the applied events through the MidiStreamEventNotification event.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The MidiStreamEventNotification event is not generated for MIDI events of the list.
BOOL_TRUE | 1 | The MidiStreamEventNotification event is generated for MIDI events of the list.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsListItemAdd method

MIDI.StreamEventsListItemAdd method

Remarks

Adds a specific single MIDI event to the list of MIDI events that will be applied to the loaded MIDI stream in one single shot through a call to the MIDI.StreamEventsListApply method.

The call to this method generates a unique identifier for the specific MIDI event added to the list, allowing to perform removal or modifications of the MIDI event at a later time using the provided methods MIDI StreamEventsListItemRemove, MIDI.StreamEventsListItemGet. and MIDI.StreamEventsListItemModify.

The total number of MIDI events added to the list can be obtained through the MIDI.StreamEventsListItemCountGet method and, for each MIDI event, you can obtain the specific unique identifier through the MIDI.StreamEventsListItemUniqueIdGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsListItemAdd (

nPlayer as Integer,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Integer,

nMidiParam2 as Integer,

nMidiChannel as Integer

) as Long

[C++]

long control.MIDI.StreamEventsListItemAdd (

short nPlayer,

short nMidiEvent,

short nMidiParam1,

short nMidiParam2,

short nMidiChannel

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nMidiEvent

MIDI event to add to the list.

Supported values, with related parameters, are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_NOTE | 1 | Presses or releases a key note. nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: velocity; 0 means key released while values from 1 to 127 mean pressure
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument. nMidiParam1: the preset program number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure. nMidiParam1: the pressure level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position. nMidiParam1: the pitch wheel position; can range from 0 to 16383 nMidiParam2: not used
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0). nMidiParam1: the pitch wheel range nMidiParam2: not used
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel. nMidiParam1: if set to 0 melody channels are used, if set to 1 the rhythm channel is used. nMidiParam2: not used
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1). nMidiParam1: fine tuning in cents, can range from 0 to 16383. 0 means a fine tuning of -100, 8192 means normal while 16383 means a fine tuning of +100. nMidiParam2: not used
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2). nMidiParam1: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63. nMidiParam2: not used
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume. nMidiParam1: can range from 0 to 16383 where 0 means silence and 16383 means max volume. nMidiParam2: not used
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0). nMidiParam1: the bank number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1). nMidiParam1: the modulation level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7). nMidiParam1: the volume level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10). nMidiParam1: the pan position from 0 to 128. 0 means left, 64 means middle, 127 means right while 128 sets a random position. nMidiParam2: not used
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11). nMidiParam1: the expression level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64). nMidiParam1: from 0 to 63 the sustain is off while from 64 to 127 the sustain is on. nMidiParam2: not used
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65). nMidiParam1: from 0 to 63 the portamento is off while from 64 to 127 the portamento is on. nMidiParam2: not used
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5). nMidiParam1: the portamento time from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84). nMidiParam1: the key number from 1 to 127; 60 means middle C nMidiParam2: not used
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127) nMidiParam1: 0 means poly while 1 means mono nMidiParam2: not used
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91). nMidiParam1: the reverb level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93). nMidiParam1: the chorus level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h). nMidiParam1: cutoff level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h). nMidiParam1: resonance level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h). nMidiParam1: release time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h). nMidiParam1: attack time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time. nMidiParam1: reverb time in milliseconds. nMidiParam2: not used
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay. nMidiParam1: reverb delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level. nMidiParam1: reverb level; 0 means no reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay. nMidiParam1: chorus delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth. nMidiParam1: chorus depth in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate. nMidiParam1: chorus in 100ths of Hertz. nMidiParam2: not used
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback.. nMidiParam1: the chorus feedback level, can range from 0 to 200. 0 means -100%, 100 means that feedback is off while 200 means +100%. nMidiParam2: not used
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level. nMidiParam1: chorus level; 0 means no chorus, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level. nMidiParam1: chorus reverb level; 0 means no chorus reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: fine tune in cents, can range from 0 to 127. 0 means -100, 64 means normal while 127 means +100.
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63.
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the pan position from 0 to 127. 0 means left, 64 means middle while 127 means right. .
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the reverb level from 0 to 128.
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh) nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the chorus level from 0 to 128.
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: cutoff level from 0 to 127
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: resonance level from 0 to 127
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: level from 0 to 127; 127 means full level.
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67). nMidiParam1: from 0 to 63 the soft pedal is off while from 64 to 127 the soft pedal is on. nMidiParam2: not used
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81). nMidiParam1: tempo in microseconds per quarter note. nMidiParam2: not used
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave. nMidiParam1: tuning change in cents, can range from 0 to 16383. 0 means a tuning of -100, 8192 means normal while 16383 means a tuning of +100. nMidiParam2: note; can range from 0 to 11 where 0 is note C
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth. nMidiParam1: vibrato depth effect in cents (0=none, 128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch. nMidiParam1: pitch effect in semitones (0=-24, 24=none, 48=+24). . nMidiParam2: not used
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff. nMidiParam1: filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600). nMidiParam2: not used
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume. nMidiParam1: volume effect percentage (0=-100, 100=none, 200=+100). nMidiParam2: not used
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5). nMidiParam1: vibrato depth in cents (128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32). nMidiParam1: bank number LSB (0-127). nMidiParam2: not used
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file. nMidiParam1: volume level; 0 means silence, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes. nMidiParam1: amount of transposition in semitones, can range from 0 to 200. 0 means -100, 100 means normal while 200 means +100. nMidiParam2: not used
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used

nMidiParam1

Number representing the first parameter related to the event (see the MIDI events table above for details)

nMidiParam2

Number representing the second parameter related to the event (see the MIDI events table above for details)

nMidiChannel

The MIDI channel on which the event is applied. The current number of channels can be retrieved through a call to the MIDI.ChannelsGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
Value > 0 | The method call was successful and the returned value is the unique identifier of the event.


MIDI.StreamEventsListItemCountGet method

MIDI.StreamEventsListItemCountGet method

Remarks

Obtains the number of MIDI events inside the list that will be applied at a later time through the MIDI.StreamEventsListApply method. The unique id of each MIDI event can be retrieved through the MIDI.StreamEventsListItemUniqueIdGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsListItemCountGet (

nPlayer as Integer,

nCount as Long

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsListItemCountGet (

short nPlayer,

long *nCount

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nCount | Reference that, on return from the method call, will contain the number of MIDI events inside the list.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsListItemGet method

MIDI.StreamEventsListItemGet method

Remarks

Retrieves information about a specific single MIDI event available inside the list of MIDI events that will be applied to the loaded MIDI stream in one single shot through a call to the MIDI.StreamEventsListApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsListItemGet (

nPlayer as Integer,

nUniqueId as Long,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Integer,

nMidiParam2 as Integer,

nMidiChannel as Integer

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsListItemGet (

short nPlayer,

long nUniqueId,

long *nMidiEvent,

short *nMidiParam1,

short *nMidiParam2,

short *nMidiChannel

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nUniqueId

The unique identifier of the MIDI event inside the list. This unique identifier is generated and returned by the MIDI.StreamEventsListItemAdd method when the MIDI event is added to the list.

The total number of MIDI events added to the list can be obtained through the MIDI.StreamEventsListItemCountGet method and, for each MIDI event, you can obtain the specific unique identifier through the MIDI.StreamEventsListItemUniqueIdGet method.

nMidiEvent

Reference that, on return from the method call, will contain the MIDI event.

Supported values, with related parameters, are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_NOTE | 1 | Presses or releases a key note. nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: velocity; 0 means key released while values from 1 to 127 mean pressure
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument. nMidiParam1: the preset program number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure. nMidiParam1: the pressure level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position. nMidiParam1: the pitch wheel position; can range from 0 to 16383 nMidiParam2: not used
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0). nMidiParam1: the pitch wheel range nMidiParam2: not used
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel. nMidiParam1: if set to 0 melody channels are used, if set to 1 the rhythm channel is used. nMidiParam2: not used
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1). nMidiParam1: fine tuning in cents, can range from 0 to 16383. 0 means a fine tuning of -100, 8192 means normal while 16383 means a fine tuning of +100. nMidiParam2: not used
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2). nMidiParam1: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63. nMidiParam2: not used
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume. nMidiParam1: can range from 0 to 16383 where 0 means silence and 16383 means max volume. nMidiParam2: not used
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0). nMidiParam1: the bank number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1). nMidiParam1: the modulation level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7). nMidiParam1: the volume level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10). nMidiParam1: the pan position from 0 to 128. 0 means left, 64 means middle, 127 means right while 128 sets a random position. nMidiParam2: not used
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11). nMidiParam1: the expression level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64). nMidiParam1: from 0 to 63 the sustain is off while from 64 to 127 the sustain is on. nMidiParam2: not used
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65). nMidiParam1: from 0 to 63 the portamento is off while from 64 to 127 the portamento is on. nMidiParam2: not used
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5). nMidiParam1: the portamento time from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84). nMidiParam1: the key number from 1 to 127; 60 means middle C nMidiParam2: not used
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127) nMidiParam1: 0 means poly while 1 means mono nMidiParam2: not used
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91). nMidiParam1: the reverb level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93). nMidiParam1: the chorus level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h). nMidiParam1: cutoff level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h). nMidiParam1: resonance level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h). nMidiParam1: release time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h). nMidiParam1: attack time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time. nMidiParam1: reverb time in milliseconds. nMidiParam2: not used
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay. nMidiParam1: reverb delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level. nMidiParam1: reverb level; 0 means no reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay. nMidiParam1: chorus delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth. nMidiParam1: chorus depth in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate. nMidiParam1: chorus in 100ths of Hertz. nMidiParam2: not used
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback.. nMidiParam1: the chorus feedback level, can range from 0 to 200. 0 means -100%, 100 means that feedback is off while 200 means +100%. nMidiParam2: not used
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level. nMidiParam1: chorus level; 0 means no chorus, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level. nMidiParam1: chorus reverb level; 0 means no chorus reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: fine tune in cents, can range from 0 to 127. 0 means -100, 64 means normal while 127 means +100.
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63.
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the pan position from 0 to 127. 0 means left, 64 means middle while 127 means right. .
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the reverb level from 0 to 128.
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh) nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the chorus level from 0 to 128.
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: cutoff level from 0 to 127
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: resonance level from 0 to 127
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: level from 0 to 127; 127 means full level.
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67). nMidiParam1: from 0 to 63 the soft pedal is off while from 64 to 127 the soft pedal is on. nMidiParam2: not used
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81). nMidiParam1: tempo in microseconds per quarter note. nMidiParam2: not used
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave. nMidiParam1: tuning change in cents, can range from 0 to 16383. 0 means a tuning of -100, 8192 means normal while 16383 means a tuning of +100. nMidiParam2: note; can range from 0 to 11 where 0 is note C
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth. nMidiParam1: vibrato depth effect in cents (0=none, 128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch. nMidiParam1: pitch effect in semitones (0=-24, 24=none, 48=+24). . nMidiParam2: not used
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff. nMidiParam1: filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600). nMidiParam2: not used
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume. nMidiParam1: volume effect percentage (0=-100, 100=none, 200=+100). nMidiParam2: not used
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5). nMidiParam1: vibrato depth in cents (128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32). nMidiParam1: bank number LSB (0-127). nMidiParam2: not used
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file. nMidiParam1: volume level; 0 means silence, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes. nMidiParam1: amount of transposition in semitones, can range from 0 to 200. 0 means -100, 100 means normal while 200 means +100. nMidiParam2: not used
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used

nMidiParam1

Reference that, on return from the method call, will contain the first parameter related to the event (see the MIDI events table above for details)

nMidiParam2

Reference that, on return from the method call, will contain the second parameter related to the event (see the MIDI events table above for details)

nMidiChannel

Reference that, on return from the method call, will contain the MIDI channel on which the event is applied. The current number of channels can be retrieved through a call to the MIDI.ChannelsGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsListItemModify method

MIDI.StreamEventsListItemModify method

Remarks

Modifies a specific single MIDI event inside the list of MIDI events that will be applied at a later time through the MIDI.StreamEventsListApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsListItemModify (

nPlayer as Integer,

nUniqueId as Long,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Integer,

nMidiParam2 as Integer,

nMidiChannel as Integer

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsListItemModify (

short nPlayer,

long nUniqueId,

short nMidiEvent,

short nMidiParam1,

short nMidiParam2,

short nMidiChannel

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nUniqueId

The unique identifier of the MIDI event inside the list. This unique identifier is generated and returned by the MIDI.StreamEventsListItemAdd method when the MIDI event is added to the list.

The total number of MIDI events added to the list can be obtained through the MIDI.StreamEventsListItemCountGet method and, for each MIDI event, you can obtain the specific unique identifier through the MIDI.StreamEventsListItemUniqueIdGet method.

nMidiEvent

The MIDI event to apply.

Supported values, with related parameters, are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_NOTE | 1 | Presses or releases a key note. nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: velocity; 0 means key released while values from 1 to 127 mean pressure
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument. nMidiParam1: the preset program number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure. nMidiParam1: the pressure level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position. nMidiParam1: the pitch wheel position; can range from 0 to 16383 nMidiParam2: not used
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0). nMidiParam1: the pitch wheel range nMidiParam2: not used
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel. nMidiParam1: if set to 0 melody channels are used, if set to 1 the rhythm channel is used. nMidiParam2: not used
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1). nMidiParam1: fine tuning in cents, can range from 0 to 16383. 0 means a fine tuning of -100, 8192 means normal while 16383 means a fine tuning of +100. nMidiParam2: not used
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2). nMidiParam1: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63. nMidiParam2: not used
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume. nMidiParam1: can range from 0 to 16383 where 0 means silence and 16383 means max volume. nMidiParam2: not used
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0). nMidiParam1: the bank number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1). nMidiParam1: the modulation level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7). nMidiParam1: the volume level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10). nMidiParam1: the pan position from 0 to 128. 0 means left, 64 means middle, 127 means right while 128 sets a random position. nMidiParam2: not used
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11). nMidiParam1: the expression level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64). nMidiParam1: from 0 to 63 the sustain is off while from 64 to 127 the sustain is on. nMidiParam2: not used
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65). nMidiParam1: from 0 to 63 the portamento is off while from 64 to 127 the portamento is on. nMidiParam2: not used
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5). nMidiParam1: the portamento time from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84). nMidiParam1: the key number from 1 to 127; 60 means middle C nMidiParam2: not used
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127) nMidiParam1: 0 means poly while 1 means mono nMidiParam2: not used
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91). nMidiParam1: the reverb level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93). nMidiParam1: the chorus level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h). nMidiParam1: cutoff level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h). nMidiParam1: resonance level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h). nMidiParam1: release time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h). nMidiParam1: attack time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time. nMidiParam1: reverb time in milliseconds. nMidiParam2: not used
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay. nMidiParam1: reverb delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level. nMidiParam1: reverb level; 0 means no reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay. nMidiParam1: chorus delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth. nMidiParam1: chorus depth in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate. nMidiParam1: chorus in 100ths of Hertz. nMidiParam2: not used
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback.. nMidiParam1: the chorus feedback level, can range from 0 to 200. 0 means -100%, 100 means that feedback is off while 200 means +100%. nMidiParam2: not used
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level. nMidiParam1: chorus level; 0 means no chorus, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level. nMidiParam1: chorus reverb level; 0 means no chorus reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: fine tune in cents, can range from 0 to 127. 0 means -100, 64 means normal while 127 means +100.
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63.
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the pan position from 0 to 127. 0 means left, 64 means middle while 127 means right. .
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the reverb level from 0 to 128.
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh) nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the chorus level from 0 to 128.
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: cutoff level from 0 to 127
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: resonance level from 0 to 127
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: level from 0 to 127; 127 means full level.
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67). nMidiParam1: from 0 to 63 the soft pedal is off while from 64 to 127 the soft pedal is on. nMidiParam2: not used
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81). nMidiParam1: tempo in microseconds per quarter note. nMidiParam2: not used
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave. nMidiParam1: tuning change in cents, can range from 0 to 16383. 0 means a tuning of -100, 8192 means normal while 16383 means a tuning of +100. nMidiParam2: note; can range from 0 to 11 where 0 is note C
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth. nMidiParam1: vibrato depth effect in cents (0=none, 128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch. nMidiParam1: pitch effect in semitones (0=-24, 24=none, 48=+24). . nMidiParam2: not used
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff. nMidiParam1: filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600). nMidiParam2: not used
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume. nMidiParam1: volume effect percentage (0=-100, 100=none, 200=+100). nMidiParam2: not used
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5). nMidiParam1: vibrato depth in cents (128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32). nMidiParam1: bank number LSB (0-127). nMidiParam2: not used
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file. nMidiParam1: volume level; 0 means silence, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes. nMidiParam1: amount of transposition in semitones, can range from 0 to 200. 0 means -100, 100 means normal while 200 means +100. nMidiParam2: not used
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used

nMidiParam1

Number representing the first parameter related to the event (see the MIDI events table above for details)

nMidiParam2

Number representing the second parameter related to the event (see the MIDI events table above for details)

nMidiChannel

Number representing the MIDI channel on which the event is applied. The current number of channels can be retrieved through a call to the MIDI.ChannelsGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsListItemRemove method

MIDI.StreamEventsListItemRemove method

Remarks

Removes a specific single MIDI event from the list of MIDI events that will be applied to the loaded MIDI stream in one single shot through a call to the MIDI.StreamEventsListApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsListItemRemove (

nPlayer as Integer,

nUniqueId as Long

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsListItemRemove (

short nPlayer

long nUniqueId

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the MIDI event inside the list. This unique identifier is generated and returned by the MIDI.StreamEventsListItemAdd method when the MIDI event is added to the list. If this parameter is set to -1, the full list is cleared and removed from memory.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsListItemUniqueIdGet method

MIDI.StreamEventsListItemUniqueIdGet method

Remarks

Obtains the unique identifier of a specific MIDI event inside the list that will be applied at a later time through the MIDI.StreamEventsListApply method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsListItemUniqueIdGet (

nPlayer as Integer,

nIndex as Long,

nUniqueId as Long,

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsListItemUniqueIdGet (

short nPlayer,

long nIndex,

long *nUniqueId

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndex | Number representing the zero-based index of the MIDI event inside the list. The total number of MIDI events available inside the list can be obtained through the MIDI.StreamEventsListItemCountGet method.
nUniqueId | Reference that, on return from the method call, will contain the unique identifier of the requested MIDI event.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamEventsRawApply method

MIDI.StreamEventsRawApply method

Remarks

Applies in one single shot a list of raw MIDI events stored inside a memory buffer.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamEventsRawApply (

nPlayer as Integer,

pBuffer as Variant,

nBufferLength as Long,

bSendEventNotif as enumBoolean

) as enumErrorCodes

[C++]

short control.MIDI.StreamEventsRawApply (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLength,

short bSendEventNotif

);

\

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

pBuffer

Variant parameter containing the pointer to raw MIDI events previously loaded in memory.

nBufferLength

Length in bytes of the given buffer

bSendEventNotif

Boolean flag that specifies if the container application must be notified about the applied events through the MidiStreamEventNotification event.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The MidiStreamEventNotification event is not generated for MIDI events of the list.
BOOL_TRUE | 1 | The MidiStreamEventNotification event is generated for MIDI events of the list.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamPreloadSamples method

MIDI.StreamPreloadSamples method

Remarks

Pre-loads samples of the MIDI stream loaded inside the given player allowing to avoid CPU spikes during playback of the MIDI stream.

For further details about the use of MIDI protocol see the MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamPreloadSamples (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.MIDI.StreamPreloadSamples (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


MIDI.StreamStart method

MIDI.StreamStart method

Remarks

Allows creating and starting playback of a MIDI stream that will receive and reproduce MIDI events. The stream can be stopped at any time through the MIDI.StreamStop method.

The MIDI stream can be fed in several ways:

· through the MIDI.StreamEventApply method
· through the MIDI.StreamEventsListApply method
· through the MIDI.StreamEventsRawApply method
· through the MIDI.InputDevicesStartOnPlayer method
· through the MIDI.KeyboardNote method

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamStart (

nPlayer as Integer,

nFrequency as Long,

nMidiChannels as Integer,

bMono as enumBoolean

nBitsPerSample as Integer

) as enumErrorCodes

[C++]

short control.MIDI.StreamStart (

short nPlayer,

long nFrequency,

short nMidiChannels,

short bMono,

short nBitsPerSample

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nFrequency

Sample rate of the sound stream (e.g. 44100)

nMidiChannels

Number of MIDI channels, can be in the range from 1 to 128.

bMono

Boolean flag that specifies if the stream will be in Mono or in Stereo.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The sound stream will be in Stereo.
BOOL_TRUE | 1 | The sound stream will be in Mono

nBitsPerSample

Number of bits per sample (e.g. 8, 16 or 32)

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.StreamStop method

MIDI.StreamStop method

Remarks

Stops playback of a MIDI stream previously started through the MIDI.StreamStart method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.StreamStop (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.MIDI.StreamStop (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.TempoPercGet method

MIDI.TempoPercGet method

Remarks

Obtains the tempo of the playing MIDI stream. The current tempo can be modified through the MIDI.TempoPercSet method and is also affected by calls to the MIDI.BPMSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.TempoPercGet (

nPlayer as Integer,

fPercentage as Single

) as enumErrorCodes

[C++]

short control.MIDI.TempoPercGet (

short nPlayer,

float *fPercentage

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

fPercentage

Reference that, on return from the method call, will contain the tempo variation, expressed in percentage, of the loaded MIDI stream.

Negative values mean that playback speed has been slowed down while positive values mean that playback speed has been accelerated.

A value 0 means that the the MIDI stream is playing at its original speed.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.TempoPercSet method

MIDI.TempoPercSet method

Remarks

Modifies the tempo of the playing MIDI stream. The current tempo can be obtained through the MIDI.TempoPercGet method. By modifying the tempo of the playing MIDI stream, the number of Beats Per Minute (BPM) will be affected accordingly.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.TempoPercSet (

nPlayer as Integer,

fPercentage as Single

) as enumErrorCodes

[C++]

short control.MIDI.TempoPercSet (

short nPlayer,

float fPercentage

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
fPercentage | The tempo variation expressed in percentage. Can assume negative values to slow down the playback tempo or positive values to accelerate the playback tempo. Setting this parameter to 0 will set the original tempo of the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.TrackCountGet method

MIDI.TrackCountGet method

Remarks

Obtains the number of available MIDI tracks inside the loaded MIDI stream.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.TrackCountGet (

nPlayer as Integer,

nTracks as Integer

) as enumErrorCodes

[C++]

short control.MIDI.TrackCountGet (

short nPlayer,

short *nTracks

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.
nTracks | Reference that, on return from the method call, will contain the number of MIDI tracks inside the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.TrackTagsEnum method

MIDI.TrackTagsEnum method

Remarks

Enumerates meta tag strings available inside a given MIDI track of the loaded MIDI stream. Each enumerated tag string can be obtained at a later time using the MIDI.TrackTagsItemGet method. Each enumeration stays available in memory until a new enumeration is performed.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.TrackTagsEnum (

nPlayer as Integer,

nTrack as Integer,

nCount as Integer

) as enumErrorCodes

[C++]

short control.MIDI.TrackTagsEnum (

short nPlayer,

short nTrack,

short *nCount

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.
nTrack | Number representing the zero-based index of the MIDI track. The total number of available MIDI tracks can be obtained through the MIDI:TrackCountGet method.
nCount | Reference that, on return from the method call, will contain the number of meta tag strings inside the given track of the loaded MIDI stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.TrackTagsItemGet method

MIDI.TrackTagsItemGet method

Remarks

After completing the enumeration, started through the MIDI.TrackTagsEnum method, of meta tag strings detected inside the given track of the loaded MIDI stream, allows retrieving a specific meta tag string.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.TrackTagsItemGet (

nPlayer as Integer,

nItemIndex as Integer

) as BSTR

[C++]

BSTR control.MIDI.TrackTagsItemGet (

short nPlayer,

short nItemIndex

);

\

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nItemIndex | Number representing the zero-based index of the string.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the requested meta tag string


MIDI.TrackVolumeGet method

MIDI.TrackVolumeGet method

Remarks

Obtains the volume level of a specific MIDI track inside the loaded MIDI stream. The volume level can be modified through the MIDI.TrackVolumeSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.TrackVolumeGet (

nPlayer as Integer,

nTrack as Integer,

fTrackVolume as Single

) as enumErrorCodes

[C++]

short control.MIDI.TrackVolumeGet (

short nPlayer,

short nTrack,

float *fTrackVolume

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.
nTrack | Number representing the zero-based index of the MIDI track inside the loaded MIDI stream. The total number of available MIDI tracks can be obtained through the MIDI:TrackCountGet method.
fTrackVolume | Reference that, on return from the method call, will contain the volume, expressed in percentage, applied to the track.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.TrackVolumeSet method

MIDI.TrackVolumeSet method

Remarks

Sets the volume level of a specific MIDI track inside the loaded MIDI stream. The current volume level can be obtained through the MIDI.TrackVolumeGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.TrackVolumeSet (

nPlayer as Integer,

nTrack as Integer,

fTrackVolume as Single

) as enumErrorCodes

[C++]

short control.MIDI.TrackVolumeSet (

short nPlayer,

short nTrack,

float fTrackVolume

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.
nTrack | Number representing the zero-based index of the MIDI track inside the loaded MIDI stream. The total number of available MIDI tracks can be obtained through the MIDI:TrackCountGet method.
fTrackVolume | The new volume, expressed in percentage, to apply to the track.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.TriggerAdd method

MIDI.TriggerAdd method

Remarks

Adds a trigger to the given player at a certain position of the loaded MIDI stream: when the trigger is reached, the TriggerReached event is fired.

Triggers positioning is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always refer to the position of the song as it should be played at its original speed.

This method is mostly identical to the basic TriggerAdd method but allows specifying the position in MIDI ticks also and can only be used with MIDI streams.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.TriggerAdd (

nPlayer as Integer,

nTriggerID as Integer,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C++]

short control.MIDI.TriggerAdd (

short nPlayer,

short nTriggerID,

double fPosition,

short nPositionUnit

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTriggerID

Number representing the identifier of the new trigger.

If this identifier should be already assigned to another trigger, an error code would be returned.

fPosition

Number representing the position of the trigger; its value depends upon the value of the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for the position value stored inside fPosition parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_POS_UNIT_TICKS | 0 | The fPosition parameter is expressed in MIDI ticks
MIDI_POS_UNIT_MS | 1 | The fPosition parameter is expressed in milliseconds. The position is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always move playback to the position on the song as it should be played at its original speed.
MIDI_POS_UNIT_PERCENTAGE | 2 | The fPosition parameter is expressed in percentage

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.TriggerSetPos method

MIDI.TriggerSetPos method

oveRemarks

Modifies the current position for the given trigger.

Triggers positioning is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always refer to the position of the song as it should be played at its original speed.

This method is mostly identical to the basic TriggerSetPos method but allows specifying the position in MIDI ticks also and can only be used with MIDI streams.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

control.MIDI.TriggerSetPos (

nPlayer as Integer,

nTriggerID as Integer,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C++]

short control.MIDI.TriggerSetPos (

short nPlayer,

short nTriggerID,

double fPosition,

short nPositionUnit

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nTriggerID

Number representing the identifier of the trigger to modify.

fPosition

Number representing the position to reach; its value depends upon the value of the nPositionUnit parameter below.

nPositionUnit

The unit of measure used for the position value stored inside fPosition parameter above.

Supported values are the following:

Mnemonic constant | Value | Meaning
MIDI_POS_UNIT_TICKS | 0 | The fPosition parameter is expressed in MIDI ticks
MIDI_POS_UNIT_MS | 1 | The fPosition parameter is expressed in milliseconds. The position is always referred to the original sound duration, meaning that it won't keep count of eventual tempo and/or playback rate changes and will always move playback to the position on the song as it should be played at its original speed.
MIDI_POS_UNIT_PERCENTAGE | 2 | The fPosition parameter is expressed in percentage

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.VoicesDefaultGet method

MIDI.VoicesDefaultGet method

Remarks

Obtains the default maximum number of voices to play at a time for supporting polyphony. The maximum number can be modified through the MIDI.VoicesDefaultSet method.

The number of voices for a loaded MIDI stream can be determined through the MIDI.VoicesGet method or modified through the MIDI.VoicesSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.VoicesDefaultGet (

nVoices as Integer

) as enumErrorCodes

[C++]

short control.MIDI.VoicesDefaultGet (

short *nVoices

);

Parameter | Description
nVoices | Reference that, on return from the method call, will contain the default maximum number of voices to play at a time.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.VoicesDefaultSet method

MIDI.VoicesDefaultSet method

Remarks

Sets the default maximum number of voices to play at a time for supporting polyphony. The current maximum number can be obtained through the MIDI.VoicesDefaultGet method.

The default number of voices for a loaded MIDI stream can be determined through the MIDI.VoicesGet method or modified through the MIDI.VoicesSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.VoicesDefaultSet (

nVoices as Integer

) as enumErrorCodes

[C++]

short control.MIDI.VoicesDefaultSet (

short nVoices

);

Parameter | Description
nVoices | The default maximum number of voices to play at a time; the accepted range of values is from 1 to 256. The higher the number of voices, the higher will be the amount of needed CPU so by reducing the number of voices there will be some CPU saving.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.VoicesGet method

MIDI.VoicesGet method

Remarks

Obtains the maximum number of voices to play at a time for supporting polyphony on the loaded MIDI stream. The maximum number can be modified through the MIDI.VoicesSet method.

The default number of voices for MIDI streams can be determined through the MIDI.VoicesDefaultGet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.VoicesGet (

nPlayer as Integer,

nVoices as Integer

) as enumErrorCodes

[C++]

short control.MIDI.VoicesGet (

short nPlayer,

short *nVoices

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nVoices | Reference that, on return from the method call, will contain the maximum number of voices to play at a time.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI.VoicesSet method

MIDI.VoicesSet method

Remarks

Sets the maximum number of voices to play at a time for supporting polyphony on the loaded MIDI stream. The current maximum number can be obtained through the MIDI.VoicesGet method.

The default number of voices for MIDI streams can be modified through the MIDI.VoicesDefaultSet method.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.MIDI.VoicesSet (

nPlayer as Integer,

nVoices as Integer

) as enumErrorCodes

[C++]

short control.MIDI.VoicesSet (

short nPlayer,

short nVoices

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nVoices | The maximum number of voices to play at a time; the accepted range of values is from 1 to 256. The higher the number of voices, the higher will be the amount of needed CPU so by reducing the number of voices there will be some CPU saving.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


MIDI_KEYBOARD_SETTINGS structure

MIDI_KEYBOARD_SETTINGS structure

The MIDI_KEYBOARD_SETTINGS structure describes the graphical settings applied to a specific virtual piano keyboard. The current settings can be retrieved through the MIDI.KeyboardGraphicalSettingsGet method and modified through the MIDI.KeyboardGraphicalSettingsSet method. Below you can see an example of a horizontal virtual piano keyboard with default colors.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Visual C++ definition

typedef struct

{

OLE_COLOR        colorBackground;

OLE_COLOR        colorWhiteKeys;

OLE_COLOR        colorBlackKeys;

OLE_COLOR        colorWhiteKeysBorders;

OLE_COLOR        colorBlackKeysBorders;

OLE_COLOR        colorWhiteKeysPressed;

OLE_COLOR        colorBlackKeysPressed;

OLE_COLOR        colorWhiteKeysPressedBorders;

OLE_COLOR        colorBlackKeysPressedBorders;

} MIDI_KEYBOARD_SETTINGS;

Visual Basic definition

Public Type MIDI_KEYBOARD_SETTINGS

colorBackground As OLE_COLOR

colorWhiteKeys As OLE_COLOR

colorBlackKeys As OLE_COLOR

colorWhiteKeysBorders As OLE_COLOR

colorBlackKeysBorders As OLE_COLOR

colorWhiteKeysPressed As OLE_COLOR

colorBlackKeysPressed As OLE_COLOR

colorWhiteKeysPressedBorders As OLE_COLOR

colorBlackKeysPressedBorders As OLE_COLOR

End Type

Member | Description
colorBackground | The color used for rendering the keyboard's background (default is set to Black)
colorWhiteKeys | The color used for rendering white keys (default is set to White)
colorBlackKeys | The color used for rendering black keys (default is set to Black)
colorWhiteKeysBorders | The color used for rendering the border of white keys (default is set to Black)
colorBlackKeysBorders | The color used for rendering the border of black keys (default is set to Black)
colorWhiteKeysPressed | The color used for rendering white keys in pressed state (default is set to Light Blue)
colorBlackKeysPressed | The color used for rendering black keys in pressed state (default is set to Light Blue)
colorWhiteKeysPressedBorders | The color used for rendering the border of white keys in pressed state (default is set to Black)
colorBlackKeysPressedBorders | The color used for rendering the border of black keys in pressed state (default is set to Black)


Oscilloscope object

Oscilloscope object

The Oscilloscope object, accessible through the control's Oscilloscope property, is internally implemented as a COM interface called IOscilloscope and contains information needed to render the embedded Oscilloscope visual feedback.

It can be used at Run-time in order to create the embedded Oscilloscope and to change its graphic settings. For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

The Oscilloscope object is implemented through the following methods and properties:

Methods

Create

Resize

Show

SetHwnd

SetBackPictureFromFile

SetBackPictureFromHandle

Properties

LineWidth

ColorLine

ColorBackground

Type

ZoomPerc

The following code snippets show how to create and change this object in your code. These examples assume that you have placed a control named MyPlayer on a form or dialog and that you want to change a couple of graphic settings (Line and Background colors).

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Microsoft Visual Basic (5.0 and 6.0)

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual J#.NET

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Properties and methods of the control are accessible through the control wrapper class CAmp3dj contained inside the amp3dj.cpp and amp3dj.h files: these wrapper files are automatically generated when you insert the control inside your project so, in order to access the wrapper functions, you will have to insert the following line of code somewhere in your code.

#include "amp3dj.h"

The Oscilloscope object is defined by the control wrapper class COscilloscope contained inside the oscilloscope.cpp and oscilloscope.h files: also these wrapper files are automatically generated when you insert the control inside your project so, in order to access this object, you will have to insert the following line of code somewhere in your code.

#include "oscilloscope.h"

Here follows the code needed to perform the requested operation of initialising the Oscilloscope object and changing some of its properties.

// declare a Oscilloscope object

COscilloscope oscilloscope;

// init the object with the control's oscilloscope reference

oscilloscope = MyPlayer.GetOscilloscope ();

// create the oscilloscope for player 0

oscilloscope.Create (0, (OLE_HANDLE) GetDlgItem(IDC_PICTURE)->GetSafeHwnd ());

// again for player 0, set the oscilloscope line color to blue and background color to white

oscilloscope.SetColorLine (0, RGB (0, 0, 255));

oscilloscope.SetColorBackground (0, RGB (255, 255, 255));

As you can see the access to the Oscilloscope properties ColorLine and ColorBackground are wrapped by the SetColorLine and SetColorBackground functions declared inside the wrapper class COscilloscope.

Microsoft Visual Basic (5.0 and 6.0)

Here follows the code needed to perform the requested operations

' create the Oscilloscope on player 0 over an existing control

MyPlayer.Oscilloscope.Create 0, Picture1.hWnd

' set the blue color for Oscilloscope line of player 0

MyPlayer.Oscilloscope.ColorLine(0) = RGB(0, 0, 255)

' set the white color for Oscilloscope background of player 0

MyPlayer.Oscilloscope.ColorBackground(0) = RGB(255, 255, 255)

Microsoft Visual Basic.NET

Here follows the code needed to perform the requested operations

' create the Oscilloscope on player 0 over an existing control

MyPlayer.Oscilloscope.Create(0, PictureBox1.Handle.ToInt32())

' set the blue color for Oscilloscope line of player 0

MyPlayer.Oscilloscope.ColorLine(0) = Convert.ToUInt32(RGB(0, 0, 255))

' set the white color for Oscilloscope background of player 0

MyPlayer.Oscilloscope.ColorBackground(0) = Convert.ToUInt32(RGB(255, 255, 255))

Microsoft Visual C#.NET

Here follows the code needed to perform the requested operations

// create the Oscilloscope on player 0 over an existing control

MyPlayer.Oscilloscope.Create(0, pictureBox1.Handle.ToInt32());

// set the blue color for Oscilloscope line of player 0

MyPlayer.Oscilloscope.set_ColorLine (0, Convert.ToUInt32 (ColorTranslator.ToWin32 (Color.Blue)));

// set the white color for Oscilloscope background of player 0

MyPlayer.Oscilloscope.set_ColorBackground(0, Convert.ToUInt32 (ColorTranslator.ToWin32 (Color.White)));

Microsoft Visual J#.NET

Here follows the code needed to perform the requested operations

// create the Oscilloscope on player 0 over an existing control

MyPlayer.get_Oscilloscope ().Create ((short) 0, (int) pictureBox1.get_Handle().ToInt32());

// set the blue color for Oscilloscope line of player 0

System.UInt32 colorBlue = (System.UInt32) ColorTranslator.ToWin32 (Color.get_Blue ());

MyPlayer.get_Oscilloscope ().set_ColorLine ((short) 0, colorBlue);

// set the white color for Oscilloscope background of player 0

System.UInt32 colorWhite = (System.UInt32) ColorTranslator.ToWin32 (Color.get_White ());

MyPlayer.get_Oscilloscope ().set_ColorBackground((short) 0, colorWhite);

As you can see, in J#.NET the access to the control properties is made through the use of wrapper functions (automatically generated when you insert the control inside your project) with the "get_" and "set_" prefixes. Intellisense will help you finding the right wrapper function.


Oscilloscope.ColorBackground property

Oscilloscope.ColorBackground property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Oscilloscope.ColorBackground (nPlayer as integer) [=long]
Remarks | Sets the color of the Oscilloscope background for the given player.
See also | Oscilloscope COM object. Oscilloscope property How to use the embedded Visual Feedbacks section.


Oscilloscope.ColorLine property

Oscilloscope.ColorLine property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Oscilloscope.ColorLine (nPlayer as integer) [=long]
Remarks | Sets the color of the Oscilloscope line for the given player.
See also | Oscilloscope COM object. Oscilloscope property How to use the embedded Visual Feedbacks section.


Oscilloscope.LineWidth property

Oscilloscope.LineWidth property

Type | short for Visual C++ integer for Visual Basic
Syntax | object.Oscilloscope.LineWidth (nPlayer as integer) [=integer]
Remarks | Sets the width in pixels of the Oscilloscope line for the given player.
See also | Oscilloscope COM object. Oscilloscope property How to use the embedded Visual Feedbacks section.


Oscilloscope.Type property

Oscilloscope.Type property

Type

short for Visual C++

enumOscillType for Visual Basic

Syntax

object.Oscilloscope.Type (nPlayer as integer) [=integer]

Remarks

Sets the type of drawing used to render the Oscilloscope line for the given player.

Supported values are the following:

Mnemonic constant | Value | Meaning
OSCILL_TYPE_LINES (default) | 0 | The oscilloscope line is rendered through contiguous lines
OSCILL_TYPE_DOTS | 1 | The oscilloscope line is rendered through dots

See also

Oscilloscope COM object.

Oscilloscope property

How to use the embedded Visual Feedbacks section.


Oscilloscope.ZoomPerc property

Oscilloscope.ZoomPerc property

Type | short for Visual C++ integer for Visual Basic
Syntax | object.Oscilloscope.ZoomPerc (nPlayer as integer) [=integer]
Remarks | Sets, for the given player, the height zoom percentage of the oscilloscope line. By default set to 100%, can assume values in the range from 5% to 500%
See also | Oscilloscope COM object. Oscilloscope property How to use the embedded Visual Feedbacks section.


Oscilloscope.Create method

Oscilloscope.Create method

Remarks

Creates the Oscilloscope object: once created, the Oscilloscope will stay active until the termination of the container application: being a graphical object, the Oscilloscope needs to be associated to an existing window that will be used as a surface for the graphic rendering: this window can be changed at a later time through the Oscilloscope.SetHwnd method.

Once created, by default the Oscilloscope is still not visible: you must make a call to the Oscilloscope.Show method in order to display it.

Note that you can have a different Oscilloscope for each of the allocated players.

For further details about using the embedded Oscilloscope refer to the Oscilloscope object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Oscilloscope.Create (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Oscilloscope.Create (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Oscilloscope
hWndTarget | Handle of the window whose surface will be used in order to render the Oscilloscope graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Oscilloscope.Resize method

Oscilloscope.Resize method

Remarks

Resizes the embedded Oscilloscope, useful when a resize of the hosting window occurs. This method has no effect without a previous call to the Oscilloscope.Create method.

For further details about using the embedded Oscilloscope refer to the Oscilloscope object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Oscilloscope.Resize (

nPlayer as Integer,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.Oscilloscope.Resize (

short nPlayer,

long nWidth,

long nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Oscilloscope
nWidth | New width of the oscilloscope expressed in pixels
nHeight | New height of the oscilloscope expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Oscilloscope.SetBackPictureFromFile method

Oscilloscope.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the embedded Oscilloscope refer to the Oscilloscope object section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Oscilloscope.SetBackPictureFromFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.Oscilloscope.SetBackPictureFromFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Oscilloscope
strPathname | Absolute pathname of the picture file to load. Accepted graphic formats are BMP, JPEG, GIF, TIFF and PNG. An empty pathname will reset an eventual picture set through a previous call to this method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Oscilloscope.SetBackPictureFromHandle method

Oscilloscope.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle (HBITMAP).

For further details about using the embedded Oscilloscope refer to the Oscilloscope object section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Oscilloscope.SetBackPictureFromHandle (

nPlayer as Integer,

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Oscilloscope.SetBackPictureFromHandle (

short nPlayer,

OLE_HANDLE hBitmap

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Oscilloscope
hBitmap | Handle of the bitmap to apply. If this parameter is set to 0 an eventual picture set through a previous call to this method will be reset.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Oscilloscope.SetHwnd method

Oscilloscope.SetHwnd method

Remarks

Changes the HWND of the window used as a surface for the graphic rendering.

For further details about using the embedded Oscilloscope refer to the Oscilloscope object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Oscilloscope.SetHwnd (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Oscilloscope.SetHwnd (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Oscilloscope
hWndTarget | Handle of the window whose surface will be used in order to render the Oscilloscope graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Oscilloscope.Show method

Oscilloscope.Show method

Remarks

Shows/hides the embedded Oscilloscope. This method has no effect without a previous call to the Oscilloscope.Create method.

For further details about using the embedded Oscilloscope refer to the Oscilloscope object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Oscilloscope.Show (

nPlayer as Integer,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.Oscilloscope.Show (

short nPlayer,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the Oscilloscope

bShow

Boolean value that specifies to the player if it must show/hide the Oscilloscope.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the Oscilloscope graphics
BOOL_TRUE | 1 | Shows the Oscilloscope graphics

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundComposer object

SoundComposerMan class

The SoundComposer object, accessible through the control's SoundComposer property, is internally implemented as a COM interface called ISoundComposerand and contains methods needed to compose a sound through the mixing and combination of other entities like sound files and text to speech items.

The SoundComposerMan class is implemented through the following methods:

Methods

SessionCreate

SessionAutomaticStopWhenDoneGet

SessionAutomaticStopWhenDoneSet

SessionItemsCountGet

SessionLoad

SessionSave

ItemSoundFileAdd

ItemSoundFileMemoryAdd

ItemSoundFileMemoryRawAdd

ItemSoundFileRawAdd

ItemSoundFileLoadRangeGet

ItemSoundFileRawInfoGet

ItemSoundFileVolumeSmoothingGet

ItemSoundFileVolumeSmoothingSet

ItemSpeechFromFileAdd

ItemSpeechFromStringAdd

ItemSpeechFileSet

ItemSpeechStringSet

ItemSpeechVoiceGet

ItemSpeechVoiceSet

ItemAmplitudeGet

ItemAmplitudeSet

ItemAppendNext

ItemChannelGet

ItemChannelSet

ItemContentGet

ItemFriendlyNameGet

ItemFriendlyNameSet

ItemInfoGet

ItemIsPlaying

ItemOffsetGet

ItemOffsetSet

ItemPlaybackPositionGet

ItemRemove

ItemTypeGet

ItemUniqueIdGet

For further details about sound composing see the How to compose a sound tutorial.


SoundComposer.SessionCreate method

SoundComposer.SessionCreate method

Remarks

Creates a new and empty multi-channel sound composer session that may host various sound files on allocated channels.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.SessionCreate (

nPlayer as Integer,

nSampleRate as Long,

nChannels as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.SessionCreate (

short nPlayer,

long nSampleRate,

long nChannels

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nSampleRate

Sample rate of the stream, e.g. 44100

nChannels

Number of channels of the audio stream.

Supported values are the following:

Value | Meaning
1 | Mono audio stream
2 | Stereo audio stream
4 | 3.1 audio stream
6 | 5.1 audio stream
8 | 7.1 audio stream

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SoundComposer.SessionAutomaticStopWhenDoneGet method

SoundComposer.SessionAutomaticStopWhenDoneGet method

Remarks

Verifies if the sound composer session is set to be automatically stopped when playback of the last item is completed. The automatic stop can be set or reset through the SoundComposer.SessionAutomaticStopWhenDoneSet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.SessionAutomaticStopWhenDoneGet (

nPlayer as Integer,

ByRef bAutomaticStop as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundGenerator.SessionAutomaticStopWhenDoneGet (

short nPlayer,

short *bAutomaticStop

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

bAutomaticStop

Reference that, on return from the method call, will contain the boolean flag specifying if the sound composer session is set to be automatically stopped when playback of the last item is completed.

Supported values are the following:

Mnemonic Value | Meaning
false (Default) | Automatic stop is disabled
true | Automatic stop is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.SessionAutomaticStopWhenDoneSet method

SoundComposer.SessionAutomaticStopWhenDoneSet method

Remarks

Instructs the sound composer session to automatically stop or to continue playing the session stream when playback of the last item is completed. The automatic stop setting can be verified through the SoundComposer.SessionAutomaticStopWhenDoneGet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.SessionAutomaticStopWhenDoneSet (

nPlayer as Integer,

bAutomaticStop as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundGenerator.SessionAutomaticStopWhenDoneSet (

short nPlayer,

short bAutomaticStop

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

bAutomaticStop

Boolean flag specifying if the sound composer session must be automatically stopped when playback of the last item is completed.

Supported values are the following:

Mnemonic Value | Meaning
false (Default) | Automatic stop is disabled
true | Automatic stop is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.SessionItemsCountGet method

SoundComposer.SessionItemsCountGet method

Remarks

Obtains the number of items currently added to the session previously created through the SoundComposer.SessionCreate method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.SessionItemsCountGet (

nPlayer as Integer,

ByRef nItems as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.SessionItemsCountGet (

short nPlayer,

long *nItems

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the sound composer session
nItems | Reference that, on return from the method call, will contain the number of items

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SoundComposer.SessionLoad method

SoundComposer.SessionLoad method

Remarks

Loads a session from a XML file.

Session's XML files can be created manually through a normal text editor, through your own code or through a previous call to the SoundComposer.SessionSave method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.SessionLoad (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.SoundGenerator.SessionLoad (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the XML file containing session items to load.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.SessionSave method

SoundComposer.SessionSave method

Remarks

Saves the current sound composer session into a XML file. The same session can be loaded at a later time through a call to the SoundComposer.SessionLoad method.

IMPORTANT NOTE: Items eventually added through the SoundComposer.ItemSoundFileMemoryAdd and SoundComposer.ItemSoundFileMemoryRawAdd methods are not saved into the file because their contents, being memory-based, become unavailable once the container application is closed and there would be no way to retrieve the original content of the memory buffer once the container application is launched again.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.SessionSave (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.SoundGenerator.SessionSave (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the destination XML file.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemAmplitudeGet method

SoundComposer.ItemAmplitudeGet method

Remarks

Obtains the volume amplitude of the given item. The current amplitude can be modified through the SoundComposer.ItemAmplitudeSet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemAmplitudeGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef fAmplitude as Single

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemAmplitudeGet (

short nPlayer,

long nUniqueId,

float *fAmplitude

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

fAmplitude

Reference that, on return from the method call, will contain the item's volume amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemAmplitudeSet method

SoundComposer.ItemAmplitudeSet method

Remarks

Modifies the volume amplitude of the given item. The current amplitude can be obtained through the SoundComposer.ItemAmplitudeGet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemAmplitudeSet (

nPlayer as Integer,

nUniqueId as Long,

fAmplitude as Single

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemAmplitudeSet (

short nPlayer,

long nUniqueId,

float fAmplitude

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

fAmplitude

The item's volume amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemAppendNext method

SoundComposer.ItemAppendNext method

Remarks

Instructs the sound composer to append to an existing item the next item that will be added through one of the following methods: SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAd, SoundComposer.ItemSpeechFromFileAdd, SoundComposer.ItemSpeechFromStringAdd.

When this method is invoked successfully, the next item will be appended to the given existing item on the same audio channel of the sound composer and with the same "downmix to mono" setting. After the new item has been appended, the "append mode" is automatically reset.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemAppendNext (

nPlayer as Integer,

nUniqueIdAppendTo as Long,

nOffsetFromAppendPosInMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemAppendNext (

short nPlayer,

long nUniqueIdAppendTo,

long nOffsetFromAppendPosInMs

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueIdAppendTo

Unique identifier of the previously added item

nOffsetFromAppendPosInMs

Offset, expressed in millisecond, to add between the existing item and the new one that is going to be appended.

· Set this parameter to a positive value when you need to add silence between the existing item and the new one that is going to be appended.
· Set this parameter to 0 if no silence is needed.
· Set this parameter to a negative value if you need the new added item to overlap the end of the existing item of the given amount of time.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemChannelGet method

SoundComposer.ItemChannelGet method

Remarks

Obtains the channel of the audio stream that will reproduce the item. The channel can be modified through the SoundComposer.ItemChannelSet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

short control.SoundGenerator.ItemChannelGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nChannel as Long,

ByRef bDownMixToMono as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemChannelGet (

short nPlayer,

long nUniqueId,

long *nChannel,

short *bDownMixToMono

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

nChannel

Reference that, on return from the method call, will contain the channel of the audio stream that will reproduce the item

bDownMixToMono

Reference that, on return from the method call, will contain the boolean flag specifying if there is the need of a downmix in order to store a stereo sound file into a mono channel of the stream.

Supported values are the following:

Mnemonic Value | Meaning
false | Keep stereo channels separated
true | Downmix stereo channels to mono

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemChannelSet method

SoundComposer.ItemChannelSet method

Remarks

Modifies the channel of the audio stream that will reproduce the item. The current channel can be obtained through the SoundComposer.ItemInfoGet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemChannelSet (

nPlayer as Integer,

nUniqueId as Long,

nChannel as Long,

bDownMixToMono as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemChannelSet (

short nPlayer,

long nUniqueId,

long nChannel,

short bDownMixToMono

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

nChannel

Channel of the audio stream that will reproduce the item

bDownMixToMono

Boolean flag specifying if there is the need of a downmix in order to store a stereo sound file into a mono channel of the stream.

Supported values are the following:

Value | Meaning
false | Keep stereo channels separated
true | Downmix stereo channels to mono

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemContentGet method

SoundComposer.ItemContentGet method

Remarks

Obtains contents of a specific item.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemContentGet (

nPlayer as Integer,

nUniqueId as Long

) as String

[C++]

LPCTSTR control.SoundGenerator.ItemContentGet (

short nPlayer,

long nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing contents of the item: - for audio files taken from disk the returned string will be the absolute pathname of the file - for audio files taken from memory the returned string will be empty - for text to speech files taken from disk the returned string will be the absolute pathname of the file - for text to speech strings the returned string will be related text


SoundComposer.ItemFriendlyNameGet method

SoundComposer.ItemFriendlyNameGet method

Remarks

Obtains the friendly name of the given item. The current friendly name can be modified through the SoundComposer.ItemFriendlyNameSet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemFriendlyNameGet (

nPlayer as Integer,

nUniqueId as Long

) as String

[C++]

LPCTSTR control.SoundGenerator.ItemFriendlyNameGet (

short nPlayer,

long nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing the friendly name of the item


SoundComposer.ItemFriendlyNameSet method

SoundComposer.ItemFriendlyNameSet method

Remarks

Modifies the friendly name for a specific item. The current friendly name can be obtained through the SoundComposer.ItemFriendlyNameGet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemFriendlyNameSet (

nPlayer as Integer,

nUniqueId as Long,

strFriendlyName as String

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemFriendlyNameSet (

short nPlayer,

long nUniqueId,

LPCTSTR strFriendlyName

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

strFriendlyName

String containing the friendly name of the item

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemInfoGet method

SoundComposer.ItemInfoGet method

Remarks

Obtains information about the given item.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemInfoGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nDurationMs as Long,

ByRef nChannelsSource as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemInfoGet (

short nPlayer,

long nUniqueId,

long *nDurationMs,

long *nChannelsSource

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

nDurationMs

Reference that, on return from the method call, will contain the duration of the item expressed in milliseconds.

nChannelsSource

Reference that, on return from the method call, will contain the original number of channels of the sound file.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemIsPlaying method

SoundComposer.ItemIsPlaying method

Remarks

Verifies if the given item is in playback status.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemIsPlaying (

nPlayer as Integer,

nUniqueId as Long,

ByRef bIsPlaying as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemIsPlaying (

short nPlayer,

long nUniqueId,

short *bIsPlaying

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the sound file item previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

bIsPlaying

Reference that, on return from the method call, will contain the boolean flag specifying if the item is currently playing.

Supported values are the following:

Mnemonic Value | Meaning
false | The item is currently not playing
true | The item is currently playing

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemOffsetGet method

SoundComposer.ItemOffsetGet method

Remarks

Obtains the offset of the item respect to the beginning of the audio stream. The offset of the item can be modified through the SoundComposer.ItemOffsetSet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemOffsetGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nOffset as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemOffsetGet (

short nPlayer,

long nUniqueId,

long *nOffset

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

nOffset

Reference that, on return from the method call, will contain the offset of the item expressed in milliseconds.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemOffsetSet method

SoundComposer.ItemOffsetSet method

Remarks

Modifies the offset of the item respect to the beginning of the audio stream. The current offset of the item can be obtained through the The current channel can be obtained through the SoundComposer.ItemOffsetGet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemOffsetSet (

nPlayer as Integer,

nUniqueId as Long,

nOffset as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemOffsetSet (

short nPlayer,

long nUniqueId,

long nOffset

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

nOffset

The offset of the item expressed in milliseconds.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemPlaybackPositionGet method

SoundComposer.ItemPlaybackPositionGet method

Remarks

Obtains the current playback position of the given item. Before invoking this method you may check if the item is effectively in playback state through the SoundComposer.ItemIsPlaying method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemPlaybackPositionGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nPositionInMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemPlaybackPositionGet (

short nPlayer,

long nUniqueId,

long *nPositionInMs

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the sound file item previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

nPositionInMs

Value representing the current playback position expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemRemove method

SoundComposer.ItemRemove method

Remarks

Removes the given item from the session.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemRemove (

nPlayer as Integer,

nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemRemove (

short nPlayer,

long nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSoundFileAdd method

SoundComposer.ItemSoundFileAdd method

Remarks

Adds a sound file, or a given range within the sound file, to the audio stream previously created through the SoundComposer.SessionCreate method. Supported sound file formats are the same mentioned inside the LoadSound method.

In case the sound file should be stored inside a memory buffer, use the SoundComposer.ItemSoundFileMemoryAdd method.

In case the sound file should be in a RAW format, use the SoundComposer.ItemSoundFileRawAdd or SoundComposer.ItemSoundFileMemoryRawAdd methods.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

short control.SoundGenerator.ItemSoundFileAdd (

nPlayer as Integer,

strFriendlyName as String,

nChannel as Integer,

strPathname as String,

bDownMixToMonoe as enumBoolean,

nOffsetMs as Long,

nStartPositionMs as Long,

nEndPositionMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSoundFileAdd (

short nPlayer,

LPCTSTR strFriendlyName,

short nChannel,

LPCTSTR strPathname,

short bDownMixToMono,

long nOffsetMs,

long nStartPositionMs,

long nEndPositionMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nChannel

Mono channel or stereo channel pair of the audio stream that will reproduce the item.

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

Due to the fact that the audio stream previously created through the SoundComposer.SessionCreate method could be multi-channel, this would be the behaviour when a sound file item is added:

· if the sound file has one single channel (Mono) or two channels (Stereo), its mapping on the audio stream would be in two possible ways:
· if the bDownMixToMono parameter is set to "true" the sound file is downmixed to mono and mapped on the audio stream inside the channel identified by the nChannel parameter
· if the bDownMixToMono parameter is set to "false" the nChannel parameter, instead of representing the index of a mono channel, represents the index of the stereo channel pair (*) on which the sound file item is mapped: for Mono sound files the stream will be duplicated on both channels.
· if the sound file has more than two channels (multi-channel), its mapping on the audio stream would be in two possible ways:
· if the bDownMixToMono parameter is set to "true" the sound file is downmixed to mono and mapped on the audio stream inside the channel identified by the nChannel parameter
· if the bDownMixToMono parameter is set to "false" the sound file is in any case downmixed to stereo and the nChannel parameter, instead of representing the index of a mono channel, represents the index of the stereo channel pair (*) on which the sound file item is mapped.

(*) If for example the audio stream previously created through the SoundComposer.SessionCreate method should have 8 channels (7.1 multi-channel), stereo channels pairs would be mapped as follows:

- stereo channel pair 0 would group mono channels 0 and 1

- stereo channel pair 1 would group mono channels 2 and 3

- stereo channel pair 2 would group mono channels 4 and 5

- stereo channel pair 3 would group mono channels 6 and 7

strPathname

Absolute pathname of the sound file

bDownMixToMono

Boolean flag specifying if there is the need of a downmix in order to store a stereo sound file into a mono channel of the stream.

Supported values are the following:

Mnemonic Value | Meaning
false | Keep stereo channels separated
true | Downmix stereo channels to mono

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

nOffsetMs

Offset of the sound, expressed in milliseconds, respect to the beginning of the audio stream.

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

nStartPositionMs

The start position, expressed in milliseconds, where the sound file loading will occur. Set this value to 0 for loading from the beginning of the sound.

nEndPositionMs

The end position, expressed in milliseconds, where the sound file loading will occur. Set this value to -1 for loading till the sound end.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element:

- SoundComposer.ItemFriendlyNameGet to obtain the friendly name of the item

- SoundComposer.ItemFriendlyNameSet to obtain the friendly name of the item

- SoundComposer.ItemContentGet to obtain contents of the item

- SoundComposer.ItemInfoGet to obtain various information about the item

- SoundComposer.ItemAmplitudeSet to modify the amplitude of the item

- SoundComposer.ItemChannelSet to modify the channel of of the audio stream that will reproduce the item

- SoundComposer.ItemRemove to remove the item from the sound composition

- SoundComposer.ItemOffsetSet to modify the offset, expressed in milliseconds, of the item respect to the beginning of the audio stream

- SoundComposer.ItemTypeGet to obtain the item's type

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSoundFileMemoryAdd method

SoundComposer.ItemSoundFileMemoryAdd method

Remarks

Adds a sound stored inside a memory buffer, or a given range within the sound, to the audio stream previously created through the SoundComposer.SessionCreate method. Supported sound file formats are the same mentioned inside the LoadSound method.

In case the sound file should be stored inside a file on disk use the SoundComposer.ItemSoundFileAdd method.

In case the sound file should be in a RAW format use the SoundComposer.ItemSoundFileRawAdd or SoundComposer.ItemSoundFileMemoryRawAdd methods.

IMPORTANT NOTE: Items added through this method will not be saved into the destination XML file when the SoundComposer.SessionSave method is invoked.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSoundFileMemoryAdd (

nPlayer as Integer,

strFriendlyName as String,

nChannel as Integer,

pBuffer as Variant,

nBufferLength as Long,

bDownMixToMono as enumBoolean,

nOffsetMs as Long,

nStartPositionMs as Long,

nEndPositionMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSoundFileMemoryAdd (

short nPlayer,

LPCTSTR strFriendlyName,

short nChannel,

const VARIANT FAR& pBuffer,

long nBufferLength,

short bDownMixToMono,

long nOffsetMs,

long nStartPositionMs,

long nEndPositionMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

strFriendlyName

Friendly name of the item

nChannel

Mono channel or stereo channel pair of the audio stream that will reproduce the item.

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

Due to the fact that the audio stream previously created through the SoundComposer.SessionCreate method could be multi-channel, this would be the behaviour when a sound file item is added:

· if the sound file has one single channel (Mono) or two channels (Stereo), its mapping on the audio stream would be in two possible ways:
· if the bDownMixToMono parameter is set to "true" the sound file is downmixed to mono and mapped on the audio stream inside the channel identified by the nChannel parameter
· if the bDownMixToMono parameter is set to "false" the nChannel parameter, instead of representing the index of a mono channel, represents the index of the stereo channel pair (*) on which the sound file item is mapped: for Mono sound files the stream will be duplicated on both channels.
· if the sound file has more than two channels (multi-channel), its mapping on the audio stream would be in two possible ways:
· if the bDownMixToMono parameter is set to "true" the sound file is downmixed to mono and mapped on the audio stream inside the channel identified by the nChannel parameter
· if the bDownMixToMono parameter is set to "false" the sound file is in any case downmixed to stereo and the nChannel parameter, instead of representing the index of a mono channel, represents the index of the stereo channel pair (*) on which the sound file item is mapped.

(*) If for example the audio stream previously created through the SoundComposer.SessionCreate method should have 8 channels (7.1 multi-channel), stereo channels pairs would be mapped as follows:

- stereo channel pair 0 would group mono channels 0 and 1

- stereo channel pair 1 would group mono channels 2 and 3

- stereo channel pair 2 would group mono channels 4 and 5

- stereo channel pair 3 would group mono channels 6 and 7

pBuffer

Input buffer containing the original sound

nBufferLength

Length of the input buffer expressed in bytes

bDownMixToMono

Boolean flag specifying if there is the need of a downmix in order to store a stereo sound file into a mono channel of the stream.

Supported values are the following:

Mnemonic Value | Meaning
false | Keep stereo channels separated
true | Downmix stereo channels to mono

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

nOffsetMs

Offset of the sound, expressed in milliseconds, respect to the beginning of the audio stream.

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

nStartPositionMs

The start position, expressed in milliseconds, where the sound file loading will occur. Set this value to 0 for loading from the beginning of the sound.

nEndPositionMs

The end position, expressed in milliseconds, where the sound file loading will occur. Set this value to -1 for loading till the sound end.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element:

- SoundComposer.ItemFriendlyNameGet to obtain the friendly name of the item

- SoundComposer.ItemFriendlyNameSet to obtain the friendly name of the item

- SoundComposer.ItemContentGet to obtain contents of the item

- SoundComposer.ItemInfoGet to obtain various information about the item

- SoundComposer.ItemAmplitudeSet to modify the amplitude of the item

- SoundComposer.ItemChannelSet to modify the channel of of the audio stream that will reproduce the item

- SoundComposer.ItemRemove to remove the item from the sound composition

- SoundComposer.ItemOffsetSet to modify the offset, expressed in milliseconds, of the item respect to the beginning of the audio stream

- SoundComposer.ItemTypeGet to obtain the item's type

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSoundFileRawAdd method

SoundComposer.ItemSoundFileRawAdd method

Remarks

Adds a sound file, or a given range within the sound file, containing RAW audio data to the audio stream previously created through the SoundComposer.SessionCreate method.

After the item has been added to the session, its raw setting can be obtained at a later time through the SoundComposer.ItemSoundFileRawInfoGet method.

In case the raw sound file should be stored inside a memory buffer use the SoundComposer.ItemSoundFileMemoryRawAdd method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSoundFileRawAdd (

nPlayer as Integer,

strFriendlyName as String,

nChannel as Integer,

strPathname as String,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as enumBoolean,

nFrequency as Long,

nChannels as Long,

bDownMixToMono as enumBoolean,

nOffsetMs as Long,

nStartPositionMs as Long,

nEndPositionMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSoundFileRawAdd (

short nPlayer,

LPCTSTR strFriendlyName,

short nChannel,

LPCTSTR strPathname,

short nEncodeMode,

short bIsBigEndian,

long nFrequency,

long nChannels,

short bDownMixToMono,

long nOffsetMs,

long nStartPositionMs,

long nEndPositionMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

strFriendlyName

Friendly name of the item

nChannel

Mono channel or stereo channel pair of the audio stream that will reproduce the item.

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

Due to the fact that the audio stream previously created through the SoundComposer.SessionCreate method could be multi-channel, this would be the behaviour when a sound file item is added:

· if the sound file has one single channel (Mono) or two channels (Stereo), its mapping on the audio stream would be in two possible ways:
· if the bDownMixToMono parameter is set to "true" the sound file is downmixed to mono and mapped on the audio stream inside the channel identified by the nChannel parameter
· if the bDownMixToMono parameter is set to "false" the nChannel parameter, instead of representing the index of a mono channel, represents the index of the stereo channel pair (*) on which the sound file item is mapped: for Mono sound files the stream will be duplicated on both channels.
· if the sound file has more than two channels (multi-channel), its mapping on the audio stream would be in two possible ways:
· if the bDownMixToMono parameter is set to "true" the sound file is downmixed to mono and mapped on the audio stream inside the channel identified by the nChannel parameter
· if the bDownMixToMono parameter is set to "false" the sound file is in any case downmixed to stereo and the nChannel parameter, instead of representing the index of a mono channel, represents the index of the stereo channel pair (*) on which the sound file item is mapped.

(*) If for example the audio stream previously created through the SoundComposer.SessionCreate method should have 8 channels (7.1 multi-channel), stereo channels pairs would be mapped as follows:

- stereo channel pair 0 would group mono channels 0 and 1

- stereo channel pair 1 would group mono channels 2 and 3

- stereo channel pair 2 would group mono channels 4 and 5

- stereo channel pair 3 would group mono channels 6 and 7

strPathname

Absolute pathname of the raw sound file

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
RAW_ENCODE_PCM_U8 | 0 | RAW PCM 8 bits Unsigned
RAW_ENCODE_PCM_S8 | 1 | RAW PCM 8 bits Signed
RAW_ENCODE_PCM_S16 | 2 | RAW PCM 16 bits Signed
RAW_ENCODE_PCM_S24 | 3 | RAW PCM 24 bits Signed
RAW_ENCODE_PCM_S32 | 4 | RAW PCM 32 bits Signed
RAW_ENCODE_FLOAT32 | 5 | RAW 32 bits floating point
RAW_ENCODE_G711_ULAW | 6 | RAW G711 U-LAW
RAW_ENCODE_G711_ALAW | 7 | RAW G711 A-LAW
RAW_ENCODE_GSM_610 | 8 | RAW GSM 6.10
RAW_ENCODE_DIALOGIC_VOX | 9 | RAW Dialogic ADPCM VOX

bIsBigEndian

Boolean flag that specifies if bits order inside the RAW file are little-endian or big-endian

Supported values are the following:

Mnemonic Value | Meaning
false | The RAW file is encoded using little-endian
true | The RAW file is encoded using big-endian

nFrequency

Sample rate of the RAW file (e.g. 44100)

nChannels

Number of channels of the RAW file: for example, 1 for Mono or 2 for Stereo, 6 for 5.1 formats and so on

bDownMixToMono

Boolean flag specifying if there is the need of a downmix in order to store a stereo sound file into a mono channel of the stream.

Supported values are the following:

Mnemonic Value | Meaning
false | Keep stereo channels separated
true | Downmix stereo channels to mono

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

nOffsetMs

Offset of the sound, expressed in milliseconds, respect to the beginning of the audio stream.

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

nStartPositionMs

The start position, expressed in milliseconds, where the sound file loading will occur. Set this value to 0 for loading from the beginning of the sound.

nEndPositionMs

The end position, expressed in milliseconds, where the sound file loading will occur. Set this value to -1 for loading till the sound end.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element:

- SoundComposer.ItemFriendlyNameGet to obtain the friendly name of the item

- SoundComposer.ItemFriendlyNameSet to obtain the friendly name of the item

- SoundComposer.ItemContentGet to obtain contents of the item

- SoundComposer.ItemInfoGet to obtain various information about the item

- SoundComposer.ItemAmplitudeSet to modify the amplitude of the item

- SoundComposer.ItemChannelSet to modify the channel of of the audio stream that will reproduce the item

- SoundComposer.ItemRemove to remove the item from the sound composition

- SoundComposer.ItemOffsetSet to modify the offset, expressed in milliseconds, of the item respect to the beginning of the audio stream

- SoundComposer.ItemTypeGet to obtain the item's type

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSoundFileMemoryRawAdd method

SoundComposer.ItemSoundFileMemoryRawAdd method

Remarks

Adds a sound stored inside a memory buffer, or a given range within the sound, containing RAW audio data to the audio stream previously created through the SoundComposer.SessionCreate method.

After the item has been added to the session, its raw setting can be obtained at a later time through the SoundComposer.ItemSoundFileRawInfoGet method.

In case the raw sound should be stored inside a file on disk use the SoundComposer.ItemSoundFileRawAdd method.

IMPORTANT NOTE: Items added through this method will not be saved into the destination XML file when the SoundComposer.SessionSave method is invoked.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSoundFileMemoryRawAdd (

nPlayer as Integer,

strFriendlyName as String,

nChannel as Integer,

pBuffer as Variant,

nBufferLength as Long,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as enumBoolean,

nFrequency as Long,

nChannels as Long,

bDownMixToMono as enumBoolean,

nOffsetMs as Long,

nStartPositionMs as Long,

nEndPositionMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSoundFileMemoryRawAdd (

short nPlayer,

LPCTSTR strFriendlyName,

short nChannel,

const VARIANT FAR& pBuffer,

long nBufferLength,

short nEncodeMode,

short bIsBigEndian,

long nFrequency,

long nChannels,

short bDownMixToMono,

long nOffsetMs,

long nStartPositionMs,

long nEndPositionMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

strFriendlyName

Friendly name of the item

nChannel

Mono channel or stereo channel pair of the audio stream that will reproduce the item.

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

Due to the fact that the audio stream previously created through the SoundComposer.SessionCreate method could be multi-channel, this would be the behaviour when a sound file item is added:

· if the sound file has one single channel (Mono) or two channels (Stereo), its mapping on the audio stream would be in two possible ways:
· if the bDownMixToMono parameter is set to "true" the sound file is downmixed to mono and mapped on the audio stream inside the channel identified by the nChannel parameter
· if the bDownMixToMono parameter is set to "false" the nChannel parameter, instead of representing the index of a mono channel, represents the index of the stereo channel pair (*) on which the sound file item is mapped: for Mono sound files the stream will be duplicated on both channels.
· if the sound file has more than two channels (multi-channel), its mapping on the audio stream would be in two possible ways:
· if the bDownMixToMono parameter is set to "true" the sound file is downmixed to mono and mapped on the audio stream inside the channel identified by the nChannel parameter
· if the bDownMixToMono parameter is set to "false" the sound file is in any case downmixed to stereo and the nChannel parameter, instead of representing the index of a mono channel, represents the index of the stereo channel pair (*) on which the sound file item is mapped.

(*) If for example the audio stream previously created through the SoundComposer.SessionCreate method should have 8 channels (7.1 multi-channel), stereo channels pairs would be mapped as follows:

- stereo channel pair 0 would group mono channels 0 and 1

- stereo channel pair 1 would group mono channels 2 and 3

- stereo channel pair 2 would group mono channels 4 and 5

- stereo channel pair 3 would group mono channels 6 and 7

pBuffer

Input buffer containing the original sound

nBufferLength

Length of the input buffer expressed in bytes

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
RAW_ENCODE_PCM_U8 | 0 | RAW PCM 8 bits Unsigned
RAW_ENCODE_PCM_S8 | 1 | RAW PCM 8 bits Signed
RAW_ENCODE_PCM_S16 | 2 | RAW PCM 16 bits Signed
RAW_ENCODE_PCM_S24 | 3 | RAW PCM 24 bits Signed
RAW_ENCODE_PCM_S32 | 4 | RAW PCM 32 bits Signed
RAW_ENCODE_FLOAT32 | 5 | RAW 32 bits floating point
RAW_ENCODE_G711_ULAW | 6 | RAW G711 U-LAW
RAW_ENCODE_G711_ALAW | 7 | RAW G711 A-LAW
RAW_ENCODE_GSM_610 | 8 | RAW GSM 6.10
RAW_ENCODE_DIALOGIC_VOX | 9 | RAW Dialogic ADPCM VOX

bIsBigEndian

Boolean flag that specifies if bits order inside the RAW file are little-endian or big-endian

Supported values are the following:

Mnemonic Value | Meaning
false | The RAW file is encoded using little-endian
true | The RAW file is encoded using big-endian

nFrequency

Sample rate of the RAW file (e.g. 44100)

nChannels

Number of channels of the RAW file: for example, 1 for Mono or 2 for Stereo, 6 for 5.1 formats and so on

bDownMixToMono

Boolean flag specifying if there is the need of a downmix in order to store a stereo sound file into a mono channel of the stream.

Supported values are the following:

Mnemonic Value | Meaning
false | Keep stereo channels separated
true | Downmix stereo channels to mono

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

nOffsetMs

Offset of the sound, expressed in milliseconds, respect to the beginning of the audio stream.

This parameter is ignored when the sound file is added in "append mode" after a previous call to the SoundComposer.ItemAppendNext method.

nStartPositionMs

The start position, expressed in milliseconds, where the sound file loading will occur. Set this value to 0 for loading from the beginning of the sound.

nEndPositionMs

The end position, expressed in milliseconds, where the sound file loading will occur. Set this value to -1 for loading till the sound end.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element:

- SoundComposer.ItemFriendlyNameGet to obtain the friendly name of the item

- SoundComposer.ItemFriendlyNameSet to obtain the friendly name of the item

- SoundComposer.ItemContentGet to obtain contents of the item

- SoundComposer.ItemInfoGet to obtain various information about the item

- SoundComposer.ItemAmplitudeSet to modify the amplitude of the item

- SoundComposer.ItemChannelSet to modify the channel of of the audio stream that will reproduce the item

- SoundComposer.ItemRemove to remove the item from the sound composition

- SoundComposer.ItemOffsetSet to modify the offset, expressed in milliseconds, of the item respect to the beginning of the audio stream

- SoundComposer.ItemTypeGet to obtain the item's type

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSoundFileLoadRangeGet method

SoundComposer.ItemSoundFileLoadRangeGet method

Remarks

Obtains the sound file loading range used when the sound file was added to the session's stream.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSoundFileLoadRangeGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nStartPositionMs as Long,

ByRef nEndPositionMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSoundFileLoadRangeGet (

short nPlayer,

long nUniqueId,

long *nStartPositionMs,

long *nEndPositionMs

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the sound composer session
nUniqueId | The unique identifier of the sound file item previously returned by the call to one of the following methods: SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd.
nStartPositionMs | Reference that, on return from the method call, will contain the start position, expressed in milliseconds, where the sound file loading will occur
nEndPositionMs | Reference that, on return from the method call, will contain the end position, expressed in milliseconds, where the sound file loading will occur

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSoundFileRawInfoGet method

SoundComposer.ItemSoundFileRawInfoGet method

Remarks

Adds a sound file, or a given range within the sound file, containing RAW audio data to the audio stream previously created through the SoundComposer.SessionCreate method.

In case the raw sound file should be stored inside a memory buffer use the SoundComposer.ItemSoundFileMemoryRawAdd method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSoundFileRawInfoGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nEncodeMode as enumRAWEncodeModes,

ByRef bIsBigEndian as enumBoolean,

ByRef nFrequency as Long,

ByRef nChannels as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSoundFileRawInfoGet (

short nPlayer,

long nUniqueId,

short *nEncodeMode,

short *bIsBigEndian,

long *nFrequency,

long *nChannels

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the sound file item previously returned by the call to one of the following methods: SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd.

nEncodeMode

Reference that, on return from the method call, will contain the encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
RAW_ENCODE_PCM_U8 | 0 | RAW PCM 8 bits Unsigned
RAW_ENCODE_PCM_S8 | 1 | RAW PCM 8 bits Signed
RAW_ENCODE_PCM_S16 | 2 | RAW PCM 16 bits Signed
RAW_ENCODE_PCM_S24 | 3 | RAW PCM 24 bits Signed
RAW_ENCODE_PCM_S32 | 4 | RAW PCM 32 bits Signed
RAW_ENCODE_FLOAT32 | 5 | RAW 32 bits floating point
RAW_ENCODE_G711_ULAW | 6 | RAW G711 U-LAW
RAW_ENCODE_G711_ALAW | 7 | RAW G711 A-LAW
RAW_ENCODE_GSM_610 | 8 | RAW GSM 6.10
RAW_ENCODE_DIALOGIC_VOX | 9 | RAW Dialogic ADPCM VOX

bIsBigEndian

Reference that, on return from the method call, will contain the boolean flag that specifies if bits order inside the RAW file are little-endian or big-endian

Supported values are the following:

Mnemonic Value | Meaning
false | The RAW file is encoded using little-endian
true | The RAW file is encoded using big-endian

nFrequency

Reference that, on return from the method call, will contain the sample rate of the RAW file (e.g. 44100)

nChannels

Reference that, on return from the method call, will contain the number of channels of the RAW file: for example, 1 for Mono or 2 for Stereo, 6 for 5.1 formats and so on

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSoundFileVolumeSmoothingGet method

SoundComposer.ItemSoundFileVolumeSmoothingGet method

Remarks

Obtains the eventual volume smoothing at the beginning and at the end of the given sound file item. The volume smoothing can be modified or removed through the SoundComposer.ItemSoundFileVolumeSmoothingSet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSoundFileVolumeSmoothingGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nSlideDurationStartMs as Long,

ByRef nSlideDurationEndMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSoundFileVolumeSmoothingGet (

short nPlayer,

long nUniqueId,

long *nSlideDurationStartMs,

long *nSlideDurationEndMs

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the sound composer session
nUniqueId | The unique identifier of the sound file item previously returned by the call to one of the following methods: SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd.
nSlideDurationStartMs | Reference to a value that, on return from the method call, will contain the duration of the volume fade-in, expressed in milliseconds, at the beginning of the item
nSlideDurationEndMs | Reference to a value that, on return from the method call, will contain the duration of the volume fade-out, expressed in milliseconds, at the end of the item

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSoundFileVolumeSmoothingSet method

SoundComposer.ItemSoundFileVolumeSmoothingSet method

Remarks

Applies a volume smoothing at the beginning and at the end of the given sound file item. The current volume smoothing can be obtained through the SoundComposer.ItemVolumeSmoothingGet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSoundFileVolumeSmoothingSet (

nPlayer as Integer,

nUniqueId as Long,

nSlideDurationStartMs as Long,

nSlideDurationEndMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSoundFileVolumeSmoothingSet (

short nPlayer,

long nUniqueId,

long nSlideDurationStartMs,

long nSlideDurationEndMs

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the sound composer session
nUniqueId | The unique identifier of the sound file item previously returned by the call to one of the following methods: SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd.
nSlideDurationStartMs | Duration of the volume fade-in, expressed in milliseconds, at the beginning of the item
nSlideDurationEndMs | Duration of the volume fade-out, expressed in milliseconds, at the end of the item

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSpeechFromFileAdd method

SoundComposer.ItemSpeechFromFileAdd method

Remarks

Adds a speech item, obtained from a text file, to the audio stream previously created through the SoundComposer.SessionCreate method. In case you should need to add a text to speech stream from a simple string of text you may use the SoundComposer.ItemSpeechFromStringAdd method.

The text file may eventually contain XML markups: see the MSDN documentation for a tutorial about XML markup syntax.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSpeechFromFileAdd (

nPlayer as Integer,

strFriendlyName as String,

nChannel as Integer,

strPathname as String,

nVoice as Long,

bRemoveFinalSilence as enumBoolean,

nOffsetMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSpeechFromFileAdd (

short nPlayer,

LPCTSTR strFriendlyName,

short nChannel,

LPCTSTR strPathname,

long nVoice,

short bRemoveFinalSilence,

long nOffsetMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

strFriendlyName

Friendly name of the item

nChannel

Channel of the audio stream that will reproduce the item: can be a value between 0 and the number of channels of the audio stream created through the SoundComposer.SessionCreate method.

strPathname

Absolute pathname of the text file

nVoice

Zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method and related attributes can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method.

bRemoveFinalSilence

Boolean flag that specifies to remove the final silence usually introduced by the Speech API.

Supported values are the following:

Mnemonic Value | Meaning
false | Don't remove final silence
true | Remove final silence

nOffsetMs

Offset of the voice, expressed in milliseconds, respect to the beginning of the audio stream.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element:

- SoundComposer.ItemSpeechStringSet to modify the string of the text to speech

- SoundComposer.ItemContentGet to obtain the current string of text to speech or the pathname of the file containing the text to speech

- SoundComposer.ItemSpeechVoiceGet to obtain the speaking voice

- SoundComposer.ItemSpeechVoiceSet to modify the speaking voice

- SoundComposer.ItemFriendlyNameGet to obtain the friendly name of the item

- SoundComposer.ItemFriendlyNameSet to obtain the friendly name of the item

- SoundComposer.ItemInfoGet to obtain various information about the item

- SoundComposer.ItemAmplitudeSet to modify the amplitude of the item

- SoundComposer.ItemChannelSet to modify the channel of of the audio stream that will reproduce the item

- SoundComposer.ItemRemove to remove the item from the sound composition

- SoundComposer.ItemOffsetSet to modify the offset, expressed in milliseconds, of the item respect to the beginning of the audio stream

- SoundComposer.ItemTypeGet to obtain the item's type

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSpeechFromStringAdd method

SoundComposer.ItemSpeechFromStringAdd method

Remarks

Adds a speech item, contained inside a string, to the audio stream previously created through the SoundComposer.SessionCreate method. In case you should need to add a text to speech stream from contents of a text file you may use the SoundComposer.ItemSpeechFromFileAdd method.

Once added to the list of available items, the string of text can be still modified through the SoundComposer.ItemSpeechStringSet method until playback of the item starts.

The string of text may eventually contain XML markups: see the MSDN documentation for a tutorial about XML markup syntax.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSpeechFromStringAdd (

nPlayer as Integer,

strFriendlyName as String,

nChannel as Integer,

strTextToSpeech as String,

nVoice as Long,

bRemoveFinalSilence as enumBoolean,

nOffsetMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSpeechFromStringAdd (

short nPlayer,

LPCTSTR strFriendlyName,

short nChannel,

LPCTSTR strTextToSpeech,

long nVoice,

short bRemoveFinalSilence,

long nOffsetMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

strFriendlyName

Friendly name of the item

nChannel

Channel of the audio stream that will reproduce the item: can be a value between 0 and the number of channels of the audio stream created through the SoundComposer.SessionCreate method.

strTextToSpeech

String of text to speech

nVoice

Zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method and related attributes can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method.

bRemoveFinalSilence

Boolean flag that specifies to remove the final silence usually introduced by the Speech API.

Supported values are the following:

Mnemonic Value | Meaning
false | Don't remove final silence
true | Remove final silence

nOffsetMs

Offset of the voice, expressed in milliseconds, respect to the beginning of the audio stream.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element:

- SoundComposer.ItemSpeechStringSet to modify the string of the text to speech

- SoundComposer.ItemContentGet to obtain the current string of text to speech or the pathname of the file containing the text to speech

- SoundComposer.ItemSpeechVoiceGet to obtain the speaking voice

- SoundComposer.ItemSpeechVoiceSet to modify the speaking voice

- SoundComposer.ItemFriendlyNameGet to obtain the friendly name of the item

- SoundComposer.ItemFriendlyNameSet to obtain the friendly name of the item

- SoundComposer.ItemInfoGet to obtain various information about the item

- SoundComposer.ItemAmplitudeSet to modify the amplitude of the item

- SoundComposer.ItemChannelSet to modify the channel of of the audio stream that will reproduce the item

- SoundComposer.ItemRemove to remove the item from the sound composition

- SoundComposer.ItemOffsetSet to modify the offset, expressed in milliseconds, of the item respect to the beginning of the audio stream

- SoundComposer.ItemTypeGet to obtain the item's type

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSpeechFileSet method

SoundComposer.ItemSpeechFileSet method

Remarks

Modifies the text file, containing the string of text to speech, of the given item. The text file can be obtained through the SoundComposer.ItemContentGet method.

Due to the fact that modifying the string of text may certainly modify the original duration of the item, invoking the SoundComposer.ItemInfoGet method would allow keeping the duration updated.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSpeechFileSet (

nPlayer as Integer,

ByRef nUniqueId as Long,

strPathname as String

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSpeechFileSet (

short nPlayer,

long nUniqueId,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the sound composer session
nUniqueId | The unique identifier of the element previously returned by the call to the SoundComposer.ItemSpeechFromStringAdd method or to the SoundComposer.ItemSpeechFromFileAdd method.
strPathname | Absolute pathname of the text file

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSpeechStringSet method

SoundComposer.ItemSpeechStringSet method

Remarks

Modifies the string of text to speech of the given item. The current string of text to speech can be obtained through the SoundComposer.ItemContentGet method.

Due to the fact that modifying the string of text may certainly modify the original duration of the item, invoking the SoundComposer.ItemInfoGet method would allow keeping the duration updated.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSpeechStringSet (

nPlayer as Integer,

ByRef nUniqueId as Long,

strTextToSpeech as String

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSpeechStringSet (

short nPlayer,

long nUniqueId,

LPCTSTR strTextToSpeech

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the sound composer session
nUniqueId | The unique identifier of the element previously returned by the call to the SoundComposer.ItemSpeechFromStringAdd method or to the SoundComposer.ItemSpeechFromFileAdd method.
strTextToSpeech | String of text to speech

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSpeechVoiceGet method method

SoundComposer.ItemSpeechVoiceGet method

Remarks

Obtains the voice used to render the speech text of the given item. The voice of the item can be modified through the SoundComposer.ItemSpeechVoiceSet method.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSpeechVoiceGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nVoice as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSpeechVoiceGet (

short nPlayer,

long nUniqueId,

long *nVoice

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the sound composer session
nUniqueId | The unique identifier of the element previously returned by the call to the SoundComposer.ItemSpeechFromStringAdd method or to the SoundComposer.ItemSpeechFromFileAdd method.
nVoice | Reference that, on return from the method call, will contain the zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method and related attributes can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemSpeechVoiceSet method

SoundComposer.ItemSpeechVoiceSet method

Remarks

Modifies the voice used to render the speech text of the given item. The current voice of the item can be obtained through the SoundComposer.ItemSpeechVoiceGet method.

Due to the fact that modifying the speaking voice may certainly modify the original duration of the item, invoking the SoundComposer.ItemInfoGet method would allow keeping the duration updated.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemSpeechVoiceSet (

nPlayer as Integer,

nUniqueId as Long,

nVoice as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemSpeechVoiceSet (

short nPlayer,

long nUniqueId,

long nVoice

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that owns the sound composer session
nUniqueId | The unique identifier of the element previously returned by the call to the SoundComposer.ItemSpeechFromStringAdd method or to the SoundComposer.ItemSpeechFromFileAdd method.
nVoice | The zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method and related attributes can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemTypeGet method

SoundComposer.ItemTypeGet method

Remarks

Obtains the type of a specific item.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemTypeGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nType as enumPlayerSoundComposerTypes

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemTypeGet (

short nPlayer,

long nUniqueId,

short *nType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nUniqueId

The unique identifier of the element previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

nType

Reference that, on return from the method call, will contain the type of item.

Supported values are the following:

Mnemonic Value | Value | Meaning
PLAYER_SOUND_COMPOSER_TYPE_SOUNDFILE | 0 | Sound file
PLAYER_SOUND_COMPOSER_TYPE_SOUNDFILE_RAW | 1 | Raw sound file
PLAYER_SOUND_COMPOSER_TYPE_SPEECHFILE | 2 | File containing text to speech
PLAYER_SOUND_COMPOSER_TYPE_SPEECHSTRING | 3 | Text to speech string

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundComposer.ItemUniqueIdGet method

SoundComposer.ItemUniqueIdGet method

Remarks

Obtains the unique identifier of a specific item previously added to the session.

For further details about sound composing see the the SoundComposer object and the How to compose a sound tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.ItemUniqueIdGet (

nPlayer as Integer,

nItem as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.ItemUniqueIdGet (

short nPlayer,

long nItem,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that owns the sound composer session

nItem

Zero-based index of the item. The total number of items added to the session can be obtained through the SoundComposer.SessionItemsCountGet method.

nUniqueId

Reference that, on return from the method call, will contain the unique identifier of the item previously returned by the call to one of the following methods:

- SoundComposer.ItemSoundFileAdd, SoundComposer.ItemSoundFileMemoryAdd, SoundComposer.ItemSoundFileRawAdd, SoundComposer.ItemSoundFileMemoryRawAdd for sound file items.

- SoundComposer.ItemSpeechFromStringAdd and SoundComposer.ItemSpeechFromFileAdd for text to speech items.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundGenerator object

SoundGenerator object

The SoundGenerator object, accessible through the control's SoundGenerator property, is internally implemented as a COM interface called ISoundGenerator and contains methods needed to generate several kinds of sounds like wave tones, noises, DTMF tones and text to speech.

The SoundGenerator object is implemented through the following methods and properties:

Methods

SpeechVoicesNumGet

SpeechVoiceAttributeGet

StreamCreateDtmfString

StreamCreateNoise

StreamCreateSlidingTone

StreamCreateSpeechFromFile

StreamCreateSpeechFromString

StreamCreateTone

StreamCreateMultiChannelEmpty

StreamChannelAddDtmfString

StreamChannelAddNoise

StreamChannelAddSlidingTone

StreamChannelAddSpeechFromFile

StreamChannelAddSpeechFromString

StreamChannelAddTone

StreamChannelElementsCountGet

StreamChannelElementUniqueIdGet

StreamChannelEmpty

StreamChannelIsEmpty

StreamElementAmplitudeGet

StreamElementAmplitudeSet

StreamElementDtmfStringGet

StreamElementDurationGet

StreamElementNoiseTypeGet

StreamElementOffsetGet

StreamElementRemove

StreamElementSlidingToneFrequenciesGet

StreamElementSlidingToneTypeGet

StreamElementSpeechTextGet

StreamElementSpeechVoiceGet

StreamElementToneFrequencyGet

StreamElementToneFrequencySet

StreamElementToneTypeGet

StreamElementTypeGet

For details about using the sound generator refer to the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Samples of usage of sound generation in Visual C++ and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- SoundGenerator


SoundGenerator.SpeechVoicesNumGet method

SoundGenerator.SpeechVoicesNumGet method

Remarks

Obtains the number of Speech API voices installed inside the system. Attributes of each voice installed inside the system can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.SpeechVoicesNumGet (

ByRef nVoices as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.SpeechVoicesNumGet (

long *nVoices

);

Parameter | Description
nVoices | Reference that, on return from the method call, will contain the number of voices installed inside the system.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.SpeechVoiceAttributeGet method

SoundGenerator.SpeechVoiceAttributeGet method

Remarks

Obtains a specific attribute of the given voice.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial..

Syntax

[Visual Basic]

control.SoundGenerator.SpeechVoiceAttributeGet (

nVoice as Long,

nAttribute as enumSapiVoiceAttributes

) as String

[C++]

BSTR control.SoundGenerator.SpeechVoiceAttributeGet (

long nVoice,

short nAttribute

);

Parameter

Description

nVoice

Zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method.

nAttribute

Identifier of the attribute to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
SAPI_VOICE_ATTRIBUTE_NAME | 0 | Name
SAPI_VOICE_ATTRIBUTE_AGE | 1 | Age
SAPI_VOICE_ATTRIBUTE_GENDER | 2 | Gender
SAPI_VOICE_ATTRIBUTE_LANGUAGE | 3 | Language
SAPI_VOICE_ATTRIBUTE_VENDOR | 4 | Vendor
SAPI_VOICE_ATTRIBUTE_VERSION | 5 | Version

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing the specific attribute


SoundGenerator.StreamChannelAddDtmfString method

SoundGenerator.StreamChannelAddDtmfString method

Remarks

Adds a DTMF (Dual Tone Multi Frequency) tones generator element to the audio stream previously created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

When the rendering of the DTMF tones has been completed, the element itself is automatically removed from the the audio stream; if you need to create a DTMF tones generator that could be reproduced again after its complete rendering, use the SoundGenerator.StreamCreateDtmfString method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelAddDtmfString (

nPlayer as Integer,

nChannel as Integer,

strDtmf as String,

nToneDurationMs as Long,

nSilenceDurationMs as Long,

nOffsetMs as Long,

nFadeInMs as Long,

nFadeOutMs as Long,

fAmplitude as Single,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelAddDtmfString (

short nPlayer,

short nChannel,

LPCTSTR strDtmf,

long nToneDurationMs,

long nSilenceDurationMs,

long nOffsetMs,

long nFadeInMs,

long nFadeOutMs,

float fAmplitude,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nChannel

Channel of the audio stream that will reproduce DTMF tones: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

strDtmf

String containing DTMF characters that will dial the phone number

nToneDurationMs

Duration of each DTMF tone expressed in milliseconds

nSilenceDurationMs

Duration of silence between each DTMF tone expressed in milliseconds

nOffsetMs

Offset of the DTMF tones, expressed in milliseconds, respect to the beginning of the audio stream.

nFadeInMs

Duration of the fade-in at the beginning of each DTMF tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-in at the beginning of each DTMF tone.

nFadeOutMs

Duration of the fade-out at the end of each DTMF tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-out at the end of each DTMF tone.

fAmplitude

Amplitude of DTMF tones.

- value 0.0 means that DTMF tones are muted

- values higher than 0.0 and smaller than 1.0 attenuate DTMF tones

- value 1.0 sets DTMF tones at full volume

- values higher than 1.0 amplify DTMF tones

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element:

- SoundGenerator.StreamElementAmplitudeSet and SoundGenerator.StreamElementAmplitudeGet to modify and retrieve the amplitude of the DTMF element.

- SoundGenerator.StreamElementDtmfStringGet to obtain the current string of DTMF characters.

- SoundGenerator.StreamElementRemove to remove the DTMF element from the audio stream.

- SoundGenerator.StreamElementOffsetGet to obtain the offset of the DTMF element

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelAddNoise method

SoundGenerator.StreamChannelAddNoise method

Remarks

Adds a noise generator element to the audio stream previously created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

When the rendering of the wave noise has been completed, the element itself is automatically removed from the the audio stream; if you need to create a noise that could be reproduced again after its complete rendering, use the SoundGenerator.StreamCreateNoise method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelAddNoise (

nPlayer as Integer,

nChannel as Integer,

nNoiseType as enumSoundGenNoiseTypes,

fReserved as Single,

fAmplitude as Single,

nDurationMs as Long,

nOffsetMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelAddNoise (

short nPlayer,

short nChannel,

short nNoiseType,

float fReserved,

float fAmplitude,

long nDurationMs,

long nOffsetMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nChannel

Channel of the audio stream that will reproduce the noise: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

nNoiseType

Type of noise.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_NOISE_TYPE_WHITE | 0 | White noise
SOUNDGEN_NOISE_TYPE_PINK | 1 | Pink noise
SOUNDGEN_NOISE_TYPE_BROWN | 2 | Brown noise

fReserved

Reserved for future uses, set this parameter to 0

fAmplitude

Noise amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

nDurationMs

Duration of the noise expressed in milliseconds

nOffsetMs

Offset of the noise, expressed in milliseconds, respect to the beginning of the audio stream.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element:

- SoundGenerator.StreamElementAmplitudeSet and SoundGenerator.StreamElementAmplitudeGet to modify and retrieve the amplitude of the noise element.

- SoundGenerator.StreamElementNoiseTypeGet to obtain the type of noise.

- SoundGenerator.StreamElementRemove to remove the noise element from the audio stream.

- SoundGenerator.StreamElementDurationGet to obtain the duration of the noise element.

- SoundGenerator.StreamElementOffsetGet to obtain the offset of the noise element

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelAddSlidingTone method

SoundGenerator.StreamChannelAddSlidingTone method

Remarks

Adds a sliding wave tone element to the audio stream previously created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

When the rendering of the sliding wave tone has been completed, the element itself is automatically removed from the the audio stream; if you need to create a sliding wave tone that could be reproduced again after its complete rendering, use the SoundGenerator.StreamCreateSlidingTone method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelAddSlidingTone (

nPlayer as Integer,

nChannel as Integer,

nWaveType as enumSoundGenSlidingWaveTypes,

fFrequencyStart as Single,

fFrequencyEnd as Single,

fAmplitudeStart as Single,

fAmplitudeEnd as Single,

bLogInterpolation as enumBoolean,

nDurationMs as Long,

nOffsetMs as Long,

nFadeInMs as Long,

nFadeOutMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelAddSlidingTone (

short nPlayer,

short nChannel,

short nWaveType,

float fFrequencyStart,

float fFrequencyEnd,

float fAmplitudeStart,

float fAmplitudeEnd,

short bLogInterpolation,

long nDurationMs,

long nOffsetMs,

long nFadeInMs,

long nFadeOutMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nChannel

Channel of the audio stream that will reproduce the sliding wave tone: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

nWaveType

Type of wave tone.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_SLIDING_WAVE_TYPE_SINE | 0 | Sine wave
SOUNDGEN_SLIDING_WAVE_TYPE_SQUARE | 1 | Square wave
SOUNDGEN_SLIDING_WAVE_TYPE_SAWTOOTH | 2 | Sawtooth wave
SOUNDGEN_SLIDING_WAVE_TYPE_SQUARE_NO_ALIAS | 3 | Square wave without aliasing

fFrequencyStart

Initial wave tone frequency expressed in Hertz, e.g. 700

fFrequencyEnd

Final wave tone frequency expressed in Hertz, e.g. 1000

fAmplitudeStart

Initial wave tone amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuates the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplifies the sound volume

fAmplitudeEnd

Final wave tone amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

bLogInterpolation

Boolean value indicating if the sliding should use linear or logarithmic interpolation.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Uses linear interpolation
BOOL_TRUE | Uses logarithmic interpolation

nDurationMs

Duration of the wave tone expressed in milliseconds

nOffsetMs

Offset of the sliding wave tone, expressed in milliseconds, respect to the beginning of the audio stream.

nFadeInMs

Duration of the fade-in at the beginning of the tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-in at the beginning of the audio stream.

nFadeOutMs

Duration of the fade-out at the end of the tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-out at the end of the audio stream.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element.

- SoundGenerator.StreamElementSlidingToneLimitsGet to retrieve frequencies and amplitudes used to render the sliding wave tone element.

- SoundGenerator.StreamElementSlidingToneTypeGet to obtain the type of sliding wave tone.

- SoundGenerator.StreamElementRemove to remove the wave tone element from the audio stream.

- SoundGenerator.StreamElementDurationGet to obtain the duration of the wave tone element.

- SoundGenerator.StreamElementOffsetGet to obtain the offset of the wave tone element.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelAddSpeechFromFile method

SoundGenerator.StreamChannelAddSpeechFromFile method

Remarks

Adds a speech element, obtained from a text file, to the audio stream previously created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

The text file may eventually contain XML markup: see the MSDN documentation for a tutorial about XML markup syntax.

When the rendering of the speech has been completed, the element itself is automatically removed from the the audio stream; if you need to create a speech that could be reproduced again after its complete rendering, use the SoundGenerator.StreamCreateSpeechFromString or SoundGenerator.StreamCreateSpeechFromFile methods.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelAddSpeechFromFile (

nPlayer as Integer,

nChannel as Integer,

strPathname as String,

nVoice as Long,

fAmplitude as Single,

nOffsetMs as Long,

bRemoveFinalSilence as enumBoolean,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelAddSpeechFromFile (

short nPlayer,

short nChannel,

LPCTSTR strPathname,

long nVoice,

float fAmplitude,

long nOffsetMs,

short bRemoveFinalSilence,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nChannel

Channel of the audio stream that will reproduce the speech: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

strPathname

Absolute pathname of the text file

nVoice

Zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method and related attributes can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method..

fAmplitude

Audio stream amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

nOffsetMs

Offset of the speech, expressed in milliseconds, respect to the beginning of the audio stream.

bRemoveFinalSilence

Boolean flag that specifies to remove the final silence usually introduced by the Speech API.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Don't remove final silence
BOOL_TRUE | Remove final silence

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element.

- SoundGenerator.StreamElementAmplitudeSet and SoundGenerator.StreamElementAmplitudeGet to modify and retrieve the amplitude of the text to speech element.

- SoundGenerator.StreamElementSpeechTextGet to obtain the string containing the pathname of the text file

- SoundGenerator.StreamElementSpeechVoiceGet to obtain the voice used to speak

- SoundGenerator.StreamElementRemove to remove the wave tone element from the audio stream.

- SoundGenerator.StreamElementDurationGet to obtain the duration of the wave tone element.

- SoundGenerator.StreamElementOffsetGet to obtain the offset of the wave tone element.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelAddSpeechFromString method

SoundGenerator.StreamChannelAddSpeechFromString method

Remarks

Adds a speech element, obtained from a string of characters, to the audio stream previously created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

The text string may eventually contain XML markup: see the MSDN documentation for a tutorial about XML markup syntax.

When the rendering of the speech has been completed, the element itself is automatically removed from the the audio stream; if you need to create a speech that could be reproduced again after its complete rendering, use the SoundGenerator.StreamCreateSpeechFromString or SoundGenerator.StreamCreateSpeechFromFile methods.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelAddSpeechFromString (

nPlayer as Integer,

nChannel as Integer,

strTextToSpeech as String,

nVoice as Long,

fAmplitude as Single,

nOffsetMs as Long,

bRemoveFinalSilence as enumBoolean,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelAddSpeechFromString (

short nPlayer,

short nChannel,

LPCTSTR strTextToSpeech,

long nVoice,

float fAmplitude,

long nOffsetMs,

short bRemoveFinalSilence,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nChannel

Channel of the audio stream that will reproduce the speech: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

strTextToSpeech

String of text to speech

nVoice

Zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method and related attributes can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method..

fAmplitude

Audio stream amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

nOffsetMs

Offset of the speech, expressed in milliseconds, respect to the beginning of the audio stream.

bRemoveFinalSilence

Boolean flag that specifies to remove the final silence usually introduced by the Speech API.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Don't remove final silence
BOOL_TRUE | Remove final silence

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element.

- SoundGenerator.StreamElementAmplitudeSet and SoundGenerator.StreamElementAmplitudeGet to modify and retrieve the amplitude of the text to speech element.

- SoundGenerator.StreamElementSpeechTextGet to obtain the string containing the pathname of the text file

- SoundGenerator.StreamElementSpeechVoiceGet to obtain the voice used to speak

- SoundGenerator.StreamElementRemove to remove the wave tone element from the audio stream.

- SoundGenerator.StreamElementDurationGet to obtain the duration of the wave tone element.

- SoundGenerator.StreamElementOffsetGet to obtain the offset of the wave tone element.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelAddTone method

SoundGenerator.StreamChannelAddTone method

Remarks

Adds a wave tone generator element to the audio stream previously created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

When the rendering of the wave tone element has been completed, the element itself is automatically removed from the the audio stream; if you need to create a wave tone that could be reproduced again after its complete rendering, use the SoundGenerator.StreamCreateTone method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelAddTone (

nPlayer as Integer,

nChannel as Integer,

nWaveType as enumSoundGenWaveTypes,

fFrequency as Single,

fAmplitude as Single,

nDurationMs as Long,

nOffsetMs as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelAddTone (

short nPlayer,

short nChannel,

short nWaveType,

float fFrequency,

float fAmplitude,

long nDurationMs,

long nOffsetMs,

long *nUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nChannel

Channel of the audio stream that will reproduce the wave tone: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

nWaveType

Type of wave tone.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_WAVE_TYPE_SINE | 0 | Sine wave
SOUNDGEN_WAVE_TYPE_SQUARE | 1 | Square wave
SOUNDGEN_WAVE_TYPE_SAWTOOTH | 2 | Sawtooth wave
SOUNDGEN_WAVE_TYPE_SAWTOOTH_NEGATIVE | 3 | Negative sawtooth wave
SOUNDGEN_WAVE_TYPE_TRIANGLE | 4 | Triangle wave

fFrequency

Wave tone frequency expressed in Hertz

fAmplitude

Wave tone amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

nDurationMs

Duration of the wave tone expressed in milliseconds. Set this value to 0 for creating an endless wave tone.

nOffsetMs

Offset of the wave tone, expressed in milliseconds, respect to the beginning of the audio stream.

nUniqueId

Reference to a value that, on return from the method call, will contain the unique identifier of the newly added element: this unique identifier will be used in order to invoke further methods related to the use of this specific element.

- SoundGenerator.StreamElementAmplitudeSet and SoundGenerator.StreamElementAmplitudeGet to modify and retrieve the amplitude of the wave tone element.

- SoundGenerator.StreamElementToneFrequencySet and SoundGenerator.StreamElementToneFrequencyGet to modify and retrieve the wave tone frequency of the element.

- SoundGenerator.StreamElementToneTypeGet to obtain the type of wave tone.

- SoundGenerator.StreamElementRemove to remove the wave tone element from the audio stream.

- SoundGenerator.StreamElementDurationGet to obtain the duration of the wave tone element.

- SoundGenerator.StreamElementOffsetGet to obtain the offset of the wave tone element.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelElementsCountGet method

SoundGenerator.StreamChannelElementsCountGet method

Remarks

Retrieves the number of sound elements added to the given channel of the audio stream; the unique identifier of each single element can be obtained through the SoundGenerator.StreamChannelElementUniqueIdGet method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelElementsCountGet (

nPlayer as Integer,

nChannel as Integer,

ByRef nElements as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelElementsCountGet (

short nPlayer,

short nChannel,

long *nElements

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nChannel | Channel of the audio stream: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.
nElements | Reference to a value that, on return from the method call, will contain the number of elements added to the given channel of the audio stream

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelElementUniqueIdGet method

SoundGenerator.StreamChannelElementUniqueIdGet method

Remarks

Retrieves the unique identifier of a specific sound element added to the given channel of the audio stream. The total number of elements added to a specific channel can be obtained through the SoundGenerator.StreamChannelElementsCountGet method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelElementUniqueIdGet (

nPlayer as Integer,

nChannel as Integer,

nElement as Long,

ByRef nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelElementUniqueIdGet (

short nPlayer,

short nChannel,

long nElement,

long *nUniqueId

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nChannel | Channel of the audio stream: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.
nElement | The zero-based index of the element added to the given channel of the audio stream. The total number of elements added to a specific channel can be obtained through the SoundGenerator.StreamChannelElementsCountGet method.
nUniqueId | Reference to a value that, on return from the method call, will contain the unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddTone - SoundGenerator.StreamChannelAddNoise - SoundGenerator.StreamChannelAddDtmfString - SoundGenerator.StreamChannelAddSlidingTone - SoundGenerator.StreamChannelAddSpeechFromFile - SoundGenerator.StreamChannelAddSpeechFromString

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelEmpty method

SoundGenerator.StreamChannelEmpty method

Remarks

Removes any existing sound element from the given channel of the multi-channel audio stream previously created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

You can know if a specific channel is already empty through the SoundGenerator.StreamChannelIsEmpty method; in case the channel should contain one or more elements, they could be enumerated through the SoundGenerator.StreamChannelElementsCountGet method and the unique identifier of each single element could be obtained through the SoundGenerator.StreamChannelElementUniqueIdGet method; after obtaining the unique identifier, each single element could be removed through the SoundGenerator.StreamElementRemove method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelEmpty (

nPlayer as Integer,

nChannel as Integer

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamChannelEmpty (

short nPlayer,

short nChannel

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nChannel | Channel of the audio stream: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamChannelIsEmpty method

SoundGenerator.StreamChannelIsEmpty method

Remarks

Determines if the given channel of the audio stream, previously created through the SoundGenerator.StreamCreateMultiChannelEmpty method, is empty,

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamChannelIsEmpty (

nPlayer as Integer,

nChannel as Integer

) as enumBoolean

[C++]

BOOL control.SoundGenerator.StreamChannelIsEmpty (

short nPlayer,

short nChannel

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nChannel | Channel of the audio stream: can be a value between 0 and the number of channels of the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

Return value

Value | Meaning
FALSE | The channel is not empty
TRUE | The channel is empty


SoundGenerator.StreamCreateDtmfString method

SoundGenerator.StreamCreateDtmfString method

Remarks

Creates a DTMF (Dual Tone Multi Frequency) tones audio stream and loads it inside the given player.

Once created, the audio stream can be played through the PlaySound method, paused through the PauseSound method and stopped through the StopSound method. Once no more needed, the audio stream can be discarded from memory through the CloseSound method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamCreateDtmfString (

nPlayer as Integer,

nSampleRate as Long,

bMono as enumBoolean,

strDtmf as String,

nToneDurationMs as Long,

nSilenceDurationMs as Long,

nFadeInMs as Long,

nFadeOutMs as Long,

fAmplitude as Single

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamCreateDtmfString (

short nPlayer,

long nSampleRate,

short bMono,

LPCTSTR strDtmf,

long nToneDurationMs,

long nSilenceDurationMs,

long nFadeInMs,

long nFadeOutMs,

float fAmplitude

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSampleRate

Sample rate of the stream, e.g. 44100

bMono

Boolean value specifying if the audio stream is in mono or stereo.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Creates a stereo audio stream
BOOL_TRUE | Creates a mono audio stream

strDtmf

String containing DTMF characters that will dial the phone number

nToneDurationMs

Duration of each DTMF tone expressed in milliseconds

nSilenceDurationMs

Duration of silence between each DTMF tone expressed in milliseconds

nFadeInMs

Duration of the fade-in at the beginning of each DTMF tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-in at the beginning of each DTMF tone.

nFadeOutMs

Duration of the fade-out at the end of each DTMF tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-out at the end of each DTMF tone.

fAmplitude

Amplitude of DTMF tones.

- value 0.0 means that DTMF tones are muted

- values higher than 0.0 and smaller than 1.0 attenuate DTMF tones

- value 1.0 sets DTMF tones at full volume

- values higher than 1.0 amplify DTMF tones

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamCreateMultiChannelEmpty method

SoundGenerator.StreamCreateMultiChannelEmpty method

Remarks

Creates and loads into the given player a new and empty multi-channel (up to 7.1) audio stream that may host the following kinds of sound generators on allocated channels:

- Pure wave tones through the SoundGenerator.StreamChannelAddTone method

- Sliding wave tones through the SoundGenerator.StreamChannelAddSlidingTone method

- Noises through the SoundGenerator.StreamChannelAddNoise method

- DTMF tones through the SoundGenerator.StreamChannelAddDtmfString method

- Text to speech through the SoundGenerator.StreamChannelAddSpeechFromString and SoundGenerator.StreamChannelAddSpeechFromFile methods.

Once created and filled with needed sound generators, the audio stream can be played through the PlaySound method, paused through the PauseSound method and stopped through the StopSound method. Once no more needed, the audio stream can be discarded from memory through the CloseSound method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamCreateMultiChannelEmpty (

nPlayer as Integer,

nSampleRate as Long,

nChannels as Integer

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamCreateMultiChannelEmpty (

short nPlayer,

long nSampleRate,

short nChannels

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSampleRate

Sample rate of the stream, e.g. 44100

nChannels

Number of channels of the audio stream.

Supported values are the following:

Value | Meaning
1 | Mono audio stream
2 | Stereo audio stream
4 | 3.1 audio stream
6 | 5.1 audio stream
8 | 7.1 audio stream

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamCreateNoise method

SoundGenerator.StreamCreateNoise method

Remarks

Creates a noise audio stream and loads it inside the given player.

Once created, the audio stream can be played through the PlaySound method, paused through the PauseSound method and stopped through the StopSound method. Once no more needed, the audio stream can be discarded from memory through the CloseSound method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamCreateNoise (

nPlayer as Integer,

nSampleRate as Long,

bMono as enumBoolean,

nNoiseType as enumSoundGenNoiseTypes,

fReserved as Single,

fAmplitude as Single,

nDurationMs as Long,

nFadeInMs as Long,

nFadeOutMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamCreateNoise (

short nPlayer,

long nSampleRate,

short bMono,

short nNoiseType,

float fReserved,

float fAmplitude,

long nDurationMs,

long nFadeInMs,

long nFadeOutMs

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSampleRate

Sample rate of the stream, e.g. 44100

bMono

Boolean value specifying if the audio stream is in mono or stereo.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Creates a stereo audio stream
BOOL_TRUE | Creates a mono audio stream

nNoiseType

Type of noise.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_NOISE_TYPE_WHITE | 0 | White noise
SOUNDGEN_NOISE_TYPE_PINK | 1 | Pink noise
SOUNDGEN_NOISE_TYPE_BROWN | 2 | Brown noise

fReserved

Reserved for future uses, set this parameter to 0

fAmplitude

Noise amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

nDurationMs

Duration of the noise expressed in milliseconds.

In case you should need to create an endless noise, use the SoundGenerator.StreamCreateMultiChannelEmpty method in combination with the SoundGenerator.StreamChannelAddNoise method having the nDurationMs parameter set to 0.

nFadeInMs

Duration of the fade-in at the beginning of the noise expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-in at the beginning of the audio stream.

nFadeOutMs

Duration of the fade-out at the end of the noise expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-out at the end of the audio stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamCreateSlidingTone method

SoundGenerator.StreamCreateSlidingTone method

Remarks

Creates a sliding wave tone audio stream and loads it inside the given player. This method allows sliding the wave tone frequency and/or the wave tone amplitude.

Once created, the audio stream can be played through the PlaySound method, paused through the PauseSound method and stopped through the StopSound method. Once no more needed, the audio stream can be discarded from memory through the CloseSound method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamCreateSlidingTone (

nPlayer as Integer,

nSampleRate as Long,

bMono as enumBoolean,

nWaveType as enumSoundGenSlidingWaveTypes,

fFrequencyStart as Single,

fFrequencyEnd as Single,

fAmplitudeStart as Single,

fAmplitudeEnd as Single,

bLogInterpolation as enumBoolean,

nDurationMs as Long,

nFadeInMs as Long,

nFadeOutMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamCreateSlidingTone (

short nPlayer,

long nSampleRate,

short bMono,

short nWaveType,

float fFrequencyStart,

float fFrequencyEnd,

float fAmplitudeStart,

float fAmplitudeEnd,

short bLogInterpolation,

long nDurationMs,

long nFadeInMs,

long nFadeOutMs

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSampleRate

Sample rate of the stream, e.g. 44100

bMono

Boolean value specifying if the audio stream is in mono or stereo.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Creates a stereo audio stream
BOOL_TRUE | Creates a mono audio stream

nWaveType

Type of wave tone.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_SLIDING_WAVE_TYPE_SINE | 0 | Sine wave
SOUNDGEN_SLIDING_WAVE_TYPE_SQUARE | 1 | Square wave
SOUNDGEN_SLIDING_WAVE_TYPE_SAWTOOTH | 2 | Sawtooth wave
SOUNDGEN_SLIDING_WAVE_TYPE_SQUARE_NO_ALIAS | 3 | Square wave without aliasing

fFrequencyStart

Initial wave tone frequency expressed in Hertz, e.g. 700

fFrequencyEnd

Final wave tone frequency expressed in Hertz, e.g. 1000

fAmplitudeStart

Initial wave tone amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuates the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplifies the sound volume

fAmplitudeEnd

Final wave tone amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

bLogInterpolation

Boolean value indicating if the sliding should use linear or logarithmic interpolation.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Uses linear interpolation
BOOL_TRUE | Uses logarithmic interpolation

nDurationMs

Duration of the wave tone expressed in milliseconds

nFadeInMs

Duration of the fade-in at the beginning of the tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-in at the beginning of the audio stream.

nFadeOutMs

Duration of the fade-out at the end of the tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-out at the end of the audio stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamCreateSpeechFromFile method

SoundGenerator.StreamCreateSpeechFromFile method

Remarks

Creates a speech audio stream from a text file and loads it inside the given player. In case you should need to generate an audio stream from a simple string of text you may use the SoundGenerator.StreamCreateSpeechFromString method.

The text file may eventually contain XML markup: see the MSDN documentation for a tutorial about XML markup syntax.

Once created, the audio stream can be played through the PlaySound method, paused through the PauseSound method and stopped through the StopSound method. Once no more needed, the audio stream can be discarded from memory through the CloseSound method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamCreateSpeechFromFile (

nPlayer as Integer,

nSampleRate as Long,

bMono as enumBoolean,

strPathname as String,

nVoice as Long,

fAmplitude as Single,

bRemoveFinalSilence as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamCreateSpeechFromFile (

short nPlayer,

long nSampleRate,

short bMono,

LPCTSTR strPathname,

long nVoice,

float fAmplitude,

short bRemoveFinalSilence

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSampleRate

Sample rate of the stream, e.g. 44100

bMono

Boolean value specifying if the audio stream is in mono or stereo.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Creates a stereo audio stream
BOOL_TRUE | Creates a mono audio stream

strPathname

Absolute pathname of the text file

nVoice

Zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method.

fAmplitude

Audio stream amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

bRemoveFinalSilence

Boolean flag that specifies to remove the final silence usually introduced by the Speech API.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Don't remove final silence
BOOL_TRUE | Remove final silence

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamCreateSpeechFromString method

SoundGenerator.StreamCreateSpeechFromString method

Remarks

Creates a speech audio stream from a string of text and loads it inside the given player. In case you should need to generate an audio stream from text contained inside a file you may use the SoundGenerator.StreamCreateSpeechFromFile method.

The text string may eventually contain XML markup: see the MSDN documentation for a tutorial about XML markup syntax.

Once created, the audio stream can be played through the PlaySound method, paused through the PauseSound method and stopped through the StopSound method. Once no more needed, the audio stream can be discarded from memory through the CloseSound method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamCreateSpeechFromString (

nPlayer as Integer,

nSampleRate as Long,

bMono as enumBoolean,

strTextToSpeech as String,

nVoice as Long,

fAmplitude as Single,

bRemoveFinalSilence as enumBoolean

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamCreateSpeechFromString (

short nPlayer,

long nSampleRate,

short bMono,

LPCTSTR strTextToSpeech,

long nVoice,

float fAmplitude,

short bRemoveFinalSilence

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSampleRate

Sample rate of the stream, e.g. 44100

bMono

Boolean value specifying if the audio stream is in mono or stereo.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Creates a stereo audio stream
BOOL_TRUE | Creates a mono audio stream

strTextToSpeech

String of text to speech

nVoice

Zero-based index of the speaking voice. The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method.

fAmplitude

Audio stream amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

bRemoveFinalSilence

Boolean flag that specifies to remove the final silence usually introduced by the Speech API.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Don't remove final silence
BOOL_TRUE | Remove final silence

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamCreateTone method

SoundGenerator.StreamCreateTone method

Remarks

Creates a wave tone audio stream and loads it inside the given player.

Once created, the audio stream can be played through the PlaySound method, paused through the PauseSound method and stopped through the StopSound method. Once no more needed, the audio stream can be discarded from memory through the CloseSound method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamCreateTone (

nPlayer as Integer,

nSampleRate as Long,

bMono as enumBoolean,

nWaveType as enumSoundGenWaveTypes,

fFrequency as Single,

fAmplitude as Single,

nDurationMs as Long,

nFadeInMs as Long,

nFadeOutMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamCreateTone (

short nPlayer,

long nSampleRate,

short bMono,

short nWaveType,

float fFrequency,

float fAmplitude,

long nDurationMs,

long nFadeInMs,

long nFadeOutMs

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nSampleRate

Sample rate of the stream, e.g. 44100

bMono

Boolean value specifying if the audio stream is in mono or stereo.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | Creates a stereo audio stream
BOOL_TRUE | Creates a mono audio stream

nWaveType

Type of wave tone.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_WAVE_TYPE_SINE | 0 | Sine wave
SOUNDGEN_WAVE_TYPE_SQUARE | 1 | Square wave
SOUNDGEN_WAVE_TYPE_SAWTOOTH | 2 | Sawtooth wave
SOUNDGEN_WAVE_TYPE_SAWTOOTH_NEGATIVE | 3 | Negative sawtooth wave
SOUNDGEN_WAVE_TYPE_TRIANGLE | 4 | Triangle wave

fFrequency

Wave tone frequency expressed in Hertz

fAmplitude

Wave tone amplitude.

- value 0.0 means that sound volume is muted

- values higher than 0.0 and smaller than 1.0 attenuate the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplify the sound volume

nDurationMs

Duration of the wave tone expressed in milliseconds.

In case you should need to create an endless tone, use the SoundGenerator.StreamCreateMultiChannelEmpty method in combination with the SoundGenerator.StreamChannelAddTone method having the nDurationMs parameter set to 0.

nFadeInMs

Duration of the fade-in at the beginning of the tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-in at the beginning of the audio stream.

nFadeOutMs

Duration of the fade-out at the end of the tone expressed in milliseconds. Set this value to 0 if you don't need to apply a fade-out at the end of the audio stream.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementAmplitudeGet method

SoundGenerator.StreamElementAmplitudeGet method

Remarks

Obtains the amplitude of the sound element identified by a specific unique identifier. The amplitude of a sound element can be modified through the SoundGenerator.StreamElementAmplitudeSet method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementAmplitudeGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef fAmplitude as Single

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementAmplitudeGet (

short nPlayer,

long nUniqueId,

float *fAmplitude

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddTone - SoundGenerator.StreamChannelAddNoise - SoundGenerator.StreamChannelAddDtmfString - SoundGenerator.StreamChannelAddSlidingTone - SoundGenerator.StreamChannelAddSpeechFromFile - SoundGenerator.StreamChannelAddSpeechFromString - SoundGenerator.StreamChannelElementUniqueIdGet
fAmplitude | Reference to a value that, on return from the method call, will contain the amplitude of the element. - value 0.0 means that the element is muted - values higher than 0.0 and smaller than 1.0 attenuate the element - value 1.0 sets the element at full volume - values higher than 1.0 amplify the element

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementAmplitudeSet method

SoundGenerator.StreamElementAmplitudeSet method

Remarks

Modifies the amplitude of the sound element identified by a specific unique identifier. The current amplitude of a sound element can be obtained through the SoundGenerator.StreamElementAmplitudeGet method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementAmplitudeSet (

nPlayer as Integer,

nUniqueId as Long,

fAmplitude as Single

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementAmplitudeSet (

short nPlayer,

long nUniqueId,

float fAmplitude

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddTone - SoundGenerator.StreamChannelAddNoise - SoundGenerator.StreamChannelAddDtmfString - SoundGenerator.StreamChannelAddSlidingTone - SoundGenerator.StreamChannelAddSpeechFromFile - SoundGenerator.StreamChannelAddSpeechFromString - SoundGenerator.StreamChannelElementUniqueIdGet
fAmplitude | Amplitude of the sound element. - value 0.0 means that the sound element is muted - values higher than 0.0 and smaller than 1.0 attenuate the sound element - value 1.0 sets the sound element at full volume - values higher than 1.0 amplify the sound element

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementDtmfStringGet method

SoundGenerator.StreamElementDtmfStringGet method

Remarks

Obtains the string of DTMF tones and related settings for the given DTMF element.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial..

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementDtmfStringGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nToneDurationMs as Long,

ByRef nSilenceDurationMs as Long,

ByRef nFadeInMs as Long,

ByRef nFadeOutMs as Long

) as String

[C++]

BSTR control.SoundGenerator.StreamElementDtmfStringGet (

short nPlayer,

long nUniqueId,

long *nToneDurationMs,

long *nSilenceDurationMs,

long *nFadeInMs,

long *nFadeOutMs

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddDtmfString - SoundGenerator.StreamChannelElementUniqueIdGet
nToneDurationMs | Reference to a value that, on return from the method call, will contain the duration of each DTMF tone expressed in milliseconds
nSilenceDurationMs | Reference to a value that, on return from the method call, will contain the duration of silence between each DTMF tone expressed in milliseconds
nFadeInMs | Reference to a value that, on return from the method call, will contain the duration of the fade-in at the beginning of each DTMF tone expressed in milliseconds.
nFadeOutMs | Reference to a value that, on return from the method call, will contain the duration of the fade-out at the end of each DTMF tone expressed in milliseconds.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing characters of DTMF tones


SoundGenerator.StreamElementDurationGet method

SoundGenerator.StreamElementDurationGet method

Remarks

Obtains the duration of the given sound element.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementDurationGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nDurationMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementDurationGet (

short nPlayer,

long nUniqueId,

long *nDurationMs

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddTone - SoundGenerator.StreamChannelAddNoise - SoundGenerator.StreamChannelAddDtmfString - SoundGenerator.StreamChannelAddSlidingTone - SoundGenerator.StreamChannelAddSpeechFromFile - SoundGenerator.StreamChannelAddSpeechFromString - SoundGenerator.StreamChannelElementUniqueIdGet
nDurationMs | Reference to a value that, on return from the method call, will contain the duration of the sound element, expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementNoiseTypeGet method

SoundGenerator.StreamElementNoiseTypeGet method

Remarks

Obtains the type of noise for the given noise element.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementNoiseTypeGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nType as enumSoundGenNoiseTypes

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementNoiseTypeGet (

short nPlayer,

long nUniqueId,

short *nType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nUniqueId

The unique identifier of the element previously returned by one of the following calls:

- SoundGenerator.StreamChannelAddNoise

- SoundGenerator.StreamChannelElementUniqueIdGet

nType

Reference to a value that, on return from the method call, will contain the type of noise.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_NOISE_TYPE_WHITE | 0 | White noise
SOUNDGEN_NOISE_TYPE_PINK | 1 | Pink noise
SOUNDGEN_NOISE_TYPE_BROWN | 2 | Brown noise

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementOffsetGet method

SoundGenerator.StreamElementOffsetGet method

Remarks

Obtains the offset of the given sound element respect to the beginning of the audio stream.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementOffsetGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nOffsetMs as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementOffsetGet (

short nPlayer,

long nUniqueId,

long *nOffsetMs

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddTone - SoundGenerator.StreamChannelAddNoise - SoundGenerator.StreamChannelAddDtmfString - SoundGenerator.StreamChannelAddSlidingTone - SoundGenerator.StreamChannelAddSpeechFromFile - SoundGenerator.StreamChannelAddSpeechFromString - SoundGenerator.StreamChannelElementUniqueIdGet
nOffsetMs | Reference to a value that, on return from the method call, will contain the offset of the sound element, expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementRemove method

SoundGenerator.StreamElementRemove method

Remarks

Removes an element previously added to the audio stream created through the SoundGenerator.StreamCreateMultiChannelEmpty method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementRemove (

nPlayer as Integer,

nUniqueId as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementRemove (

short nPlayer,

long nUniqueId

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddTone - SoundGenerator.StreamChannelAddNoise - SoundGenerator.StreamChannelAddDtmfString - SoundGenerator.StreamChannelAddSlidingTone - SoundGenerator.StreamChannelAddSpeechFromFile - SoundGenerator.StreamChannelAddSpeechFromString - SoundGenerator.StreamChannelElementUniqueIdGet

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementSlidingToneLimitsGet method

SoundGenerator.StreamElementSlidingToneLimitsGet method

Remarks

Obtains current frequencies and amplitudes of the sliding wave tone element identified by a specific unique identifier.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementSlidingToneLimitsGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef fFrequencyStart as Single,

ByRef fFrequencyEnd as Single,

ByRef fAmplitudeStart as Single,

ByRef fAmplitudeEnd as Single,

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementSlidingToneLimitsGet (

short nPlayer,

long nUniqueId,

float *fFrequencyStart,

float *fFrequencyEnd,

float *fAmplitudeStart,

float *fAmplitudeEnd

);

StreamElementSlidingToneLimitsGet

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddSlidingTone - SoundGenerator.StreamChannelElementUniqueIdGet
fFrequencyStart | Reference to a value that, on return from the method call, will contain the sliding wave tone start frequency expressed in Hertz
fFrequencyEnd | Reference to a value that, on return from the method call, will contain the sliding wave tone end frequency expressed in Hertz
fAmplitudeStart | Reference to a value that, on return from the method call, will contain the initial wave tone amplitude. - value 0.0 means that sound volume is muted - values higher than 0.0 and smaller than 1.0 attenuates the sound volume - value 1.0 sets the sound at full volume - values higher than 1.0 amplifies the sound volume
fAmplitudeEnd | Reference to a value that, on return from the method call, will contain the final wave tone amplitude. - value 0.0 means that sound volume is muted - values higher than 0.0 and smaller than 1.0 attenuate the sound volume - value 1.0 sets the sound at full volume - values higher than 1.0 amplify the sound volume

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementSlidingToneTypeGet method

SoundGenerator.StreamElementSlidingToneTypeGet method

Remarks

Obtains the type of sliding wave tone for the given sliding wave tone element.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementSlidingToneTypeGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nType as enumSoundGenSlidingWaveTypes

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementSlidingToneTypeGet (

short nPlayer,

long nUniqueId,

short *nType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nUniqueId

The unique identifier of the element previously returned by one of the following calls:

- SoundGenerator.StreamChannelAddSlidingTone

- SoundGenerator.StreamChannelElementUniqueIdGet

nType

Reference to a value that, on return from the method call, will contain the type of sliding wave tone.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_SLIDING_WAVE_TYPE_SINE | 0 | Sine wave
SOUNDGEN_SLIDING_WAVE_TYPE_SQUARE | 1 | Square wave
SOUNDGEN_SLIDING_WAVE_TYPE_SAWTOOTH | 2 | Sawtooth wave
SOUNDGEN_SLIDING_WAVE_TYPE_SQUARE_NO_ALIAS | 3 | Square wave without aliasing

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementSpeechTextGet method

SoundGenerator.StreamElementSpeechTextGet method

Remarks

Obtains the string of text to speech for the given element.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial..

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementSpeechTextGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef bIsFile as enumBoolean

) as String

[C++]

BSTR control.SoundGenerator.StreamElementSpeechTextGet (

short nPlayer,

long nUniqueId,

long *bIsFile

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nUniqueId

The unique identifier of the element previously returned by one of the following calls:

- SoundGenerator.StreamChannelAddSpeechFromFile

- SoundGenerator.StreamChannelAddSpeechFromString

- SoundGenerator.StreamChannelElementUniqueIdGet

bIsFile

Reference to a value that, on return from the method call, will contain a boolean value stating if the returned string is the text to speech or the absolute pathname of a file containing the text to speech.

Supported values are the following:

Mnemonic Value | Meaning
BOOL_FALSE | The returned string represents the text to speech
BOOL_TRUE | The returned string represents the absolute pathname of a file containing the text to speech

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing the text to speech or the absolute pathname of a file containing the text to speech.


SoundGenerator.StreamElementSpeechVoiceGet method

SoundGenerator.StreamElementSpeechVoiceGet method

Remarks

Obtains the voice used to speech for the given text to speech element.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial..

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementSpeechVoiceGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nVoice as Long

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementSpeechVoiceGet (

short nPlayer,

long nUniqueId,

long *nVoice

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nUniqueId

The unique identifier of the element previously returned by one of the following calls:

- SoundGenerator.StreamChannelAddSpeechFromFile

- SoundGenerator.StreamChannelAddSpeechFromString

- SoundGenerator.StreamChannelElementUniqueIdGet

nVoice

Reference to a value that, on return from the method call, will contain the zero-based index of the voice used to speech.

The total number of voices installed inside the system can be obtained through the SoundGenerator.SpeechVoicesNumGet method while attributes of each single voice can be obtained through the SoundGenerator.SpeechVoiceAttributeGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementToneFrequencyGet method

SoundGenerator.StreamElementToneFrequencyGet method

Remarks

Obtains the current frequency of the wave tone element identified by a specific unique identifier. The frequency of a wave tone element can be modified through the SoundGenerator.StreamElementToneFrequencySet method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementToneFrequencyGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef fFrequency as Single

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementToneFrequencyGet (

short nPlayer,

long nUniqueId,

float *fFrequency

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddTone - SoundGenerator.StreamChannelElementUniqueIdGet
fFrequency | Reference to a value that, on return from the method call, will contain the wave tone frequency expressed in Hertz

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementToneFrequencySet method

SoundGenerator.StreamElementToneFrequencySet method

Remarks

Modifies the frequency of the wave tone element identified by a specific unique identifier. The current frequency of a wave tone element can be obtained through the SoundGenerator.StreamElementToneFrequencyGet method.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementToneFrequencySet (

nPlayer as Integer,

nUniqueId as Long,

fFrequency as Single

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementToneFrequencySet (

short nPlayer,

long nUniqueId,

float fFrequency

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nUniqueId | The unique identifier of the element previously returned by one of the following calls: - SoundGenerator.StreamChannelAddTone - SoundGenerator.StreamChannelElementUniqueIdGet
fFrequency | Wave tone frequency expressed in Hertz

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementToneTypeGet method

SoundGenerator.StreamElementToneTypeGet method

Remarks

Obtains the type of wave tone for the given wave tone element.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementToneTypeGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nType as enumSoundGenWaveTypes

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementToneTypeGet (

short nPlayer,

long nUniqueId,

short *nType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nUniqueId

The unique identifier of the element previously returned by one of the following calls:

- SoundGenerator.StreamChannelAddTone

- SoundGenerator.StreamChannelElementUniqueIdGet

nType

Reference to a value that, on return from the method call, will contain the type of wave tone.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUNDGEN_WAVE_TYPE_SINE | 0 | Sine wave
SOUNDGEN_WAVE_TYPE_SQUARE | 1 | Square wave
SOUNDGEN_WAVE_TYPE_SAWTOOTH | 2 | Sawtooth wave
SOUNDGEN_WAVE_TYPE_SAWTOOTH_NEGATIVE | 3 | Negative sawtooth wave
SOUNDGEN_WAVE_TYPE_TRIANGLE | 4 | Triangle wave

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SoundGenerator.StreamElementTypeGet method

SoundGenerator.StreamElementTypeGet method

Remarks

Obtains the type of the given sound element.

For further details about sound generation see the SoundGenerator object and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

control.SoundGenerator.StreamElementTypeGet (

nPlayer as Integer,

nUniqueId as Long,

ByRef nType as enumSoundGeneratorTypes

) as enumErrorCodes

[C++]

short control.SoundGenerator.StreamElementTypeGet (

short nPlayer,

long nUniqueId,

short *nType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nUniqueId

The unique identifier of the element previously returned by one of the following calls:

- SoundGenerator.StreamChannelAddTone

- SoundGenerator.StreamChannelAddNoise

- SoundGenerator.StreamChannelAddDtmfString

- SoundGenerator.StreamChannelAddSlidingTone

- SoundGenerator.StreamChannelAddSpeechFromFile

- SoundGenerator.StreamChannelAddSpeechFromString

- SoundGenerator.StreamChannelElementUniqueIdGet

nType

Reference to a value that, on return from the method call, will contain the type of the sound element.

Supported values are the following:

Mnemonic Value | Value | Meaning
SOUND_GEN_TYPE_WAVETONE | 0 | Wave tone element added through a call to the SoundGenerator.StreamChannelAddTone method.
SOUND_GEN_TYPE_NOISE | 1 | Noise element added through a call to the SoundGenerator.StreamChannelAddNoise method.
SOUND_GEN_TYPE_SLIDING_WAVETONE | 2 | Sliding wave tone element added through a call to the SoundGenerator.StreamChannelAddSlidingTone method.
SOUND_GEN_TYPE_DTMF | 3 | DTMF string element added through a call to the SoundGenerator.StreamChannelAddDtmfString method.
SOUND_GEN_TYPE_TEXT_TO_SPEECH | 4 | Text to speech element added through a call to the SoundGenerator.StreamChannelAddSpeechFromFile or SoundGenerator.StreamChannelAddSpeechFromString methods.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Spectrum object

Spectrum object

The Spectrum object, accessible through the control's Spectrum property, is internally implemented as a COM interface called ISpectrum and contains information needed to render the embedded Spectrum visual feedback.

It can be used at Run-time in order to create the embedded Spectrum and to change its graphic settings. For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

The Spectrum object is implemented through the following methods and properties:

Methods

Create

GetTable

Resize

SetNumberOfBands

SetHwnd

SetBackPictureFromFile

SetBackPictureFromHandle

Show

Properties

BandsWidth

ColorBands

ColorPeaks

ColorBackground

HasPeaks

UseLogarithmic

ZoomPerc

The following code snippets show how to create and change this object in your code. These examples assume that you have placed a control named MyPlayer on a form or dialog and that you want to change a couple of graphic settings (Bands and Background colors).

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Microsoft Visual Basic (5.0 and 6.0)

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual J#.NET

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Properties and methods of the control are accessible through the control wrapper class CAmp3dj contained inside the amp3dj.cpp and amp3dj.h files: these wrapper files are automatically generated when you insert the control inside your project so, in order to access the wrapper functions, you will have to insert the following line of code somewhere in your code.

#include "amp3dj.h"

The Spectrum object is defined by the control wrapper class CSpectrum contained inside the spectrum.cpp and spectrum.h files: also these wrapper files are automatically generated when you insert the control inside your project so, in order to access this object, you will have to insert the following line of code somewhere in your code.

#include "spectrum.h"

Here follows the code needed to perform the requested operation of initialising the Spectrum object and changing some of its properties.

// declare a Spectrum object

CSpectrum spectrum;

// init the object with the control's Spectrum reference

spectrum = MyPlayer.GetSpectrum ();

// create the Spectrum for player 0 over an existing control

spectrum.Create (0, (OLE_HANDLE) GetDlgItem (IDC_PICTURE)->GetSafeHwnd ());

// again for player 0, set the Spectrum bands color to blue and background color to white

spectrum.SetColorBands (0, RGB (0, 0, 255));

spectrum.SetColorBackground (0, RGB (255, 255, 255));

As you can see the access to the Spectrum properties ColorBands and ColorBackground are wrapped by the SetColorBands and SetColorBackground functions declared inside the wrapper class CSpectrum.

Microsoft Visual Basic (5.0 and 6.0)

Here follows the code needed to perform the requested operations

' create the Spectrum on player 0 over an existing control

MyPlayer.Spectrum.Create 0, Picture1.hWnd

' set the blue color for Spectrum bands of player 0

MyPlayer.Spectrum.ColorBands(0) = RGB(0, 0, 255)

' set the white color for Spectrum background of player 0

MyPlayer.Spectrum.ColorBackground(0) = RGB(255, 255, 255)

Microsoft Visual Basic.NET

Here follows the code needed to perform the requested operations

' create the Spectrum on player 0 over an existing control

MyPlayer.Spectrum.Create(0, PictureBox1.Handle.ToInt32())

' set the blue color for Spectrum bands of player 0

MyPlayer.Spectrum.ColorBands(0) = Convert.ToUInt32(RGB(0, 0, 255))

' set the white color for Spectrum background of player 0

MyPlayer.Spectrum.ColorBackground(0) = Convert.ToUInt32(RGB(255, 255, 255))

Microsoft Visual C#.NET

Here follows the code needed to perform the requested operations

// create the Spectrum on player 0 over an existing control

MyPlayer.Spectrum.Create(0, pictureBox1.Handle.ToInt32());

// set the blue color for Spectrum bands of player 0

MyPlayer.Spectrum.set_ColorBands (0, Convert.ToUlong (ColorTranslator.ToWin32 (Color.Blue)));

// set the white color for Spectrum background of player 0

MyPlayer.Spectrum.set_ColorBackground(0, Convert.ToUlong (ColorTranslator.ToWin32 (Color.White)));

Microsoft Visual J#.NET

Here follows the code needed to perform the requested operations

// create the Spectrum on player 0 over an existing control

MyPlayer.get_Spectrum ().Create ((short) 0, (int) pictureBox1.get_Handle().ToInt32());

// set the blue color for Spectrum bands of player 0

System.Ulong colorBlue = (System.UInt32) ColorTranslator.ToWin32 (Color.get_Blue ());

MyPlayer.get_Spectrum ().set_ColorBands ((short) 0, colorBlue);

// set the white color for Spectrum background of player 0

System.Ulong colorWhite = (System.UInt32) ColorTranslator.ToWin32 (Color.get_White ());

MyPlayer.get_Spectrum ().set_ColorBackground((short) 0, colorWhite);

As you can see, in J#.NET the access to the control properties is made through the use of wrapper functions (automatically generated when you insert the control inside your project) with the "get_" and "set_" prefixes. Intellisense will help you finding the right wrapper function.


Spectrum.BandsWidth property

Spectrum.BandsWidth property

Type | short for Visual C++ integer for Visual Basic
Syntax | object.Spectrum.BandsWidth (nPlayer as integer) [=Integer]
Remarks | Sets the width in pixel of each single band composing the Spectrum visual feedback for the given player.
See also | Spectrum COM object. Spectrum property How to use the embedded Visual Feedbacks section.


Spectrum.ColorBackground property

Spectrum.ColorBackground property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Spectrum.ColorBackground (nPlayer as integer) [=long]
Remarks | Sets the color of the Spectrum background for the given player.
See also | Spectrum COM object. Spectrum property How to use the embedded Visual Feedbacks section.


Spectrum.ColorBands property

Spectrum.ColorBands property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Spectrum.ColorBands (nPlayer as integer) [=long]
Remarks | Sets the spectrum "bands" color for the given player.
See also | Spectrum COM object. Spectrum property How to use the embedded Visual Feedbacks section.


Spectrum.ColorPeaks property

Spectrum.ColorPeaks property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Spectrum.ColorPeaks (nPlayer as integer) [=long]
Remarks | Sets the Spectrum "peaks" color for the given player.
See also | Spectrum COM object. Spectrum property How to use the embedded Visual Feedbacks section.


Spectrum.HasPeaks property

Spectrum.HasPeaks property

Type | short for Visual C++ enumBoolean for Visual Basic
Syntax | object.Spectrum.HasPeaks (nPlayer as integer) [=Integer]
Remarks | Determines, for the given player, if the embedded Spectrum visual feedback will display graphic "peaks" over the "bands".
See also | Spectrum COM object. Spectrum property How to use the embedded Visual Feedbacks section.


Spectrum.UseLogarithmic property

Spectrum.UseLogarithmic property

Type | short for Visual C++ enumBoolean for Visual Basic
Syntax | object.Spectrum.UseLogarithmic (nPlayer as integer) [=Integer]
Remarks | Specifies, for the given player, if the embedded Spectrum visual feedback, in order to determine bands height, will use logarithmic calculation (default) or if it will apply a normal FFT calculation.
See also | Spectrum COM object. Spectrum property How to use the embedded Visual Feedbacks section.


Spectrum.ZoomPerc property

Spectrum.ZoomPerc property

Type | short for Visual C++ integer for Visual Basic
Syntax | object.Spectrum.ZoomPerc (nPlayer as integer) [=integer]
Remarks | Sets the height zoom percentage of bands for the given player. By default set to 100%, can assume values in the range from 5% to 500%
See also | Spectrum COM object. Spectrum property How to use the embedded Visual Feedbacks section.


Spectrum.Create method

Spectrum.Create method

Remarks

Creates the Spectrum object: once created, the Spectrum will stay active until the termination of the container application: being a graphical object, the Spectrum needs to be associated to an existing window that will be used as a surface for the graphic rendering: this window can be changed at a later time through the Spectrum.SetHwnd method.

Once created, by default the Spectrum is still not visible: you must make a call to the Spectrum.Show method in order to display it.

Note that you can have a different Spectrum for each of the allocated players.

For further details about using the embedded Spectrum refer to the Spectrum object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Spectrum.Create (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Spectrum.Create (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Spectrum
hWndTarget | Handle of the window whose surface will be used in order to render the Spectrum graphics. If this parameter is set to NULL or 0, no graphical representation will be performed but you will have the opportunity to be notified about spectrum values change through the SpectrumValueChange event, allowing to render your custom spectrum graphics after calling the Spectrum.GetTable method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Spectrum.GetTable method

Spectrum.GetTable method

Remarks

Obtains the table of values related to each band of the spectrum: you can call this method each time you catch the SpectrumValueChange event.

For further details about using the embedded Spectrum refer to the Spectrum object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Spectrum.GetTable (

nPlayer as Integer,

tableValues as Integer,

nTableLength as Integer

) as enumErrorCodes

[C++]

short control.Spectrum.GetTable (

short nPlayer,

short *tableValues,

short nTableLength

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Spectrum
tableValues | Memory buffer that, on exit, will contain all of the available spectrum values: each value (2 bytes long) is in the range from 0 to 100.
nTableLength | Length of the table that needs to be obtained, expressed in number of values: the maximum number of values generated by the control is 64 and exceeding this limit would be useless.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


Spectrum.Resize method

Spectrum.Resize method

Remarks

Resizes the embedded Spectrum, useful when a resize of the hosting window occurs. This method has no effect without a previous call to the Spectrum.Create method.

For further details about using the embedded Spectrum refer to the Spectrum object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Spectrum.Resize (

nPlayer as Integer,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.Spectrum.Resize (

short nPlayer,

long nWidth,

long nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Spectrum
nWidth | New width of the Spectrum expressed in pixels
nHeight | New height of the Spectrum expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Spectrum.SetBackPictureFromFile method

Spectrum.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the embedded Spectrum refer to the Spectrum object section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Spectrum.SetBackPictureFromFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.Spectrum.SetBackPictureFromFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Spectrum
strPathname | Absolute pathname of the picture file to load. Accepted graphic formats are BMP, JPEG, GIF, TIFF and PNG. An empty pathname will reset an eventual picture set through a previous call to this method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Spectrum.SetBackPictureFromHandle method

Spectrum.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle (HBITMAP).

For further details about using the embedded Spectrum refer to the Spectrum object section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Spectrum.SetBackPictureFromHandle (

nPlayer as Integer,

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Spectrum.SetBackPictureFromHandle (

short nPlayer,

OLE_HANDLE hBitmap

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Spectrum
hBitmap | Handle of the bitmap to apply. If this parameter is set to 0 an eventual picture set through a previous call to this method will be reset.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Spectrum.SetHwnd method

Spectrum.SetHwnd method

Remarks

Changes the HWND of the window used as a surface for the graphic rendering.

For further details about using the embedded Spectrum refer to the Spectrum object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Spectrum.SetHwnd (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Spectrum.SetHwnd (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Spectrum
hWndTarget | Handle of the window whose surface will be used in order to render the Spectrum graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Spectrum.SetNumberOfBands method

Spectrum.SetNumberOfBands method

Remarks

Sets the number of bands used to display the spectrum: by default the spectrum will create 64 bands covering all of the needed frequencies; when number of bands is reduced, frequencies will be redistributed into available bands.

For further details about using the embedded Spectrum refer to the Spectrum object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Spectrum.SetNumberOfBands (

nPlayer as Integer,

nBands as Integer

) as enumErrorCodes

[C++]

short control.Spectrum.SetNumberOfBands (

short nPlayer,

short nBands

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Spectrum
nBands | Number of bands used to display the spectrum. Its value can range from 8 to 64 (default).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Spectrum.Show method

Spectrum.Show method

Remarks

Shows/hides the embedded Spectrum. This method has no effect without a previous call to the Spectrum.Create method.

For further details about using the embedded Spectrum refer to the Spectrum object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Spectrum.Show (

nPlayer as Integer,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.Spectrum.Show (

short nPlayer,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the Spectrum

bShow

Boolean value that specifies to the player if it must show/hide the Spectrum.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the Spectrum graphics
BOOL_TRUE | 1 | Shows the Spectrum graphics

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SpectrumEnh object

SpectrumEnh object

The SpectrumEnh object, accessible through the control's SpectrumEnh property, is internally implemented as a COM interface called ISpectrumEnhDJ and contains information needed to render the embedded Enhanced Spectrum Analyzer visual feedback.

It can be used at Run-time in order to create the embedded Enhanced Spectrum Analyzer and to change its graphic settings. For details about using Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

The SpectrumEnh object is implemented through the following methods:

Methods

Create

CreateNew

Move

SetBackPictureFromFile

SetBackPictureFromHandle

SetHwnd

Show

SettingsGeneralGet

SettingsGeneralSet

SettingsRulersGet

SettingsRulersSet

SettingsWaveGet

SettingsWaveSet


SpectrumEnh.Create method

SpectrumEnh.Create method

Remarks

Creates an instance of the enhanced spectrum analyzer for the given player on the full client area of the given parent window. The parent window can be changed at a later time through the SpectrumEnh.SetHwnd method.

In case you should need to create the enhanced spectrum analyzer on a specific initial position and with a specific initial size you may use the SpectrumEnh.CreateNew method.

Once created, by default the enhanced spectrum analyzer is still not visible: you must make a call to the SpectrumEnh.Show method in order to display it.

Note that you can have a different enhanced spectrum analyzer for each of the allocated players.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.Spectrum.Create (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Spectrum.Create (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
hWndTarget | Handle of the parent window that will contain the enhanced spectrum analyzer. This parameter cannot be set to NULL or 0.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SpectrumEnh.CreateNew method

SpectrumEnh.CreateNew method

Remarks

Creates an instance of the enhanced spectrum analyzer for the given player on a specific position of the client area of the given parent window. The parent window can be changed at a later time through the SpectrumEnh.SetHwnd method.

Once created, by default the enhanced spectrum analyzer is still not visible: you must make a call to the SpectrumEnh.Show method in order to display it.

Note that you can have a different enhanced spectrum analyzer for each of the allocated players.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.CreateNew (

nPlayer as Integer,

hWndTarget as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.SpectrumEnh.CreateNew (

short nPlayer,

OLE_HANDLE hWndTarget,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
hWndTarget | Handle of the parent window that will contain the enhanced spectrum analyzer. This parameter cannot be set to NULL or 0.
nLeft | Left position of the window, expressed in parent's client coordinates (pixels)
nTop | Top position of the window, expressed in parent's client coordinates (pixels)
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SpectrumEnh.Move method

SpectrumEnh.Move method

Remarks

Moves or resizes an enhanced spectrum analyzer.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.Move (

nPlayer as Integer,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.SpectrumEnh.Move (

short nPlayer,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
nLeft | Left position of the window, expressed in parent's client coordinates (pixels)
nTop | Top position of the window, expressed in parent's client coordinates (pixels)
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SpectrumEnh.SetBackPictureFromFile method

SpectrumEnh.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SetBackPictureFromFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SetBackPictureFromFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
strPathname | Absolute pathname of the picture file to load. Accepted graphic formats are BMP, JPEG, GIF, TIFF and PNG. An empty pathname will reset an eventual picture set through a previous call to this method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SpectrumEnh.SetBackPictureFromHandle method

SpectrumEnh.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle (HBITMAP).

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SetBackPictureFromHandle (

nPlayer as Integer,

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SetBackPictureFromHandle (

short nPlayer,

OLE_HANDLE hBitmap

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
hBitmap | Handle of the bitmap to apply. If this parameter is set to 0 an eventual picture set through a previous call to this method will be reset.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SpectrumEnh.SetHwnd method

SpectrumEnh.SetHwnd method

Remarks

Changes the HWND of the window used as a surface for the graphic rendering of the enhanced spectrum analyzer.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SetHwnd (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SetHwnd (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
hWndTarget | Handle of the window whose surface will be used in order to render the spectrum analyzer graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SpectrumEnh.Show method

SpectrumEnh.Show method

Remarks

Shows/hides the enhanced spectrum analyzer. This method has no effect without a previous call to the SpectrumEnh.Create method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.Show (

nPlayer as Integer,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.SpectrumEnh.Show (

short nPlayer,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the spectrum analyzer.

bShow

Boolean value that specifies to the player if it must show/hide the spectrum analyzer.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the spectrum analyzer graphics
BOOL_TRUE | 1 | Shows the spectrum analyzer graphics

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


SpectrumEnh.SettingsGeneralGet method

SpectrumEnh.SettingsGeneralGet method

Remarks

Retrieves the current general settings for the enhanced spectrum analyzer of the given player. Settings can be modified through the SpectrumEnh.SettingsGeneralSet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SettingsGeneralGet (

short nPlayer,

ByRef settings as Long

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SettingsGeneralGet (

short nPlayer,

void *settings

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
settings | Address of a structure of type SPECTR_ENH_GENERAL_SETTINGS that, on return from the method call, will contain the current general settings.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SpectrumEnh.SettingsGeneralSet method

SpectrumEnh.SettingsGeneralSet method

Remarks

Sets new general settings for the waveform analyzer. Current settings can be obtained through the SpectrumEnh.SettingsGeneralGet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SettingsGeneralSet (

short nPlayer,

ByRef settings as Long

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SettingsGeneralSet (

short nPlayer,

void *settings

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
settings | Address of a structure of type SPECTR_ENH_GENERAL_SETTINGS that contains the new general settings.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SpectrumEnh.SettingsRulersGet method

SpectrumEnh.SettingsRulersGet method

Remarks

Retrieves the current settings for the rulers of the enhanced spectrum analyzer of the given player. Settings can be modified through the SpectrumEnh.SettingsRulersSet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SettingsRulersGet (

short nPlayer,

ByRef settings as Long

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SettingsRulersGet (

short nPlayer,

void *settings

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
settings | Address of a structure of type SPECTR_ENH_RULERS_SETTINGS that, on return from the method call, will contain the current rulers settings.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SpectrumEnh.SettingsRulersSet method

SpectrumEnh.SettingsRulersSet method

Remarks

Sets new settings for the rulers of the spectrum analyzer. Current settings can be obtained through the SpectrumEnh.SettingsRulersGet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SettingsRulersSet (

short nPlayer,

ByRef settings as Long

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SettingsRulersSet (

short nPlayer,

void *settings

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
settings | Address of a structure of type SPECTR_ENH_RULERS_SETTINGS that contains the new rulers settings.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SpectrumEnh.SettingsWaveGet method

SpectrumEnh.SettingsWaveGet method

Remarks

Retrieves the current settings for the spectrum wave displayed on the enhanced spectrum analyzer of the given player. Settings can be modified through the SpectrumEnh.SettingsWaveSet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SettingsWaveGet (

short nPlayer,

ByRef settings as Long

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SettingsWaveGet (

short nPlayer,

void *settings

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
settings | Address of a structure of type SPECTR_ENH_WAVE_SETTINGS that, on return from the method call, will contain the current spectrum wave settings.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SpectrumEnh.SettingsWaveSet method

SpectrumEnh.SettingsWaveSet method

Remarks

Sets new settings for the spectrum wave displayed on the enhanced spectrum analyzer. Current settings can be obtained through the SpectrumEnh.SettingsWaveGet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other embedded Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

Syntax

[Visual Basic]

control.SpectrumEnh.SettingsWaveSet (

short nPlayer,

ByRef settings as Long

) as enumErrorCodes

[C++]

short control.SpectrumEnh.SettingsWaveSet (

short nPlayer,

void *settings

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the spectrum analyzer.
settings | Address of a structure of type SPECTR_ENH_WAVE_SETTINGS that contains the new spectrum wave settings.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SPECTR_ENH_GENERAL_SETTINGS structure

SPECTR_ENH_GENERAL_SETTINGS structure

The SPECTR_ENH_GENERAL_SETTINGS data structure describes the general graphical settings applied to a specific enhanced spectrum analyzer. The current settings can be obtained through the SpectrumEnh.SettingsGeneralGet method and modified through the SpectrumEnh.SettingsGeneralSet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

Visual C++ definition

typedef struct

{

 short     bAppearance3d;

 long       nResolution;

 long       nGraphType;

 long       nFFTWindowType;

 short     bFreqGridVisible;

 short     bDbGridVisible;

 short     bSubGridVisible;

 short     bBackBitmapVisible;

 short     bBackBitmapStretch;

 OLE_COLOR colorBackground;

 OLE_COLOR colorFreqGrid;

 OLE_COLOR colorDbGrid;

 OLE_COLOR colorSubGrid;

} SPECTR_ENH_GENERAL_SETTINGS;

Visual Basic definition

Public Type SPECTR_ENH_GENERAL_SETTINGS

bAppearance3d as Boolean

nResolution As Long

nGraphType As enumSpectrumEnhTypes

nFFTWindowType As enumSpectrumEnhWindowTypes

bFreqGridVisible as Boolean

bDbGridVisible as Boolean

bSubGridVisible as Boolean

bBackBitmapVisible as Boolean

bBackBitmapStretch as Boolean

colorBackground As OLE_COLOR

colorFreqGrid As OLE_COLOR

colorDbGrid As OLE_COLOR

colorSubGrid As OLE_COLOR

End Type

Member

Description

bAppearance3d

Boolean value that specifies if the spectrum analyzer is displayed with 3D borders.

Supported values are the following:

Value | Meaning
false | Doesn't display 3D borders
true (default) | Displays 3D borders

nResolution

Resolution in bytes of audio PCM data for FFT calculation (the value must be power of 2). Default is set to 2048 bytes.

nGraphType

Type of graphic representation.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
SPECTR_ENH_LINE_LEFT_TOP (default) | 0 | Line with left channel on top
SPECTR_ENH_LINE_RIGHT_TOP | 1 | Line with right channel on top
SPECTR_ENH_AREA_LEFT_TOP | 2 | Area with left channel on top
SPECTR_ENH_AREA_RIGHT_TOP | 3 | Area with right channel on top
SPECTR_ENH_BARS_LEFT_TOP | 4 | Bars with left channel on top
SPECTR_ENH_BARS_RIGHT_TOP | 5 | Bars with right channel on top
SPECTR_ENH_SPECTRAL_VIEW | 6 | Spectral view

nFFTWindowType

Type of window for FFT calculation.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
SPECTR_ENH_FFT_WINDOW_RECTANGULAR | 0 | Rectangular window
SPECTR_ENH_FFT_WINDOW_HAMMING | 1 | Hamming window
SPECTR_ENH_FFT_WINDOW_HANN | 2 | Hann window
SPECTR_ENH_FFT_WINDOW_COSINE | 3 | Cosine window
SPECTR_ENH_FFT_WINDOW_LANCZOS | 4 | Lanczos window
SPECTR_ENH_FFT_WINDOW_BARTLETT | 5 | Bartlett window
SPECTR_ENH_FFT_WINDOW_TRIANGULAR | 6 | Triangular window
SPECTR_ENH_FFT_WINDOW_GAUSS | 7 | Gauss window
SPECTR_ENH_FFT_WINDOW_BARTLETT_HANN | 8 | Bartlett-Hann window
SPECTR_ENH_FFT_WINDOW_BLACKMAN | 9 | Blackman window
SPECTR_ENH_FFT_WINDOW_NUTTALL | 10 | Nutall window
SPECTR_ENH_FFT_WINDOW_BLACKMAN_HARRIS (default) | 11 | Harris window
SPECTR_ENH_FFT_WINDOW_BLACKMAN_NUTTALL | 12 | Blackman-Nutall window
SPECTR_ENH_FFT_WINDOW_FLAT_TOP | 13 | Flat top window

bFreqGridVisible

Boolean value that specifies if the frequency grid is visible.

Supported values are the following:

Value | Meaning
false | Doesn't display the frequency grid
true (default) | Displays the frequency grid

bDbGridVisible

Boolean value that specifies if the decibels grid is visible.

Supported values are the following:

Value | Meaning
false | Doesn't display the decibels grid
true (default) | Displays the decibels grid

bSubGridVisible

Boolean value that specifies if sub-grids are visible.

Supported values are the following:

Value | Meaning
false | Doesn't display sub-grids
true (default) | Displays sub-grids

bBackBitmapVisible

Boolean value that specifies if an eventual background image (bitmap) is visible.

Supported values are the following:

Value | Meaning
false | Doesn't display the background image
true (default) | Displays the background image

bBackBitmapStretch

Boolean value that specifies if an eventual background image (bitmap) should be stretched to fit the spectrum analyzer background area.

Supported values are the following:

Value | Meaning
false (default) | Doesn't stretch the background image
true | Stretches the background image

colorBackground

The color used for rendering the background of the spectrum analyzer.

colorFreqGrid

The color used for rendering the frequency grid

colorDbGrid

The color used for rendering the decibels grid

colorSubGrid

The color used for rendering sub-grids

Below you can see a zoomed image of the enhanced spectrum analyzer evidencing some of the configurable elements:


SPECTR_ENH_RULERS_SETTINGS structure

SPECTR_ENH_RULERS_SETTINGS structure

The SPECTR_ENH_RULERS_SETTINGS data structure describes the settings applied to rulers of a specific enhanced spectrum analyzer. The current settings can be obtained through the SpectrumEnh.SettingsRulersGet method and modified through the SpectrumEnh.SettingsRulersSet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

Visual C++ definition

typedef struct

{

 short     bLinearScale;

 short     bScaleTopVisible;

 short     bScaleBottomVisible;

 short     bScaleLeftVisible;

 short     bScaleRightVisible;

 OLE_COLOR colorBackground;

 OLE_COLOR colorTicks;

 OLE_COLOR colorText;

} SPECTR_ENH_RULERS_SETTINGS;

Visual Basic definition

Public Type SPECTR_ENH_RULERS_SETTINGS

bLinearScale as Boolean

bScaleTopVisible as Boolean

bScaleBottomVisible as Boolean

bScaleLeftVisible as Boolean

bScaleRightVisible as Boolean

colorBackground As OLE_COLOR

colorTicks As OLE_COLOR

colorText As OLE_COLOR

End Type

Member

Description

bLinearScale

Boolean value that specifies if the frequency ruler should display a linear or logarithmic scale.

Supported values are the following:

Value | Meaning
false (default) | Displays logarithmic scale
true | Displays linear scale

bScaleTopVisible

Boolean value that specifies if the frequency ruler on the top should be visible.

Supported values are the following:

Value | Meaning
false | Doesn't display the frequency top ruler
true (default) | Displays the frequency top ruler

bScaleBottomVisible

Boolean value that specifies if the frequency ruler on the bottom should be visible.

Supported values are the following:

Value | Meaning
false | Doesn't display the frequency bottom ruler
true (default) | Displays the frequency bottom ruler

bScaleLeftVisible

Boolean value that specifies if the decibels ruler on the left side should be visible.

Supported values are the following:

Value | Meaning
false | Doesn't display the decibels left ruler
true (default) | Displays the decibels left ruler

bScaleRightVisible

Boolean value that specifies if the decibels ruler on the right side should be visible.

Supported values are the following:

Value | Meaning
false (default) | Doesn't display the decibels right ruler
true | Displays the decibels right ruler

colorBackground

The color used for rendering the rulers background.

colorTicks

The color used for rendering rulers ticks

colorText

The color used for rendering rulers text

Below you can see an image of the enhanced spectrum analyzer evidencing some of the configurable elements:


SPECTR_ENH_WAVE_SETTINGS structure

SPECTR_ENH_WAVE_SETTINGS structure

The SPECTR_ENH_WAVE_SETTINGS data structure describes the graphical settings applied to the spectrum wave displayed on the spectrum analyzer. The current settings can be obtained through the SpectrumEnh.SettingsWaveGet method and modified through the SpectrumEnh.SettingsWaveSet method.

For further details about using the Enhanced Spectrum Analyzer refer to the SpectrumEnh section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

Visual C++ definition

typedef struct

{

 short     nAreaTransparency;

 short     bClearSpectralViewOnEnd;

 OLE_COLOR colorLineTopLeftChan;

 OLE_COLOR colorLineTopRightChan;

 OLE_COLOR colorLineCoveredLeftChan;

 OLE_COLOR colorLineCoveredRightChan;

 OLE_COLOR colorAreaLeftChan;

 OLE_COLOR colorAreaRightChan;

 OLE_COLOR colorAreaCoveredLeftChan;

 OLE_COLOR colorAreaCoveredRightChan;

 OLE_COLOR colorVertLineSpectralView;

} SPECTR_ENH_WAVE_SETTINGS;

Visual Basic definition

Public Type SPECTR_ENH_WAVE_SETTINGS

nAreaTransparency As Integer

bClearSpectralViewOnEnd as Boolean

colorLineTopLeftChan As OLE_COLOR

colorLineTopRightChan As OLE_COLOR

colorLineCoveredLeftChan As OLE_COLOR

colorLineCoveredRightChan As OLE_COLOR

colorAreaLeftChan As OLE_COLOR

colorAreaRightChan As OLE_COLOR

colorAreaCoveredLeftChan As OLE_COLOR

colorAreaCoveredRightChan As OLE_COLOR

colorVertLineSpectralView As OLE_COLOR

End Type

Member

Description

nAreaTransparency

Numerical value representing the transparency applied to area colors: can be in the range from 0 to 100 where 0 means solid (no transparency) while 100 means totally transparent. The default value is 25.

bClearSpectralViewOnEnd

Boolean value that specifies if the spectral view must be cleared when the end of the spectrum analyzer's display is reached.

Supported values are the following:

Value | Meaning
false (default) | Doesn't clear the display. In the image below you can see the vertical line of the spectral view in grey
true | Clears the display.

colorLineTopLeftChan

The color used for rendering the top line of left channel

colorLineTopRightChan

The color used for rendering the top line of right channel

colorLineCoveredLeftChan

The color used for rendering the top line of left channel when covered by the area of the right channel

colorLineCoveredRightChan

The color used for rendering the top line of right channel when covered by the area of the left channel

colorAreaLeftChan

The color used for rendering the area of left channel

colorAreaRightChan

The color used for rendering the area of right channel

colorAreaCoveredLeftChan

The color used for rendering the area of left channel when covered by the area of the right channel

colorAreaCoveredRightChan

The color used for rendering the area of right channel when covered by the area of the left channel

colorVertLineSpectralView

The color used for rendering the vertical line of the spectral view.

In the image below you can see the vertical line of the spectral view in grey

Below you can see an image of the enhanced spectrum analyzer evidencing some of the configurable elements:

In the image above the left channel, which is represented on top respect to the right channel, is rendered through the cyan line and through the blue area while the left channel, partially covered by the left channel, is rendered through the red line and through the darker red area; the portion of right channel area covered by the left channel's area is rendered in violet.

As you can see, frequency and dB grids are still partially visible also when covered by channels areas: this is obtained by rending areas in transparency through the setting of the nAreaTransparency field: in this case the value was set to 25.


TagsReader object

TagsReader object

The TagsReader object, accessible through the control's TagsReader property, is internally implemented as a COM interface called ITagsReader and contains methods needed to manage meta tags information stored in sound files of various audio formats.

The TagsReader object is implemented through a set of methods covering various tagging formats: APE, FLAC, ID3V1, ID3V2, LYRICS3, MP4, OGG Vorbis, WAV and WMA.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Methods

ALL_AnalyzeSoundOnPlayer

ALL_AnalyzeSoundFile

ALL_CommonFrameGet

APE_TextFieldGet

APE_UniqueFramesCountGet

APE_UniqueFramesIdGet

APE_UserFieldGet

FLAC_PictureFrameBitmapGet

FLAC_PictureFrameCountGet

FLAC_PictureFrameFileGet

FLAC_PictureFrameInfoGet

FLAC_PictureFrameMemoryFileGet

FLAC_PictureFrameSizeGet

FLAC_PictureFrameTypeGet

FLAC_TextFrameGet

FLAC_UniqueFramesCountGet

FLAC_UniqueFramesIdGet

ID3V1_FieldGet

ID3V2_CommentFrameGet

ID3V2_CommentFrameInfoGet

ID3V2_CommercialFrameInfoGet

ID3V2_CommercialFramePictureBitmapGet

ID3V2_CommercialFramePictureFileGet

ID3V2_CommercialFramePictureMemoryFileGet

ID3V2_CommercialFrameReceivedAsGet

ID3V2_CommercialFramePictureSizeGet

ID3V2_EventTimingsFrameEventCountGet

ID3V2_EventTimingsFrameEventInfoGet

ID3V2_FrameCountGet

ID3V2_GeneralObjectFrameFileGet

ID3V2_GeneralObjectFrameInfoGet

ID3V2_GeneralObjectFrameMemoryFileGet

ID3V2_GeneralObjectFrameSizeGet

ID3V2_MusicCdIdentifierFrameGet

ID3V2_MusicCdIdentifierFrameSizeGet

ID3V2_OwnershipFrameInfoGet

ID3V2_PictureFrameBitmapGet

ID3V2_PictureFrameFileGet

ID3V2_PictureFrameInfoGet

ID3V2_PictureFrameMemoryFileGet

ID3V2_PictureFrameSizeGet

ID3V2_PictureFrameTypeGet

ID3V2_PlayCounterFrameCountGet

ID3V2_PopularimeterFrameCounterGet

ID3V2_PopularimeterFrameEmailGet

ID3V2_PopularimeterFrameRatingGet

ID3V2_PrivateFrameFileGet

ID3V2_PrivateFrameMemoryFileGet

ID3V2_PrivateFrameOwnerGet

ID3V2_PrivateFrameSizeGet

ID3V2_SynchLyricsFrameGet

ID3V2_SynchLyricsFrameInfoGet

ID3V2_SynchLyricsFrameInfoNumGet

ID3V2_TermsOfUseFrameGet

ID3V2_TermsOfUseFrameLanguageGet

ID3V2_TextFrameGet

ID3V2_UniqueFramesCountGet

ID3V2_UniqueFramesIdGet

ID3V2_UnsynchLyricsFrameGet

ID3V2_UnsynchLyricsFrameInfoGet

ID3V2_URLFrameGet

ID3V2_UserTextFrameDescriptionGet

ID3V2_UserTextFrameGet

ID3V2_UserURLFrameDescriptionGet

ID3V2_UserURLFrameGet

LYRICS3_ImageLinkGet

LYRICS3_LyricsGet

LYRICS3_TextFieldGet

MP4_PictureFrameBitmapGet

MP4_PictureFrameCountGet

MP4_PictureFrameFileGet

MP4_PictureFrameMemoryFileGet

MP4_PictureFrameMimeGet

MP4_PictureFrameSizeGet

MP4_TextFrameGet

MP4_UniqueFramesCountGet

MP4_UniqueFramesIdGet

OGG_TextFrameGet

OGG_UniqueFramesCountGet

OGG_UniqueFramesIdGet

OGG_UserFrameGet

WAV_BextChunkBinaryFieldGet

WAV_BextChunkTextFieldGet

WAV_CartChunkTextFieldGet

WAV_CartChunkTimeMarkerFieldGet

WAV_DisplayChunkTextGet

WAV_ListInfoChunkFrameGet

WAV_ListInfoChunkUniqueFramesCountGet

WAV_ListInfoChunkUniqueFramesIdGet

WMA_PictureFrameBitmapGet

WMA_PictureFrameCountGet

WMA_PictureFrameFileGet

WMA_PictureFrameMemoryFileGet

WMA_PictureFrameInfoGet

WMA_PictureFrameSizeGet

WMA_PictureFrameTypeGet

WMA_TextFrameGet

WMA_UniqueFramesCountGet

WMA_UniqueFramesIdGet

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Samples of usage of tags reading in Visual C++ and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- TagsReader


TagsReader.ALL_AnalyzeSoundOnPlayer method

TagsReader.ALL_AnalyzeSoundOnPlayer method

Remarks

Analyzes the sound currently loaded inside the given player and, if any, determines the type of embedded tag(s) info.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ALL_AnalyzeSoundOnPlayer (

nPlayer as Integer

) as enumTagAvailable

[C++]

short control.TagsReader.ALL_AnalyzeSoundOnPlayer (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player.

Return value

Value

Meaning

Negative value

An error occurred (see the LastError property for further error details)

Other values

The combination of flags indicating which tags were detected inside the file under editing. Certain audio formats may contain more than one tag format; for example MP3 files may contain, inside the same file, tags in ID3V2, ID3V1 and LYRICS3 formats while WAV files may contain, inside the same file, CART and BEXT chunks.

The returned value can be a combination of the following flags:

Mnemonic Value | Decimal value | Hexadecimal value | Meaning
TAG_FLAG_NONE | 0 | 0000 | No tag detected or unknown format
TAG_FLAG_ID3V1 | 1 | 0001 | ID3V1 tag is available
TAG_FLAG_ID3V2 | 2 | 0002 | ID3V2 tag is available
TAG_FLAG_LYRICS3 | 4 | 0004 | Lyrics3 tag is available
TAG_FLAG_OGG | 8 | 0008 | OGG Vorbis tag is available
TAG_FLAG_WMA | 16 | 0010 | Windows Media Audio tag is available
TAG_FLAG_MP4 | 32 | 0020 | MP4 tag is available
TAG_FLAG_APE | 64 | 0040 | APE tag is available
TAG_FLAG_WAV_CART | 128 | 0080 | WAV Cart chunk is available
TAG_FLAG_FLAC | 256 | 0100 | FLAC tag is available
TAG_FLAG_WAV_BEXT | 512 | 0200 | WAV Bext chunk is available
TAG_FLAG_WAV_LIST_INFO | 1024 | 0400 | WAV LIST INFO chunk is available
TAG_FLAG_WAV_DISP | 2048 | 0800 | WAV DISP chunk is available


TagsReader.ALL_AnalyzeSoundFile method

TagsReader.ALL_AnalyzeSoundFile method

Remarks

Analyzes a given sound file and, if any, determines the type of embedded tag(s) info.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ALL_AnalyzeSoundFile (

strPathname as String

) as enumTagAvailable

[C++]

short control.TagsReader.ALL_AnalyzeSoundFile (

string strPathname

);

Parameter | Description
strPathname | String representing the absolute pathname of the sound file to analyze for tags detection.

Return value

Value

Meaning

Negative value

An error occurred (see the LastError property for further error details)

Other values

The combination of flags indicating which tags were detected inside the file under editing. Certain audio formats may contain more than one tag format; for example MP3 files may contain, inside the same file, tags in ID3V2, ID3V1 and LYRICS3 formats while WAV files may contain, inside the same file, CART and BEXT chunks.

The returned value can be a combination of the following flags:

Mnemonic Value | Decimal value | Hexadecimal value | Meaning
TAG_FLAG_NONE | 0 | 0000 | No tag detected or unknown format
TAG_FLAG_ID3V1 | 1 | 0001 | ID3V1 tag is available
TAG_FLAG_ID3V2 | 2 | 0002 | ID3V2 tag is available
TAG_FLAG_LYRICS3 | 4 | 0004 | Lyrics3 tag is available
TAG_FLAG_OGG | 8 | 0008 | OGG Vorbis tag is available
TAG_FLAG_WMA | 16 | 0010 | Windows Media Audio tag is available
TAG_FLAG_MP4 | 32 | 0020 | MP4 tag is available
TAG_FLAG_APE | 64 | 0040 | APE tag is available
TAG_FLAG_WAV_CART | 128 | 0080 | WAV Cart chunk is available
TAG_FLAG_FLAC | 256 | 0100 | FLAC tag is available
TAG_FLAG_WAV_BEXT | 512 | 0200 | WAV Bext chunk is available
TAG_FLAG_WAV_LIST_INFO | 1024 | 0400 | WAV LIST INFO chunk is available
TAG_FLAG_WAV_DISP | 2048 | 0800 | WAV DISP chunk is available


TagsReader.ALL_CommonFrameGet method

TagsReader.ALL_CommonFrameGet method

Remarks

Obtains the contents of a tag field common to most of the tags format.

This method can work with both sound files loaded from memory or from the HDU.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ALL_CommonFrameGet (

nField as enumTagFields

) as String

[C++]

BSTR control.TagsReader.ALL_CommonFrameGet (

short nField

);

Parameter

Description

nField

Identifier of the tag field to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
TAG_FIELD_TITLE | 0 | Title
TAG_FIELD_ARTIST | 1 | Artist
TAG_FIELD_ALBUM | 2 | Album
TAG_FIELD_YEAR | 3 | Year
TAG_FIELD_COMMENT | 4 | Comment
TAG_FIELD_TRACK | 5 | Track number
TAG_FIELD_GENRE_CODE | 6 | Genre code for ID3
TAG_FIELD_GENRE_STRING | 7 | Genre string
TAG_FIELD_COMPOSER | 8 | Composer
TAG_FIELD_COPYRIGHT | 9 | Copyright
TAG_FIELD_SUBTITLE | 10 | Subtitle
TAG_FIELD_ALBUMARTIST | 11 | Album artist

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested field


TagsReader.APE_TextFieldGet method

TagsReader.APE_TextFieldGet method

Remarks

Obtains contents of a specific text-based frame of the APE tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.APE_TextFieldGet (

nField as enumTagFields

) as String

[C++]

BSTR control.TagsReader.APE_TextFieldGet (

short nField

);

Parameter

Description

nField

Identifier of the tag field to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
TAG_FIELD_TITLE | 0 | Title
TAG_FIELD_ARTIST | 1 | Artist
TAG_FIELD_ALBUM | 2 | Album
TAG_FIELD_YEAR | 3 | Year
TAG_FIELD_COMMENT | 4 | Comment
TAG_FIELD_TRACK | 5 | Track number
TAG_FIELD_GENRE_CODE | 6 | Genre code for ID3
TAG_FIELD_GENRE_STRING | 7 | Genre string
TAG_FIELD_COPYRIGHT | 9 | Copyright

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.APE_UniqueFramesCountGet method

TagsReader.APE_UniqueFramesCountGet method

Remarks

Obtains the number of unique frames found inside the APE tag. The identifier of each unique frame can be obtained through the TagsReader.APE_UniqueFramesIdGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.APE_UniqueFramesCountGet (

) as Integer

[C++]

short control.TagsReader.APE_UniqueFramesCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of unique frames found inside the APE tag


TagsReader.APE_UniqueFramesIdGet method

TagsReader.APE_UniqueFramesIdGet method

Remarks

Obtains a unique frame identifier between the list of unique frames enumerated inside the APE tag through a previous call to the TagsReader.APE_UniqueFramesCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.APE_UniqueFramesIdGet (

nFrameIndex as Integer

) as String

[C++]

BSTR control.TagsReader.APE_UniqueFramesIdGet (

short nFrameIndex

);

Parameter | Description
nFrameIndex | Zero-based index of the frame.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the unique frame identifier


TagsReader.APE_UserFieldGet method

TagsReader.APE_UserFieldGet method

Remarks

Obtains contents of a specific user-defined frame of the APE tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.APE_UserFieldGet (

strFrameId as String

) as String

[C++]

BSTR control.TagsReader.APE_UserFieldGet (

BSTR strFrameId

);

Parameter | Description
strFrameId | String containing the identifier of the specific user-defined frame to get. You can know which frames are available inside the APE tag by using the combination of the TagsReader.APE_UniqueFramesCountGet and TagsReader.APE_UniqueFramesIdGet methods.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.FLAC_PictureFrameBitmapGet method

TagsReader.FLAC_PictureFrameBitmapGet method

Remarks

Obtains the memory bitmap (HBITMAP) representation of the picture stored inside a FLAC picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_PictureFrameBitmapGet (

nIndex as Integer,

hBitmap as OLE_HANDLE,

nOriginalWidth as Long,

nOriginalHeight as Long,

nResizeWidth as Long,

nResizeHeight as Long

) as enumErrorCodes

[C++]

short control.TagsReader.FLAC_PictureFrameBitmapGet (

short nIndex,

OLE_HANDLE *hBitmap,

long *nOriginalWidth,

long *nOriginalHeight,

long nResizeWidth,

long nResizeHeight

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the FLAC tag can be obtained through a call to the TagsReader.FLAC_PictureFrameCountGet method.
hBitmap | Reference that, on return from the method call, will contain the HBITMAP of the picture.
nOriginalWidth | Reference that, on return from the method call, will contain the original width, expressed in pixels, of the picture.
nOriginalHeight | Reference that, on return from the method call, will contain the original height, expressed in pixels, of the picture.
nResizeWidth | Value containing the width, expressed in pixels, for horizontally resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same width returned inside the nOriginalWidth parameter.
nResizeHeight | Value containing the height, expressed in pixels, for vertically resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same height returned inside the nOriginalHeight parameter.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.FLAC_PictureFrameCountGet method

TagsReader.FLAC_PictureFrameCountGet method

Remarks

Obtains the number of picture frames available inside the FLAC tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_PictureFrameCountGet (

) as Integer

[C++]

short control.TagsReader.FLAC_PictureFrameCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of picture frames available inside the FLAC tag


TagsReader.FLAC_PictureFrameFileGet method

TagsReader.FLAC_PictureFrameFileGet method

Remarks

Creates a graphic file, of a given graphic format, containing the picture stored inside a FLAC picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_PictureFrameFileGet (

nIndex as Integer,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Long

) as enumErrorCodes

[C++]

short control.TagsReader.FLAC_PictureFrameFileGet (

short nIndex,

BSTR strPathname,

short nFormat,

long nFormatParameter

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the FLAC tag can be obtained through a call to the TagsReader.FLAC_PictureFrameCountGet method.

strPathname

String representing the absolute pathname of the output graphic file.

nFormat

Graphic format of the output graphic file.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_ORIGINAL | -1 | Original format used to store the picture inside the tag. When this option is selected, the output graphic file will be an exact copy of the contents of the picture frame. You can determine the original graphic format, through its MIME type, by calling the TagsReader.FLAC_PictureFrameInfoGet method with the parameter nInfo set to ID3V2_FRAME_INFO_MIME_TYPE; this information can be also useful to determine the file extension to use when composing the strPathname parameter above.
GRAPHIC_FORMAT_BMP | 0 | The output file will be converted to BMP format
GRAPHIC_FORMAT_JPEG | 1 | The output file will be converted to JPEG format
GRAPHIC_FORMAT_PNG | 2 | The output file will be converted to PNG format
GRAPHIC_FORMAT_GIF | 3 | The output file will be converted to GIF format
GRAPHIC_FORMAT_TIFF | 4 | The output file will be converted to TIFF format

nFormatParameter

Eventual parameter required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.FLAC_PictureFrameInfoGet method

TagsReader.FLAC_PictureFrameInfoGet method

Remarks

Obtains textual information about the given FLAC picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_PictureFrameInfoGet (

nIndex as Integer,

nInfo as enumId3v2FrameInfo

) as String

[C++]

BSTR control.TagsReader.FLAC_PictureFrameInfoGet (

short nIndex,

short nInfo

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the FLAC tag can be obtained through a call to the TagsReader.FLAC_PictureFrameCountGet method.

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_FRAME_INFO_DESCRIPTION | 1 | Description
ID3V2_FRAME_INFO_CONTENT_TYPE_TEXT | 3 | Content type textual description
ID3V2_FRAME_INFO_MIME_TYPE | 4 | Mime type

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.FLAC_PictureFrameMemoryFileGet method

TagsReader.FLAC_PictureFrameMemoryFileGet method

Remarks

Obtains a copy in memory of the picture file stored inside a FLAC picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_PictureFrameMemoryFileGet (

nIndex as Integer,

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.FLAC_PictureFrameMemoryFileGet (

short nIndex,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the FLAC tag can be obtained through a call to the TagsReader.FLAC_PictureFrameCountGet method.
pBuffer | Output buffer that, on return from the method call, will contain the picture file data
nBufferLength | Length of the buffer expressed in bytes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.

Below you can find a couple of samples that demonstrate how to retrieve a picture and store it inside a memory buffer in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub Command1_Click()

' obtain the size in bytes of the first available picture (having index 0)

Dim nSizeInBytes As Long

ActiveSoundEditor1.TagsReader.FLAC_PictureFrameSizeGet 0, nSizeInBytes

if nSizeInBytes = 0 then Exit Sub

' allocate the destination buffer

Dim bytImage() As Byte

ReDim bytImage(nSizeInBytes)

' read picture data into the buffer

ActiveSoundEditor1.TagsReader.FLAC_PictureFrameMemoryFileGet 0, VarPtr(bytImage(0)), nSizeInBytes

...

use the buffer

...

' erase the buffer and free memory

Erase bytImage

End Sub

Visual C++ 6 with MFC

void CReadId3v2Dlg::OnButton1()

{

long nSizeInBytes = 0;

m_editor.TagsReader.FLAC_PictureFrameSizeGet (0, &nSizeInBytes);

if (nSizeInBytes == 0)

   return;

BYTE *pBuffer = new BYTE[nTagSize];

COleVariant var;

var.vt = VT_BYREF | VT_UI1;

var.pbVal = pTagBuffer;

m_editor.TagsReader.FLAC_PictureFrameMemoryFileGet (0, var, nSizeInBytes);

...

use the buffer

...

delete pBuffer;

}


TagsReader.FLAC_PictureFrameSizeGet method

TagsReader.FLAC_PictureFrameSizeGet method

Remarks

Obtains the size of the picture stored inside a FLAC picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_PictureFrameSizeGet (

nIndex as Integer,

nSize as Long

) as enumErrorCodes

[C++]

short control.TagsReader.FLAC_PictureFrameSizeGet (

short nIndex,

long *nSize

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the FLAC tag can be obtained through a call to the TagsReader.FLAC_PictureFrameCountGet method.
nSize | Reference that, on return from the method call, will contain the size in bytes of the picture stored inside the frame.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.FLAC_PictureFrameTypeGet method

TagsReader.FLAC_PictureFrameTypeGet method

Remarks

Obtains the type of picture stored inside a FLAC picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_PictureFrameTypeGet (

nIndex as Integer,

nPictureType as enumId3v2PictureType

) as enumErrorCodes

[C++]

short control.TagsReader.FLAC_PictureFrameTypeGet (

short nIndex,

short *nPictureType

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the FLAC tag can be obtained through a call to the TagsReader.FLAC_PictureFrameCountGet method.

nPictureType

Reference that, on return from the method call, will contain the type of picture stored inside the frame.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_PICTURE_OTHER | 0 | Other
ID3V2_PICTURE_ICON_32x32 | 1 | 32x32 icon
ID3V2_PICTURE_ICON_OTHER | 2 | Other icon
ID3V2_PICTURE_COVER_FRONT | 3 | Front cover
ID3V2_PICTURE_COVER_BACK | 4 | Back cover
ID3V2_PICTURE_LEAFLET_PAGE | 5 | Leaflet page
ID3V2_PICTURE_MEDIA | 6 | Media (e.g. label side of CD)
ID3V2_PICTURE_LEAD_ARTIST_PERFORMER_SOLOIST | 7 | Lead artist/lead performer/soloist
ID3V2_PICTURE_ARTIST_PERFORMER | 8 | Artist/performer
ID3V2_PICTURE_CONDUCTOR | 9 | Conductor
ID3V2_PICTURE_BAND_ORCHESTRA | 10 | Band/Orchestra
ID3V2_PICTURE_COMPOSER | 11 | Composer
ID3V2_PICTURE_LYRICIST_TEXT_WRITER | 12 | Lyricist/text writer
ID3V2_PICTURE_RECORDING_LOCATION | 13 | Recording Location
ID3V2_PICTURE_DURING_RECORDING | 14 | During recording
ID3V2_PICTURE_DURING_PERFORMANCE | 15 | During performance
ID3V2_PICTURE_MOVIE_VIDEO_SCREEN_CAPTURE | 16 | Movie/video screen capture
ID3V2_PICTURE_BRIGHT_FISH | 17 | A bright coloured fish
ID3V2_PICTURE_ILLUSTRATION | 18 | Illustration
ID3V2_PICTURE_BAND_ARTIST_LOGO | 19 | Band/artist logotype
ID3V2_PICTURE_PUBLISHER_STUDIO_LOGO | 20 | Publisher/Studio logotype

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.FLAC_TextFrameGet method

TagsReader.FLAC_TextFrameGet method

Remarks

Obtains contents of a specific text-based frame of the FLAC tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_TextFrameGet (

strFrameId as String

) as String

[C++]

BSTR control.TagsReader.FLAC_TextFrameGet (

BSTR strFrameId

);

Parameter | Description
strFrameId | String containing the identifier of the specific user-defined frame to set. You can know which frames are available inside the FLAC tag by using the combination of the TagsReader.FLAC_UniqueFramesCountGet and TagsReader.FLAC_UniqueFramesIdGet methods.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.FLAC_UniqueFramesCountGet method

TagsReader.FLAC_UniqueFramesCountGet method

Remarks

Obtains the number of unique frames found inside the FLAC tag. The identifier of each unique frame can be obtained through the TagsReader.FLAC_UniqueFramesIdGet method.

Multiple instances of the picture frame can be available inside the same FLAC tag: when this method is called, the enumeration will not keep count of multiple instances of a specific frame but will only report the availability of the frame itself; once the availability of a specific frame is known, single specific picture frames can be enumerated using the TagsReader.FLAC_PictureFrameCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_UniqueFramesCountGet (

) as Integer

[C++]

short control.TagsReader.FLAC_UniqueFramesCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of unique frames found inside the FLAC tag


TagsReader.FLAC_UniqueFramesIdGet method

TagsReader.FLAC_UniqueFramesIdGet method

Remarks

Obtains a unique frame identifier between the list of unique frames enumerated inside the FLAC tag through a previous call to the TagsReader.FLAC_UniqueFramesCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.FLAC_UniqueFramesIdGet (

nFrameIndex as Integer

) as String

[C++]

BSTR control.TagsReader.FLAC_UniqueFramesIdGet (

short nFrameIndex

);

Parameter | Description
nFrameIndex | Zero-based index of the frame.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the unique frame identifier


TagsReader.ID3V1_FieldGet method

TagsReader.ID3V1_FieldGet method

Remarks

Obtains a field of the ID3V1 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V1_FieldGet (

nField as enumTagFields

) as String

[C++]

BSTR control.TagsReader.ID3V1_FieldGet (

short nField

);

Parameter

Description

nField

Identifier of the tag field to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
TAG_FIELD_TITLE | 0 | Title
TAG_FIELD_ARTIST | 1 | Artist
TAG_FIELD_ALBUM | 2 | Album
TAG_FIELD_YEAR | 3 | Year
TAG_FIELD_COMMENT | 4 | Comment
TAG_FIELD_TRACK | 5 | Track number
TAG_FIELD_GENRE_CODE | 6 | Genre code for ID3
TAG_FIELD_GENRE_STRING | 7 | Genre string

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested field


TagsReader.ID3V2_CommentFrameGet method

TagsReader.ID3V2_CommentFrameGet method

Remarks

Obtains the text of the given ID3V2 comment frame (COMM).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_CommentFrameGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_CommentFrameGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the comment frame. The total number of comment frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "COMM".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_CommentFrameInfoGet method

TagsReader.ID3V2_CommentFrameInfoGet method

Remarks

Obtains textual information about the given ID3V2 comment frame (COMM).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_CommentFrameInfoGet (

nIndex as Integer,

nInfo as enumId3v2FrameInfo

) as String

[C++]

BSTR control.TagsReader.ID3V2_CommentFrameInfoGet (

short nIndex,

short nInfo

);

Parameter

Description

nIndex

Zero-based index of the comment frame. The total number of comment frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "COMM".

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_FRAME_INFO_LANGUAGE | 0 | Language
ID3V2_FRAME_INFO_DESCRIPTION | 1 | Description

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_CommercialFrameInfoGet method

TagsReader.ID3V2_CommercialFrameInfoGet method

Remarks

Obtains textual information about the given ID3V2 commercial frame (COMR).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_CommercialFrameInfoGet (

nIndex as Integer,

nInfo as enumId3v2CommercialInfo

) as String

[C++]

BSTR control.TagsReader.ID3V2_CommercialFrameInfoGet (

short nIndex,

short nInfo

);

Parameter

Description

nIndex

Zero-based index of the commercial frame. The total number of commercial frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "COMR".

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_COMMERCIAL_INFO_PRICE | 0 | Price
ID3V2_COMMERCIAL_INFO_VALID_UNTIL | 1 | Valid until
ID3V2_COMMERCIAL_INFO_CONTACT_URL | 2 | Contact URL
ID3V2_COMMERCIAL_INFO_SELLER | 3 | Seller
ID3V2_COMMERCIAL_INFO_DESCRIPTION | 4 | Description
ID3V2_COMMERCIAL_INFO_PICTURE_MIME_TYPE | 5 | Picture mime type
ID3V2_COMMERCIAL_INFO_RECEIVED_AS_TEXT | 6 | Received As text

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_CommercialFramePictureBitmapGet method

TagsReader.ID3V2_CommercialFramePictureBitmapGet method

Remarks

Obtains the memory bitmap (HBITMAP) representation of the picture stored inside an ID3V2 commercial frame (COMR).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_CommercialFramePictureBitmapGet (

nIndex as Integer,

hBitmap as OLE_HANDLE,

nOriginalWidth as Long,

nOriginalHeight as Long,

nResizeWidth as Long,

nResizeHeight as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_CommercialFramePictureBitmapGet (

short nIndex,

OLE_HANDLE *hBitmap,

long *nOriginalWidth,

long *nOriginalHeight,

long nResizeWidth,

long nResizeHeight

);

Parameter | Description
nIndex | Zero-based index of the commercial frame. The total number of commercial frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "COMR".
hBitmap | Reference that, on return from the method call, will contain the HBITMAP of the picture.
nOriginalWidth | Reference that, on return from the method call, will contain the original width, expressed in pixels, of the picture.
nOriginalHeight | Reference that, on return from the method call, will contain the original height, expressed in pixels, of the picture.
nResizeWidth | Value containing the width, expressed in pixels, for horizontally resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same width returned inside the nOriginalWidth parameter.
nResizeHeight | Value containing the height, expressed in pixels, for vertically resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same height returned inside the nOriginalHeight parameter.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_CommercialFramePictureFileGet method

TagsReader.ID3V2_CommercialFramePictureFileGet method

Remarks

Creates a graphic file, of a given graphic format, containing the picture stored inside an ID3V2 commercial frame (COMR).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_CommercialFramePictureFileGet (

nIndex as Integer,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_CommercialFramePictureFileGet (

short nIndex,

BSTR strPathname,

short nFormat,

long nFormatParameter

);

Parameter

Description

nIndex

Zero-based index of the commercial frame. The total number of commercial frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "COMR".

strPathname

String representing the absolute pathname of the output graphic file.

nFormat

Graphic format of the output graphic file.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_ORIGINAL | -1 | Original format used to store the picture inside the tag. When this option is selected, the output graphic file will be an exact copy of the contents of the picture frame. You can determine the original graphic format, through its MIME type, by calling the TagsReader.ID3V2_PictureFrameInfoGet method with the parameter nInfo set to ID3V2_FRAME_INFO_MIME_TYPE; this information can be also useful to determine the file extension to use when composing the strPathname parameter above.
GRAPHIC_FORMAT_BMP | 0 | The output file will be converted to BMP format
GRAPHIC_FORMAT_JPEG | 1 | The output file will be converted to JPEG format
GRAPHIC_FORMAT_PNG | 2 | The output file will be converted to PNG format
GRAPHIC_FORMAT_GIF | 3 | The output file will be converted to GIF format
GRAPHIC_FORMAT_TIFF | 4 | The output file will be converted to TIFF format

nFormatParameter

Eventual parameter required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_CommercialFramePictureMemoryFileGet method

TagsReader.ID3V2_CommercialFramePictureMemoryFileGet method

Remarks

Obtains a copy in memory of the picture file stored inside an ID3V2 commercial frame (COMR).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_CommercialFramePictureMemoryFileGet (

nIndex as Integer,

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_CommercialFramePictureMemoryFileGet (

short nIndex,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nIndex | Zero-based index of the commercial frame. The total number of commercial frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "COMR".
pBuffer | Output buffer that, on return from the method call, will contain the picture file data
nBufferLength | Length of the buffer expressed in bytes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.

Below you can find a couple of samples that demonstrate how to retrieve a picture and store it inside a memory buffer in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub Command1_Click()

' obtain the size in bytes of the first available picture (having index 0)

Dim nSizeInBytes As Long

ActiveSoundEditor1.TagsReader.ID3V2_CommercialFramePictureSizeGet 0, nSizeInBytes

if nSizeInBytes = 0 then Exit Sub

' allocate the destination buffer

Dim bytImage() As Byte

ReDim bytImage(nSizeInBytes)

' read picture data into the buffer

ActiveSoundEditor1.TagsReader.ID3V2_CommercialFramePictureMemoryFileGet 0, VarPtr(bytImage(0)), nSizeInBytes

...

use the buffer

...

' erase the buffer and free memory

Erase bytImage

End Sub

Visual C++ 6 with MFC

void CReadId3v2Dlg::OnButton1()

{

long nSizeInBytes = 0;

m_editor.TagsReader.ID3V2_CommercialFramePictureSizeGet (0, &nSizeInBytes);

if (nSizeInBytes == 0)

   return;

BYTE *pBuffer = new BYTE[nTagSize];

COleVariant var;

var.vt = VT_BYREF | VT_UI1;

var.pbVal = pTagBuffer;

m_editor.TagsReader.ID3V2_CommercialFramePictureMemoryFileGet (0, var, nSizeInBytes);

...

use the buffer

...

delete pBuffer;

}


TagsReader.ID3V2_CommercialFramePictureSizeGet method

TagsReader.ID3V2_CommercialFramePictureSizeGet method

Remarks

Obtains the size of the picture stored inside the given commercial frame (COMR) of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_CommercialFramePictureSizeGet (

nIndex as Integer,

nSize as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_CommercialFramePictureSizeGet (

short nIndex,

long *nSize

);

Parameter | Description
nIndex | Zero-based index of the commercial frame. The total number of commercial frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "COMR".
nSize | Reference that, on return from the method call, will contain the size in bytes of the picture stored inside the commercial frame.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_CommercialFrameReceivedAsGet method

TagsReader.ID3V2_CommercialFrameReceivedAsGet method

Remarks

Obtains the type of "Received as" field of the given commercial frame (COMR) of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_CommercialFrameReceivedAsGet (

nIndex as Integer,

ByRef nReceivedAs as enumId3v2ReceivedAsType

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_CommercialFrameReceivedAsGet (

short nIndex,

short *nReceivedAs

);

Parameter

Description

nIndex

Zero-based index of the commercial frame. The total number of commercial frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "COMR".

nReceivedAs

Reference that, on return from the method call, will contain the type of "Received as" field.

Supported values are the following:

Mnemonic value | Value | Meaning
ID3V2_COMMERCIAL_RECAS_Other | 0 | Other
ID3V2_COMMERCIAL_RECAS_Standard_CD | 1 | Standard CD album with other songs
ID3V2_COMMERCIAL_RECAS_Compressed | 2 | Compressed audio on CD
ID3V2_COMMERCIAL_RECAS_File_Internet | 3 | File over the Internet
ID3V2_COMMERCIAL_RECAS_Stream_Internet | 4 | Stream over the Internet
ID3V2_COMMERCIAL_RECAS_Note_sheets | 5 | As note sheets
ID3V2_COMMERCIAL_RECAS_Note_sheets_book | 6 | As note sheets in a book with other sheets
ID3V2_COMMERCIAL_RECAS_Music | 7 | Music on other media
ID3V2_COMMERCIAL_RECAS_Merchandise | 8 | Non-musical merchandise

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_EventTimingsFrameEventCountGet method

TagsReader.ID3V2_EventTimingsFrameEventCountGet method

Remarks

Obtains the number of event timings inside the event timing frame (ETCO) of the ID3V2 tag and, at the same time, obtains also the original time stamp format used to indicate the event timing position when the frame was created.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_EventTimingsFrameEventCountGet (

nCount as Long,

nTimeStampFormat as enumId3v2TimeStampFormats

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_EventTimingsFrameEventCountGet (

long nCount,

short nTimeStampFormat

);

Parameter

Description

nCount

Reference that, on return from the method call, will contain the number of event timing frames

nTimeStampFormat

Reference that, on return from the method call, will contain the position of the time stamp format.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_TIMESTAMP_FORMAT_FRAMES | 1 | MPEG frames
ID3V2_TIMESTAMP_FORMAT_MS | 2 | Milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_EventTimingsFrameEventInfoGet method

TagsReader.ID3V2_EventTimingsFrameEventInfoGet method

Remarks

Obtains information about a specific event timing inside the event timing frame (ETCO) of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_EventTimingsFrameEventInfoGet (

nIndex as Long,

nEventTimingType as enumId3v2EventTimingTypes,

nPositionInMs as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_EventTimingsFrameEventInfoGet (

long nIndex,

short *nEventTimingType,

long *nPositionInMs

);

Parameter

Description

nIndex

Zero-based index of the event timing frame. The total number of event timings available inside the ETCO frame of the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_EventTimingsFrameEventCountGet method

nEventTimingType

Reference that, on return from the method call, will contain the value representing the type of event timing.

The value can be in the range from 0 to 254; some value is already predefined by the ID3V2 standard, other are reserved for future uses.

Supported predefined values are the following:

Mnemonic Value | Value | Meaning
ID3V2_ETCO_Padding | 0 | Padding
ID3V2_ETCO_End_of_initial_silence | 1 | End of initial silence
ID3V2_ETCO_Intro_start | 2 | Intro start
ID3V2_ETCO_Main_part_start | 3 | Main part start
ID3V2_ETCO_Outro_start | 4 | Outro start
ID3V2_ETCO_Outro_end | 5 | Outro end
ID3V2_ETCO_Verse_start | 6 | Verse start
ID3V2_ETCO_Refrain_start | 7 | Refrain start
ID3V2_ETCO_Interlude_start | 8 | Interlude start
ID3V2_ETCO_Theme_start | 9 | Theme start
ID3V2_ETCO_Variation_start | 10 | Variation start
ID3V2_ETCO_Key_change | 11 | Key change
ID3V2_ETCO_Time_change | 12 | Time change
ID3V2_ETCO_Momentary_unwanted_noise | 13 | Momentary unwanted noise (Snap, Crackle and Pop)
ID3V2_ETCO_Sustained_noise | 14 | Sustained noise
ID3V2_ETCO_Sustained_noise_end | 15 | Sustained noise end
ID3V2_ETCO_Intro_end | 16 | Intro end
ID3V2_ETCO_Main_part_end | 17 | Main part end
ID3V2_ETCO_Verse_end | 18 | Verse end
ID3V2_ETCO_Refrain_end | 19 | Refrain end
ID3V2_ETCO_Theme_end | 20 | Theme end
ID3V2_ETCO_Profanity | 21 | Profanity
ID3V2_ETCO_Profanity_end | 22 | Profanity end
ID3V2_ETCO_Audio_end_start_of_silence | 253 | Audio end - start of silence
ID3V2_ETCO_Audio_file_end | 254 | Audio file end

Not predefined values and/or reserved for future uses are the following:

Values range | Meaning
from 23 to 223 | Reserved for future use
from 224 to 239 | Not predefined synch 0-15 (0-F)
from 240 to 252 | Reserved for future use

nPositionInMs

Reference that, on return from the method call, will contain the position of the event timing expressed in milliseconds.

NOTE: Although the ID3V2 standard supports positions expressed in frames, this version of the component, after converting the eventual position expressed in frames, will always return the position expressed in milliseconds.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_FrameCountGet method

TagsReader.ID3V2_FrameCountGet method

Remarks

Obtains the number of frames having the given identifier inside the ID3V2 tag. Identifiers of frames available inside the ID3V2 tag can be enumerated using the combination of the TagsReader.ID3V2_UniqueFramesCountGet and TagsReader.ID3V2_UniqueFramesIdGet methods.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_FrameCountGet (

strFrameId as String

) as Integer

[C++]

short control.TagsReader.ID3V2_FrameCountGet (

BSTR strFrameId

);

Parameter | Description
strFrameId | String containing the identifier of the specific frame to enumerate

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of frames having the given identifier inside the ID3V2 tag


TagsReader.ID3V2_GeneralObjectFrameFileGet method

TagsReader.ID3V2_GeneralObjectFrameFileGet method

Remarks

Creates a file containing data stored inside an ID3V2 general object frame (GEOB).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_GeneralObjectFrameFileGet (

nIndex as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_GeneralObjectFrameFileGet (

short nIndex,

BSTR strPathname

);

Parameter | Description
nIndex | Zero-based index of the general object frame. The total number of general object frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "GEOB".
strPathname | String representing the absolute pathname of the output graphic file.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_GeneralObjectFrameInfoGet method

TagsReader.ID3V2_GeneralObjectFrameInfoGet method

Remarks

Obtains textual information about the given ID3V2 general object frame (GEOB).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_GeneralObjectFrameInfoGet (

nIndex as Integer,

nInfo as enumId3v2FrameInfo

) as String

[C++]

BSTR control.TagsReader.ID3V2_GeneralObjectFrameInfoGet (

short nIndex,

short nInfo

);

Parameter

Description

nIndex

Zero-based index of the general object frame. The total number of general object frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "GEOB".

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_FRAME_INFO_DESCRIPTION | 1 | Description
ID3V2_FRAME_INFO_MIME_TYPE | 4 | Mime type
ID3V2_FRAME_INFO_FILENAME | 5 | Filename

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet method

TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet method

Remarks

Obtains a copy in memory of the file stored inside an ID3V2 general object frame (GEOB).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet (

nIndex as Integer,

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet (

short nIndex,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nIndex | Zero-based index of the general object frame. The total number of general object frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "GEOB".
pBuffer | Output buffer that, on return from the method call, will contain the file data
nBufferLength | Length of the buffer expressed in bytes. The size for the memory buffer can be obtained through the TagsReader.ID3V2_GeneralObjectFrameSizeGet method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.

Below you can find a couple of samples that demonstrate how to retrieve a general object and store it inside a memory buffer in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub Command1_Click()

' obtain the size in bytes of the first available picture (having index 0)

Dim nSizeInBytes As Long

ActiveSoundEditor1.TagsReader.ID3V2_GeneralObjectFrameSizeGet 0, nSizeInBytes

if nSizeInBytes = 0 then Exit Sub

' allocate the destination buffer

Dim bytImage() As Byte

ReDim bytImage(nSizeInBytes)

' read picture data into the buffer

ActiveSoundEditor1.TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet 0, VarPtr(bytImage(0)), nSizeInBytes

...

use the buffer

...

' erase the buffer and free memory

Erase bytImage

End Sub

Visual C++ 6 with MFC

void CReadId3v2Dlg::OnButton1()

{

long nSizeInBytes = 0;

m_editor.TagsReader.ID3V2_GeneralObjectFrameSizeGet (0, &nSizeInBytes);

if (nSizeInBytes == 0)

   return;

BYTE *pBuffer = new BYTE[nTagSize];

COleVariant var;

var.vt = VT_BYREF | VT_UI1;

var.pbVal = pTagBuffer;

m_editor.TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet (0, var, nSizeInBytes);

...

use the buffer

...

delete pBuffer;

}


TagsReader.ID3V2_GeneralObjectFrameSizeGet method

TagsReader.ID3V2_GeneralObjectFrameSizeGet method

Remarks

Obtains the size of the object stored inside a general object frame (GEOB) of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_GeneralObjectFrameSizeGet (

nIndex as Integer,

nSize as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_GeneralObjectFrameSizeGet (

short nIndex,

long *nSize

);

Parameter | Description
nIndex | Zero-based index of the general object frame. The total number of general object frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "GEOB".
nSize | Reference that, on return from the method call, will contain the size in bytes of the general object stored inside the frame.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_MusicCdIdentifierFrameGet method

TagsReader.ID3V2_MusicCdIdentifierFrameGet method

Remarks

Obtains a copy in memory of the music CD identifier frame (MCDI) of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_MusicCdIdentifierFrameGet (

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_MusicCdIdentifierFrameGet (

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
pBuffer | Output buffer that, on return from the method call, will contain the CD identifier data
nBufferLength | Length of the buffer expressed in bytes. You can know the size in bytes of the buffer needed to store the CD identifier data through the TagsReader.ID3V2_MusicCdIdentifierFrameSizeGet method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_MusicCdIdentifierFrameSizeGet method

TagsReader.ID3V2_MusicCdIdentifierFrameSizeGet method

Remarks

Obtains the size of the music CD identifier frame (MCDI) of the ID3V2 tag.

You can know if the music CD identifier frame is available inside the ID3V2 tag by enumerating available unique frames, through the combination of the TagsReader.ID3V2_UniqueFramesCountGet and TagsReader.ID3V2_UniqueFramesIdGet methods, then by checking if one of the calls to the TagsReader.ID3V2_UniqueFramesIdGet method returns the "MCDI" value.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_MusicCdIdentifierFrameSizeGet (

nSize as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_MusicCdIdentifierFrameSizeGet (

long *nSize

);

Parameter | Description
nSize | Reference that, on return from the method call, will contain the size in bytes of the music CD identifier frame.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_OwnershipFrameInfoGet method

TagsReader.ID3V2_OwnershipFrameInfoGet method

Remarks

Obtains textual information about the ID3V2 ownership frame (OWNE).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_OwnershipFrameInfoGet (

nInfo as enumId3v2CommercialInfo

) as String

[C++]

BSTR control.TagsReader.ID3V2_OwnershipFrameInfoGet (

short nInfo

);

Parameter

Description

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_OWNERSHIP_INFO_PRICE | 0 | Price
ID3V2_OWNERSHIP_INFO_PURCH_DATE | 1 | Purchase date
ID3V2_OWNERSHIP_INFO_SELLER | 2 | Seller

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_PictureFrameBitmapGet method

TagsReader.ID3V2_PictureFrameBitmapGet method

Remarks

Obtains the memory bitmap (HBITMAP) representation of the picture stored inside an ID3V2 picture frame (APIC).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PictureFrameBitmapGet (

nIndex as Integer,

hBitmap as OLE_HANDLE,

nOriginalWidth as Long,

nOriginalHeight as Long,

nResizeWidth as Long,

nResizeHeight as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PictureFrameBitmapGet (

short nIndex,

OLE_HANDLE *hBitmap,

long *nOriginalWidth,

long *nOriginalHeight,

long nResizeWidth,

long nResizeHeight

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "APIC".
hBitmap | Reference that, on return from the method call, will contain the HBITMAP of the picture.
nOriginalWidth | Reference that, on return from the method call, will contain the original width, expressed in pixels, of the picture.
nOriginalHeight | Reference that, on return from the method call, will contain the original height, expressed in pixels, of the picture.
nResizeWidth | Value containing the width, expressed in pixels, for horizontally resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same width returned inside the nOriginalWidth parameter.
nResizeHeight | Value containing the height, expressed in pixels, for vertically resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same height returned inside the nOriginalHeight parameter.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_PictureFrameFileGet method

TagsReader.ID3V2_PictureFrameFileGet method

Remarks

Creates a graphic file, of a given graphic format, containing the picture stored inside an ID3V2 picture frame (APIC).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PictureFrameFileGet (

nIndex as Integer,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PictureFrameFileGet (

short nIndex,

BSTR strPathname,

short nFormat,

long nFormatParameter

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "APIC".

strPathname

String representing the absolute pathname of the output graphic file.

nFormat

Graphic format of the output graphic file.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_ORIGINAL | -1 | Original format used to store the picture inside the tag. When this option is selected, the output graphic file will be an exact copy of the contents of the picture frame. You can determine the original graphic format, through its MIME type, by calling the TagsReader.ID3V2_PictureFrameInfoGet method with the parameter nInfo set to ID3V2_FRAME_INFO_MIME_TYPE; this information can be also useful to determine the file extension to use when composing the strPathname parameter above.
GRAPHIC_FORMAT_BMP | 0 | The output file will be converted to BMP format
GRAPHIC_FORMAT_JPEG | 1 | The output file will be converted to JPEG format
GRAPHIC_FORMAT_PNG | 2 | The output file will be converted to PNG format
GRAPHIC_FORMAT_GIF | 3 | The output file will be converted to GIF format
GRAPHIC_FORMAT_TIFF | 4 | The output file will be converted to TIFF format

nFormatParameter

Eventual parameter required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_PictureFrameInfoGet method

TagsReader.ID3V2_PictureFrameInfoGet method

Remarks

Obtains textual information about the given ID3V2 picture frame (APIC).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PictureFrameInfoGet (

nIndex as Integer,

nInfo as enumId3v2OwnershipInfo

) as String

[C++]

BSTR control.TagsReader.ID3V2_PictureFrameInfoGet (

short nIndex,

short nInfo

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "APIC".

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_FRAME_INFO_DESCRIPTION | 1 | Description
ID3V2_FRAME_INFO_CONTENT_TYPE_TEXT | 3 | Content type textual description
ID3V2_FRAME_INFO_MIME_TYPE | 4 | Mime type

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_PictureFrameMemoryFileGet method

TagsReader.ID3V2_PictureFrameMemoryFileGet method

Remarks

Obtains a copy in memory of the picture file stored inside an ID3V2 picture frame (APIC).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PictureFrameMemoryFileGet (

nIndex as Integer,

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PictureFrameMemoryFileGet (

short nIndex,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "APIC".
pBuffer | Output buffer that, on return from the method call, will contain the picture file data
nBufferLength | Length of the buffer expressed in bytes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.

Below you can find a couple of samples that demonstrate how to retrieve a picture and store it inside a memory buffer in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub Command1_Click()

' obtain the size in bytes of the first available picture (having index 0)

Dim nSizeInBytes As Long

ActiveSoundEditor1.TagsReader.ID3V2_PictureFrameSizeGet 0, nSizeInBytes

if nSizeInBytes = 0 then Exit Sub

' allocate the destination buffer

Dim bytImage() As Byte

ReDim bytImage(nSizeInBytes)

' read picture data into the buffer

ActiveSoundEditor1.TagsReader.ID3V2_PictureFrameMemoryFileGet 0, VarPtr(bytImage(0)), nSizeInBytes

...

use the buffer

...

' erase the buffer and free memory

Erase bytImage

End Sub

Visual C++ 6 with MFC

void CReadId3v2Dlg::OnButton1()

{

long nSizeInBytes = 0;

m_editor.TagsReader.ID3V2_PictureFrameSizeGet (0, &nSizeInBytes);

if (nSizeInBytes == 0)

   return;

BYTE *pBuffer = new BYTE[nTagSize];

COleVariant var;

var.vt = VT_BYREF | VT_UI1;

var.pbVal = pTagBuffer;

m_editor.TagsReader.ID3V2_PictureFrameMemoryFileGet (0, var, nSizeInBytes);

...

use the buffer

...

delete pBuffer;

}


TagsReader.ID3V2_PictureFrameSizeGet method

TagsReader.ID3V2_PictureFrameSizeGet method

Remarks

Obtains the size of the picture stored inside an ID3V2 picture frame (APIC).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PictureFrameSizeGet (

nIndex as Integer,

nSize as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PictureFrameSizeGet (

short nIndex,

long *nSize

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "APIC".
nSize | Reference that, on return from the method call, will contain the size in bytes of the picture stored inside the frame.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_PictureFrameTypeGet method

TagsReader.ID3V2_PictureFrameTypeGet method

Remarks

Obtains the type of picture stored inside an ID3V2 picture frame (APIC).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PictureFrameTypeGet (

nIndex as Integer,

nPictureType as enumId3v2PictureType

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PictureFrameTypeGet (

short nIndex,

short *nPictureType

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "APIC".

nPictureType

Reference that, on return from the method call, will contain the type of picture stored inside the frame.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_PICTURE_OTHER | 0 | Other
ID3V2_PICTURE_ICON_32x32 | 1 | 32x32 icon
ID3V2_PICTURE_ICON_OTHER | 2 | Other icon
ID3V2_PICTURE_COVER_FRONT | 3 | Front cover
ID3V2_PICTURE_COVER_BACK | 4 | Back cover
ID3V2_PICTURE_LEAFLET_PAGE | 5 | Leaflet page
ID3V2_PICTURE_MEDIA | 6 | Media (e.g. label side of CD)
ID3V2_PICTURE_LEAD_ARTIST_PERFORMER_SOLOIST | 7 | Lead artist/lead performer/soloist
ID3V2_PICTURE_ARTIST_PERFORMER | 8 | Artist/performer
ID3V2_PICTURE_CONDUCTOR | 9 | Conductor
ID3V2_PICTURE_BAND_ORCHESTRA | 10 | Band/Orchestra
ID3V2_PICTURE_COMPOSER | 11 | Composer
ID3V2_PICTURE_LYRICIST_TEXT_WRITER | 12 | Lyricist/text writer
ID3V2_PICTURE_RECORDING_LOCATION | 13 | Recording Location
ID3V2_PICTURE_DURING_RECORDING | 14 | During recording
ID3V2_PICTURE_DURING_PERFORMANCE | 15 | During performance
ID3V2_PICTURE_MOVIE_VIDEO_SCREEN_CAPTURE | 16 | Movie/video screen capture
ID3V2_PICTURE_BRIGHT_FISH | 17 | A bright coloured fish
ID3V2_PICTURE_ILLUSTRATION | 18 | Illustration
ID3V2_PICTURE_BAND_ARTIST_LOGO | 19 | Band/artist logotype
ID3V2_PICTURE_PUBLISHER_STUDIO_LOGO | 20 | Publisher/Studio logotype

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_PlayCounterFrameCountGet method

TagsReader.ID3V2_PlayCounterFrameCountGet method

Remarks

Obtains the count value for the play counter frame (PCNT) of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PlayCounterFrameCountGet (

nCount as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PlayCounterFrameCountGet (

long *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the play counter

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_PopularimeterFrameCounterGet method

TagsReader.ID3V2_PopularimeterFrameCounterGet method

Remarks

Obtains the play counter of the given ID3V2 popularimeter frame (POPM).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PopularimeterFrameCounterGet (

nIndex as Integer,

nCounter as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PopularimeterFrameCounterGet (

short nIndex,

long *nCounter

);

Parameter | Description
nIndex | Zero-based index of the popularimeter frame. The total number of popularimeter available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "POPM".
nCounter | Reference that, on return from the method call, will contain the play counter

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_PopularimeterFrameEmailGet method

TagsReader.ID3V2_PopularimeterFrameEmailGet method

Remarks

Obtains the personal e-mail stored inside a popularimeter frame (POPM) of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PopularimeterFrameEmailGet (

nIndex as Long

) as String

[C++]

BSTR control.TagsReader.ID3V2_PopularimeterFrameEmailGet (

long nIndex

);

Parameter | Description
nIndex | Zero-based index of the popularimeter frame. The total number of popularimeter available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "POPM".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the personal e-mail


TagsReader.ID3V2_PopularimeterFrameRatingGet method

TagsReader.ID3V2_PopularimeterFrameRatingGet method

Remarks

Obtains the rating of the given ID3V2 popularimeter frame (POPM).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PopularimeterFrameRatingGet (

nIndex as Integer,

nRating as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PopularimeterFrameRatingGet (

short nIndex,

long *nRating

);

Parameter | Description
nIndex | Zero-based index of the popularimeter frame. The total number of popularimeter available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "POPM".
nRating | Reference that, on return from the method call, will contain the song rating: can be a value in the range from 1 (worst) to 255 (best), 0 means that no rating is assigned.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_PrivateFrameFileGet method

TagsReader.ID3V2_PrivateFrameFileGet method

Remarks

Creates a file containing data stored inside an ID3V2 private frame (PRIV).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PrivateFrameFileGet (

nIndex as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PrivateFrameFileGet (

short nIndex,

BSTR strPathname

);

Parameter | Description
nIndex | Zero-based index of the private frame. The total number of private frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "PRIV".
strPathname | String representing the absolute pathname of the output file.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_PrivateFrameMemoryFileGet method

TagsReader.ID3V2_PrivateFrameMemoryFileGet method

Remarks

Obtains a copy in memory of the file stored inside an ID3V2 private frame (PRIV).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PrivateFrameMemoryFileGet (

nIndex as Integer,

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PrivateFrameMemoryFileGet (

short nIndex,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nIndex | Zero-based index of the private frame. The total number of private frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "PRIV".
pBuffer | Output buffer that, on return from the method call, will contain the file data
nBufferLength | Length of the buffer expressed in bytes. The size for the memory buffer can be obtained through the TagsReader.ID3V2_PrivateFrameSizeGet method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.

Below you can find a couple of samples that demonstrate how to retrieve a general object and store it inside a memory buffer in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub Command1_Click()

' obtain the size in bytes of the first private frame (having index 0)

Dim nSizeInBytes As Long

ActiveSoundEditor1.TagsReader.ID3V2_PrivateFrameSizeGet 0, nSizeInBytes

if nSizeInBytes = 0 then Exit Sub

' allocate the destination buffer

Dim bytImage() As Byte

ReDim bytImage(nSizeInBytes)

' read frame's data into the buffer

ActiveSoundEditor1.TagsReader.ID3V2_PrivateFrameMemoryFileGet 0, VarPtr(bytImage(0)), nSizeInBytes

...

use the buffer

...

' erase the buffer and free memory

Erase bytImage

End Sub

Visual C++ 6 with MFC

void CReadId3v2Dlg::OnButton1()

{

long nSizeInBytes = 0;

m_editor.TagsReader.ID3V2_PrivateFrameSizeGet (0, &nSizeInBytes);

if (nSizeInBytes == 0)

   return;

BYTE *pBuffer = new BYTE[nTagSize];

COleVariant var;

var.vt = VT_BYREF | VT_UI1;

var.pbVal = pTagBuffer;

m_editor.TagsReader.ID3V2_PrivateFrameMemoryFileGet (0, var, nSizeInBytes);

...

use the buffer

...

delete pBuffer;

}


TagsReader.ID3V2_PrivateFrameOwnerGet method

TagsReader.ID3V2_PrivateFrameOwnerGet method

Remarks

Obtains the owner of the given ID3V2 private frame (PRIV).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PrivateFrameOwnerGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_PrivateFrameOwnerGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the private frame. The total number of private frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "PRIV".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_PrivateFrameSizeGet method

TagsReader.ID3V2_PrivateFrameSizeGet method

Remarks

Obtains the size of the object stored inside a private frame (PRIV) of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_PrivateFrameSizeGet (

nIndex as Integer,

nSize as Long

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_PrivateFrameSizeGet (

short nIndex,

long *nSize

);

Parameter | Description
nIndex | Zero-based index of the private frame. The total number of private frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "PRIV".
nSize | Reference that, on return from the method call, will contain the size in bytes of the private frame's data.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_SynchLyricsFrameGet method

TagsReader.ID3V2_SynchLyricsFrameGet method

Remarks

Obtains the lyrics text stored inside the given ID3V2 synchronized lyrics frame (SYLT).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_SynchLyricsFrameGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_SynchLyricsFrameGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the synchronized lyrics frame. The total number of synchronized lyrics frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "SYLT".

Return value

Value

Meaning

Empty string

The information is not available or an error occurred (see the LastError property for further error details)

Valid string

String with the requested information.

The string is made up of multiple lines, each terminated by the CR+LF sequence. Each line starts with the timestamp which indicates the position within the sound file where the line is located during playback using the format below:

[xxxxxxxx] line1

[xxxxxxxx] line2

[xxxxxxxx] line3

etc.

where xxxxxxxx, enclosed within [ ] characters (square brackets), represents the timestamp value which may be expressed in MPEG frames or in milliseconds: you can know the timestamp format by calling the TagsReader.ID3V2_SynchLyricsFrameInfoNumGet method and by checking the value of the nTimeStampFormat parameter.

In the example below the timestamp has been expressed in milliseconds:

[00015030]Tale

[00015070]as

[00016020]old

[00016070]as

[00017020]time

The equivalent string in C++ would result like this:

"[00015030]Tale \r\n[00015070]as \r\n[00016020]old \r\n[00016070]as \r\n[00017020]time \r\n"

while in VB6 would result like this:

"[00015030]Tale " & vbCrLf & "[00015070]as " & vbCrLf & "[00016020]old " & vbCrLf & "[00016070]as " & vbCrLf & "[00017020]time " & vbCrLf


TagsReader.ID3V2_SynchLyricsFrameInfoGet method

TagsReader.ID3V2_SynchLyricsFrameInfoGet method

Remarks

Obtains textual information about the given ID3V2 synchronized lyrics frame (SYLT).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_SynchLyricsFrameInfoGet (

nIndex as Integer,

nInfo as enumId3v2FrameInfo

) as String

[C++]

BSTR control.TagsReader.ID3V2_SynchLyricsFrameInfoGet (

short nIndex,

short nInfo

);

Parameter

Description

nIndex

Zero-based index of the synchronized lyrics frame. The total number of synchronized lyrics frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "SYLT".

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_FRAME_INFO_LANGUAGE | 0 | Language
ID3V2_FRAME_INFO_DESCRIPTION | 1 | Description
ID3V2_FRAME_INFO_TIME_FORMAT | 2 | Time format
ID3V2_FRAME_INFO_CONTENT_TYPE_TEXT | 3 | Content type textual description

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_SynchLyricsFrameInfoNumGet method

TagsReader.ID3V2_SynchLyricsFrameInfoNumGet method

Remarks

Obtains numeric information about the given ID3V2 synchronized lyrics frame (SYLT).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_SynchLyricsFrameInfoNumGet (

nIndex as Integer,

nLyricsType as enumId3v2SyncLyricsType,

nTimeStampFormat as enumId3v2TimeStampFormats

) as enumErrorCodes

[C++]

short control.TagsReader.ID3V2_SynchLyricsFrameInfoNumGet (

short nIndex,

short *nLyricsType,

short *nTimeStampFormat

);

Parameter

Description

nIndex

Zero-based index of the synchronized lyrics frame. The total number of synchronized lyrics frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "SYLT".

nLyricsType

Reference that, on return from the method call, will contain the type of lyric contents.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_SYNC_LYRICS_TYPE_OTHER | 0 | Other
ID3V2_SYNC_LYRICS_TYPE_LYRICS | 1 | Lyrics
ID3V2_SYNC_LYRICS_TYPE_TEXT_TRANSCRIPTION | 2 | Text transcription
ID3V2_SYNC_LYRICS_TYPE_MOVEMENT_PARTNAME | 3 | Movement/part name
ID3V2_SYNC_LYRICS_TYPE_EVENTS | 4 | Events
ID3V2_SYNC_LYRICS_TYPE_CHORD | 5 | Chord
ID3V2_SYNC_LYRICS_TYPE_TRIVIA_POPUP | 6 | Trivia/pop up information
ID3V2_SYNC_LYRICS_TYPE_URL_TO_WEBPAGE | 7 | URLs to webpages
ID3V2_SYNC_LYRICS_TYPE_URL_TO_IMAGES | 8 | URL to images

nTimeStampFormat

Reference that, on return from the method call, will contain the timestamp format.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_TIMESTAMP_FORMAT_FRAMES | 1 | MPEG frames
ID3V2_TIMESTAMP_FORMAT_MS | 2 | Milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.ID3V2_TermsOfUseFrameGet method

TagsReader.ID3V2_TermsOfUseFrameGet method

Remarks

Obtains the text of the given ID3V2 terms of use frame (USER).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_TermsOfUseFrameGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_TermsOfUseFrameGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the terms of use frame. The total number of terms of use frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "USER".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_TermsOfUseFrameLanguageGet method

TagsReader.ID3V2_TermsOfUseFrameLanguageGet method

Remarks

Obtains the language of the text for the given ID3V2 terms of use frame (USER).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_TermsOfUseFrameLanguageGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_TermsOfUseFrameLanguageGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the terms of use frame. The total number of terms of use frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "USER".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing the language of the terms of use frame, for example "ENG", "ITA", etc.: this string should be always 3 characters long.


TagsReader.ID3V2_TextFrameGet method

TagsReader.ID3V2_TextFrameGet method

Remarks

Obtains contents of a specific text-based frame of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_TextFrameGet (

strFrameId as String

) as String

[C++]

BSTR control.TagsReader.ID3V2_TextFrameGet (

BSTR strFrameId

);

Parameter

Description

strFrameId

String containing the identifier of the specific frame to get.

Supported identifiers for text-based frames are the following: TIT1, TIT2, TIT3, TALB, TOAL, TRCK, TPOS, TSST, TSRC, TPE1, TPE2, TPE3, TPE4, TOPE, TEXT, TOLY, TCOM, TMCL, TIPL, TENC, TBPM, TLEN, TKEY, TLAN, TCON, TFLT, TMED, TMOO, TCOP, TPRO, TPUB, TOWN, TRSN, TRSO, TOFN, TDLY, TDEN, TDOR, TDRC, TDRL, TDTG, TSSE, TSOA, TSOP, TSOT.

Identifiers defined by version 2.2 of the ID3V2 tag format, which are based upon 3 characters instead of 4 characters, are supported as well.

You can know if one of the frames above is available inside the ID3V2 tag by using the TagsReader.ID3V2_FrameCountGet method.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.ID3V2_UniqueFramesCountGet method

TagsReader.ID3V2_UniqueFramesCountGet method

Remarks

Obtains the number of unique frames found inside the ID3V2 tag. The identifier of each unique frame can be obtained through the TagsReader.ID3V2_UniqueFramesIdGet method.

Certain ID3V2 frames, for example APIC or COMM, can be available in multiple instances inside the same ID3V2 tag: when this method is called, the enumeration will not keep count of multiple instances of a specific frame but will only report the availability of the frame itself; once the availability of a specific frame is known, single specific frames can be enumerated using the TagsReader.ID3V2_FrameCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_UniqueFramesCountGet (

) as Integer

[C++]

short control.TagsReader.ID3V2_UniqueFramesCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of unique frames found inside the ID3V2 tag


TagsReader.ID3V2_UniqueFramesIdGet method

TagsReader.ID3V2_UniqueFramesIdGet method

Remarks

Obtains a unique frame identifier between the list of unique frames enumerated inside the ID3V2 tag through a previous call to the TagsReader.ID3V2_UniqueFramesCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_UniqueFramesIdGet (

nFrameIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_UniqueFramesIdGet (

short nFrameIndex

);

Parameter | Description
nFrameIndex | Zero-based index of the frame.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the unique frame identifier


TagsReader.ID3V2_UnsynchLyricsFrameGet method

TagsReader.ID3V2_UnsynchLyricsFrameGet method

Remarks

Obtains the text of the given ID3V2 unsynchronized lyrics frame (USLT).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_UnsynchLyricsFrameGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_UnsynchLyricsFrameGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the unsynchronized lyrics frame. The total number of unsynchronized lyrics frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "USLT".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_UnsynchLyricsFrameInfoGet method

TagsReader.ID3V2_UnsynchLyricsFrameInfoGet method

Remarks

Obtains textual information about the given ID3V2 unsynchronized lyrics frame (USLT).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_UnsynchLyricsFrameInfoGet (

nIndex as Integer,

nInfo as enumId3v2FrameInfo

) as String

[C++]

BSTR control.TagsReader.ID3V2_UnsynchLyricsFrameInfoGet (

short nIndex,

short nInfo

);

Parameter

Description

nIndex

Zero-based index of the unsynchronized lyrics frame. The total number of unsynchronized lyrics frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "USLT".

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_FRAME_INFO_LANGUAGE | 0 | Language
ID3V2_FRAME_INFO_DESCRIPTION | 1 | Description

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_URLFrameGet method

TagsReader.ID3V2_URLFrameGet method

Remarks

Obtains contents of a specific URL-based frame of the ID3V2 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_URLFrameGet (

strFrameId as String

) as String

[C++]

BSTR control.TagsReader.ID3V2_URLFrameGet (

BSTR strFrameId

);

Parameter

Description

strFrameId

String containing the identifier of the specific frame to get.

Supported identifiers for URL-based frames are the following: WCOM, WCOP, WOAF, WOAR, WOAS, WORS, WPAY, WPUB.

Identifiers defined by version 2.2 of the ID3V2 tag format, which are based upon 3 characters instead of 4 characters, are supported as well.

You can know if one of the frames above is available inside the ID3V2 tag by using the TagsReader.ID3V2_FrameCountGet method.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.ID3V2_UserTextFrameDescriptionGet method

TagsReader.ID3V2_UserTextFrameDescriptionGet method

Remarks

Obtains the description of the text for the given ID3V2 user text frame (TXXX).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_UserTextFrameDescriptionGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_UserTextFrameDescriptionGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the user text frame. The total number of user text frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "TXXX".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_UserTextFrameGet method

TagsReader.ID3V2_UserTextFrameGet method

Remarks

Obtains the text of the given ID3V2 user text frame (TXXX).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_UserTextFrameGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_UserTextFrameGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the user text frame. The total number of user text frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "TXXX".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_UserURLFrameDescriptionGet method

TagsReader.ID3V2_UserURLFrameDescriptionGet method

Remarks

Obtains the description of the URL for the given ID3V2 user defined URL frame (WXXX).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_UserURLFrameDescriptionGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_UserURLFrameDescriptionGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the user defined URL frame. The total number of user defined URL frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "WXXX".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.ID3V2_UserURLFrameGet method

TagsReader.ID3V2_UserURLFrameGet method

Remarks

Obtains the URL of the given ID3V2 user defined URL frame (WXXX).

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.ID3V2_UserURLFrameGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.ID3V2_UserURLFrameGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the user defined URL frame. The total number of user defined URL frames available inside the ID3V2 tag can be obtained through a call to the TagsReader.ID3V2_FrameCountGet method with the strFrameId parameter set to "WXXX".

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.LYRICS3_ImageLinkGet method

TagsReader.LYRICS3_ImageLinkGet method

Remarks

Obtains the image link stored inside the LYRICS3 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.LYRICS3_ImageLinkGet (

) as String

[C++]

BSTR control.TagsReader.LYRICS3_ImageLinkGet (

);

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing the image link


TagsReader.LYRICS3_LyricsGet method

TagsReader.LYRICS3_LyricsGet method

Remarks

Obtains lyrics text contained inside the LYRICS3 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.LYRICS3_LyricsGet (

) as String

[C++]

BSTR control.TagsReader.LYRICS3_LyricsGet (

);

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing the lyrics text


TagsReader.LYRICS3_TextFieldGet method

TagsReader.LYRICS3_TextFieldGet method

Remarks

Obtains a field of the LYRICS3 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.LYRICS3_TextFieldGet (

nField as enumTagFields

) as String

[C++]

BSTR control.TagsReader.LYRICS3_TextFieldGet (

short nField

);

Parameter

Description

nField

Identifier of the tag field to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
TAG_FIELD_TITLE | 0 | Title
TAG_FIELD_ARTIST | 1 | Artist
TAG_FIELD_ALBUM | 2 | Album
TAG_FIELD_COMMENT | 4 | Comment
TAG_FIELD_GENRE_CODE | 6 | Genre code for ID3
TAG_FIELD_GENRE_STRING | 7 | Genre string
TAG_FIELD_COMPOSER | 8 | Composer

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested field


TagsReader.MP4_PictureFrameBitmapGet method

TagsReader.MP4_PictureFrameBitmapGet method

Remarks

Obtains the memory bitmap (HBITMAP) representation of the picture stored inside a MP4 picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_PictureFrameBitmapGet (

nIndex as Integer,

hBitmap as OLE_HANDLE,

nOriginalWidth as Long,

nOriginalHeight as Long,

nResizeWidth as Long,

nResizeHeight as Long

) as enumErrorCodes

[C++]

short control.TagsReader.MP4_PictureFrameBitmapGet (

short nIndex,

OLE_HANDLE *hBitmap,

long *nOriginalWidth,

long *nOriginalHeight,

long nResizeWidth,

long nResizeHeight

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the MP4 tag can be obtained through a call to the TagsReader.MP4_PictureFrameCountGet method.
hBitmap | Reference that, on return from the method call, will contain the HBITMAP of the picture.
nOriginalWidth | Reference that, on return from the method call, will contain the original width, expressed in pixels, of the picture.
nOriginalHeight | Reference that, on return from the method call, will contain the original height, expressed in pixels, of the picture.
nResizeWidth | Value containing the width, expressed in pixels, for horizontally resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same width returned inside the nOriginalWidth parameter.
nResizeHeight | Value containing the height, expressed in pixels, for vertically resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same height returned inside the nOriginalHeight parameter.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.MP4_PictureFrameCountGet method

TagsReader.MP4_PictureFrameCountGet method

Remarks

Obtains the number of picture frames available inside the MP4 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_PictureFrameCountGet (

) as Integer

[C++]

short control.TagsReader.MP4_PictureFrameCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of picture frames available inside the MP4 tag


TagsReader.MP4_PictureFrameFileGet method

TagsReader.MP4_PictureFrameFileGet method

Remarks

Creates a graphic file, of a given graphic format, containing the picture stored inside a MP4 picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_PictureFrameFileGet (

nIndex as Integer,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Long

) as enumErrorCodes

[C++]

short control.TagsReader.MP4_PictureFrameFileGet (

short nIndex,

BSTR strPathname,

short nFormat,

long nFormatParameter

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the MP4 tag can be obtained through a call to the TagsReader.MP4_PictureFrameCountGet method.

strPathname

String representing the absolute pathname of the output graphic file.

nFormat

Graphic format of the output graphic file.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_ORIGINAL | -1 | Original format used to store the picture inside the tag. When this option is selected, the output graphic file will be an exact copy of the contents of the picture frame. You can determine the original graphic format, through its MIME type, by calling the TagsReader.MP4_PictureFrameMimeGet method; this information can be also useful to determine the file extension to use when composing the strPathname parameter above.
GRAPHIC_FORMAT_BMP | 0 | The output file will be converted to BMP format
GRAPHIC_FORMAT_JPEG | 1 | The output file will be converted to JPEG format
GRAPHIC_FORMAT_PNG | 2 | The output file will be converted to PNG format
GRAPHIC_FORMAT_GIF | 3 | The output file will be converted to GIF format
GRAPHIC_FORMAT_TIFF | 4 | The output file will be converted to TIFF format

nFormatParameter

Eventual parameter required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.MP4_PictureFrameMemoryFileGet method

TagsReader.MP4_PictureFrameMemoryFileGet method

Remarks

Obtains a copy in memory of the picture file stored inside a MP4 picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_PictureFrameMemoryFileGet (

nIndex as Integer,

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.MP4_PictureFrameMemoryFileGet (

short nIndex,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the MP4 tag can be obtained through a call to the TagsReader.MP4_PictureFrameCountGet method.
pBuffer | Output buffer that, on return from the method call, will contain the picture file data
nBufferLength | Length of the buffer expressed in bytes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.

Below you can find a couple of samples that demonstrate how to retrieve a picture and store it inside a memory buffer in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub Command1_Click()

' obtain the size in bytes of the first available picture (having index 0)

Dim nSizeInBytes As Long

ActiveSoundEditor1.TagsReader.MP4_PictureFrameSizeGet 0, nSizeInBytes

if nSizeInBytes = 0 then Exit Sub

' allocate the destination buffer

Dim bytImage() As Byte

ReDim bytImage(nSizeInBytes)

' read picture data into the buffer

ActiveSoundEditor1.TagsReader.MP4_PictureFrameMemoryFileGet 0, VarPtr(bytImage(0)), nSizeInBytes

...

use the buffer

...

' erase the buffer and free memory

Erase bytImage

End Sub

Visual C++ 6 with MFC

void CReadId3v2Dlg::OnButton1()

{

long nSizeInBytes = 0;

m_editor.TagsReader.MP4_PictureFrameSizeGet (0, &nSizeInBytes);

if (nSizeInBytes == 0)

   return;

BYTE *pBuffer = new BYTE[nTagSize];

COleVariant var;

var.vt = VT_BYREF | VT_UI1;

var.pbVal = pTagBuffer;

m_editor.TagsReader.MP4_PictureFrameMemoryFileGet (0, var, nSizeInBytes);

...

use the buffer

...

delete pBuffer;

}


TagsReader.MP4_PictureFrameMimeGet method

TagsReader.MP4_PictureFrameMimeGet method

Remarks

Obtains the MIME type of the picture stored inside a MP4 picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_PictureFrameMimeGet (

nIndex as Integer

) as String

[C++]

BSTR control.TagsReader.MP4_PictureFrameMimeGet (

short nIndex

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the MP4 tag can be obtained through a call to the TagsReader.MP4_PictureFrameCountGet method.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String containing the MIME type of the picture, for example "image/jpeg", "image/gif", "image/bmp", etc.


TagsReader.MP4_PictureFrameSizeGet method

TagsReader.MP4_PictureFrameSizeGet method

Remarks

Obtains the size of the picture stored inside a MP4 picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_PictureFrameSizeGet (

nIndex as Integer,

nSize as Long

) as enumErrorCodes

[C++]

short control.TagsReader.MP4_PictureFrameSizeGet (

short nIndex,

long *nSize

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the MP4 tag can be obtained through a call to the TagsReader.MP4_PictureFrameCountGet method.
nSize | Reference that, on return from the method call, will contain the size in bytes of the picture stored inside the frame.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.MP4_TextFrameGet method

TagsReader.MP4_TextFrameGet method

Remarks

Obtains contents of a specific text-based frame of the MP4 tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_TextFrameGet (

nFrameId as enumMp4Frames

) as String

[C++]

BSTR control.TagsReader.MP4_TextFrameGet (

short nFrameId

);

Parameter

Description

nFrameId

Identifier of the specific frame to get.

Supported identifiers are the following:

Mnemonic Value | Value | Meaning
MP4_FRAME_ALBUM | 0 | Album (identifier ©alb)
MP4_FRAME_ARTIST | 1 | Artist (identifier ©ART)
MP4_FRAME_AUTHOR | 2 | Author (identifier ©aut)
MP4_FRAME_ALBUMARTIST | 3 | Album artist (identifier aART)
MP4_FRAME_BEATSPERMINUTE | 4 | Beats Per Minute (identifier tmpo)
MP4_FRAME_CATEGORY | 5 | Category (identifier catg)
MP4_FRAME_CDSETNUMBER | 6 | CD set number (identifier dsk)
MP4_FRAME_DISCNUMBER | 7 | Disk number (identifier disk)
MP4_FRAME_COMMENT | 9 | Comment (identifier ©cmt)
MP4_FRAME_COMPOSER | 10 | Composer (identifier ©wrt)
MP4_FRAME_COMPILATION | 11 | Compilation (identifier cpil)
MP4_FRAME_DAY | 12 | Day (identifier ©day)
MP4_FRAME_COPYRIGHT | 13 | Copyright (identifier ©cpy)
MP4_FRAME_CREATEDATE | 14 | Creation date (identifier ©day)
MP4_FRAME_DESCRIPTION | 15 | Description (identifier ©des)
MP4_FRAME_INFORMATION | 16 | Information (identifier ©inf)
MP4_FRAME_DIRECTOR | 17 | Director (identifier ©dir)
MP4_FRAME_DISCLAIMER | 18 | Disclaimer (identifier ©dis)
MP4_FRAME_ENCODER | 19 | Encoder (identifier ©too)
MP4_FRAME_GROUPING | 20 | Grouping (identifier ©grp)
MP4_FRAME_KEYWORD | 21 | Keyword (identifier keyw)
MP4_FRAME_LYRICS | 22 | Lyrics (identifier ©lyr)
MP4_FRAME_TITLE | 23 | Title (identifier ©nam)
MP4_FRAME_NETURL | 24 | Net URL (identifier ©url)
MP4_FRAME_ORIGINALARTIST | 25 | Original artist (identifier ©ope)
MP4_FRAME_ORIGINALFORMAT | 26 | Original format (identifier ©fmt)
MP4_FRAME_ORIGINALSOURCE | 27 | Original source (identifier ©src)
MP4_FRAME_PERFORMER | 28 | Performer (identifier ©prf)
MP4_FRAME_RATING | 29 | Rating (identifier rate)
MP4_FRAME_PRODUCER | 30 | Producer (identifier ©prd)
MP4_FRAME_WARNING | 31 | Warning (identifier ©wrn)
MP4_FRAME_GENRE | 32 | Genre
MP4_FRAME_TRACK | 33 | Track

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.MP4_UniqueFramesCountGet method

TagsReader.MP4_UniqueFramesCountGet method

Remarks

Obtains the number of unique frames found inside the MP4 tag. The identifier of each unique frame can be obtained through the TagsReader.MP4_UniqueFramesIdGet method.

Multiple instances of the picture frame can be available inside the same MP4 tag: when this method is called, the enumeration will not keep count of multiple instances of a specific frame but will only report the availability of the frame itself; once the availability of a specific frame is known, single specific picture frames can be enumerated using the TagsReader.MP4_PictureFrameCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_UniqueFramesCountGet (

) as Integer

[C++]

short control.TagsReader.MP4_UniqueFramesCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of unique frames found inside the MP4 tag


TagsReader.MP4_UniqueFramesIdGet method

TagsReader.MP4_UniqueFramesIdGet method

Remarks

Obtains a unique frame identifier between the list of unique frames enumerated inside the MP4 tag through a previous call to the TagsReader.MP4_UniqueFramesCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.MP4_UniqueFramesIdGet (

nFrameIndex as Integer

) as String

[C++]

BSTR control.TagsReader.MP4_UniqueFramesIdGet (

short nFrameIndex

);

Parameter | Description
nFrameIndex | Zero-based index of the frame.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the unique frame identifier


TagsReader.OGG_TextFrameGet method

TagsReader.OGG_TextFrameGet method

Remarks

Obtains contents of a specific text-based frame of the OGG Vorbis tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.OGG_TextFrameGet (

nFrameId as enumOggFrames

) as String

[C++]

BSTR control.TagsReader.OGG_TextFrameGet (

short nFrameId

);

Parameter

Description

nFrameId

Identifier of the tag frame to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
OGG_FRAME_Album | 0 | Album
OGG_FRAME_Artist | 1 | Artist
OGG_FRAME_Comment | 2 | Comment
OGG_FRAME_Contact | 3 | Contact
OGG_FRAME_Copyright | 4 | Copyright
OGG_FRAME_Date | 5 | Date
OGG_FRAME_Description | 6 | Description
OGG_FRAME_Genre | 7 | Genre
OGG_FRAME_ISRC | 8 | International Standard Recording Code (ISRC)
OGG_FRAME_License | 9 | License
OGG_FRAME_Location | 10 | Location
OGG_FRAME_Organization | 11 | Organization
OGG_FRAME_Performer | 12 | Performer
OGG_FRAME_Title | 13 | Title
OGG_FRAME_Track | 14 | Track
OGG_FRAME_Vendor | 15 | Vendor
OGG_FRAME_Version | 16 | Version

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.OGG_UniqueFramesCountGet method

TagsReader.OGG_UniqueFramesCountGet method

Remarks

Obtains the number of unique frames found inside the OGG Vorbis tag. The identifier of each unique frame can be obtained through the TagsReader.OGG_UniqueFramesIdGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.OGG_UniqueFramesCountGet (

) as Integer

[C++]

short control.TagsReader.OGG_UniqueFramesCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of unique frames found inside the OGG Vorbis tag


TagsReader.OGG_UniqueFramesIdGet method

TagsReader.OGG_UniqueFramesIdGet method

Remarks

Obtains a unique frame identifier between the list of unique frames enumerated inside the OGG Vorbis tag through a previous call to the TagsReader.OGG_UniqueFramesCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.OGG_UniqueFramesIdGet (

nFrameIndex as Integer

) as String

[C++]

BSTR control.TagsReader.OGG_UniqueFramesIdGet (

short nFrameIndex

);

Parameter | Description
nFrameIndex | Zero-based index of the frame.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the unique frame identifier


TagsReader.OGG_UserFrameGet method

TagsReader.OGG_UserFrameGet method

Remarks

Obtains contents of a specific user-defined frame of the OGG Vorbis tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.OGG_UserFrameGet (

strFrameId as String

) as String

[C++]

BSTR control.TagsReader.OGG_UserFrameGet (

BSTR strFrameId

);

Parameter | Description
strFrameId | String containing the identifier of the specific user-defined frame to get. You can know which frames are available inside the OGG Vorbis tag by using the combination of the TagsReader.OGG_UniqueFramesCountGet and TagsReader.OGG_UniqueFramesIdGet methods.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.WAV_BextChunkBinaryFieldGet method

TagsReader.WAV_BextChunkBinaryFieldGet method

Remarks

Obtains a copy in memory of a binary field stored inside the WAV Bext chunk.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WAV_BextChunkBinaryFieldGet (

nFieldId as enumBextChunkBinaryField,

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.WAV_BextChunkBinaryFieldGet (

short nFieldId,

const VARIANT FAR& pBuffer,

long *nBufferLen

);

Parameter

Description

nFieldId

Identifier of the binary field to read.

Supported values are the following:

Mnemonic Value | Value | Meaning
WAV_BEXT_CHUNK_BIN_UMID_0 | 0 | Binary bytes of SMPTE UMID
WAV_BEXT_CHUNK_BIN_Reserved | 1 | Reserved for future expansion

pBuffer

Output buffer that, on return from the method call, will contain binary data of the requested field.

nBufferLength

Reference that represents the maximum allowed size of the buffer (in input) and, on return from the method call, will contain the effective size of the buffer read; the value is expressed in bytes.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.WAV_BextChunkTextFieldGet method

TagsReader.WAV_BextChunkTextFieldGet method

Remarks

Obtains contents of a specific text-based field of the BEXT chunk.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WAV_BextChunkTextFieldGet (

nFieldId as enumBextChunkField

) as String

[C++]

BSTR control.TagsReader.WAV_BextChunkTextFieldGet (

short nFieldId

);

Parameter

Description

nFieldId

Identifier of the field to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
WAV_BEXT_CHUNK_Description | 0 | Description of the sound sequence
WAV_BEXT_CHUNK_Originator | 1 | Name of the originator
WAV_BEXT_CHUNK_OriginatorReference | 2 | Reference of the originator
WAV_BEXT_CHUNK_OriginationDate | 3 | Originator date yyyy-mm-dd
WAV_BEXT_CHUNK_OriginationTime | 4 | Originator time hh-mm-ss
WAV_BEXT_CHUNK_TimeReference_Low | 5 | First sample count since midnight: lower 32 bits
WAV_BEXT_CHUNK_TimeReference_High | 6 | First sample count since midnight: higher 32 bits
WAV_BEXT_CHUNK_TimeReference_Full | 7 | First sample count since midnight: 64 bits number
WAV_BEXT_CHUNK_TimeReference_Formatted | 8 | Formatted time since midnight
WAV_BEXT_CHUNK_Version | 9 | Version of the BWF; unsigned binary number (Read only)
WAV_BEXT_CHUNK_CodHistory | 10 | Coding history

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested field


TagsReader.WAV_CartChunkTextFieldGet method

TagsReader.WAV_CartChunkTextFieldGet method

Remarks

Obtains contents of a specific text-based field of the CART chunk.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WAV_CartChunkTextFieldGet (

nFieldId as enumCartChunkField

) as String

[C++]

BSTR control.TagsReader.WAV_CartChunkTextFieldGet (

short nFieldId

);

Parameter

Description

nFieldId

Identifier of the field to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
WAV_CART_CHUNK_VERSION | 0 | Version of the data structure (Read only)
WAV_CART_CHUNK_TITLE | 1 | Title of cart audio sequence
WAV_CART_CHUNK_ARTIST | 2 | Artist or creator name
WAV_CART_CHUNK_CUTID | 3 | Cut number identification
WAV_CART_CHUNK_CLIENTID | 4 | Client identification
WAV_CART_CHUNK_CATEGORY | 5 | Category ID, PSA, NEWS, etc
WAV_CART_CHUNK_CLASSIFICATION | 6 | Classification or auxiliary key
WAV_CART_CHUNK_OUTCUE | 7 | Out cue text
WAV_CART_CHUNK_STARTDATE | 8 | Start date YYYY-MM-DD
WAV_CART_CHUNK_STARTTIME | 9 | Start time hh:mm:ss
WAV_CART_CHUNK_ENDDATE | 10 | End date YYYY-MM-DD
WAV_CART_CHUNK_ENDTIME | 11 | End time hh:mm:ss
WAV_CART_CHUNK_PRODUCERAPPID | 12 | Name of vendor or application
WAV_CART_CHUNK_PRODUCERAPPVERSION | 13 | Version of producer application
WAV_CART_CHUNK_USERDEF | 14 | User defined text
WAV_CART_CHUNK_LEVELREFERENCE | 15 | Sample value for 0 dB reference
WAV_CART_CHUNK_URL | 16 | Uniform resource locator
WAV_CART_CHUNK_TAGTEXT | 17 | Tag text

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested field


TagsReader.WAV_CartChunkTimeMarkerFieldGet method

TagsReader.WAV_CartChunkTimeMarkerFieldGet method

Remarks

Obtains a time marker field of the CART chunk.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WAV_CartChunkTimeMarkerFieldGet (

nFieldId as enumCartChunkTimeMarkerField,

nPositionInSamples as Long

) as String

[C++]

BSTR control.TagsReader.WAV_CartChunkTimeMarkerFieldGet (

short nFieldId,

long *nPositionInSamples

);

Parameter

Description

nFieldId

Identifier of the field to get.

Supported values are the following:

Mnemonic Value | Value | Meaning
WAV_CART_CHUNK_TIME_MARKER1 | 0 | Time marker 1
WAV_CART_CHUNK_TIME_MARKER2 | 1 | Time marker 2
WAV_CART_CHUNK_TIME_MARKER3 | 2 | Time marker 3
WAV_CART_CHUNK_TIME_MARKER4 | 3 | Time marker 4
WAV_CART_CHUNK_TIME_MARKER5 | 4 | Time marker 5
WAV_CART_CHUNK_TIME_MARKER6 | 5 | Time marker 6
WAV_CART_CHUNK_TIME_MARKER7 | 6 | Time marker 7
WAV_CART_CHUNK_TIME_MARKER8 | 7 | Time marker 8

nPositionInSamples

Reference that, on return from the method call, will contain the time marker position expressed in samples.

Return value

Value

Meaning

Empty string

The information is not available or an error occurred (see the LastError property for further error details)

Valid string

String of 4 characters (also known as FOURCC) containing the identifier of the time marker.

The following table summarizes the basic timer types:

Timer ID | Description | Start-End | Enumerated | Multiples
XXX (*) | Custom timer | No | No | Yes
SEGx (**) | Segue timer | Yes | Yes | Yes
AUDx (**) | Audio boundary | Yes | No | No
INTx (**) | Introduction | Yes | Yes | Yes
OUTx (**) | Epilog | Yes | Yes | Yes
SECx (**) | Secondary | Yes | Yes | Yes
TERx (**) | Tertiary | Yes | Yes | Yes
MRKx (**) | Generic marker | No | Yes | Yes
EODx (**) | End-of-data | No | No | Yes

(*) You can define your own timer ID by replacing the XXX with other ASCII characters.

(**) Timers may be qualified in one of following ways:

1. as start or end timers, by replacing the "x" character with a lower case ASCII letter "s" for a start timer or a lower case ASCII letter "e" for an end timer; for example, the timer identification AUDs designates the start of audio following silence, while AUDe designates the end of the audio segment.
2. as enumerated timers, by replacing the "x" character with an ASCII numeric character; for example, SEC1 may be designated secondary timer number 1, SEC2 may be secondary number 2, and so on
3. as multiple timers, by having multiple instances of the same timer ID; one may have, for example, multiple instances of MRK. Custom timers belong in this category.


TagsReader.WAV_DisplayChunkTextGet method

TagsReader.WAV_DisplayChunkTextGet method

Remarks

Obtains contents of the DISP chunk.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WAV_DisplayChunkTextGet (

) as String

[C++]

BSTR control.TagsReader.WAV_DisplayChunkTextGet (

);

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the chunk


TagsReader.WAV_ListInfoChunkFrameGet method

TagsReader.WAV_ListInfoChunkFrameGet method

Remarks

Obtains the text of an INFO frame of the WAV's LIST chunk.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WAV_ListInfoChunkFrameGet (

strFrameId as String

) as String

[C++]

BSTR control.TagsReader.WAV_ListInfoChunkFrameGet (

BSTR strFrameId

);

Parameter | Description
strFrameId | String of 4 characters (FOURCC) containing the identifier of the INFO frame to read. You can enumerate identifiers of existing frames through the combination of the TagsReader.WAV_ListInfoChunkUniqueFramesCountGet and TagsReader.WAV_ListInfoChunkUniqueFramesIdGet methods.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.WAV_ListInfoChunkUniqueFramesCountGet method

TagsReader.WAV_ListInfoChunkUniqueFramesCountGet method

Remarks

Obtains the number of unique frames found inside the LIST INFO chunk of the WAV file. The identifier of each unique frame can be obtained through the TagsReader.WAV_ListInfoChunkUniqueFramesIdGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WAV_ListInfoChunkUniqueFramesCountGet (

) as Integer

[C++]

short control.TagsReader.WAV_ListInfoChunkUniqueFramesCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of unique frames found inside the LIST INFO chunk


TagsReader.WAV_ListInfoChunkUniqueFramesIdGet method

TagsReader.WAV_ListInfoChunkUniqueFramesIdGet method

Remarks

Obtains a unique frame identifier between the list of unique frames enumerated inside the LIST INFO chunk of a WAV file through a previous call to the TagsReader.WAV_ListInfoChunkUniqueFramesCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WAV_ListInfoChunkUniqueFramesIdGet (

nFrameIndex as Integer

) as String

[C++]

BSTR control.TagsReader.WAV_ListInfoChunkUniqueFramesIdGet (

short nFrameIndex

);

Parameter | Description
nFrameIndex | Zero-based index of the frame.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the unique frame identifier


TagsReader.WMA_PictureFrameBitmapGet method

TagsReader.WMA_PictureFrameBitmapGet method

Remarks

Obtains the memory bitmap (HBITMAP) representation of the picture stored inside a WMA picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_PictureFrameBitmapGet (

nIndex as Integer,

hBitmap as OLE_HANDLE,

nOriginalWidth as Long,

nOriginalHeight as Long,

nResizeWidth as Long,

nResizeHeight as Long

) as enumErrorCodes

[C++]

short control.TagsReader.WMA_PictureFrameBitmapGet (

short nIndex,

OLE_HANDLE *hBitmap,

long *nOriginalWidth,

long *nOriginalHeight,

long nResizeWidth,

long nResizeHeight

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the WMA tag can be obtained through a call to the TagsReader.WMA_PictureFrameCountGet method.
hBitmap | Reference that, on return from the method call, will contain the HBITMAP of the picture.
nOriginalWidth | Reference that, on return from the method call, will contain the original width, expressed in pixels, of the picture.
nOriginalHeight | Reference that, on return from the method call, will contain the original height, expressed in pixels, of the picture.
nResizeWidth | Value containing the width, expressed in pixels, for horizontally resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same width returned inside the nOriginalWidth parameter.
nResizeHeight | Value containing the height, expressed in pixels, for vertically resizing the picture before returning the HBITMAP; this parameter is ignored if set to 0 in which case the picture represented by the HBITMAP handle will have the same height returned inside the nOriginalHeight parameter.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.WMA_PictureFrameCountGet method

TagsReader.WMA_PictureFrameCountGet method

Remarks

Obtains the number of picture frames, identified by the "WM/Picture" attribute, available inside the WMA tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_PictureFrameCountGet (

) as Integer

[C++]

short control.TagsReader.WMA_PictureFrameCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of picture frames available inside the WMA tag


TagsReader.WMA_PictureFrameFileGet method

TagsReader.WMA_PictureFrameFileGet method

Remarks

Creates a graphic file, of a given graphic format, containing the picture stored inside a WMA picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_PictureFrameFileGet (

nIndex as Integer,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Long

) as enumErrorCodes

[C++]

short control.TagsReader.WMA_PictureFrameFileGet (

short nIndex,

BSTR strPathname,

short nFormat,

long nFormatParameter

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the WMA tag can be obtained through a call to the TagsReader.WMA_PictureFrameCountGet method.

strPathname

String representing the absolute pathname of the output graphic file.

nFormat

Graphic format of the output graphic file.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_ORIGINAL | -1 | Original format used to store the picture inside the tag. When this option is selected, the output graphic file will be an exact copy of the contents of the picture frame. You can determine the original graphic format, through its MIME type, by calling the TagsReader.WMA_PictureFrameInfoGet method with the parameter nInfo set to ID3V2_FRAME_INFO_MIME_TYPE; this information can be also useful to determine the file extension to use when composing the strPathname parameter above.
GRAPHIC_FORMAT_BMP | 0 | The output file will be converted to BMP format
GRAPHIC_FORMAT_JPEG | 1 | The output file will be converted to JPEG format
GRAPHIC_FORMAT_PNG | 2 | The output file will be converted to PNG format
GRAPHIC_FORMAT_GIF | 3 | The output file will be converted to GIF format
GRAPHIC_FORMAT_TIFF | 4 | The output file will be converted to TIFF format

nFormatParameter

Eventual parameter required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.WMA_PictureFrameInfoGet method

TagsReader.WMA_PictureFrameInfoGet method

Remarks

Obtains textual information about the given WMA picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_PictureFrameInfoGet (

nIndex as Integer,

nInfo as enumId3v2FrameInfo

) as String

[C++]

BSTR control.TagsReader.WMA_PictureFrameInfoGet (

short nIndex,

short nInfo

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the WMA tag can be obtained through a call to the TagsReader.WMA_PictureFrameCountGet method.

nInfo

Type of information that needs to be retrieved.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_FRAME_INFO_DESCRIPTION | 1 | Description
ID3V2_FRAME_INFO_CONTENT_TYPE_TEXT | 3 | Content type textual description
ID3V2_FRAME_INFO_MIME_TYPE | 4 | Mime type

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the requested information


TagsReader.WMA_PictureFrameMemoryFileGet method

TagsReader.WMA_PictureFrameMemoryFileGet method

Remarks

Obtains a copy in memory of the picture file stored inside a WMA picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_PictureFrameMemoryFileGet (

nIndex as Integer,

pBuffer as variant,

nBufferLen as long

) as enumErrorCodes

[C++]

short control.TagsReader.WMA_PictureFrameMemoryFileGet (

short nIndex,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the WMA tag can be obtained through a call to the TagsReader.WMA_PictureFrameCountGet method.
pBuffer | Output buffer that, on return from the method call, will contain the picture file data
nBufferLength | Length of the buffer expressed in bytes

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.

Below you can find a couple of samples that demonstrate how to retrieve a picture and store it inside a memory buffer in Visual Basic 6 and Visual C++ 6:

Visual Basic 6

Private Sub Command1_Click()

' obtain the size in bytes of the first available picture (having index 0)

Dim nSizeInBytes As Long

ActiveSoundEditor1.TagsReader.WMA_PictureFrameSizeGet 0, nSizeInBytes

if nSizeInBytes = 0 then Exit Sub

' allocate the destination buffer

Dim bytImage() As Byte

ReDim bytImage(nSizeInBytes)

' read picture data into the buffer

ActiveSoundEditor1.TagsReader.WMA_PictureFrameMemoryFileGet 0, VarPtr(bytImage(0)), nSizeInBytes

...

use the buffer

...

' erase the buffer and free memory

Erase bytImage

End Sub

Visual C++ 6 with MFC

void CReadId3v2Dlg::OnButton1()

{

long nSizeInBytes = 0;

m_editor.TagsReader.WMA_PictureFrameSizeGet (0, &nSizeInBytes);

if (nSizeInBytes == 0)

   return;

BYTE *pBuffer = new BYTE[nTagSize];

COleVariant var;

var.vt = VT_BYREF | VT_UI1;

var.pbVal = pTagBuffer;

m_editor.TagsReader.WMA_PictureFrameMemoryFileGet (0, var, nSizeInBytes);

...

use the buffer

...

delete pBuffer;

}


TagsReader.WMA_PictureFrameSizeGet method

TagsReader.WMA_PictureFrameSizeGet method

Remarks

Obtains the size of the picture stored inside a WMA picture frame .

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_PictureFrameSizeGet (

nIndex as Integer,

nSize as Long

) as enumErrorCodes

[C++]

short control.TagsReader.WMA_PictureFrameSizeGet (

short nIndex,

long *nSize

);

Parameter | Description
nIndex | Zero-based index of the picture frame. The total number of picture frames available inside the WMA tag can be obtained through a call to the TagsReader.WMA_PictureFrameCountGet method.
nSize | Reference that, on return from the method call, will contain the size in bytes of the picture stored inside the frame.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.WMA_PictureFrameTypeGet method

TagsReader.WMA_PictureFrameTypeGet method

Remarks

Obtains the type of picture stored inside a WMA picture frame.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_PictureFrameTypeGet (

nIndex as Integer,

nPictureType as enumId3v2PictureType

) as enumErrorCodes

[C++]

short control.TagsReader.WMA_PictureFrameTypeGet (

short nIndex,

short *nPictureType

);

Parameter

Description

nIndex

Zero-based index of the picture frame. The total number of picture frames available inside the WMA tag can be obtained through a call to the TagsReader.WMA_PictureFrameCountGet method.

nPictureType

Reference that, on return from the method call, will contain the type of picture stored inside the frame.

Supported values are the following:

Mnemonic Value | Value | Meaning
ID3V2_PICTURE_OTHER | 0 | Other
ID3V2_PICTURE_ICON_32x32 | 1 | 32x32 icon
ID3V2_PICTURE_ICON_OTHER | 2 | Other icon
ID3V2_PICTURE_COVER_FRONT | 3 | Front cover
ID3V2_PICTURE_COVER_BACK | 4 | Back cover
ID3V2_PICTURE_LEAFLET_PAGE | 5 | Leaflet page
ID3V2_PICTURE_MEDIA | 6 | Media (e.g. label side of CD)
ID3V2_PICTURE_LEAD_ARTIST_PERFORMER_SOLOIST | 7 | Lead artist/lead performer/soloist
ID3V2_PICTURE_ARTIST_PERFORMER | 8 | Artist/performer
ID3V2_PICTURE_CONDUCTOR | 9 | Conductor
ID3V2_PICTURE_BAND_ORCHESTRA | 10 | Band/Orchestra
ID3V2_PICTURE_COMPOSER | 11 | Composer
ID3V2_PICTURE_LYRICIST_TEXT_WRITER | 12 | Lyricist/text writer
ID3V2_PICTURE_RECORDING_LOCATION | 13 | Recording Location
ID3V2_PICTURE_DURING_RECORDING | 14 | During recording
ID3V2_PICTURE_DURING_PERFORMANCE | 15 | During performance
ID3V2_PICTURE_MOVIE_VIDEO_SCREEN_CAPTURE | 16 | Movie/video screen capture
ID3V2_PICTURE_BRIGHT_FISH | 17 | A bright coloured fish
ID3V2_PICTURE_ILLUSTRATION | 18 | Illustration
ID3V2_PICTURE_BAND_ARTIST_LOGO | 19 | Band/artist logotype
ID3V2_PICTURE_PUBLISHER_STUDIO_LOGO | 20 | Publisher/Studio logotype

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


TagsReader.WMA_TextFrameGet method

TagsReader.WMA_TextFrameGet method

Remarks

Obtains contents of a specific text-based frame of the WMA tag.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_TextFrameGet (

strFrameId as String

) as String

[C++]

BSTR control.TagsReader.WMA_TextFrameGet (

BSTR strFrameId

);

Parameter | Description
strFrameId | String containing the identifier of the specific frame to get. Typical identifiers are "Author", "Title", "WM/AlbumArtist", "WM/Genre", etc. A list of identifiers for WMA frames can be found inside the Windows Media Format SDK.

Return value

Value | Meaning
Empty string | The information is not available or an error occurred (see the LastError property for further error details)
Valid string | String with the content of the requested frame


TagsReader.WMA_UniqueFramesCountGet method

TagsReader.WMA_UniqueFramesCountGet method

Remarks

Obtains the number of unique frames found inside the WMA tag. The identifier of each unique frame can be obtained through the TagsReader.WMA_UniqueFramesIdGet method.

Certain WMA frames, for example the "WM/Picture" one, can be available in multiple instances inside the same WMA tag: when this method is called, the enumeration will not keep count of multiple instances of a specific frame but will only report the availability of the frame itself; once the availability of a specific frame is known, single specific frames of type "WM/Picture" can be enumerated using the TagsReader.WMA_PictureFrameCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_UniqueFramesCountGet (

) as Integer

[C++]

short control.TagsReader.WMA_UniqueFramesCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Other values | The number of unique frames found inside the WMA tag


TagsReader.WMA_UniqueFramesIdGet method

TagsReader.WMA_UniqueFramesIdGet method

Remarks

Obtains a unique frame identifier between the list of unique frames enumerated inside the WMA tag through a previous call to the TagsReader.WMA_UniqueFramesCountGet method.

For further details about methods related to tags reading refer to the TagsReader object.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

control.TagsReader.WMA_UniqueFramesIdGet (

nFrameIndex as Integer

) as String

[C++]

BSTR control.TagsReader.WMA_UniqueFramesIdGet (

short nFrameIndex

);

Parameter | Description
nFrameIndex | Zero-based index of the frame.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the unique frame identifier


VideoMixer object

VideoMixer object

The VideoMixer object, accessible through the control's VideoMixer property, is internally implemented as a COM interface called IVideoMixer and allows mixing/blending video clips through DirectShow inside the same output window. As a further feature it provides support for On-Screen-Display (OSD).

For details about video mixing refer to the How to use the video mixer and the How to combine the video mixer and the automatic fader tutorials.

The VideoMixer object is implemented through the following methods:

Methods

BackgroundColorSet

Create

Destroy

GetHWND

Move

OSDBackgroundBitmapSet

OSDBackgroundPictureFileSet

OSDEnable

OSDIsEnabled

OSDItemAlphaGet

OSDItemAlphaSet

OSDItemBitmapAdd

OSDItemBitmapChange

OSDItemBitmapGet

OSDItemChangeAlignment

OSDItemIsOnVisibleArea

OSDItemMove

OSDItemMovementSet

OSDItemNormalizedRectGet

OSDItemOutlineTextAdd

OSDItemOutlineTextChange

OSDItemPictureFileAdd

OSDItemPictureFileChange

OSDItemPictureMemoryAdd

OSDItemPictureMemoryChange

OSDItemRectangleAdd

OSDItemRectangleChange

OSDItemRemove

OSDItemScrollByPixels

OSDItemShow

OSDItemTextAdd

OSDItemTextChange

OSDItemZOrderGet

OSDItemZOrderSet

OSDKeyColorGet

OSDKeyColorSet

OSDNormalizedRectGet

OSDNormalizedRectSet

PlayerAlphaGet

PlayerAlphaSet

PlayerNormalizedRectGet

PlayerNormalizedRectSet

PlayerNormalizedRectSetIdeal

PlayerZOrderGet

PlayerZOrderSet

Reset

Show

Examples of use of the VideoMixer object in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- VideoMixer

- VideoMixerWithFader


VideoMixer.BackgroundColorSet method

VideoMixer.BackgroundColorSet method

Remarks

Modifies the color used to render the video mixer window background.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.BackgroundColorSet (

nMixerUniqueId as Long,

colorBackground as OLE_COLOR

) as enumErrorCodes

[C++]

short control.VideoMixer.BackgroundColorSet (

long nMixerUniqueId,

OLE_COLOR colorBackground

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
colorBackground | Color used to render the video mixer background

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.Create method

VideoMixer.Create method

Remarks

Creates the video mixer: only one instance of the video mixer can be created during the life of the container application.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.Create (

hWndParent as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long,

colorBackground as OLE_COLOR

) as Long

[C++]

long control.VideoMixer.Create (

OLE_HANDLE hWndParent,

long nLeft,

long nTop,

long nWidth,

long nHeight,

OLE_COLOR colorBackground

);

Parameter | Description
hWndParent | Handle of the parent window used for the video mixing rendering
nLeft | Left position of the video mixer window, expressed in client coordinates (pixels) of the parent window
nTop | Top position of the video mixer window, expressed in client coordinates (pixels) of the parent window
nWidth | Width of the video mixer window, expressed in pixels
nHeight | Height of the video mixer window, expressed in pixels
colorBackground | Color used to render the video mixer background

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the video mixer: this unique identifier will be used in order to invoke further methods related to the use of the video mixer


VideoMixer.Destroy method

VideoMixer.Destroy method

Remarks

Destroys the instance of the video mixer and detaches attached players.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.Destroy (

nMixerUniqueId as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.Destroy (

long nMixerUniqueId

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.GetHWND method

VideoMixer.GetHWND method

Remarks

Obtains the window handle (HWND) of the video mixer rendering window.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.GetHWND (

nMixerUniqueId as Long

) as Long

[C++]

long control.VideoMixer.GetHWND (

long nMixerUniqueId

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Other values | The HWND of the video rendering window


VideoMixer.Move method

VideoMixer.Move method

Remarks

Moves/resizes the video mixer rendering window.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.Move (

nMixerUniqueId as Long,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.Move (

long nMixerUniqueId,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nLeft | Left position of the video mixer window, expressed in client coordinates (pixels) of the parent window
nTop | Top position of the video mixer window, expressed in client coordinates (pixels) of the parent window
nWidth | Width of the video mixer window, expressed in pixels
nHeight | Height of the video mixer window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDBackgroundBitmapSet method

VideoMixer.OSDBackgroundBitmapSet method

Remarks

Sets a bitmap to display as a background for the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDBackgroundBitmapSet (

nMixerUniqueId as Long,

hBitmap as OLE_HANDLE,

bKeepAspectRatio as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDBackgroundBitmapSet (

long nMixerUniqueId,

OLE_HANDLE hBitmap,

short bKeepAspectRatio

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

hBitmap

Handle of the bitmap (HBITMAP). You can set this parameter to 0 for removing an existing background bitmap.

bKeepAspectRatio

Boolean value that determines if the bitmap must keep its original aspect ratio

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Don't keep aspect ratio
BOOL_TRUE | 1 | Keep aspect ratio

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDBackgroundPictureFileSet method

VideoMixer.OSDBackgroundPictureFileSet method

Remarks

Sets a picture file to display as a background for the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDBackgroundPictureFileSet (

nMixerUniqueId as Long,

strPathname as String,

bKeepAspectRatio as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDBackgroundPictureFileSet (

long nMixerUniqueId,

LPCTSTR strPathname,

short bKeepAspectRatio

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

strPathname

Absolute pathname of the picture file.

Accepted picture formats are BMP, GIF, JPEG and PNG.

You can use an empty string for removing an existing background bitmap.

bKeepAspectRatio

Boolean value that determines if the bitmap must keep its original aspect ratio

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Don't keep aspect ratio
BOOL_TRUE | 1 | Keep aspect ratio

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDEnable method

VideoMixer.OSDEnable method

Remarks

Enables/disables the On-Screen-Display (OSD) that will be used to show graphics over the video mixer window. You can know if the OSD is enabled or disabled through a call to the VideoMixer.OSDIsEnabled method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDEnable (

nMixerUniqueId as Long,

bEnable as enumBoolean,

bZoomContentsOnResize as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDEnable (

long nMixerUniqueId,

short bEnable,

short bZoomContentsOnResize

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

bEnable

Boolean value that determines if the OSD is enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Disable the OSD
BOOL_TRUE | 1 | Enable the OSD

bZoomContentsOnResize

Boolean value that determines if items inside the OSD will be zoomed to fit inside the OSD area after a resize of the video mixer window.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Don't zoom items on resize of the video mixer window
BOOL_TRUE | 1 | Zoom items on resize of the video mixer window

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDIsEnabled method

VideoMixer.OSDIsEnabled method

Remarks

Checks if the On-Screen-Display (OSD) for the given video mixer is enabled or disabled. The OSD can be enabled/disabled through the VideoMixer.OSDEnable method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDIsEnabled (

nMixerUniqueId as Long

) as Boolean

[C++]

BOOL control.VideoMixer.OSDIsEnabled (

long nMixerUniqueId

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The OSD is disabled
BOOL_TRUE | 1 | The OSD is enabled


VideoMixer.OSDItemAlphaGet method

VideoMixer.OSDItemAlphaGet method

Remarks

Obtains the current alpha channel transparency applied to the graphical item on the On-Screen-Display (OSD). The value can be modified through the VideoMixer.OSDItemAlphaSet method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemAlphaGet (

nMixerUniqueId as Long,

nItemUniqueId as Long,

nAlpha as Integer

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemAlphaGet (

long nMixerUniqueId,

long nItemUniqueId,

short *nAlpha

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd
nAlpha | Reference that, on return from the method call, will contain the alpha channel transparency expressed in percentage. Values can range from 0 (total opacity) to 100 (total transparency).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemAlphaSet method

VideoMixer.OSDItemAlphaSet method

Remarks

Sets the alpha channel transparency applied to the graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemAlphaSet (

nMixerUniqueId as Long,

nItemUniqueId as Long,

nAlpha as Integer

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemAlphaSet (

long nMixerUniqueId,

long nItemUniqueId,

short nAlpha

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd
nAlpha | The alpha channel transparency expressed in percentage. Values can range from 0 (total opacity) to 100 (total transparency).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemBitmapAdd method

VideoMixer.OSDItemBitmapAdd method

Remarks

Adds a new graphical item to the On-Screen-Display (OSD) by getting its representation from memory bitmap.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemBitmapAdd (

nMixerUniqueId as Long,

hBitmap as OLE_HANDLE,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean

) as Long

[C++]

long control.VideoMixer.OSDItemBitmapAdd (

long nMixerUniqueId,

OLE_HANDLE hBitmap,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

hBitmap

Handle of the bitmap (HBITMAP). The bitmap can be modified at a later time through the VideoMixer.OSDItemBitmapChange method.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoMixer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoMixer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoMixer.OSDItemShow method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoMixer.OSDItemBitmapChange method

VideoMixer.OSDItemBitmapChange method

Remarks

Changes the bitmap for an existing graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemBitmapChange (

nMixerUniqueId as Long,

nItemUniqueId as Long,

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemBitmapChange (

long nMixerUniqueId,

long nItemUniqueId,

OLE_HANDLE hBitmap

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoMixer.OSDItemBitmapAdd method
hBitmap | Handle of the bitmap (HBITMAP).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemBitmapGet method

VideoMixer.OSDItemBitmapGet method

Remarks

Obtains the bitmap for an existing graphical item previously added to the On-Screen-Display (OSD) through a call to the VideoMixer.OSDItemBitmapAdd or VideoMixer.OSDItemPictureFileAdd or VideoMixer.OSDItemPictureMemoryAdd methods.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemBitmapGet (

nMixerUniqueId as Long,

nItemUniqueId as Long,

hBitmap as OLE_HANDLE,

nOriginalWidth as Long,

nOriginalHeight as Long,

nResizeWidth as Long,

nResizeHeight as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemBitmapGet (

long nMixerUniqueId,

long nItemUniqueId,

OLE_HANDLE *hBitmap,

long *nOriginalWidth,

long *nOriginalHeight,

long nResizeWidth,

long nResizeHeight

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoMixer.OSDItemBitmapAdd method
hBitmap | Reference that, on return from the method call, will contain the handle of the bitmap (HBITMAP).
nOriginalWidth | Reference that, on return from the method call, will contain the original width, expressed in pixels, of the picture
nOriginalHeight | Reference that, on return from the method call, will contain the original height, expressed in pixels, of the picture
nResizeWidth | Width, expressed in pixels, for resizing the picture before returning the HBITMAP; ignored if set to 0
nResizeHeight | Height, expressed in pixels, for resizing the picture before returning the HBITMAP; ignored if set to 0

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemChangeAlignment method

VideoMixer.OSDItemChangeAlignment method

Remarks

Changes the alignment of the graphical item respect to the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemChangeAlignment (

nMixerUniqueId as Long,

nItemUniqueId as Long,

nAlignment as enumRectAlignment

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemChangeAlignment (

long nMixerUniqueId,

long nItemUniqueId,

short nAlignment

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

nItemUniqueId

Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd

nAlignment

Alignment of the item's rectangle respect to the rectangle of the OSD.

Supported values are the following:

Mnemonic constant | Value | Meaning
RECT_ALIGN_LEFT_TOP | 0 | Item is Left-Top aligned
RECT_ALIGN_CENTER_TOP | 1 | Item is Center-Top aligned
RECT_ALIGN_RIGHT_TOP | 2 | Item is Right-Top aligned
RECT_ALIGN_LEFT_MIDDLE | 3 | Item is Left-Middle aligned
RECT_ALIGN_CENTER_MIDDLE | 4 | Item is Center-Middle aligned
RECT_ALIGN_RIGHT_MIDDLE | 5 | Item is Right-Middle aligned
RECT_ALIGN_LEFT_BOTTOM | 6 | Item is Left-Bottom aligned
RECT_ALIGN_CENTER_BOTTOM | 7 | Item is Center-Bottom aligned
RECT_ALIGN_RIGHT_BOTTOM | 8 | Item is Right-Bottom aligned

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemIsOnVisibleArea method

VideoMixer.OSDItemIsOnVisibleArea method

Remarks

Determines if the given graphical item is currently positioned inside the visible area of the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemIsOnVisibleArea (

nMixerUniqueId as Long,

nItemUniqueId as Long,

bIsVisible as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemIsOnVisibleArea (

long nMixerUniqueId,

long nItemUniqueId,

short *bIsVisible

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

nItemUniqueId

Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd

bIsVisible

Reference to a boolean value that, on return from the method call, will tell if the item is inside the visible area of the OSD.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is outside of the visible area
BOOL_TRUE | 1 | The item is inside the visible area

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemMove method

VideoMixer.OSDItemMove method

Remarks

Moves the position of the graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemMove (

nMixerUniqueId as Long,

nItemUniqueId as Long,

fLeftPos as Single,

fTopPos as Single

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemMove (

long nMixerUniqueId,

long nItemUniqueId,

float fLeftPos,

float fTopPos

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd
fLeftPos | Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.
fTopPos | Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemMovementSet method

VideoMixer.OSDItemMovementSet method

Remarks

Sets the movement direction for the given graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemMovementSet (

nMixerUniqueId as Long,

nItemUniqueId as Long,

nDirection as enumOSDAutoMoveDirection,

nSpeedInPixPerSec as Integer

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemMovementSet (

long nMixerUniqueId,

long nItemUniqueId,

short nDirection,

short nSpeedInPixPerSec

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

nItemUniqueId

Unique identifier of item returned by a previous call to one between the VideoMixer.OSDItemTextAdd, VideoMixer.OSDItemOutlineTextAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemPictureMemoryAdd or VideoMixer.OSDItemRectangleAdd methods.

nDirection

Movement direction.

Supported values are the following:

Mnemonic constant | Value | Meaning
OSD_ITEM_AUTO_MOVE_NONE | 0 | No movement
OSD_ITEM_AUTO_MOVE_LEFT | 1 | Moves the item from right to left
OSD_ITEM_AUTO_MOVE_RIGHT | 2 | Moves the item from left to right
OSD_ITEM_AUTO_MOVE_TOP | 3 | Moves the item from bottom to top
OSD_ITEM_AUTO_MOVE_BOTTOM | 4 | Moves the item from top to bottom

nSpeedInPixPerSec

Movement speed expressed in pixels per second

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemNormalizedRectGet method

VideoMixer.OSDItemNormalizedRectGet method

Remarks

Obtains the normalized rectangle, respect to the On-Screen-Display (OSD) area, for the given item of the OSD.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemNormalizedRectGet (

nMixerUniqueId as Long,

nItemUniqueId as Long,

fLeft as Single,

fTop as Single,

fRight as Single,

fBottom as Single

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemNormalizedRectGet (

long nMixerUniqueId,

long nItemUniqueId,

float *fLeft,

float *fTop,

float *fRight,

float *fBottom

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd
fLeft | Reference that, on return from the method call, will contain the current left position, expressed in percentage, of the item's rectangle respect to the rectangle of the OSD
fTop | Reference that, on return from the method call, will contain the current top position, expressed in percentage, of the item's rectangle respect to the rectangle of the OSD
fRight | Reference that, on return from the method call, will contain the current right position, expressed in percentage, of the item's rectangle respect to the rectangle of the OSD
fBottom | Reference that, on return from the method call, will contain the current bottom position, expressed in percentage, of the item's rectangle respect to the rectangle of the OSD

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemOutlineTextAdd method

VideoMixer.OSDItemOutlineTextAdd method

Remarks

Adds a string of outlined text as a new graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemOutlineTextAdd (

nMixerUniqueId as Long,

strText as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean,

pLogFont as Long,

strFacename as String,

color as OLE_COLOR,

colorOutline as OLE_COLOR,

nAlignment as enumTextAlignment,

nOutlineWidth as Integer

) as Long

[C++]

long control.VideoMixer.OSDItemOutlineTextAdd (

long nMixerUniqueId,

LPCTSTR strText,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow,

long pLogFont,

LPCTSTR strFacename,

OLE_COLOR color,

OLE_COLOR colorOutline,

short nAlignment,

short nOutlineWidth

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

strText

Text string.

The text string can can be modified at a later time through the VideoMixer.OSDItemOutlineTextChange method.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoMixer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoMixer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoMixer.OSDItemShow method.

pLogFont

Address in memory of the the LOGFONT structure containing the font settings used to render this item.

Refer to the Microsoft documentation for details about the LOGFONT structure. The lfFaceName member of the LOGFONT structure is currently ignored: use the strFacename parameter below for passing the typeface of the font.

This setting can can be modified at a later time through the VideoMixer.OSDItemOutlineTextChange method.

strFacename

String containing the typeface of the font, for example "Arial" or "Times New Roman".

This setting can can be modified at a later time through the VideoMixer.OSDItemOutlineTextChange method.

color

Color used to render this item.

This setting can can be modified at a later time through the VideoMixer.OSDItemOutlineTextChange method.

colorOutline

Color used to render the outline of the text.

This setting can can be modified at a later time through the VideoMixer.OSDItemOutlineTextChange method.

nAlignment

Text alignment respect to the item's rectangle.

Supported values are the following:

Mnemonic constant | Value | Meaning
TEXT_ALIGN_LEFT | 0 | Text is left aligned
TEXT_ALIGN_CENTER | 1 | Text is centered
TEXT_ALIGN_RIGHT | 2 | Text is right aligned

This setting can can be modified at a later time through the VideoMixer.OSDItemOutlineTextChange method.

nOutlineWidth

Width of the outline expressed in pixels.

This setting can can be modified at a later time through the VideoMixer.OSDItemOutlineTextChange method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoMixer.OSDItemOutlineTextChange method

VideoMixer.OSDItemOutlineTextChange method

Remarks

Changes the string and settings of the given outlined text item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemOutlineTextChange (

nMixerUniqueId as Long,

nItemUniqueId as Long,

strText as String,

pLogFont as long,

strFacename as String,

color as OLE_COLOR,

colorOutline as OLE_COLOR,

nAlignment as enumTextAlignment,

nOutlineWidth as Integer

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemOutlineTextChange (

long nMixerUniqueId,

long nItemUniqueId,

LPCTSTR strText,

long pLogFont,

LPCTSTR strFacename,

OLE_COLOR color,

OLE_COLOR colorOutline,

short nAlignment,

short nOutlineWidth

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

nItemUniqueId

Unique identifier of item returned by a previous call to the VideoMixer.OSDItemOutlineTextAdd method

strText

Text string

pLogFont

Address in memory of the the LOGFONT structure containing the font settings used to render this item.

Refer to the Microsoft documentation for details about the LOGFONT structure. The lfFaceName member of the LOGFONT structure is currently ignored: use the strFacename parameter below for passing the typeface of the font.

strFacename

String containing the typeface of the font, for example "Arial" or "Times New Roman"

color

Color used to render this item

colorOutline

Color used to render the outline of the text.

nAlignment

Text alignment respect to the item's rectangle.

Supported values are the following:

Mnemonic constant | Value | Meaning
TEXT_ALIGN_LEFT | 0 | Text is left aligned
TEXT_ALIGN_CENTER | 1 | Text is centered
TEXT_ALIGN_RIGHT | 2 | Text is right aligned

nOutlineWidth

Width of the outline expressed in pixels.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemPictureFileAdd method

VideoMixer.OSDItemPictureFileAdd method

Remarks

Adds a new graphical item to the On-Screen-Display (OSD) by getting its representation from a picture file.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemPictureFileAdd (

nMixerUniqueId as Long,

strPathname as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean

) as Long

[C++]

long control.VideoMixer.OSDItemPictureFileAdd (

long nMixerUniqueId,

LPCTSTR strPathname,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

strPathname

Absolute pathname of the picture file. The picture file can be modified at a later time through the VideoMixer.OSDItemPictureFileChange method.

Accepted picture formats are BMP, GIF, JPEG and PNG.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoMixer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoMixer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoMixer.OSDItemShow method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoMixer.OSDItemPictureFileChange method

VideoMixer.OSDItemPictureFileChange method

Remarks

Changes the picture for an existing graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemPictureFileChange (

nMixerUniqueId as Long,

nItemUniqueId as Long,

strPathname as String

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemPictureFileChange (

long nMixerUniqueId,

long nItemUniqueId,

LPCTSTR strPathname

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoMixer.OSDItemPictureFileAdd method
strPathname | Absolute pathname of the picture file. Accepted picture formats are BMP, GIF, JPEG and PNG.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemPictureMemoryAdd method

VideoMixer.OSDItemPictureMemoryAdd method

Remarks

Adds a new graphical item to the On-Screen-Display (OSD) by getting its representation from a picture file stored inside a memory buffer.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemPictureMemoryAdd (

nMixerUniqueId as Long,

pBuffer as Variant,

nBufferLength as Long,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean

) as Long

[C++]

long control.VideoMixer.OSDItemPictureMemoryAdd (

long nMixerUniqueId,

const VARIANT FAR& pBuffer,

long nBufferLength,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

pBuffer

Variant parameter containing the pointer to the picture file previously loaded in memory. The picture can be modified at a later time through the VideoMixer.OSDItemPictureMemoryChange method.

Accepted picture formats to store inside the memory buffer are BMP, GIF, JPEG and PNG.

nBufferLength

Length in bytes of the given buffer

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoMixer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoMixer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoMixer.OSDItemShow method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoMixer.OSDItemPictureMemoryChange method

VideoMixer.OSDItemPictureMemoryChange method

Remarks

Changes the picture for an existing graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemPictureMemoryChange (

nMixerUniqueId as Long,

nItemUniqueId as Long,

pBuffer as Variant,

nBufferLength as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemPictureMemoryChange (

long nMixerUniqueId,

long nItemUniqueId,

const VARIANT FAR& pBuffer,

long nBufferLength

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoMixer.OSDItemPictureMemoryAdd method
pBuffer | Variant parameter containing the pointer to the picture file previously loaded in memory. Accepted picture formats are BMP, GIF, JPEG and PNG.
nBufferLength | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemRectangleAdd method

VideoMixer.OSDItemRectangleAdd method

Remarks

Adds a rectangle as a new graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemRectangleAdd (

nMixerUniqueId as Long,

fLeftPos as Single,

fTopPos as Single,

fWidth as Single,

fHeight as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean,

color as OLE_COLOR

) as Long

[C++]

long control.VideoMixer.OSDItemRectangleAdd (

long nMixerUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

short nAlpha,

long nZOrder,

short bShow,

OLE_COLOR color

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method or through the VideoMixer.OSDItemRectangleChange method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method or through the VideoMixer.OSDItemRectangleChange method.

fWidth

Width, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle.

Size can be modified at a later time through the VideoMixer.OSDItemRectangleChange method..

fHeight

Height, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle.

Size can be modified at a later time through the VideoMixer.OSDItemRectangleChange method..

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoMixer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoMixer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoMixer.OSDItemShow method.

color

Color used to render this item.

This setting can can be modified at a later time through the VideoMixer.OSDItemRectangleChange method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoMixer.OSDItemRectangleChange method

VideoMixer.OSDItemRectangleChange method

Remarks

Changes characteristics of the given rectangle on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemRectangleChange (

nMixerUniqueId as Long,

nItemUniqueId as Long,

fLeftPos as Single,

fTopPos as Single,

fWidth as Single,

fHeight as Single,

color as OLE_COLOR

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemRectangleChange (

long nMixerUniqueId,

long nItemUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

OLE_COLOR color

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoMixer.OSDItemRectangleAdd method
fLeftPos | Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.
fTopPos | Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.
fWidth | Width, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle.
fHeight | Height, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle.
color | Color used to render this item.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemRemove method

VideoMixer.OSDItemRemove method

Remarks

Removes the given graphical item from the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemRemove (

nMixerUniqueId as Long,

nItemUniqueId as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemRemove (

long nMixerUniqueId,

long nItemUniqueId

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd Set this parameter to -1 for removing all of the available items in one single shot.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemScrollByPixels method

VideoMixer.OSDItemScrollByPixels method

Remarks

Scrolls the position of the graphical item on the On-Screen-Display (OSD) by a given amount of pixels.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemScrollByPixels (

nMixerUniqueId as Long,

nItemUniqueId as Long,

xOffset as Long,

yOffset as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemScrollByPixels (

long nMixerUniqueId,

long nItemUniqueId,

long xOffset,

long yOffset

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd
xOffset | Horizontal offset, expressed in pixels, used to scroll the item
yOffset | Vertical offset, expressed in pixels, used to scroll the item

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemShow method

VideoMixer.OSDItemShow method

Remarks

Shows/hides the graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemShow (

nMixerUniqueId as Long,

nItemUniqueId as Long,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemShow (

long nMixerUniqueId,

long nItemUniqueId,

short bShow

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

nItemUniqueId

Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd

bShow

Boolean value that determines if the item must be shown or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the item
BOOL_TRUE | 1 | Shows the item

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemTextAdd method

VideoMixer.OSDItemTextAdd method

Remarks

Adds a string of text as a new graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemTextAdd (

nMixerUniqueId as Long,

strText as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean,

pLogFont as Long,

strFacename as String,

color as OLE_COLOR,

nAlignment as enumTextAlignment

) as Long

[C++]

long control.VideoMixer.OSDItemTextAdd (

long nMixerUniqueId,

LPCTSTR strText,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow,

long pLogFont,

LPCTSTR strFacename,

OLE_COLOR color,

short nAlignment

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

strText

Text string.

The text string can can be modified at a later time through the VideoMixer.OSDItemTextChange method.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoMixer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoMixer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoMixer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoMixer.OSDItemShow method.

pLogFont

Address in memory of the the LOGFONT structure containing the font settings used to render this item.

Refer to the Microsoft documentation for details about the LOGFONT structure. The lfFaceName member of the LOGFONT structure is currently ignored: use the strFacename parameter below for passing the typeface of the font.

This setting can can be modified at a later time through the VideoMixer.OSDItemTextChange method.

strFacename

String containing the typeface of the font, for example "Arial" or "Times New Roman".

This setting can can be modified at a later time through the VideoMixer.OSDItemTextChange method.

color

Color used to render this item.

This setting can can be modified at a later time through the VideoMixer.OSDItemTextChange method.

nAlignment

Text alignment respect to the item's rectangle.

Supported values are the following:

Mnemonic constant | Value | Meaning
TEXT_ALIGN_LEFT | 0 | Text is left aligned
TEXT_ALIGN_CENTER | 1 | Text is centered
TEXT_ALIGN_RIGHT | 2 | Text is right aligned

This setting can can be modified at a later time through the VideoMixer.OSDItemTextChange method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoMixer.OSDItemTextChange method

VideoMixer.OSDItemTextChange method

Remarks

Changes the string and settings of the given text item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemTextChange (

nMixerUniqueId as Long,

nItemUniqueId as Long,

strText as String,

pLogFont as long,

strFacename as String,

color as OLE_COLOR,

nAlignment as enumTextAlignment

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemTextChange (

long nMixerUniqueId,

long nItemUniqueId,

LPCTSTR strText,

long pLogFont,

LPCTSTR strFacename,

OLE_COLOR color,

short nAlignment

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

nItemUniqueId

Unique identifier of item returned by a previous call to the VideoMixer.OSDItemTextAdd method

strText

Text string

pLogFont

Address in memory of the the LOGFONT structure containing the font settings used to render this item.

Refer to the Microsoft documentation for details about the LOGFONT structure. The lfFaceName member of the LOGFONT structure is currently ignored: use the strFacename parameter below for passing the typeface of the font.

strFacename

String containing the typeface of the font, for example "Arial" or "Times New Roman"

color

Color used to render this item

nAlignment

Text alignment respect to the item's rectangle.

Supported values are the following:

Mnemonic constant | Value | Meaning
TEXT_ALIGN_LEFT | 0 | Text is left aligned
TEXT_ALIGN_CENTER | 1 | Text is centered
TEXT_ALIGN_RIGHT | 2 | Text is right aligned

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemZOrderGet method

VideoMixer.OSDItemZOrderGet method

Remarks

Obtains the current Z-Order applied to the graphical item on the On-Screen-Display (OSD). The value for the Z-Order can be modified through the VideoMixer.OSDItemZOrderSet method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemZOrderGet (

nMixerUniqueId as Long,

nItemUniqueId as Long,

nZOrder as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemZOrderGet (

long nMixerUniqueId,

long nItemUniqueId,

long *nZOrder

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd
nZOrder | Reference that, on return from the method call, will contain the Z-Order for the given OSD item. Items with a lower Z-Order value will stay on top respect to other items having a higher Z-Order value; for example, an item with Z-Order 0 will stay on top of any other item but, in case two items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDItemZOrderSet method

VideoMixer.OSDItemZOrderSet method

Remarks

Sets the Z-Order applied to the graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDItemZOrderSet (

nMixerUniqueId as Long,

nItemUniqueId as Long,

nZOrder as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDItemZOrderSet (

long nMixerUniqueId,

long nItemUniqueId,

long nZOrder

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoMixer.OSDItemPictureFileAdd, VideoMixer.OSDItemBitmapAdd, VideoMixer.OSDItemTextAdd or VideoMixer.OSDItemRectangleAdd
nZOrder | The Z-Order for the given OSD item. Items with a lower Z-Order value will stay on top respect to other items having a higher Z-Order value; for example, an item with Z-Order 0 will stay on top of any other item but, in case two items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDKeyColorGet method

VideoMixer.OSDKeyColorGet method

Remarks

Obtains the current key color that will be rendered as transparent on the On-Screen-Display (OSD). The key color can be modified through the VideoMixer.OSDKeyColorSet method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDKeyColorGet (

nMixerUniqueId as Long

) as OLE_COLOR

[C++]

OLE_COLOR control.VideoMixer.OSDKeyColorGet (

long nMixerUniqueId

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The current key color


VideoMixer.OSDKeyColorSet method

VideoMixer.OSDKeyColorSet method

Remarks

Sets the key color that will be rendered as transparent on the On-Screen-Display (OSD).

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDKeyColorSet (

nMixerUniqueId as Long,

colorKey as OLE_COLOR

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDKeyColorSet (

long nMixerUniqueId,

OLE_COLOR colorKey

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
colorKey | Key color rendered as transparent

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDNormalizedRectGet method

VideoMixer.OSDNormalizedRectGet method

Remarks

Obtains the normalized rectangle of the On-Screen-Display (OSD) respect to the video mixer window area. The normalized rectangle can be modified through the VideoMixer.OSDNormalizedRectSet method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDNormalizedRectGet (

nMixerUniqueId as Long,

fLeft as Single,

fTop as Single,

fRight as Single,

fBottom as Single

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDNormalizedRectGet (

long nMixerUniqueId,

float *fLeft,

float *fTop,

float *fRight,

float *fBottom

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
fLeft | Reference that, on return from the method call, will contain the current left position, expressed in percentage, of the OSD's rectangle respect to the video mixer window area
fTop | Reference that, on return from the method call, will contain the current top position, expressed in percentage, of the OSD's rectangle respect to the video mixer window area
fRight | Reference that, on return from the method call, will contain the current right position, expressed in percentage, of the OSD's rectangle respect to the video mixer window area
fBottom | Reference that, on return from the method call, will contain the current bottom position, expressed in percentage, of the OSD's rectangle respect to the video mixer window area

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.OSDNormalizedRectSet method

VideoMixer.OSDNormalizedRectSet method

Remarks

Sets the normalized rectangle of the On-Screen-Display (OSD) respect to the video mixer window area.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.OSDNormalizedRectSet (

nMixerUniqueId as Long,

fLeft as Single,

fTop as Single,

fRight as Single,

fBottom as Single

) as enumErrorCodes

[C++]

short control.VideoMixer.OSDNormalizedRectSet (

long nMixerUniqueId,

float fLeft,

float fTop,

float fRight,

float fBottom

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
fLeft | The left position, expressed in percentage, of the OSD's rectangle respect to the video mixer window area
fTop | The top position, expressed in percentage, of the OSD's rectangle respect to the video mixer window area
fRight | The right position, expressed in percentage, of the OSD's rectangle respect to the video mixer window area
fBottom | The bottom position, expressed in percentage, of the OSD's rectangle respect to the video mixer window area

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.PlayerAlphaGet method

VideoMixer.PlayerAlphaGet method

Remarks

Obtains the current value of the alpha channel transparency applied to the given player. The value for the alpha channel transparency can be modified through the VideoMixer.PlayerAlphaSet method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.PlayerAlphaGet (

nMixerUniqueId as Long,

nPlayer as Integer,

nAlpha as Integer

) as enumErrorCodes

[C++]

short control.VideoMixer.PlayerAlphaGet (

long nMixerUniqueId,

short nPlayer,

short *nAlpha

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayer | Number representing the zero-based index of the player attached to the video mixer through a previous call to the VideoPlayer.AttachToVideoMixer method.
nAlpha | Reference that, on return from the method call, will contain the alpha channel transparency expressed in percentage. Values can range from 0 (total opacity) to 100 (total transparency).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.PlayerAlphaSet method

VideoMixer.PlayerAlphaSet method

Remarks

Sets the current value of the alpha channel transparency applied to the given player.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.PlayerAlphaSet (

nMixerUniqueId as Long,

nPlayer as Integer,

nAlpha as Integer

) as enumErrorCodes

[C++]

short control.VideoMixer.PlayerAlphaSet (

long nMixerUniqueId,

short nPlayer,

short nAlpha

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayer | Number representing the zero-based index of the player attached to the video mixer through a previous call to the VideoPlayer.AttachToVideoMixer method.
nAlpha | The alpha channel transparency expressed in percentage. Values can range from 0 (total opacity) to 100 (total transparency).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.PlayerNormalizedRectGet method

VideoMixer.PlayerNormalizedRectGet method

Remarks

Obtains the normalized rectangle of the given player respect to the video mixer window area. The normalized rectangle can be modified through the VideoMixer.PlayerNormalizedRectSet method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.PlayerNormalizedRectGet (

nMixerUniqueId as Long,

nPlayer as Integer,

fLeft as Single,

fTop as Single,

fRight as Single,

fBottom as Single

) as enumErrorCodes

[C++]

short control.VideoMixer.PlayerNormalizedRectGet (

long nMixerUniqueId,

short nPlayer,

float *fLeft,

float *fTop,

float *fRight,

float *fBottom

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayer | Number representing the zero-based index of the player attached to the video mixer through a previous call to the VideoPlayer.AttachToVideoMixer method.
fLeft | Reference that, on return from the method call, will contain the current left position, expressed in percentage, of the player's rectangle respect to the video mixer window area
fTop | Reference that, on return from the method call, will contain the current top position, expressed in percentage, of the player's rectangle respect to the video mixer window area
fRight | Reference that, on return from the method call, will contain the current right position, expressed in percentage, of the player's rectangle respect to the video mixer window area
fBottom | Reference that, on return from the method call, will contain the current bottom position, expressed in percentage, of the player's rectangle respect to the video mixer window area

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.PlayerNormalizedRectSet method

VideoMixer.PlayerNormalizedRectSet method

Remarks

Sets the normalized rectangle of the given player respect to the video mixer window area.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.PlayerNormalizedRectSet (

nMixerUniqueId as Long,

nPlayer as Integer,

fLeft as Single,

fTop as Single,

fRight as Single,

fBottom as Single

) as enumErrorCodes

[C++]

short control.VideoMixer.PlayerNormalizedRectSet (

long nMixerUniqueId,

short nPlayer,

float fLeft,

float fTop,

float fRight,

float fBottom

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayer | Number representing the zero-based index of the player attached to the video mixer through a previous call to the VideoPlayer.AttachToVideoMixer method.
fLeft | Left position, expressed in percentage, of the player's rectangle respect to the video mixer window area
fTop | Top position, expressed in percentage, of the player's rectangle respect to the video mixer window area
fRight | Right position, expressed in percentage, of the player's rectangle respect to the video mixer window area
fBottom | Bottom position, expressed in percentage, of the player's rectangle respect to the video mixer window area

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.PlayerNormalizedRectSetIdeal method

VideoMixer.PlayerNormalizedRectSetIdeal method

Remarks

Sets the ideal normalized rectangle, respect to the video mixer window area, based upon original dimensions of the video clip loaded inside the given player.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.PlayerNormalizedRectSetIdeal (

nMixerUniqueId as Long,

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoMixer.PlayerNormalizedRectSetIdeal (

long nMixerUniqueId,

short nPlayer

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayer | Number representing the zero-based index of the player attached to the video mixer through a previous call to the VideoPlayer.AttachToVideoMixer method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.PlayerZOrderGet method

VideoMixer.PlayerZOrderGet method

Remarks

Obtains the current value of the Z-Order applied to the video clip loaded into the given player. The value for the Z-Order can be modified through the VideoMixer.PlayerZOrderSet method.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.PlayerZOrderGet (

nMixerUniqueId as Long,

nPlayer as Integer,

nZOrder as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.PlayerZOrderGet (

long nMixerUniqueId,

short nPlayer,

long *nZOrder

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayer | Number representing the zero-based index of the player attached to the video mixer through a previous call to the VideoPlayer.AttachToVideoMixer method.
nZOrder | Reference that, on return from the method call, will contain the Z-Order for the given player. Players with a lower Z-Order value will stay on top respect to other players having a higher Z-Order value; for example, a player with Z-Order 0 will stay on top of any other player but, in case two players should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.PlayerZOrderSet method

VideoMixer.PlayerZOrderSet method

Remarks

Sets the current value of the Z-Order applied to the video clip loaded into the given player.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.PlayerZOrderSet (

nMixerUniqueId as Long,

nPlayer as Integer,

nZOrder as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.PlayerZOrderSet (

long nMixerUniqueId,

short nPlayer,

long nZOrder

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayer | Number representing the zero-based index of the player attached to the video mixer through a previous call to the VideoPlayer.AttachToVideoMixer method.
nZOrder | The Z-Order for the given player. Players with a lower Z-Order value will stay on top respect to other players having a higher Z-Order value; for example, a player with Z-Order 0 will stay on top of any other player but, in case two players should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.Reset method

VideoMixer.Reset method

Remarks

Resets the video mixer contents and attached players contents without detaching players themselves from the video mixer.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.Reset (

nMixerUniqueId as Long

) as enumErrorCodes

[C++]

short control.VideoMixer.Reset (

long nMixerUniqueId

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoMixer.ScreenshotSaveToFile method

VideoMixer.ScreenshotSaveToFile method

Remarks

Saves into a graphic file a screenshot of what is currently displayed on the window of the given video mixer, including eventual graphic items displayed on the OSD.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.ScreenshotSaveToFile (

nMixerUniqueId as Long,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as long

) as enumErrorCodes

[C++]

short control.VideoMixer.ScreenshotSaveToFile (

long nMixerUniqueId,

LPCTSTR strPathname,

short nFormat,

long nFormatParameter

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

strPathname

String containing the absolute pathname where the screenshot will be stored.

nFormat

Graphic format used to save the bitmap.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_BMP | 0 | BMP format
GRAPHIC_FORMAT_JPEG | 1 | JPEG format
GRAPHIC_FORMAT_PNG | 2 | PNG format
GRAPHIC_FORMAT_GIF | 3 | GIF format
GRAPHIC_FORMAT_TIFF | 4 | TIFF format

nFormatParameter

Eventual parameters required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


VideoMixer.Show method

VideoMixer.Show method

Remarks

Shows/hides the video mixer rendering window.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoMixer.Show (

nMixerUniqueId as Long,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoMixer.Show (

long nMixerUniqueId,

short bShow

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

bShow

Boolean value that determines if the rendering window must be shown or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the video mixer window
BOOL_TRUE | 1 | Shows the video mixer window

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer object

VideoPlayer object

The VideoPlayer object, accessible through the control's VideoPlayer property, is internally implemented as a COM interface called IVideoPlayer and gives access to playback of video clips through DirectShow.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

The VideoPlayer object is implemented through the following methods:

Methods

AttachToVideoMixer

AudioMultiStreamCheck

AudioMultiStreamGetCount

AudioMultiStreamGetName

AudioMultiStreamSelect

AudioRendererDelayGet

AudioRendererDelaySet

AudioRendererDsDeviceGetCount

AudioRendererDsDeviceGetDesc

AudioRendererDsDeviceSet

AudioRendererModeGet

AudioRendererModeSet

AudioTrackExtract

AudioTrackExtractAbort

AudioTrackFree

AudioTrackGetMemoryPtr

AudioTrackGetMemorySize

AudioTrackGetTempFilePathname

AudioTrackGetTempFileSize

Close

CodecAudioDescGet

CodecVideoDescGet

DurationGet

DetachFromVideoMixer

EnableDsErrorMessages

FiltersInGraphGetClsid

FiltersInGraphGetCount

FiltersInGraphGetName

FiltersInGraphHasPropertyPage

FiltersInGraphShowPropertyPage

ForceWideScreen

Forward

FrameGrabberInit

FrameGrabberExit

FrameGrabberExecToFile

FrameGrabberExecToMemory

FrameGrabberOutputResizeSet

FrameGrabberResultsGetAvailableType

FrameGrabberResultsGetPixelColor

FrameGrabberResultsGetBitmap

FrameGrabberResultsGetBitmapsCount

FrameGrabberResultsGetFilePathname

FrameGrabberResultsGetFilesCount

FramesNumberGet

FramesAverageRateGet

FullscreenMonitorActivate

FullscreenMonitorCountGet

FullscreenMonitorIsActivated

FullscreenMonitorNameGet

FullscreenMonitorPositionGet

FullscreenMonitorPredispose

FullscreenMonitorRemove

GetAspectRatio

GetNativeSize

ImageAdjustEnable

ImageAdjustIsEnabled

ImageAdjustPropertyGet

ImageAdjustPropertySet

ImageAdjustPropertyRangeGet

IsAudioStreamAvailable

IsDirectShowAvail

IsSeekable

IsVideoStreamAvailable

Load

LoadForEAX

LoadForTempoChange

LoadFromMemory

LoadFromMemoryForEAX

LoadFromMemoryForTempoChange

LoadFromMemorySync

LoadFromMemorySyncForEAX

LoadFromMemorySyncForTempoChange

LoadSync

LoadSyncForEAX

LoadSyncForTempoChange

OSDEnable

OSDIsEnabled

OSDKeyColorGet

OSDKeyColorSet

OSDItemBitmapAdd

OSDItemBitmapChange

OSDItemBitmapGet

OSDItemOutlineTextAdd

OSDItemOutlineTextChange

OSDItemPictureFileAdd

OSDItemPictureFileChange

OSDItemPictureMemoryAdd

OSDItemPictureMemoryChange

OSDItemRectangleAdd

OSDItemRectangleChange

OSDItemTextAdd

OSDItemTextChange

OSDItemAlphaGet

OSDItemAlphaSet

OSDItemChangeAlignment

OSDItemIsOnVisibleArea

OSDItemMove

OSDItemRectGet

OSDItemRemove

OSDItemScrollByPixels

OSDItemShow

OSDItemZOrderGet

OSDItemZOrderSet

Pause

Play

PlayRange

PositionGet

Resume

Rewind

Seek

SeekToNextFrame

SeekToPreviousFrame

Stop

VideoStreamKeepAspectRatio

VideoStreamSendToActiveMovieWin

VideoTransformIsAvailable

VideoWIndowAdd

VideoWindowChangeTarget

VideoWindowGetHWND

VideoWindowMove

VideoWindowShow

Examples of use of the VideoPlayer object in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- AsioVideoPlayer

- VideoMixer

- VideoPlayerAdvanced

- VideoPlayerSimple

- VideoPlayerMultipleOutout

- VideoWaveform


VideoPlayer.AttachToVideoMixer method

VideoPlayer.AttachToVideoMixer method

Remarks

Attaches the given video player to an instance of the video mixer. The video player can be detached at a later time through the VideoPlayer.DetachFromVideoMixer method.

When the video player has been attached to the video mixer, only the first rendering window added through the VideoPlayer.VideoWindowAdd will be available for preview purposes: the other eventual rendering windows will stay inactive until the video player is detached from the video mixer through a call to the VideoPlayer.DetachFromVideoMixer method and a new video clip is loaded into the video player. .

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AttachToVideoMixer (

nPlayer as Integer,

nMixerUniqueId as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.AttachToVideoMixer (

short nPlayer,

long nMixerUniqueId

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioMultiStreamCheck method

VideoPlayer.AudioMultiStreamCheck method

Remarks

Checks if the loaded video has more than one audio stream.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioMultiStreamCheck (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.AudioMultiStreamCheck (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
FALSE | The loaded video clip doesn't contain multiple audio streams
TRUE | The loaded video clip contains multiple audio streams


VideoPlayer.AudioMultiStreamGetCount method

VideoPlayer.AudioMultiStreamGetCount method

Remarks

Obtains the number of audio streams available inside the loaded video.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioMultiStreamGetCount (

nPlayer as Integer

) as Long

[C++]

long control.VideoPlayer.AudioMultiStreamGetCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
>= 0 | The number of available audio streams


VideoPlayer.AudioMultiStreamGetName method

VideoPlayer.AudioMultiStreamGetName method

Remarks

Obtains the friendly name of the given audio stream.

The total number of available audio streams can be obtained using the VideoPlayer.AudioMultiStreamGetCount method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioMultiStreamGetName (

nPlayer as Integer,

nStreamIndex as Long

) as String

[C++]

LPCTSTR control.VideoPlayer.AudioMultiStreamGetName (

short nPlayer,

long nStreamIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nStreamIndex | Number representing the zero-based index of the audio stream. Use the value returned by the VideoPlayer.AudioMultiStreamGetCount method in order to know how many audio streams are available.

Return value

Value | Meaning
Empty string | The value of the nStreamIndex parameter was out of range.
Valid string | The string containing the friendly name of the requested DirectShow filter.


VideoPlayer.AudioMultiStreamSelect method

VideoPlayer.AudioMultiStreamSelect method

Remarks

Selects a different audio stream for playback. The change of the audio stream is not immediate and, depending upon the video format in use, the new audio stream could become audible after a certain amount of seconds.

The total number of available audio streams can be obtained using the VideoPlayer.AudioMultiStreamGetCount method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioMultiStreamSelect (

nPlayer as Integer,

nStreamIndex as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.AudioMultiStreamSelect (

short nPlayer,

long nStreamIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nStreamIndex | Number representing the zero-based index of the audio stream to select. Use the value returned by the VideoPlayer.AudioMultiStreamGetCount method in order to know how many audio streams are available.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioRendererDelayGet method

VideoPlayer.AudioRendererDelayGet method

Remarks

Obtains the current delay applied to the audio stream. The audio stream delay can be modified through the VideoPlayer.AudioRendererDelaySet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioRendererDelayGet (

nPlayer as Integer,

nDelay as Long

) as Long

[C++]

long control.VideoPlayer.AudioRendererDelayGet (

short nPlayer,

long *nDelay

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nDelay | Reference that, on return from the method call, will contain the current audio delay expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioRendererDelaySet method

VideoPlayer.AudioRendererDelaySet method

Remarks

Modifies the current delay applied to the audio stream. The current audio stream delay can be obtained through the VideoPlayer.AudioRendererDelayGet method.

In order to allow applying special effects to the audio stream of video clips, Active DJ Studio implements its own audio renderer which is different respect to the one used by other players like "Windows Media Player™": by default the audio stream has a 200 milliseconds delay respect to the video stream because this works better when dealing with the majority of audio drivers and is not much noticeable on modern PCs having LCD monitors instead of CRT monitors; in case this should be noticeable on your side, you could use this method in order to remove/reduce this delay.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioRendererDelaySet (

nPlayer as Integer,

nDelay as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.AudioRendererDelaySet (

short nPlayer,

long nDelay

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nDelay

Audio delay expressed in milliseconds.

The amount of default delay and the available delay range depends upon the audio rendering mode in use set through the VideoPlayer.AudioRendererModeSet method:

· 200 milliseconds when the audio rendering mode has been set to AUDIO_RENDERER_MODE_CUSTOM, AUDIO_RENDERER_MODE_CUSTOM_RESAMPLE_STEREO or AUDIO_RENDERER_MODE_CUSTOM_NO_SURROUND; in this cases the supported range from -200 to 500 milliseconds. Negative values allow to fine tune the audio stream rendering in case it should result delayed respect to the video stream.

· 0 milliseconds when the audio rendering mode has been set to AUDIO_RENDERER_MODE_DS_STANDARD or AUDIO_RENDERER_MODE_CUSTOM_2; in this cases the supported range from 0 to 500 milliseconds.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioRendererDsDeviceGet method

VideoPlayer.AudioRendererDsDeviceGet method

Remarks

Obtains the DirectSound device currently used by the given player for playing the audio stream of the loaded video clip when the rendering mode has been set to AUDIO_RENDERER_MODE_DS_STANDARD or to AUDIO_RENDERER_MODE_CUSTOM_2 through the VideoPlayer.AudioRendererModeSet method. The current DirectSound device can be changed through the VideoPlayer.AudioRendererDsDeviceSet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioRendererDsDeviceGet (

nPlayer as Integer

) as Integer

[C++]

short control.VideoPlayer.AudioRendererDsDeviceGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Value >= 0 | The zero-based index of the current DirectSound device.
Negative value | An error occurred (see the LastError property for further error details)


VideoPlayer.AudioRendererDsDeviceGetCount method

VideoPlayer.AudioRendererDsDeviceGetCount method

Remarks

Obtains the friendly name of a specific DirectSound device recognized by DirectShow as a valid audio renderer.

The total number of available DirectSound devices can be obtained using the VideoPlayer.AudioRendererDsDeviceGetCount method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioRendererDsDeviceGetCount (

) as Integer

[C++]

short control.AudioRendererDsDeviceGetCount (

);

Return value

The number of installed DirectSound devices.


VideoPlayer.AudioRendererDsDeviceGetDesc method

VideoPlayer.AudioRendererDsDeviceGetDesc method

Remarks

Obtains the friendly name of a specific DirectSound device recognized by DirectShow as a valid audio renderer.

The total number of available DirectSound devices can be obtained using the VideoPlayer.AudioRendererDsDeviceGetCount method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioRendererDsDeviceGetDesc (

nIndex as Integer

) as String

[C++]

LPCTSTR control.VideoPlayer.AudioRendererDsDeviceGetDesc (

short nIndex

);

Parameter | Description
nIndex | Number representing the zero-based index of the DirectSound device whose friendly name must be retrieved

Return value

Value | Meaning
Empty string | The value of the nIndex parameter was out of range. Use the value returned by the VideoPlayer.AudioRendererDsDeviceGetCount method in order to know how many output devices are currently installed on the system.
Valid string | The string containing the friendly description of the requested DirectSound device.


VideoPlayer.AudioRendererDsDeviceSet method

VideoPlayer.AudioRendererDsDeviceSet method

Remarks

Sets the given DirectSound device for playing the audio stream of the video clip loaded inside the given player when the rendering mode has been set to AUDIO_RENDERER_MODE_DS_STANDARD or to AUDIO_RENDERER_MODE_CUSTOM_2 through the VideoPlayer.AudioRendererModeSet method. The current DirectSound device can be obtained through the VideoPlayer.AudioRendererDsDeviceGet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioRendererDsDeviceSet (

nPlayer as Integer,

nIndex as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.AudioRendererDsDeviceSet (

short nPlayer,

short nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nIndex | The zero-based index of the current DirectSound device. The total number of available audio renderers can be obtained through the VideoPlayer.AudioRendererDsDeviceGetCount method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioRendererModeGet method

VideoPlayer.AudioRendererModeGet method

Remarks

Obtains the current rendering mode for the audio stream of the video clip. The rendering mode can be modified through the VideoPlayer.AudioRendererModeSet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioRendererModeGet (

nPlayer as Integer

) as enumAudioRendererModes

[C++]

short control.VideoPlayer.AudioRendererModeGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value

Meaning

Value >= 0

Current rendering mode.

Supported values are the following:

Mnemonic constant

Value

Meaning

AUDIO_RENDERER_MODE_CUSTOM (default)

0

Custom renderer: in this case the audio stream is managed separately respect to the normal filter graph, allowing to apply most of the special effects, output redirection, speakers management, ASIO drivers support and visual feedbacks as seen for regular sound files.

When using this mode you could experience a small but constant latency between the audio stream that could be in advance respect to the video video stream rendering: the VideoPlayer.AudioRendererDelaySet method can be used to fine-tune or eliminate this latency.

AUDIO_RENDERER_MODE_CUSTOM_RESAMPLE_STEREO

1

Identical to the custom renderer, performs a resampling to stereo of eventual multi-channel audio streams like 5.1; in this case, all left channels will be mixed inside a single left channel and all right channels will be mixed inside a single right channel.

AUDIO_RENDERER_MODE_CUSTOM_NO_SURROUND

2

Identical to custom renderer, if the audio stream is a multi-channel one, for example a 5.1, only the front channels will be rendered, discarding rear and other surround channels.

AUDIO_RENDERER_MODE_DS_STANDARD

3

Audio is rendered through the default DirectSound audio renderer.

When using this mode, you can only apply volume change, balance change and output device redirection (no speakers management, visual feedbacks, special effects, etc. available).

Available DirectSound output devices registered as DirectShow audio renderers can be enumerated through the VideoPlayer.AudioRendererDsDeviceGetCount and VideoPlayer.AudioRendererDsDeviceGetDesc methods; the current output device can be changed/obtained through the VideoPlayer.AudioRendererDsDeviceSet and VideoPlayer.AudioRendererDsDeviceGet methods.

AUDIO_RENDERER_MODE_NULL

4

Useful when you need to render the video stream only, audio is sent to a NullRenderer filter, meaning that no audio will be reproduced and less CPU will be used.

AUDIO_RENDERER_MODE_CUSTOM_2

5

Audio is rendered through the default DirectSound audio renderer.

When using this mode, you have the same features available through the AUDIO_RENDERER_MODE_CUSTOM mode with the following exceptions:

- doesn't support speakers management

- doesn't support ASIO drivers

- cannot be attached to a custom stream mixer

Available DirectSound output devices registered as DirectShow audio renderers can be enumerated through the VideoPlayer.AudioRendererDsDeviceGetCount and VideoPlayer.AudioRendererDsDeviceGetDesc methods; the current output device can be changed/obtained through the VideoPlayer.AudioRendererDsDeviceSet and VideoPlayer.AudioRendererDsDeviceGet methods.

Negative value

An error occurred (see the LastError property for further error details)


VideoPlayer.AudioRendererModeSet method

VideoPlayer.AudioRendererModeSet method

Remarks

Sets the rendering mode for the audio stream of the video clip. The current rendering mode can be obtained through the VideoPlayer.AudioRendererModeGet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioRendererModeSet (

nPlayer as Integer,

nMode as enumAudioRendererModes

) as enumErrorCodes

[C++]

short control.VideoPlayer.AudioRendererModeSet (

short nPlayer,

short nMode

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nMode

The audio rendering mode.

Supported values are the following:

Mnemonic constant

Value

Meaning

AUDIO_RENDERER_MODE_CUSTOM (default)

0

Custom renderer: in this case the audio stream is managed separately respect to the normal filter graph, allowing to apply most of the special effects, output redirection, speakers management, ASIO drivers support and visual feedbacks as seen for regular sound files.

When using this mode you could experience a small but constant latency between the audio stream that could be in advance respect to the video video stream rendering: the VideoPlayer.AudioRendererDelaySet method can be used to fine-tune or eliminate this latency.

AUDIO_RENDERER_MODE_CUSTOM_RESAMPLE_STEREO

1

Identical to the custom renderer, performs a resampling to stereo of eventual multi-channel audio streams like 5.1; in this case, all left channels will be mixed inside a single left channel and all right channels will be mixed inside a single right channel.

AUDIO_RENDERER_MODE_CUSTOM_NO_SURROUND

2

Identical to custom renderer, if the audio stream is a multi-channel one, for example a 5.1, only the front channels will be rendered, discarding rear and other surround channels.

AUDIO_RENDERER_MODE_DS_STANDARD

3

Audio is rendered through the default DirectSound audio renderer.

When using this mode, you can only apply volume change, balance change and output device redirection (no speakers management, visual feedbacks, special effects, etc. available).

Available DirectSound output devices registered as DirectShow audio renderers can be enumerated through the VideoPlayer.AudioRendererDsDeviceGetCount and VideoPlayer.AudioRendererDsDeviceGetDesc methods; the current output device can be changed/obtained through the VideoPlayer.AudioRendererDsDeviceSet and VideoPlayer.AudioRendererDsDeviceGet methods.

When this mode is selected, automatic volume sliding set through the StreamVolumeSmoothingSet method is not available.

AUDIO_RENDERER_MODE_NULL

4

Useful when you need to render the video stream only, audio is sent to a NullRenderer filter, meaning that no audio will be reproduced and less CPU will be used.

AUDIO_RENDERER_MODE_CUSTOM_2

5

Audio is rendered through the default DirectSound audio renderer.

When using this mode, you have the same features available through the AUDIO_RENDERER_MODE_CUSTOM mode with the following exceptions:

- doesn't support speakers management

- doesn't support ASIO drivers

- cannot be attached to a custom stream mixer

- cannot redirect the audio flow to output devices through the StreamOutputDeviceSet method. Available DirectSound output devices registered as DirectShow audio renderers can be enumerated through the VideoPlayer.AudioRendererDsDeviceGetCount and VideoPlayer.AudioRendererDsDeviceGetDesc methods; the current output device can be changed/obtained through the VideoPlayer.AudioRendererDsDeviceSet and VideoPlayer.AudioRendererDsDeviceGet methods.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioTrackExtract method

VideoPlayer.AudioTrackExtract method

Remarks

Starts the extraction of the audio track stored inside the media file into a destination memory buffer or into a temporary file. The format of the extracted sound is WAV PCM having the same frequency and number of channels of the original audio stream.

Once extracted, the audio track can be used to perform waveform analysis, BPM (Beats per minute) detection and sound silence detection.

If the size of the extracted track is less than 2 GBytes, the track is stored in uncompressed WAV PCM format; for sizes higher than 2 GBytes the W64 format is automatically used.

The call to this method will generate an AudioExtractFromVideoStart event followed by a number of AudioExtractFromVideoPerc events (that will inform about extraction advancement) and, finally, a AudioExtractFromVideoDone event.

Audio extraction can be aborted at any time through the VideoPlayer.AudioTrackExtractAbort method.

Once the extracted track is no more needed, you can free the memory buffer or delete the temporary file by using the VideoPlayer.AudioTrackFree method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioTrackExtract (

nPlayer as Integer,

bStoreInMemory as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.AudioTrackExtract (

short nPlayer,

short bStoreInMemory

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

bStoreInMemory

Boolean value that specifies if the audio track needs to be stored in memory or inside a temporary file.

Supported values are the following:

Mnemonic constant

Value

Meaning

BOOL_FALSE

0

Store extracted audio stream inside a temporary file; once completed, the absolute pathname of the temporary file and its size in bytes can be accessed through the VideoPlayer.AudioTrackGetTempFilePathname and VideoPlayer.AudioTrackGetTempFileSize methods.

BOOL_TRUE

1

Store extracted audio stream inside a memory buffer; once completed, this buffer and its size in bytes can be accessed through the VideoPlayer.AudioTrackGetMemoryPtr and VideoPlayer.AudioTrackGetMemorySize methods.

In case there should be not enough memory room to store the audio stream, the control would automatically switch its output to a temporary file and this would be notified through the bOutputSwitchedToFile parameter of the AudioExtractFromVideoDone event

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioTrackExtractAbort method

VideoPlayer.AudioTrackExtractAbort method

Remarks

Aborts the extraction of the audio track previously started through the VideoPlayer.AudioTrackExtract method.

A call to this method will generate a AudioExtractFromVideoDone event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioTrackExtractAbort (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.AudioTrackExtractAbort (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioTrackFree method

VideoPlayer.AudioTrackFree method

Remarks

Frees any resource, memory buffer or temporary file, used to store the audio track extracted from a video clip through a previous call to the VideoPlayer.AudioTrackExtract method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioTrackFree (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.AudioTrackFree (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.AudioTrackGetMemoryPtr method

VideoPlayer.AudioTrackGetMemoryPtr method

Remarks

If the extraction of the audio track, previously started through the VideoPlayer.AudioTrackExtract method, has been set to store audio data in memory, this method will return the memory address (pointer) of the buffer containing sound data. The actual size in bytes of the memory buffer can be retrieved using the VideoPlayer.AudioTrackGetMemorySize method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioTrackGetMemoryPtr (

nPlayer as Integer

) as Long

[C++]

long control.VideoPlayer.AudioTrackGetMemoryPtr (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
> 0 | Address of the memory buffer


VideoPlayer.AudioTrackGetMemorySize method

VideoPlayer.AudioTrackGetMemorySize method

Remarks

If the extraction of the audio track, previously started through the VideoPlayer.AudioTrackExtract method, has been set to store audio data in memory, this method will return the size in bytes of the buffer containing sound data.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioTrackGetMemorySize (

nPlayer as Integer

) as Long

[C++]

long control.VideoPlayer.AudioTrackGetMemorySize (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
> 0 | Size of the memory buffer expressed in bytes


VideoPlayer.AudioTrackGetTempFilePathname method

VideoPlayer.AudioTrackGetTempFilePathname method

Remarks

If the extraction of the audio track, previously started through the VideoPlayer.AudioTrackExtract method, has been set to store audio data inside a temporary file, this method will return the absolute pathname of the temporary file containing sound data. The actual size in bytes of the temporary file can be retrieved using the VideoPlayer.AudioTrackGetTempFileSize method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioTrackGetTempFilePathname (

nPlayer as Integer

) as String

[C++]

LPCTSTR control.VideoPlayer.AudioTrackGetTempFilePathname (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Valid string | String containing the absolute pathname of the temporary
Empty string | An error occurred, check the LastError property value in order to see the error code meaning file


VideoPlayer.AudioTrackGetTempFileSize method

VideoPlayer.AudioTrackGetTempFileSize method

Remarks

If the extraction of the audio track, previously started through the VideoPlayer.AudioTrackExtract method, has been set to store audio data in memory, this method will return the size in bytes of the buffer containing sound data.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.AudioTrackGetTempFileSize (

nPlayer as Integer

) as Long

[C++]

long control.VideoPlayer.AudioTrackGetTempFileSize (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
> 0 | Size of the temporary file expressed in bytes


VideoPlayer.Close method

VideoPlayer.Close method

Remarks

Closes the loaded video and discard it from memory.

A successful call to this method will fire the SoundClosed event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Close (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.Close (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.CodecAudioDescGet method

VideoPlayer.CodecAudioDescGet method

Remarks

Obtains the name of the codec used to decode the audio stream of the loaded video clip.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.CodecAudioDescGet (

nPlayer as Integer

) as String

[C++]

LPCTSTR control.VideoPlayer.CodecAudioDescGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Valid string | String containing the name of the codec
Empty string | An error occurred, check the LastError property value in order to see the error code meaning file


VideoPlayer.CodecVideoDescGet method

VideoPlayer.CodecVideoDescGet method

Remarks

Obtains the name of the codec used to decode the video stream of the loaded video clip.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.CodecVideoDescGet (

nPlayer as Integer

) as String

[C++]

LPCTSTR control.VideoPlayer.CodecVideoDescGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Valid string | String containing the name of the codec
Empty string | An error occurred, check the LastError property value in order to see the error code meaning file


VideoPlayer.DetachFromVideoMixer method

VideoPlayer.DetachFromVideoMixer method

Remarks

Detaches the given video player from an instance of the video mixer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

For further details about the use of the embedded video mixer see the VideoMixer object section.

For details about video mixing/blending refer to the How to use the video mixer tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.DetachFromVideoMixer (

nPlayer as Integer,

nMixerUniqueId as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.DetachFromVideoMixer (

short nPlayer,

long nMixerUniqueId

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.DurationGet method

VideoPlayer.DurationGet method

Remarks

Gets the duration of the video currently loaded.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.DurationGet (

nPlayer as Integer,

fDuration as Double,

bKeepCountOfRateChange as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.DurationGet (

short nPlayer,

double *fDuration,

short bKeepCountOfRateChange

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

fDuration

Reference that, on return from the method call, will contain the duration of the loaded sound expressed in milliseconds.

bKeepCountOfRateChange

Boolean flag that specifies if the returned position must keep count of eventual playback rate changes set through previous calls to the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Don't keep count of playback rate changes
BOOL_TRUE | 1 | Keep count of playback rate changes

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.EnableDsErrorMessages method

VideoPlayer.EnableDsErrorMessages method

Remarks

Enables/disables the visualization of message boxes containing errors detected by DirectShow during playback of a video stream.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.EnableDsErrorMessages (

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.EnableDsErrorMessages (

short bEnable

);

Parameter

Description

bEnable

Boolean value that determines if error message boxes should be displayed.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Disables message boxes reporting DirectShow internal errors.
BOOL_TRUE (default) | 1 | Enables message boxes reporting DirectShow internal errors.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FiltersInGraphGetClsid method

VideoPlayer.FiltersInGraphGetClsid method

Remarks

Obtains the class identifier (CLSID) of a specific DirectShow filter instanced inside the filter graph for the loaded video clip.

A CLSID is a 128 bit (large) number that represents a unique identifier for a software application or application component and is in the format "{AE7AB96B-FF5E-4dce-801E-14DF2C4CD681}".

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FiltersInGraphGetClsid (

nPlayer as Integer,

nFilterIndex as Integer

) as String

[C++]

LPCTSTR control.VideoPlayer.FiltersInGraphGetClsid (

short nPlayer,

short nFilterIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nFilterIndex | Number representing the zero-based index of the DirectShow filter. The total number of instanced DirectShow filters can be obtained using the VideoPlayer.FiltersInGraphGetCount method.

Return value

Value | Meaning
Empty string | The value of the nFilterIndex parameter was out of range. Use the value returned by the VideoPlayer.FiltersInGraphGetCount method in order to know how many DirectShow filters are currently instanced inside the filter graph.
Valid string | The string containing the class identifier (CLSID) of the requested DirectShow filter.


VideoPlayer.FiltersInGraphGetCount method

VideoPlayer.FiltersInGraphGetCount method

Remarks

Obtains the number of DirectShow filters currently instanced inside the filter graph for the loaded video clip. You can obtain the friendly name of a specific filter through the VideoPlayer.FiltersInGraphGetName method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FiltersInGraphGetCount (

nPlayer as Integer

) as Integer

[C++]

short control.VideoPlayer.FiltersInGraphGetCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Value >= 0 | The number of DirectShow filters currently instanced inside the filter graph
Negative value | An error occurred (see the LastError property for further error details)


VideoPlayer.FiltersInGraphGetName method

VideoPlayer.FiltersInGraphGetName method

Remarks

Obtains the friendly name of a specific DirectShow filter instanced inside the filter graph for the loaded video clip.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FiltersInGraphGetName (

nPlayer as Integer,

nFilterIndex as Integer

) as String

[C++]

LPCTSTR control.VideoPlayer.FiltersInGraphGetName (

short nPlayer,

short nFilterIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nFilterIndex | Number representing the zero-based index of the DirectShow filter. The total number of instanced DirectShow filters can be obtained using the VideoPlayer.FiltersInGraphGetCount method.

Return value

Value | Meaning
Empty string | The value of the nFilterIndex parameter was out of range. Use the value returned by the VideoPlayer.FiltersInGraphGetCount method in order to know how many DirectShow filters are currently instanced inside the filter graph.
Valid string | The string containing the friendly name of the requested DirectShow filter.


VideoPlayer.FiltersInGraphHasPropertyPage method

VideoPlayer.FiltersInGraphHasPropertyPage method

Remarks

Checks if a specific DirectShow filter available inside the filters graph of the loaded video clip has a property page that may be eventually displayed through the VideoPlayer.FiltersInGraphShowPropertyPage method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FiltersInGraphHasPropertyPage (

nPlayer as Integer,

nFilterIndex as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.FiltersInGraphHasPropertyPage (

short nPlayer,

short nFilterIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nFilterIndex | Number representing the zero-based index of the DirectShow filter. The total number of instanced DirectShow filters can be obtained using the VideoPlayer.FiltersInGraphGetCount method.

Return value

Value | Meaning
FALSE | The given filter doesn't have a property page
TRUE | The given filter has a property page


VideoPlayer.FiltersInGraphShowPropertyPage method

VideoPlayer.FiltersInGraphShowPropertyPage method

Remarks

If available, displays the property page of the given DirectShow filter available inside the filters graph of the loaded video clip. The availability of the property page can be determined through the VideoPlayer.FiltersInGraphHasPropertyPage method.

This method always creates a modal dialog box and does not return until the dialog box is closed.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FiltersInGraphShowPropertyPage (

nPlayer as Integer,

nFilterIndex as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.FiltersInGraphShowPropertyPage (

short nPlayer,

short nFilterIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nFilterIndex | Number representing the zero-based index of the DirectShow filter. The total number of instanced DirectShow filters can be obtained using the VideoPlayer.FiltersInGraphGetCount method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.ForceWideScreen method

VideoPlayer.ForceWideScreen method

Remarks

Forces the loaded video to be rendered at 16:9 wide screen. The native aspect ratio of the loaded video can be obtained through the VideoPlayer.GetAspectRatio method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.ForceWideScreen (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.ForceWideScreen (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.Forward method

VideoPlayer.Forward method

Remarks

Moves forward the position of the playing video of the amount that has been set through a previous call to the SetForwardRewindGranularity method..

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Forward (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.Forward (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FrameGrabberInit method

VideoPlayer.FrameGrabberInit method

Remarks

Initializes the usage of the frames grabber.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberInit (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.FrameGrabberInit (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FrameGrabberExit method

VideoPlayer.FrameGrabberExit method

Remarks

Terminates the usage of the the frames grabber and frees related resources.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberExit (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.FrameGrabberExit (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FrameGrabberExecToFile method

VideoPlayer.FrameGrabberExecToFile method

Remarks

Executes a frames grabbing session whose output will be stored on disk files. After completing the grabbing session, you can enumerate all of the grabbed frames through the combination of the VideoPlayer.FrameGrabberResultsGetFilesCount and VideoPlayer.FrameGrabberResultsGetFilePathname methods.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberExecToFile (

nPlayer as Integer,

nStopType as enumVideoGrabberStopTypes,

nStartPosition as Long,

nEndPosition as Long,

nNumberOfFrames as Long,

strOutputPath as String,

strOutputFilenamePrefix as String,

nFormat as enumGraphicFormats,

nFormatParameter as long

) as enumErrorCodes

[C++]

short control.VideoPlayer.FrameGrabberExecToFile (

short nPlayer,

short nStopType,

long nStartPosition,

long nEndPosition,

long nNumberOfFrames,

LPCTSTR strOutputPath,

LPCTSTR strOutputFilenamePrefix,

short nFormat,

long nFormatParameter

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nStopType

Condition under which the stop of the grabbing session will occur.

Supported values are the following:

Mnemonic value | Value | Meaning
VIDEOGRABBER_STOP_POSITION | 0 | When this option is selected, the beginning of the grabbing is defined by the value set into the nStartPosition and the end of the grabbing is defined by the value set into the nEndPosition parameter. In this case the nNumberOfFrames parameter is ignored.
VIDEOGRABBER_STOP_FRAMES_NUM | 1 | When this option is selected, the beginning of the grabbing is defined by the value set into the nStartPosition and the end of the grabbing will occur after grabbing the number of frames set into the nNumberOfFrames parameter. In this case the nEndPosition parameter is ignored.

nStartPosition

Start position, expressed in milliseconds, where the grabbing session will begin. The value 0 represents the sound's beginning.

nEndPosition

Stop position, expressed in milliseconds, where the grabbing session will end. The value -1 represents the end of the video clip.

This parameter is ignored if the nStopType parameter is set to VIDEOGRABBER_STOP_FRAMES_NUM.

nNumberOfFrames

Number of frames to grab before stopping the grabbing session.

This parameter is ignored if the nStopType parameter is set to VIDEOGRABBER_STOP_POSITION.

strOutputPath

String containing the absolute path where grabbed frames will be stored.

strOutputFilenamePrefix

Fixed prefix of the filename for each grabbed frame.

nFormat

Graphic format used to save the bitmap.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_BMP | 0 | BMP format
GRAPHIC_FORMAT_JPEG | 1 | JPEG format
GRAPHIC_FORMAT_PNG | 2 | PNG format
GRAPHIC_FORMAT_GIF | 3 | GIF format
GRAPHIC_FORMAT_TIFF | 4 | TIFF format

nFormatParameter

Eventual parameters required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


VideoPlayer.FrameGrabberExecToMemory method

VideoPlayer.FrameGrabberExecToMemory method

Remarks

Executes a frames grabbing session whose output will be stored inside a set of memory bitmaps. After completing the grabbing session, you can enumerate all of the grabbed frames through the combination of the VideoPlayer.FrameGrabberResultsGetBitmapsCount and VideoPlayer.FrameGrabberResultsGetBitmap methods.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberExecToMemory (

nPlayer as Integer,

nStopType as enumVideoGrabberStopTypes,

nStartPosition as Long,

nEndPosition as Long,

nNumberOfFrames as Long

) as Long

[C++]

long control.VideoPlayer.FrameGrabberExecToMemory (

short nPlayer,

short nStopType,

long nStartPosition,

long nEndPosition,

long nNumberOfFrames

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nStopType

Condition under which the stop of the grabbing session will occur.

Supported values are the following:

Mnemonic value | Value | Meaning
VIDEOGRABBER_STOP_POSITION | 0 | When this option is selected, the beginning of the grabbing is defined by the value set into the nStartPosition and the end of the grabbing is defined by the value set into the nEndPosition parameter. In this case the nNumberOfFrames parameter is ignored.
VIDEOGRABBER_STOP_FRAMES_NUM | 1 | When this option is selected, the beginning of the grabbing is defined by the value set into the nStartPosition and the end of the grabbing will occur after grabbing the number of frames set into the nNumberOfFrames parameter. In this case the nEndPosition parameter is ignored.

nStartPosition

Start position, expressed in milliseconds, where the grabbing session will begin. The value 0 represents the sound's beginning.

nEndPosition

Stop position, expressed in milliseconds, where the grabbing session will end. The value -1 represents the end of the video clip.

This parameter is ignored if the nStopType parameter is set to VIDEOGRABBER_STOP_FRAMES_NUM.

nNumberOfFrames

Number of frames to grab before stopping the grabbing session.

This parameter is ignored if the nStopType parameter is set to VIDEOGRABBER_STOP_POSITION.

Return value

Value | Meaning
0 | An error occurred (check the LastError property for error details)
Other values | The method call was successful and the returned value represents the handle (HBITMAP) of the waveform's bitmap stored in memory


VideoPlayer.FrameGrabberOutputResizeSet method

VideoPlayer.FrameGrabberOutputResizeSet method

Remarks

Predisposes the resizing of pictures generated from frames grabbed from a video clip by a grabbing session that will be started through a later call to one between the VideoPlayer.FrameGrabberExecToFile and VideoPlayer.FrameGrabberExecToMemory methods.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberOutputResizeSet (

nPlayer as Integer,

nOutputWidth as Long,

nOutputHeight as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.FrameGrabberOutputResizeSet (

short nPlayer,

long nOutputWidth,

long nOutputHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nOutputWidth | The width, expressed in pixels, of the output pictures
nOutputHeight | The height, expressed in pixels, of the output pictures

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FrameGrabberResultsGetAvailableType method

VideoPlayer.FrameGrabberResultsGetAvailableType method

Remarks

After completing a grabbing session, through a call to one between the VideoPlayer.FrameGrabberExecToFile and VideoPlayer.FrameGrabberExecToMemory methods, returns the type of the latest video frames grabbing session.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberResultsGetAvailableType (

nPlayer as Integer

) as enumFramesSet

[C++]

short control.VideoPlayer.FrameGrabberResultsGetAvailableType (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value

Meaning

Negative value

An error occurred, check the LastError property value in order to get the error code

Other values

The type of the latest grabbing session.

Supported values are the following:

Mnemonic value | Value | Meaning
TYPE_OF_GRABBED_FRAME_NONE | 0 | No grabbing session occurred.
TYPE_OF_GRABBED_FRAME_FILES | 1 | Frames were grabbed and stored inside output files.
TYPE_OF_GRABBED_FRAME_BITMAPS | 2 | Frames were grabbed and stored inside memory bitmaps.


VideoPlayer.FrameGrabberResultsGetPixelColor method

VideoPlayer.FrameGrabberResultsGetPixelColor method

Remarks

After completing a grabbing session, through a call to one between the VideoPlayer.FrameGrabberExecToFile and VideoPlayer.FrameGrabberExecToMemory methods, given the index of a grabbed frame obtains the color of a pixel at specific coordinates.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberResultsGetPixelColor (

nPlayer as Integer,

nFrameIndex as Long,

X as Long,

Y as Long

) as OLE_COLOR

[C++]

OLE_COLOR control.VideoPlayer.FrameGrabberResultsGetPixelColor (

short nPlayer,

long nFrameIndex,

long X,

long Y

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nFrameIndex

Number representing the zero-based index of the grabbed frame. You can obtain the total number of grabbed frames in the following way:

· if the value returned by the VideoPlayer.FrameGrabberResultsGetAvailableType method is TYPE_OF_GRABBED_FRAME_FILES, call the VideoPlayer.FrameGrabberResultsGetFilesCount method
· if the value returned by the VideoPlayer.FrameGrabberResultsGetAvailableType method is TYPE_OF_GRABBED_FRAME_BITMAPS, call the VideoPlayer.FrameGrabberResultsGetBitmapsCount method

X

Horizontal coordinate of the frame expressed in pixels

Y

Vertical coordinate of the frame expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
Other values | The color of the requested pixel


VideoPlayer.FrameGrabberResultsGetBitmap method

VideoPlayer.FrameGrabberResultsGetBitmap method

Remarks

After completing a grabbing session, through a call to the VideoPlayer.FrameGrabberExecToMemory method, given the index of a grabbed frame obtains the handle (HBITMAP) of the related memory bitmap.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberResultsGetBitmap (

nPlayer as Integer,

nFrameIndex as Long

) as OLE_HANDLE

[C++]

OLE_HANDLE control.VideoPlayer.FrameGrabberResultsGetBitmap (

short nPlayer,

long nFrameIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nFrameIndex | Number representing the zero-based index of the grabbed frame. You can obtain the total number of grabbed frames through the VideoPlayer.FrameGrabberResultsGetBitmapsCount method.

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Other values | The handle (HBITMAP) of the memory bitmap


VideoPlayer.FrameGrabberResultsGetBitmapsCount method

VideoPlayer.FrameGrabberResultsGetBitmapsCount method

Remarks

After completing a grabbing session, through a call VideoPlayer.FrameGrabberExecToMemory method, returns the number of frames grabbed and stored into memory bitmaps.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberResultsGetBitmapsCount (

nPlayer as Integer

) as Long

[C++]

long control.VideoPlayer.FrameGrabberResultsGetBitmapsCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
Other values | The number of available memory bitmaps.


VideoPlayer.FrameGrabberResultsGetFilePathname method

VideoPlayer.FrameGrabberResultsGetFilePathname method

Remarks

After completing a grabbing session, through a call to the VideoPlayer.FrameGrabberExecToFile method, given the index of a grabbed frame obtains the absolute pathname of the picture file where the frame's bitmap is stored.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberResultsGetFilePathname (

nPlayer as Integer,

nFrameIndex as Long

) as String

[C++]

LPCTSTR control.VideoPlayer.FrameGrabberResultsGetFilePathname (

short nPlayer,

long nFrameIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nFrameIndex | Number representing the zero-based index of the grabbed frame. You can obtain the total number of grabbed frames through the VideoPlayer.FrameGrabberResultsGetFilesCount method.

Return value

Value | Meaning
Valid string | Absolute pathname of the picture file where the frame's bitmap is stored
Empty string | An error occurred, check the LastError property value in order to see the error code meaning file


VideoPlayer.FrameGrabberResultsGetFilesCount method

VideoPlayer.FrameGrabberResultsGetFilesCount method

Remarks

After completing a grabbing session, through a call VideoPlayer.FrameGrabberExecToFile method, returns the number of frames grabbed and stored into picture files on the local disk.

For further details about frames grabbing see the How to grab frames from video files tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FrameGrabberResultsGetFilesCount (

nPlayer as Integer

) as Long

[C++]

long control.VideoPlayer.FrameGrabberResultsGetFilesCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
Other values | The number of available picture files.


VideoPlayer.FramesAverageRateGet method

VideoPlayer.FramesAverageRateGet method

Remarks

Obtains the average frame rate for the loaded video clip.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FramesAverageRateGet (

nPlayer as Integer,

fAverageRate as Single

) as Integer

[C++]

short control.VideoPlayer.FramesAverageRateGet (

short nPlayer,

float *fAverageRate

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
fAverageRate | Reference that, on return from the method call, will contain the average frame rate

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FramesNumberGet method

VideoPlayer.FramesNumberGet method

Remarks

Obtains the number of video frames contained inside the loaded video clip.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FramesNumberGet (

nPlayer as Integer,

nFrames as Long

) as Integer

[C++]

short control.VideoPlayer.FramesNumberGet (

short nPlayer,

long *nFrames

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nFrames | Reference that, on return from the method call, will contain the number of frames

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FullscreenMonitorActivate method

VideoPlayer.FullscreenMonitorActivate method

Remarks

Activates or deactivates the full screen mode over a specific monitor previously predisposed for going full screen through the VideoPlayer.FullscreenMonitorPredispose method.

You can determine if full screen is currently activated on a specific monitor through the VideoPlayer.FullscreenMonitorIsActivated method.

For details about full screen management refer to the How to render video clips in full screen tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FullscreenMonitorActivate (

nPlayer as Integer,

nMonitorIndex as Integer,

bActivate as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.FullscreenMonitorActivate (

short nPlayer,

short nMonitorIndex,

short bActivate

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nMonitorIndex

Number representing the zero-based index of the monitor that must render the video clip in full screen. The total number of installed monitors can be obtained using the VideoPlayer.FullscreenMonitorCountGet method.

bActivate

Boolean value that specifies if full screen must be activated or deactivated.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Deactivates full screen
BOOL_TRUE | 1 | Activates full screen

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FullscreenMonitorCountGet method

VideoPlayer.FullscreenMonitorCountGet method

Remarks

Obtains the number of monitors actually installed inside the system that could be used for rendering video clips in full screen.

For details about full screen management refer to the How to render video clips in full screen tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FullscreenMonitorCountGet (

nCount as Integet

) as Integer

[C++]

short control.VideoPlayer.FullscreenMonitorCountGet (

short *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the number of monitors

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FullscreenMonitorIsActivated method

VideoPlayer.FullscreenMonitorIsActivated method

Remarks

Checks if the given monitor is actually rendering the loaded video clip in full screen after a previous call to the VideoPlayer.FullscreenMonitorActivate method..

For details about full screen management refer to the How to render video clips in full screen tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FullscreenMonitorIsActivated (

nPlayer as Integer,

nMonitorIndex as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.FullscreenMonitorIsActivated (

short nPlayer,

short nMonitorIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nMonitorIndex | Number representing the zero-based index of the monitor. The total number of installed monitors can be obtained using the VideoPlayer.FullscreenMonitorCountGet method.

Return value

Value | Meaning
FALSE | The given monitor is not rendering in full screen
TRUE | The given monitor is rendering in full screen


VideoPlayer.FullscreenMonitorNameGet method

VideoPlayer.FullscreenMonitorNameGet method

Remarks

Obtains the name assigned by the system to the given monitor.

For details about full screen management refer to the How to render video clips in full screen tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FullscreenMonitorNameGet (

nMonitorIndex as Integer

) as String

[C++]

LPCTSTR control.VideoPlayer.FullscreenMonitorNameGet (

short nMonitorIndex

);

Parameter | Description
nMonitorIndex | Number representing the zero-based index of the monitor. The total number of installed monitors can be obtained using the VideoPlayer.FullscreenMonitorCountGet method.

Return value

Value | Meaning
Empty string | The value of the nMonitorIndex parameter was out of range. Use the value returned by the VideoPlayer.FullscreenMonitorCountGet method in order to know how many monitors are actually installed inside the system.
Valid string | The string containing the name assigned by the system to the given monitor.


VideoPlayer.FullscreenMonitorPositionGet method

VideoPlayer.FullscreenMonitorPositionGet method

Remarks

Obtains the screen coordinates of the given monitor as assigned by the system.

For details about full screen management refer to the How to render video clips in full screen tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FullscreenMonitorPositionGet (

nMonitorIndex as Integer,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.FullscreenMonitorPositionGet (

short nMonitorIndex,

long *nLeft,

long *nTop,

long *nWidth,

long *nHeight

);

Parameter | Description
nMonitorIndex | Number representing the zero-based index of the monitor. The total number of installed monitors can be obtained using the VideoPlayer.FullscreenMonitorCountGet method.
nLeft | Reference that, on return from the method call, will contain the left position of the monitor expressed in screen coordinates (pixels)
nTop | Reference that, on return from the method call, will contain the top position of the monitor expressed in screen coordinates (pixels)
nWidth | Reference that, on return from the method call, will contain the width of the monitor expressed in pixels
nHeight | Reference that, on return from the method call, will contain the height of the monitor expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FullscreenMonitorPredispose method

VideoPlayer.FullscreenMonitorPredispose method

Remarks

Predisposes full screen management for the given player over a specific monitor. This call is mandatory in order to allow going full screen at a later time through a call to the VideoPlayer.FullscreenMonitorActivate method.

When a monitor is no more needed for going full screen, it can be removed from the list of predisposed monitors through the VideoPlayer.FullscreenMonitorRemove method.

For details about full screen management refer to the How to render video clips in full screen tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FullscreenMonitorPredispose (

nPlayer as Integer,

nMonitorIndex as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.VideoPlayer.FullscreenMonitorPredispose (

short nPlayer,

short nMonitorIndex,

long hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nMonitorIndex | Number representing the zero-based index of the monitor that will be predisposed for going full screen. The total number of installed monitors can be obtained using the VideoPlayer.FullscreenMonitorCountGet method.
hWndTarget | The Windows handle (HWND) of the target form that will be used to render the video clip in full screen over the given monitor. Creating this target form is responsibility of the container application. This form should be without border and caption bar and, if needed, may optionally contain the custom code used to manage the hiding of the form when full screen is no more needed or, as a further example, the possibility to display a context menu when the surface of the video window is clicked with one of the mouse's buttons.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.FullscreenMonitorRemove method

VideoPlayer.FullscreenMonitorRemove method

Remarks

Removes the given monitor from the list of monitors previously predisposed for going full screen through the VideoPlayer.FullscreenMonitorPredispose method.

For details about full screen management refer to the How to render video clips in full screen tutorial.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.FullscreenMonitorRemove (

nPlayer as Integer,

nMonitorIndex as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.FullscreenMonitorRemove (

short nPlayer,

short nMonitorIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nMonitorIndex | Number representing the zero-based index of the monitor that will be removed from the list of monitors predisposed for going full screen. The total number of installed monitors can be obtained using the VideoPlayer.FullscreenMonitorCountGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.GetAspectRatio method

VideoPlayer.GetAspectRatio method

Remarks

Obtains the native aspect ratio of the loaded video. The aspect ratio describes the proportional relationship between its width and its height and it's commonly expressed as two numbers separated by a colon, for example 4:3 and 16:9.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.GetAspectRatio (

nPlayer as Integer,

nAspectX as Long,

nAspectY as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.GetAspectRatio (

short nPlayer,

long *nAspectX,

long *nAspectY

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nAspectX | Reference that, on return from the method call, will contain the native horizontal ratio of the loaded video, for example 4 or 16
nAspectY | Reference that, on return from the method call, will contain the native vertical ratio of the loaded video, for example 3 or 9

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.GetNativeSize method

VideoPlayer.GetNativeSize method

Remarks

Obtains the native size, expressed in pixels, of the loaded video.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.GetNativeSize (

nPlayer as Integer,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.GetNativeSize (

short nPlayer,

long *nWidth,

long *nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nWidth | Reference that, on return from the method call, will contain the native width, expressed in pixels, of the loaded video
nHeight | Reference that, on return from the method call, will contain the native height, expressed in pixels, of the loaded video

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.ImageAdjustEnable method

VideoPlayer.ImageAdjustEnable method

Remarks

Enables/disables image adjustment of video frames.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.ImageAdjustEnable (

nPlayer as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.ImageAdjustEnable (

short nPlayer,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

bEnable

Boolean value that determines if the custom transform filter for video adjustment must be inserted when building the filter graph.

Supported values are the following:

Mnemonic constant

Value

Meaning

BOOL_FALSE (default)

0

Disable image adjustment

BOOL_TRUE

1

Enable image adjustment. In this situation a custom transform filter is inserted inside the filter graph in order to allow processing of video frames: this setting becomes effective only when a new video clip is loaded.

IMPORTANT: The transform filter can be inserted inside the video stream, downstream to the decoder, only if the decoder supports the YUY2 color space. If the YUY2 color space should not be supported, the filter graph would be in any case built without the transform filter. After loading the video clip, you can verify the availability of the transform filter through the VideoPlayer.VideoTransformIsAvailable method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.ImageAdjustIsEnabled method

VideoPlayer.ImageAdjustIsEnabled method

Remarks

Reports if the video transform filter, used for image adjusting, has been inserted correctly inside the DirectShow filter graph.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.ImageAdjustIsEnabled (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.ImageAdjustIsEnabled (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
FALSE | Image adjustment of video frames is disabled
TRUE | Image adjustment of video frames is enabled


VideoPlayer.ImageAdjustPropertyGet method

VideoPlayer.ImageAdjustPropertyGet method

Remarks

Obtains the current value of a specific property related to image adjustment The value of the property can be modified through the VideoPlayer.ImageAdjustPropertySet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.ImageAdjustPropertyGet (

nPlayer as Integer,

nProperty as enumVideoImageAdjustProps,

nValue as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.ImageAdjustPropertyGet (

short nPlayer,

short nProperty,

long *nValue

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nProperty

The property for which we need to retrieve the current value.

Supported values are the following:

Mnemonic value | Value | Meaning
VIDEO_IMAGE_ADJUST_BRIGHTNESS | 0 | Brightness
VIDEO_IMAGE_ADJUST_CONTRAST | 1 | Contrast
VIDEO_IMAGE_ADJUST_SATURATION | 2 | Saturation
VIDEO_IMAGE_ADJUST_HUE | 3 | Hue
VIDEO_IMAGE_ADJUST_GAMMA_CORRECTION | 4 | Gamma Correction

nValue

Reference that, on return from the method call, will contain the property value. The minimum, maximum, default and stepping values for the given property can be retrieved through the VideoPlayer.ImageAdjustPropertyRangeGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.ImageAdjustPropertySet method

VideoPlayer.ImageAdjustPropertySet method

Remarks

Modifies the value of a specific property related to image adjustment The current value of the property can be retrieved through the VideoPlayer.ImageAdjustPropertyGet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.ImageAdjustPropertySet (

nPlayer as Integer,

nProperty as enumVideoImageAdjustProps,

nValue as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.ImageAdjustPropertySet (

short nPlayer,

short nProperty,

long nValue

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nProperty

The property for which we need to modify the current value.

Supported values are the following:

Mnemonic value | Value | Meaning
VIDEO_IMAGE_ADJUST_BRIGHTNESS | 0 | Brightness
VIDEO_IMAGE_ADJUST_CONTRAST | 1 | Contrast
VIDEO_IMAGE_ADJUST_SATURATION | 2 | Saturation
VIDEO_IMAGE_ADJUST_HUE | 3 | Hue
VIDEO_IMAGE_ADJUST_GAMMA_CORRECTION | 4 | Gamma Correction

nValue

The new property value. The minimum, maximum, default and stepping values for the given property can be retrieved through the VideoPlayer.ImageAdjustPropertyRangeGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.ImageAdjustPropertyRangeGet method

VideoPlayer.ImageAdjustPropertyRangeGet method

Remarks

Obtains the range of values supported by a specific property related to image adjustment.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.ImageAdjustPropertyRangeGet (

nPlayer as Integer,

nProperty as enumVideoImageAdjustProps,

nValueMin as Long,

nValueMax as Long,

nValueDefault as Long,

nValueStepping as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.ImageAdjustPropertyRangeGet (

short nPlayer,

short nProperty,

long *nValueMin,

long *nValueMax,

long *nValueDefault,

long *nValueStepping

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nProperty

The property for which we need to retrieve the current value.

Supported values are the following:

Mnemonic value | Value | Meaning
VIDEO_IMAGE_ADJUST_BRIGHTNESS | 0 | Brightness
VIDEO_IMAGE_ADJUST_CONTRAST | 1 | Contrast
VIDEO_IMAGE_ADJUST_SATURATION | 2 | Saturation
VIDEO_IMAGE_ADJUST_HUE | 3 | Hue
VIDEO_IMAGE_ADJUST_GAMMA_CORRECTION | 4 | Gamma Correction

nValueMin

Reference that, on return from the method call, will contain the minimum value that can be set into the given property

nValueMax

Reference that, on return from the method call, will contain the maximum value that can be set into the given property

nValueDefault

Reference that, on return from the method call, will contain the default value for the given property

nValueStepping

Reference that, on return from the method call, will contain the stepping value that can be used for setting a new value into the given property

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.IsAudioStreamAvailable method

VideoPlayer.IsAudioStreamAvailable method

Remarks

Checks if the loaded media file contains an audio stream.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.IsAudioStreamAvailable (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.IsAudioStreamAvailable (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
FALSE | The loaded video clip doesn't contain an audio stream
TRUE | The loaded video clip contains an audio stream


VideoPlayer.IsDirectShowAvail method

VideoPlayer.IsDirectShowAvail method

Remarks

Checks if DirectShow components are installed inside the system.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoPlayer.IsDirectShowAvail (

) as Boolean

[C++]

BOOL control.VideoPlayer.VideoPlayer.IsDirectShowAvail (

);

Return value

Value | Meaning
FALSE | DirectShow components are not installed inside the system
TRUE | DirectShow components are installed inside the system


VideoPlayer.IsSeekable method

VideoPlayer.IsSeekable method

Remarks

Determines if the format of the video loaded inside the given player is seekable and so if the VideoPlayer.Seek method can be effectively called.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.IsSeekable (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.IsSeekable (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
FALSE | Video format is not seekable
TRUE | Video format is seekable


VideoPlayer.IsVideoStreamAvailable method

VideoPlayer.IsVideoStreamAvailable method

Remarks

Checks if the loaded media file contains a video stream.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.IsVideoStreamAvailable (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.IsVideoStreamAvailable (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
FALSE | The loaded video clip doesn't contain a video stream
TRUE | The loaded video clip contains a video stream


VideoPlayer.Load method

VideoPlayer.Load method

Remarks

Loads a video from the specified file. Depending upon the codec and the duration of the video clip to load, due to the fact that the loading is performed inside the main application's thread, the call to this method could cause a temporary freeze of the container application user interface: in order to avoid this issue, the use of the VideoPlayer.LoadSync method should be preferred.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

A successful call to this method will fire the SoundLoaded event.

In order to be able to apply special effects like equalizers or DMO effects, the audio stream must be in Stereo or Mono so, for this reason, 5.1 and 7.1 video files are automatically resampled to Stereo. If you should need keeping 5.1 or 7.1 channels configuration, you would have to set the EnableMixingFeatures property to False.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Load (

nPlayer as Integer,

strFilename as String

) as enumErrorCodes

[C++]

short control.VideoPlayer.Load (

short nPlayer,

LPCTSTR strFilename

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
strFilename | String containing the name of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.LoadForEAX method

VideoPlayer.LoadForEAX method

Remarks

Loads a video from the specified file converting the audio track to Mono for use with EAX effects. Depending upon the codec and the duration of the video clip to load, due to the fact that the loading is performed inside the main application's thread, the call to this method could cause a temporary freeze of the container application user interface: in order to avoid this issue, the use of the VideoPlayer.LoadSyncForEAX method should be preferred.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

A successful call to this method will fire the SoundLoaded event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.LoadForEAX (

nPlayer as Integer,

strFilename as String

) as enumErrorCodes

[C++]

short control.VideoPlayer.LoadForEAX (

short nPlayer,

LPCTSTR strFilename

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
strFilename | String containing the name of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.LoadForTempoChange method

VideoPlayer.LoadForTempoChange method

Remarks

Loads a video from the specified file and predispose it for use with tempo, playback rate and pitch change. Depending upon the codec and the duration of the video clip to load, due to the fact that the loading is performed inside the main application's thread, the call to this method could cause a temporary freeze of the container application user interface: in order to avoid this issue, the use of the VideoPlayer.LoadSyncForTempoChange method should be preferred.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

NOTE ABOUT TEMPO AND PLAYBACK RATE CHANGE: It's important to note that not all of the video codecs are able to manage playback rate change correctly: for example certain kind of AVI codecs will loose synchronism between audio and video when calling the Effects.PlaybackTempoSet or the Effects.PlaybackRateSet methods: this is not a limitation of our control but a defect of the codec when running the video at a speed different than normal. Furthermore, other video codecs are not fast enough in order to provide enough PCM sound data for tempo and/or playback rate change so you could experience "stuttering" during playback: when dealing with codecs that cause stuttering during playback it would be a better solution using the VideoPlayer.Load method.

A successful call to this method will fire the SoundLoaded event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.LoadForTempoChange (

nPlayer as Integer,

strFilename as String

) as enumErrorCodes

[C++]

short control.VideoPlayer.LoadForTempoChange (

short nPlayer,

LPCTSTR strFilename

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
strFilename | String containing the name of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.LoadFromMemory method

VideoPlayer.LoadFromMemory method

Remarks

Loads a video clip stored inside a memory buffer. Depending upon the codec and the duration of the video clip to load, due to the fact that the loading is performed inside the main application's thread, the call to this method could cause a temporary freeze of the container application user interface: in order to avoid this issue, the use of the VideoPlayer.LoadFromMemorySync method should be preferred.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

A successful call to this method will fire the SoundLoaded event.

When using a media format different from MEMORY_MEDIA_FORMAT_UNKNOWN, it's very important that the memory buffer containing the video clip is not deallocated and/or moved until the video clip is not closed through the VideoPlayer.Close method: deallocating and/or moving the memory buffer during playback could crash the container application. When using the MEMORY_MEDIA_FORMAT_UNKNOWN media format, also if the memory buffer is copied into a temporary file, you should in any case wait for the SoundLoaded event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.LoadFromMemory (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C++]

short control.LoadFromMemory (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

short nMediaFormat

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Variant parameter containing the pointer to sound data previously loaded in memory.

nBufferLen

Length in bytes of the given buffer

nMediaFormat

Media format of the video clip stored inside the memory buffer.

Supported values are the following:

Mnemonic constant | Value | Meaning
MEMORY_MEDIA_FORMAT_UNKNOWN | 0 | The media format is unknown or is a format that doesn't allow creating a filter graph from a memory source (like WMV and MP4): in this case the memory buffer is always copied into a temporary file and the filter graph is created starting from the temporary file itself.
MEMORY_MEDIA_FORMAT_AVI | 1 | AVI format.
MEMORY_MEDIA_FORMAT_MPEG1 | 2 | MPEG1 format
MEMORY_MEDIA_FORMAT_MPEG2 | 3 | MPEG2 format

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


VideoPlayer.LoadFromMemoryForEAX method

VideoPlayer.LoadFromMemoryForEAX method

Remarks

Loads a video clip stored inside a memory buffer converting the audio track to Mono for use with EAX effects. Depending upon the codec and the duration of the video clip to load, due to the fact that the loading is performed inside the main application's thread, the call to this method could cause a temporary freeze of the container application user interface: in order to avoid this issue, the use of the VideoPlayer.LoadFromMemorySyncForEAX method should be preferred.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

A successful call to this method will fire the SoundLoaded event.

When using a media format different from MEMORY_MEDIA_FORMAT_UNKNOWN, it's very important that the memory buffer containing the video clip is not deallocated and/or moved until the video clip is not closed through the VideoPlayer.Close method: deallocating and/or moving the memory buffer during playback could crash the container application. When using the MEMORY_MEDIA_FORMAT_UNKNOWN media format, also if the memory buffer is copied into a temporary file, you should in any case wait for the SoundLoaded event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.LoadFromMemoryForEAX (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C++]

short control.LoadFromMemoryForEAX (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

short nMediaFormat

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Variant parameter containing the pointer to sound data previously loaded in memory.

nBufferLen

Length in bytes of the given buffer

nMediaFormat

Media format of the video clip stored inside the memory buffer.

Supported values are the following:

Mnemonic constant | Value | Meaning
MEMORY_MEDIA_FORMAT_UNKNOWN | 0 | The media format is unknown or is a format that doesn't allow creating a filter graph from a memory source (like WMV and MP4): in this case the memory buffer is always copied into a temporary file and the filter graph is created starting from the temporary file itself.
MEMORY_MEDIA_FORMAT_AVI | 1 | AVI format.
MEMORY_MEDIA_FORMAT_MPEG1 | 2 | MPEG1 format
MEMORY_MEDIA_FORMAT_MPEG2 | 3 | MPEG2 format

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


VideoPlayer.LoadFromMemoryForTempoChange method

VideoPlayer.LoadFromMemoryForTempoChange method

Remarks

Loads a video clip stored inside a memory buffer and predispose it for use with tempo, playback rate and pitch change. Depending upon the codec and the duration of the video clip to load, due to the fact that the loading is performed inside the main application's thread, the call to this method could cause a temporary freeze of the container application user interface: in order to avoid this issue, the use of the VideoPlayer.LoadFromMemorySyncForTempoChange method should be preferred.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

A successful call to this method will fire the SoundLoaded event.

When using a media format different from MEMORY_MEDIA_FORMAT_UNKNOWN, it's very important that the memory buffer containing the video clip is not deallocated and/or moved until the video clip is not closed through the VideoPlayer.Close method: deallocating and/or moving the memory buffer during playback could crash the container application. When using the MEMORY_MEDIA_FORMAT_UNKNOWN media format, also if the memory buffer is copied into a temporary file, you should in any case wait for the SoundLoaded event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.LoadFromMemoryForTempoChange (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C++]

short control.LoadFromMemoryForTempoChange (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

short nMediaFormat

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Variant parameter containing the pointer to sound data previously loaded in memory.

nBufferLen

Length in bytes of the given buffer

nMediaFormat

Media format of the video clip stored inside the memory buffer.

Supported values are the following:

Mnemonic constant | Value | Meaning
MEMORY_MEDIA_FORMAT_UNKNOWN | 0 | The media format is unknown or is a format that doesn't allow creating a filter graph from a memory source (like WMV and MP4): in this case the memory buffer is always copied into a temporary file and the filter graph is created starting from the temporary file itself.
MEMORY_MEDIA_FORMAT_AVI | 1 | AVI format.
MEMORY_MEDIA_FORMAT_MPEG1 | 2 | MPEG1 format
MEMORY_MEDIA_FORMAT_MPEG2 | 3 | MPEG2 format

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


VideoPlayer.LoadFromMemorySync method

VideoPlayer.LoadFromMemorySync method

Remarks

Loads a video clip stored inside a memory buffer. In order to avoid a temporary freeze of the container application user interface, the loading is performed inside a secondary thread so, when this call will return, the video will not be still available: it's recommended triggering the SoundSyncLoaded event before making further calls for starting playback or for obtaining information about the loaded video.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

A successful call to this method will fire the SoundLoaded event.

When using a media format different from MEMORY_MEDIA_FORMAT_UNKNOWN, it's very important that the memory buffer containing the video clip is not deallocated and/or moved until the video clip is not closed through the VideoPlayer.Close method: deallocating and/or moving the memory buffer during playback could crash the container application. When using the MEMORY_MEDIA_FORMAT_UNKNOWN media format, also if the memory buffer is copied into a temporary file, you should in any case wait for the SoundLoaded event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.LoadFromMemorySync (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C++]

short control.LoadFromMemorySync (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

short nMediaFormat

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Variant parameter containing the pointer to sound data previously loaded in memory.

nBufferLen

Length in bytes of the given buffer

nMediaFormat

Media format of the video clip stored inside the memory buffer.

Supported values are the following:

Mnemonic constant | Value | Meaning
MEMORY_MEDIA_FORMAT_UNKNOWN | 0 | The media format is unknown or is a format that doesn't allow creating a filter graph from a memory source (like WMV and MP4): in this case the memory buffer is always copied into a temporary file and the filter graph is created starting from the temporary file itself.
MEMORY_MEDIA_FORMAT_AVI | 1 | AVI format.
MEMORY_MEDIA_FORMAT_MPEG1 | 2 | MPEG1 format
MEMORY_MEDIA_FORMAT_MPEG2 | 3 | MPEG2 format

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


VideoPlayer.LoadFromMemorySyncForEAX method

VideoPlayer.LoadFromMemorySyncForEAX method

Remarks

Loads a video clip stored inside a memory buffer converting the audio track to Mono for use with EAX effects. In order to avoid a temporary freeze of the container application user interface, the loading is performed inside a secondary thread so, when this call will return, the video will not be still available: it's recommended triggering the SoundSyncLoaded event before making further calls for starting playback or for obtaining information about the loaded video.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

A successful call to this method will fire the SoundLoaded event.

When using a media format different from MEMORY_MEDIA_FORMAT_UNKNOWN, it's very important that the memory buffer containing the video clip is not deallocated and/or moved until the video clip is not closed through the VideoPlayer.Close method: deallocating and/or moving the memory buffer during playback could crash the container application. When using the MEMORY_MEDIA_FORMAT_UNKNOWN media format, also if the memory buffer is copied into a temporary file, you should in any case wait for the SoundLoaded event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.LoadFromMemorySyncForEAX (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C++]

short control.LoadFromMemorySyncForEAX (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

short nMediaFormat

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Variant parameter containing the pointer to sound data previously loaded in memory.

nBufferLen

Length in bytes of the given buffer

nMediaFormat

Media format of the video clip stored inside the memory buffer.

Supported values are the following:

Mnemonic constant | Value | Meaning
MEMORY_MEDIA_FORMAT_UNKNOWN | 0 | The media format is unknown or is a format that doesn't allow creating a filter graph from a memory source (like WMV and MP4): in this case the memory buffer is always copied into a temporary file and the filter graph is created starting from the temporary file itself.
MEMORY_MEDIA_FORMAT_AVI | 1 | AVI format.
MEMORY_MEDIA_FORMAT_MPEG1 | 2 | MPEG1 format
MEMORY_MEDIA_FORMAT_MPEG2 | 3 | MPEG2 format

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


VideoPlayer.LoadFromMemorySyncForTempoChange method

VideoPlayer.LoadFromMemorySyncForTempoChange method

Remarks

Loads a video clip stored inside a memory buffer and predispose it for use with tempo, playback rate and pitch change. In order to avoid a temporary freeze of the container application user interface, the loading is performed inside a secondary thread so, when this call will return, the video will not be still available: it's recommended triggering the SoundSyncLoaded event before making further calls for starting playback or for obtaining information about the loaded video.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

A successful call to this method will fire the SoundLoaded event.

When using a media format different from MEMORY_MEDIA_FORMAT_UNKNOWN, it's very important that the memory buffer containing the video clip is not deallocated and/or moved until the video clip is not closed through the VideoPlayer.Close method: deallocating and/or moving the memory buffer during playback could crash the container application. When using the MEMORY_MEDIA_FORMAT_UNKNOWN media format, also if the memory buffer is copied into a temporary file, you should in any case wait for the SoundLoaded event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.LoadFromMemorySyncForTempoChange (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C++]

short control.LoadFromMemorySyncForTempoChange (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen,

short nMediaFormat

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Variant parameter containing the pointer to sound data previously loaded in memory.

nBufferLen

Length in bytes of the given buffer

nMediaFormat

Media format of the video clip stored inside the memory buffer.

Supported values are the following:

Mnemonic constant | Value | Meaning
MEMORY_MEDIA_FORMAT_UNKNOWN | 0 | The media format is unknown or is a format that doesn't allow creating a filter graph from a memory source (like WMV and MP4): in this case the memory buffer is always copied into a temporary file and the filter graph is created starting from the temporary file itself.
MEMORY_MEDIA_FORMAT_AVI | 1 | AVI format.
MEMORY_MEDIA_FORMAT_MPEG1 | 2 | MPEG1 format
MEMORY_MEDIA_FORMAT_MPEG2 | 3 | MPEG2 format

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The file has been loaded correctly.


VideoPlayer.LoadSync method

VideoPlayer.LoadSync method

Remarks

Loads a video from the specified file. In order to avoid a temporary freeze of the container application user interface, the loading is performed inside a secondary thread so, when this call will return, the video will not be still available: it's recommended triggering the SoundSyncLoaded event before making further calls for starting playback or for obtaining information about the loaded video.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

In order to be able to apply special effects like equalizers or DMO effects, the audio stream must be in Stereo or Mono so, for this reason, 5.1 and 7.1 video files are automatically resampled to Stereo. If you should need keeping 5.1 or 7.1 channels configuration, you would have to set the EnableMixingFeatures property to False.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.LoadSync (

nPlayer as Integer,

strFilename as String

) as enumErrorCodes

[C++]

short control.VideoPlayer.LoadSync (

short nPlayer,

LPCTSTR strFilename

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
strFilename | String containing the name of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.LoadSyncForEAX method

VideoPlayer.LoadSyncForEAX method

Remarks

Loads a video from the specified file converting the audio track to Mono for use with EAX effects. In order to avoid a temporary freeze of the container application user interface, the loading is performed inside a secondary thread so, when this call will return, the video will not be still available: it's recommended triggering the SoundSyncLoaded event before making further calls for starting playback or for obtaining information about the loaded video.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.LoadSyncForEAX (

nPlayer as Integer,

strFilename as String

) as enumErrorCodes

[C++]

short control.VideoPlayer.LoadSyncForEAX (

short nPlayer,

LPCTSTR strFilename

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
strFilename | String containing the name of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.LoadSyncForTempoChange method

VideoPlayer.LoadSyncForTempoChange method

Remarks

Loads a video from the specified file and predispose it for use with tempo, playback rate and pitch change. In order to avoid a temporary freeze of the container application user interface, the loading is performed inside a secondary thread so, when this call will return, the video will not be still available: it's recommended triggering the SoundSyncLoaded event before making further calls for starting playback or for obtaining information about the loaded video.

Video loading and rendering is performed through DirectShow so, in order to load a certain video format (like MPEG, MP4, AVI, etc.) the specific codec must be available on the target system or calls to this method would fail. One of the best packages containing most audio and video codecs for DirectShow is K-Lite Codec Pack and can be downloaded for free from the following link.

IMPORTANT NOTE ABOUT CODECS AND WINDOWS 7: When dealing with Windows 7, also if you have installed K-Lite and configured ffdshow to manage a specific format (for example the MPEG-2 format or the H.264 format used in some MP4 video clip), DirectShow will continue using the default decoder named "Microsoft DTV-DVD Video Decoder": the quality of this decoder is quite poor and doesn't support the VMR-9 video renderer used for mixing/blending video clips so a call to this method could return back an error when the involved player has been added to a video mixer through the VideoPlayer.AttachToVideoMixer method; inside Appendix B you will find a few guidelines that could be of help in order to manage DirectShow configuration through K-Lite provided tools.

NOTE ABOUT TEMPO AND PLAYBACK RATE CHANGE: It's important to note that not all of the video codecs are able to manage playback rate change correctly: for example certain kind of AVI codecs will loose synchronism between audio and video when calling the Effects.PlaybackTempoSet or the Effects.PlaybackRateSet methods: this is not a limitation of our control but a defect of the codec when running the video at a speed different than normal. Furthermore, other video codecs are not fast enough in order to provide enough PCM sound data for tempo and/or playback rate change so you could experience "stuttering" during playback: when dealing with codecs that cause stuttering during playback it would be a better solution using the VideoPlayer.Load method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.LoadSyncForTempoChange (

nPlayer as Integer,

strFilename as String

) as enumErrorCodes

[C++]

short control.VideoPlayer.LoadSyncForTempoChange (

short nPlayer,

LPCTSTR strFilename

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
strFilename | String containing the name of the song file to load. It can be a full path name (ex. c:\mysounds\sound.mp3) or a filename (ex: sound.mp3) if the SoundsDirectory property has already been specified.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDEnable method

VideoPlayer.OSDEnable method

Remarks

Enables/disables the On-Screen-Display (OSD) that will be used to show graphics over the video player rendering window. You can know if the OSD is enabled or disabled through a call to the VideoPlayer.OSDIsEnabled method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDEnable (

nPlayer as Integer,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDEnable (

short nPlayer,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

bEnable

Boolean value that determines if the OSD is enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Disable the OSD
BOOL_TRUE | 1 | Enable the OSD

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDIsEnabled method

VideoPlayer.OSDIsEnabled method

Remarks

Checks if the On-Screen-Display (OSD) for the given video mixer is enabled or disabled. The OSD can be enabled/disabled through the VideoPlayer.OSDEnable method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDIsEnabled (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.OSDIsEnabled (

short nPlayer,

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The OSD is disabled
BOOL_TRUE | 1 | The OSD is enabled


VideoPlayer.OSDItemAlphaGet method

VideoPlayer.OSDItemAlphaGet method

Remarks

Obtains the current alpha channel transparency applied to the graphical item on the On-Screen-Display (OSD). The value can be modified through the VideoPlayer.OSDItemAlphaSet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemAlphaGet (

nPlayer as Integer,

nItemUniqueId as Long,

nAlpha as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemAlphaGet (

short nPlayer,

long nItemUniqueId,

short *nAlpha

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd
nAlpha | Reference that, on return from the method call, will contain the alpha channel transparency expressed in percentage. Values can range from 0 (total opacity) to 100 (total transparency).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemAlphaSet method

VideoPlayer.OSDItemAlphaSet method

Remarks

Sets the alpha channel transparency applied to the graphical item on the On-Screen-Display (OSD). The current value can be obtained through the VideoPlayer.OSDItemAlphaGet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemAlphaSet (

nPlayer as Integer,

nItemUniqueId as Long,

nAlpha as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemAlphaSet (

short nPlayer,

long nItemUniqueId,

short nAlpha

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd
nAlpha | The alpha channel transparency expressed in percentage. Values can range from 0 (total opacity) to 100 (total transparency).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemBitmapAdd method

VideoPlayer.OSDItemBitmapAdd method

Remarks

Adds a new graphical item to the On-Screen-Display (OSD) by getting its representation from memory bitmap.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemBitmapAdd (

nPlayer as Integer,

hBitmap as OLE_HANDLE,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean

) as Long

[C++]

long control.VideoPlayer.OSDItemBitmapAdd (

short nPlayer,

OLE_HANDLE hBitmap,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

hBitmap

Handle of the bitmap (HBITMAP). The bitmap can be modified at a later time through the VideoPlayer.OSDItemBitmapChange method.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoPlayer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoPlayer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoPlayer.OSDItemShow method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoPlayer.OSDItemBitmapChange method

VideoPlayer.OSDItemBitmapChange method

Remarks

Changes the bitmap for an existing graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemBitmapChange (

nPlayer as Integer,

nItemUniqueId as Long,

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemBitmapChange (

short nPlayer,

long nItemUniqueId,

OLE_HANDLE hBitmap

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoPlayer.OSDItemBitmapAdd method
hBitmap | Handle of the bitmap (HBITMAP).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemBitmapGet method

VideoPlayer.OSDItemBitmapGet method

Remarks

Obtains the bitmap for an existing graphical item previously added to the On-Screen-Display (OSD) through a call to the VideoPlayer.OSDItemBitmapAdd or VideoPlayer.OSDItemPictureFileAdd or VideoPlayer.OSDItemPictureMemoryAdd methods.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemBitmapGet (

nPlayer as Integer,

nItemUniqueId as Long,

hBitmap as OLE_HANDLE,

nOriginalWidth as Long,

nOriginalHeight as Long,

nResizeWidth as Long,

nResizeHeight as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemBitmapGet (

short nPlayer,

long nItemUniqueId,

OLE_HANDLE *hBitmap,

long *nOriginalWidth,

long *nOriginalHeight,

long nResizeWidth,

long nResizeHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoPlayer.OSDItemBitmapAdd method
hBitmap | Reference that, on return from the method call, will contain the handle of the bitmap (HBITMAP).
nOriginalWidth | Reference that, on return from the method call, will contain the original width, expressed in pixels, of the picture
nOriginalHeight | Reference that, on return from the method call, will contain the original height, expressed in pixels, of the picture
nResizeWidth | Width, expressed in pixels, for resizing the picture before returning the HBITMAP; ignored if set to 0
nResizeHeight | Height, expressed in pixels, for resizing the picture before returning the HBITMAP; ignored if set to 0

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemChangeAlignment method

VideoPlayer.OSDItemChangeAlignment method

Remarks

Changes the alignment of the graphical item respect to the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemChangeAlignment (

nPlayer as Integer,

nItemUniqueId as Long,

nAlignment as enumRectAlignment

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemChangeAlignment (

short nPlayer,

long nItemUniqueId,

short nAlignment

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nItemUniqueId

Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd

nAlignment

Alignment of the item's rectangle respect to the rectangle of the OSD.

Supported values are the following:

Mnemonic constant | Value | Meaning
RECT_ALIGN_LEFT_TOP | 0 | Item is Left-Top aligned
RECT_ALIGN_CENTER_TOP | 1 | Item is Center-Top aligned
RECT_ALIGN_RIGHT_TOP | 2 | Item is Right-Top aligned
RECT_ALIGN_LEFT_MIDDLE | 3 | Item is Left-Middle aligned
RECT_ALIGN_CENTER_MIDDLE | 4 | Item is Center-Middle aligned
RECT_ALIGN_RIGHT_MIDDLE | 5 | Item is Right-Middle aligned
RECT_ALIGN_LEFT_BOTTOM | 6 | Item is Left-Bottom aligned
RECT_ALIGN_CENTER_BOTTOM | 7 | Item is Center-Bottom aligned
RECT_ALIGN_RIGHT_BOTTOM | 8 | Item is Right-Bottom aligned

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemIsOnVisibleArea method

VideoPlayer.OSDItemIsOnVisibleArea method

Remarks

Determines if the given graphical item is currently positioned inside the visible area of the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemIsOnVisibleArea (

nPlayer as Integer,

nItemUniqueId as Long,

bIsVisible as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemIsOnVisibleArea (

short nPlayer,

long nItemUniqueId,

short *bIsVisible

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nItemUniqueId

Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd

bIsVisible

Reference to a boolean value that, on return from the method call, will tell if the item is inside the visible area of the OSD.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is outside of the visible area
BOOL_TRUE | 1 | The item is inside the visible area

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemMove method

VideoPlayer.OSDItemMove method

Remarks

Moves the position of the graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemMove (

nPlayer as Integer,

nItemUniqueId as Long,

fLeftPos as Single,

fTopPos as Single

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemMove (

short nPlayer,

long nItemUniqueId,

float fLeftPos,

float fTopPos

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd
fLeftPos | Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.
fTopPos | Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemOutlineTextAdd method

VideoPlayer.OSDItemOutlineTextAdd method

Remarks

Adds a string of outlined text as a new graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemOutlineTextAdd (

nPlayer as Integer,

strText as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean,

pLogFont as Long,

strFacename as String,

color as OLE_COLOR,

colorOutline as OLE_COLOR,

nAlignment as enumTextAlignment,

nOutlineWidth as Integer

) as Long

[C++]

long control.VideoPlayer.OSDItemOutlineTextAdd (

short nPlayer,

LPCTSTR strText,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow,

long pLogFont,

LPCTSTR strFacename,

OLE_COLOR color,

OLE_COLOR colorOutline,

short nAlignment,

short nOutlineWidth

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

strText

Text string.

The text string can can be modified at a later time through the VideoPlayer.OSDItemOutlineTextChange method.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoPlayer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoPlayer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoPlayer.OSDItemShow method.

pLogFont

Address in memory of the the LOGFONT structure containing the font settings used to render this item.

Refer to the Microsoft documentation for details about the LOGFONT structure. The lfFaceName member of the LOGFONT structure is currently ignored: use the strFacename parameter below for passing the typeface of the font.

This setting can can be modified at a later time through the VideoPlayer.OSDItemOutlineTextChange method.

strFacename

String containing the typeface of the font, for example "Arial" or "Times New Roman".

This setting can can be modified at a later time through the VideoPlayer.OSDItemOutlineTextChange method.

color

Color used to render this item.

This setting can can be modified at a later time through the VideoPlayer.OSDItemOutlineTextChange method.

colorOutline

Color used to render the outline of the text.

This setting can can be modified at a later time through the VideoPlayer.OSDItemOutlineTextChange method.

nAlignment

Text alignment respect to the item's rectangle.

Supported values are the following:

Mnemonic constant | Value | Meaning
TEXT_ALIGN_LEFT | 0 | Text is left aligned
TEXT_ALIGN_CENTER | 1 | Text is centered
TEXT_ALIGN_RIGHT | 2 | Text is right aligned

This setting can can be modified at a later time through the VideoPlayer.OSDItemOutlineTextChange method.

nOutlineWidth

Width of the outline expressed in pixels.

This setting can can be modified at a later time through the VideoPlayer.OSDItemOutlineTextChange method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoPlayer.OSDItemOutlineTextChange method

VideoPlayer.OSDItemOutlineTextChange method

Remarks

Changes the string and settings of the given outlined text item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemOutlineTextChange (

nPlayer as Integer,

nItemUniqueId as Long,

strText as String,

pLogFont as long,

strFacename as String,

color as OLE_COLOR,

colorOutline as OLE_COLOR,

nAlignment as enumTextAlignment,

nOutlineWidth as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemOutlineTextChange (

short nPlayer,

long nItemUniqueId,

LPCTSTR strText,

long pLogFont,

LPCTSTR strFacename,

OLE_COLOR color,

OLE_COLOR colorOutline,

short nAlignment,

short nOutlineWidth

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nItemUniqueId

Unique identifier of item returned by a previous call to the VideoPlayer.OSDItemOutlineTextAdd method

strText

Text string

pLogFont

Address in memory of the the LOGFONT structure containing the font settings used to render this item.

Refer to the Microsoft documentation for details about the LOGFONT structure. The lfFaceName member of the LOGFONT structure is currently ignored: use the strFacename parameter below for passing the typeface of the font.

strFacename

String containing the typeface of the font, for example "Arial" or "Times New Roman"

color

Color used to render this item

colorOutline

Color used to render the outline of the text.

nAlignment

Text alignment respect to the item's rectangle.

Supported values are the following:

Mnemonic constant | Value | Meaning
TEXT_ALIGN_LEFT | 0 | Text is left aligned
TEXT_ALIGN_CENTER | 1 | Text is centered
TEXT_ALIGN_RIGHT | 2 | Text is right aligned

nOutlineWidth

Width of the outline expressed in pixels.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemPictureFileAdd method

VideoPlayer.OSDItemPictureFileAdd method

Remarks

Adds a new graphical item to the On-Screen-Display (OSD) by getting its representation from a picture file.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemPictureFileAdd (

nPlayer as Integer,

strPathname as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean

) as Long

[C++]

long control.VideoPlayer.OSDItemPictureFileAdd (

short nPlayer,

LPCTSTR strPathname,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

strPathname

Absolute pathname of the picture file. The picture file can be modified at a later time through the VideoPlayer.OSDItemPictureFileChange method.

Accepted picture formats are BMP, GIF, JPEG and PNG.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoPlayer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoPlayer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoPlayer.OSDItemShow method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoPlayer.OSDItemPictureFileChange method

VideoPlayer.OSDItemPictureFileChange method

Remarks

Changes the picture for an existing graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemPictureFileChange (

nPlayer as Integer,

nItemUniqueId as Long,

strPathname as String

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemPictureFileChange (

short nPlayer,

long nItemUniqueId,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoPlayer.OSDItemPictureFileAdd method
strPathname | Absolute pathname of the picture file. Accepted picture formats are BMP, GIF, JPEG and PNG.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemPictureMemoryAdd method

VideoPlayer.OSDItemPictureMemoryAdd method

Remarks

Adds a new graphical item to the On-Screen-Display (OSD) by getting its representation from a picture file stored inside a memory buffer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemPictureMemoryAdd (

nPlayer as Integer,

pBuffer as Variant,

nBufferLength as Long,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean

) as Long

[C++]

long control.VideoPlayer.OSDItemPictureMemoryAdd (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLength,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

pBuffer

Variant parameter containing the pointer to the picture file previously loaded in memory. The picture can be modified at a later time through the VideoPlayer.OSDItemPictureMemoryChange method.

Accepted picture formats to store inside the memory buffer are BMP, GIF, JPEG and PNG.

nBufferLength

Length in bytes of the given buffer

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoPlayer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoPlayer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoPlayer.OSDItemShow method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoPlayer.OSDItemPictureMemoryChange method

VideoPlayer.OSDItemPictureMemoryChange method

Remarks

Changes the picture for an existing graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemPictureMemoryChange (

nPlayer as Integer,

nItemUniqueId as Long,

pBuffer as Variant,

nBufferLength as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemPictureMemoryChange (

short nPlayer,

long nItemUniqueId,

const VARIANT FAR& pBuffer,

long nBufferLength

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoPlayer.OSDItemPictureMemoryAdd method
pBuffer | Variant parameter containing the pointer to the picture file previously loaded in memory. Accepted picture formats are BMP, GIF, JPEG and PNG.
nBufferLength | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemRectangleAdd method

VideoPlayer.OSDItemRectangleAdd method

Remarks

Adds a rectangle as a new graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemRectangleAdd (

nPlayer as Integer,

fLeftPos as Single,

fTopPos as Single,

fWidth as Single,

fHeight as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean,

color as OLE_COLOR

) as Long

[C++]

long control.VideoPlayer.OSDItemRectangleAdd (

short nPlayer,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

short nAlpha,

long nZOrder,

short bShow,

OLE_COLOR color

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method or through the VideoPlayer.OSDItemRectangleChange method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method or through the VideoPlayer.OSDItemRectangleChange method.

fWidth

Width, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle.

Size can be modified at a later time through the VideoPlayer.OSDItemRectangleChange method..

fHeight

Height, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle.

Size can be modified at a later time through the VideoPlayer.OSDItemRectangleChange method..

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoPlayer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoPlayer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoPlayer.OSDItemShow method.

color

Color used to render this item.

This setting can can be modified at a later time through the VideoPlayer.OSDItemRectangleChange method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoPlayer.OSDItemRectangleChange method

VideoPlayer.OSDItemRectangleChange method

Remarks

Changes characteristics of the given rectangle on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemRectangleChange (

nPlayer as Integer,

nItemUniqueId as Long,

fLeftPos as Single,

fTopPos as Single,

fWidth as Single,

fHeight as Single,

color as OLE_COLOR

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemRectangleChange (

short nPlayer,

long nItemUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

OLE_COLOR color

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of item returned by a previous call to the VideoPlayer.OSDItemRectangleAdd method
fLeftPos | Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.
fTopPos | Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.
fWidth | Width, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle.
fHeight | Height, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle.
color | Color used to render this item.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemRectGet method

VideoPlayer.OSDItemRectGet method

Remarks

Obtains the coordinates of the rectangle surrounding the item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemRectGet (

nPlayer as Integer,

nItemUniqueId as Long,

fLeftPos as Single,

fTopPos as Single,

fRightPos as Single,

fBottomPos as Single

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemRectGet (

short nPlayer,

long nItemUniqueId,

float fLeftPos,

float fTopPos,

float fRightPos,

float fBottomPos

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd.
fLeftPos | Reference that, on return from the method call, will contain the left position, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle surrounding the item,
fTopPos | Reference that, on return from the method call, will contain the top position, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle surrounding the item,
fRightPos | Reference that, on return from the method call, will contain the right position, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle surrounding the item,
fBottomPos | Reference that, on return from the method call, will contain the bottom position, expressed in percentage of the On-Screen-Display (OSD) area, of the rectangle surrounding the item,

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemRemove method

VideoPlayer.OSDItemRemove method

Remarks

Removes the given graphical item from the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemRemove (

nPlayer as Integer,

nItemUniqueId as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemRemove (

short nPlayer,

long nItemUniqueId

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd. Set this parameter to -1 for removing all of the available items in one single shot.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemScrollByPixels method

VideoPlayer.OSDItemScrollByPixels method

Remarks

Scrolls the position of the graphical item on the On-Screen-Display (OSD) by a given amount of pixels.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemScrollByPixels (

nPlayer as Integer,

nItemUniqueId as Long,

xOffset as Long,

yOffset as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemScrollByPixels (

short nPlayer,

long nItemUniqueId,

long xOffset,

long yOffset

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd
xOffset | Horizontal offset, expressed in pixels, used to scroll the item
yOffset | Vertical offset, expressed in pixels, used to scroll the item

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemShow method

VideoPlayer.OSDItemShow method

Remarks

Shows/hides the graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemShow (

nPlayer as Integer,

nItemUniqueId as Long,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemShow (

short nPlayer,

long nItemUniqueId,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nItemUniqueId

Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd

bShow

Boolean value that determines if the item must be shown or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the item
BOOL_TRUE | 1 | Shows the item

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemTextAdd method

VideoPlayer.OSDItemTextAdd method

Remarks

Adds a string of text as a new graphical item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemTextAdd (

nPlayer as Integer,

strText as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Integer,

nZOrder as Long,

bShow as enumBoolean,

pLogFont as Long,

strFacename as String,

color as OLE_COLOR,

nAlignment as enumTextAlignment

) as Long

[C++]

long control.VideoPlayer.OSDItemTextAdd (

short nPlayer,

LPCTSTR strText,

float fLeftPos,

float fTopPos,

short nAlpha,

long nZOrder,

short bShow,

long pLogFont,

LPCTSTR strFacename,

OLE_COLOR color,

short nAlignment

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

strText

Text string.

The text string can can be modified at a later time through the VideoPlayer.OSDItemTextChange method.

fLeftPos

Horizontal position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

fTopPos

Vertical position, expressed in percentage of the On-Screen-Display (OSD) area, where the item will be rendered.

Position can be moved at a later time through the VideoPlayer.OSDItemMove method.

nAlpha

Alpha channel transparency, expressed in percentage, applied to the item when rendered. Values can range from 0 (total opacity) to 100 (total transparency).

The alpha channel transparency of the item can be modified at a later time through the VideoPlayer.OSDItemAlphaSet method.

nZOrder

Z-Order of the item.

Items with a lower Z-Order value will stay on top respect to other Items having a higher Z-Order value; for example, an Item with Z-Order 0 will stay on top of any other Item but, in case two Items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

The Z-Order of the item can be modified at a later time through the VideoPlayer.OSDItemZOrderSet method.

bShow

Boolean flag that specifies if the item must be initially visible or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The item is initially kept hidden
BOOL_TRUE | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoPlayer.OSDItemShow method.

pLogFont

Address in memory of the the LOGFONT structure containing the font settings used to render this item.

Refer to the Microsoft documentation for details about the LOGFONT structure. The lfFaceName member of the LOGFONT structure is currently ignored: use the strFacename parameter below for passing the typeface of the font.

This setting can can be modified at a later time through the VideoPlayer.OSDItemTextChange method.

strFacename

String containing the typeface of the font, for example "Arial" or "Times New Roman".

This setting can can be modified at a later time through the VideoPlayer.OSDItemTextChange method.

color

Color used to render this item.

This setting can can be modified at a later time through the VideoPlayer.OSDItemTextChange method.

nAlignment

Text alignment respect to the item's rectangle.

Supported values are the following:

Mnemonic constant | Value | Meaning
TEXT_ALIGN_LEFT | 0 | Text is left aligned
TEXT_ALIGN_CENTER | 1 | Text is centered
TEXT_ALIGN_RIGHT | 2 | Text is right aligned

This setting can can be modified at a later time through the VideoPlayer.OSDItemTextChange method.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Other values | Unique identifier of the graphical item: this unique identifier will be used in order to invoke further methods related to the use of this specific item


VideoPlayer.OSDItemTextChange method

VideoPlayer.OSDItemTextChange method

Remarks

Changes the string and settings of the given text item on the On-Screen-Display (OSD).

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemTextChange (

nPlayer as Integer,

nItemUniqueId as Long,

strText as String,

pLogFont as long,

strFacename as String,

color as OLE_COLOR,

nAlignment as enumTextAlignment

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemTextChange (

short nPlayer,

long nItemUniqueId,

LPCTSTR strText,

long pLogFont,

LPCTSTR strFacename,

OLE_COLOR color,

short nAlignment

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nItemUniqueId

Unique identifier of item returned by a previous call to the VideoPlayer.OSDItemTextAdd method

strText

Text string

pLogFont

Address in memory of the the LOGFONT structure containing the font settings used to render this item.

Refer to the Microsoft documentation for details about the LOGFONT structure. The lfFaceName member of the LOGFONT structure is currently ignored: use the strFacename parameter below for passing the typeface of the font.

strFacename

String containing the typeface of the font, for example "Arial" or "Times New Roman"

color

Color used to render this item

nAlignment

Text alignment respect to the item's rectangle.

Supported values are the following:

Mnemonic constant | Value | Meaning
TEXT_ALIGN_LEFT | 0 | Text is left aligned
TEXT_ALIGN_CENTER | 1 | Text is centered
TEXT_ALIGN_RIGHT | 2 | Text is right aligned

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemZOrderGet method

VideoPlayer.OSDItemZOrderGet method

Remarks

Obtains the current Z-Order applied to the graphical item on the On-Screen-Display (OSD). The value for the Z-Order can be modified through the VideoPlayer.OSDItemZOrderSet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemZOrderGet (

nPlayer as Integer,

nItemUniqueId as Long,

nZOrder as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemZOrderGet (

short nPlayer,

long nItemUniqueId,

long *nZOrder

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd
nZOrder | Reference that, on return from the method call, will contain the Z-Order for the given OSD item. Items with a lower Z-Order value will stay on top respect to other items having a higher Z-Order value; for example, an item with Z-Order 0 will stay on top of any other item but, in case two items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDItemZOrderSet method

VideoPlayer.OSDItemZOrderSet method

Remarks

Sets the Z-Order applied to the graphical item on the On-Screen-Display (OSD). The current value for the Z-Order can be obtained through the VideoPlayer.OSDItemZOrderGet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDItemZOrderSet (

nPlayer as Integer,

nItemUniqueId as Long,

nZOrder as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDItemZOrderSet (

short nPlayer,

long nItemUniqueId,

long nZOrder

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nItemUniqueId | Unique identifier of the item returned by a previous call to one between the following methods: VideoPlayer.OSDItemPictureFileAdd, VideoPlayer.OSDItemBitmapAdd, VideoPlayer.OSDItemTextAdd, VideoPlayer.OSDItemOutlineTextAdd or VideoPlayer.OSDItemRectangleAdd
nZOrder | The Z-Order for the given OSD item. Items with a lower Z-Order value will stay on top respect to other items having a higher Z-Order value; for example, an item with Z-Order 0 will stay on top of any other item but, in case two items should be assigned the same Z-Order, the latest one having got the same Z-Order will be placed on top of the previous one.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.OSDKeyColorGet method

VideoPlayer.OSDKeyColorGet method

Remarks

Obtains the current key color that will be rendered as transparent on the On-Screen-Display (OSD). The key color can be modified through the VideoPlayer.OSDKeyColorSet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDKeyColorGet (

nPlayer as Integer

) as OLE_COLOR

[C++]

OLE_COLOR control.VideoPlayer.OSDKeyColorGet (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The current key color


VideoPlayer.OSDKeyColorSet method

VideoPlayer.OSDKeyColorSet method

Remarks

Sets the key color that will be rendered as transparent on the On-Screen-Display (OSD). The current key color can be obtained through the VideoPlayer.OSDKeyColorGet method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.OSDKeyColorSet (

nPlayer as Integer,

colorKey as OLE_COLOR

) as enumErrorCodes

[C++]

short control.VideoPlayer.OSDKeyColorSet (

short nPlayer,

OLE_COLOR colorKey

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
colorKey | Key color rendered as transparent

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.Pause method

VideoPlayer.Pause method

Remarks

Pauses the playing video.

A successful call to this method will fire the SoundPaused event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Pause (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.Pause (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.Play method

VideoPlayer.Play method

Remarks

Plays the video previously loaded inside the given player through one between VideoPlayer.Load or VideoPlayer.LoadForEAX methods.

A successful call to this method will fire the SoundPlaying event. Once the sound has been performed completely, the control will fire the SoundDone event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Play (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.Play (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.PlayRange method

VideoPlayer.PlayRange method

Remarks

Plays a defined range of the video previously loaded inside the given player through one between VideoPlayer.Load or VideoPlayer.LoadForEAX methods.

A successful call to this method will fire the SoundPlaying event. Once the sound has been performed completely, the control will fire the SoundDone event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.PlayRange (

nPlayer as Integer,

nFromPosition as Long,

nToPosition as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.PlayRange (

short nPlayer,

long nFromPosition,

long nToPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will play the sound range
nFromPosition | Range starting point expressed in milliseconds.
nToPosition | Range ending point expressed in milliseconds.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.PlayRangeDisableLoop method

VideoPlayer.PlayRangeDisableLoop method

Remarks

Disables an eventual loop, set by a previous call to the VideoPlayer.PlayRangeWithLoop method, without stopping the current playback.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Pause (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.Pause (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.PlayRangeWithLoop method

VideoPlayer.PlayRangeWithLoop method

Remarks

Plays in loop mode a defined range of the video previously loaded inside the given player through one between VideoPlayer.Load or VideoPlayer.LoadForEAX methods.

A successful call to this method will fire the SoundPlaying event; each loop completion will cause the control to fire the RangeLoopDone event: the only exception is the completion of the latest loop that will cause the control to fire the SoundDone event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.PlayRangeWithLoop (

nPlayer as Integer,

nFromPosition as Long,

nToPosition as Long,

nLoopCount as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.PlayRangeWithLoop (

short nPlayer,

long nFromPosition,

long nToPosition,

long nLoopCount

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will play the sound range

nFromPosition

Range starting point expressed in milliseconds.

nToPosition

Range ending point expressed in milliseconds.

nLoopCount

Specifies the number of loops over the defined range. Set this value to -1 for setting an infinite loop.

Once started, you can disable looping without stopping the current playback through the VideoPlayer.PlayRangeDisableLoop method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.PositionGet method

VideoPlayer.PositionGet method

Remarks

Gets the loaded video position during a playback session.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.PositionGet (

nPlayer as Integer,

fPosition as Double,

bKeepCountOfRateChange as enumBoolean

) as Long

[C++]

long control.VideoPlayer.PositionGet (

short nPlayer,

double *fPosition,

short bKeepCountOfRateChange

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

fPosition

Reference that, on return from the method call, will contain the current position. Its effective value depends upon the actual value of the ScaleUnits property.

bKeepCountOfRateChange

Boolean flag that specifies if the returned position must keep count of eventual playback rate changes set through previous calls to the Effects.PlaybackTempoSet or Effects.PlaybackRateSet methods.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Don't keep count of playback rate changes
BOOL_TRUE | 1 | Keep count of playback rate changes

Return value

Value | Meaning
Value > 0 | The video playback position expressed in milliseconds
Negative value | An error occurred (see the LastError property for further error details)


VideoPlayer.Resume method

VideoPlayer.Resume method

Remarks

Resumes playback of the paused video.

A successful call to this method will fire the SoundPlaying event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Resume (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.Resume (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.Rewind method

VideoPlayer.Rewind method

Remarks

Moves backward the position of the playing video of the amount that has been set through a previous call to the SetForwardRewindGranularity method..

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Rewind (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.Rewind (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.ScreenshotSaveToFile method

VideoPlayer.ScreenshotSaveToFile method

Remarks

Saves into a graphic file a screenshot of the image currently displayed on the given video window.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.ScreenshotSaveToFile (

nPlayer as Integer,

nUniqueID as Long,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as long

) as enumErrorCodes

[C++]

short control.VideoPlayer.ScreenshotSaveToFile (

short nPlayer,

long nUniqueID,

LPCTSTR strPathname,

short nFormat,

long nFormatParameter

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nUniqueID

Unique identifier of the video rendering window used in a previous call to the VideoPlayer.VideoWindowAdd method.

strPathname

String containing the absolute pathname where the screenshot will be stored.

nFormat

Graphic format used to save the bitmap.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_BMP | 0 | BMP format
GRAPHIC_FORMAT_JPEG | 1 | JPEG format
GRAPHIC_FORMAT_PNG | 2 | PNG format
GRAPHIC_FORMAT_GIF | 3 | GIF format
GRAPHIC_FORMAT_TIFF | 4 | TIFF format

nFormatParameter

Eventual parameters required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


VideoPlayer.Seek method

VideoPlayer.Seek method

Remarks

Seeks to a given playback position. Note that not all of the video formats support seeking: you can know if a certain format is seekable through a call to the VideoPlayer.IsSeekable method.

A call to this method is ignored if the embedded fader, through a call to the Fader.Init method, has been set to work with a single playlist (FADE_SINGLE_PLAYLIST).

If the status of the given player is "stopped" or "paused", a call to this method will move the playback position but will not cause the playback to start while, if the status of the given player is "playing", a call to this method will move the playback position and will continue playback without interruptions.

If the seek operation brings the playback position beyond the end of the file, the SoundDone event is generated.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Seek (

nPlayer as Integer,

nPosition as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.Seek (

short nPlayer,

long nPosition

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will play the sound range
nPosition | New position expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.SeekToNextFrame method

VideoPlayer.SeekToNextFrame method

Remarks

Steps to the next video frame. This method can be called only when the video playback is in paused or stopped state; the current status can be obtained through the GetPlayerStatus method.

Not all video codec support frame stepping: certain video codecs like MPEG-1 and MPEG-2 will change the displayed frame only after a few calls to this method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.SeekToNextFrame (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.SeekToNextFrame (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.SeekToPreviousFrame method

VideoPlayer.SeekToPreviousFrame method

Remarks

Steps to the previous video frame. This method can be called only when the video playback is in paused or stopped state; the current status can be obtained through the GetPlayerStatus method.

Not all video codec support frame stepping: certain video codecs like MPEG-1 and MPEG-2 will change the displayed frame only after a few calls to this method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.SeekToPreviousFrame (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.SeekToPreviousFrame (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.Stop method

VideoPlayer.Stop method

Remarks

Stops the playing video.

A successful call to this method will fire the SoundStopped event.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.Stop (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VideoPlayer.Stop (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.VideoStreamKeepAspectRatio method

VideoPlayer.VideoStreamKeepAspectRatio method

Remarks

Tells to the given player if the related video output windows must keep the original aspect ratio of the loaded video clip.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoStreamKeepAspectRatio (

nPlayer as Integer,

bKeepAspectRatio as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.VideoStreamKeepAspectRatio (

short nPlayer,

short bKeepAspectRatio

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

bKeepAspectRatio

Boolean value that determines if the loaded video clip must keep its original aspect ratio.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Don't keep the original aspect ratio
BOOL_TRUE (default) | 1 | Keep the original aspect ratio

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.VideoStreamSendToActiveMovieWin method

VideoPlayer.VideoStreamSendToActiveMovieWin method

Remarks

In absence of an output rendering window, set through a previous call to the VideoPlayer.VideoWindowAdd method, decides if the video stream must be sent to the floating ActiveMovie window instead of the NullRenderer.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoStreamSendToActiveMovieWin (

nPlayer as Integer,

bSend as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.VideoStreamSendToActiveMovieWin (

short nPlayer,

short bSend

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

bSend

Boolean value that specifies if the video stream must be sent to the ActiveMovie window instead of the NullRenderer.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE (default) | 0 | Don't send the video stream to the ActiveMovie window.
BOOL_TRUE | 1 | Send the video stream to the ActiveMovie window.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.VideoTransformIsAvailable method

VideoPlayer.VideoTransformIsAvailable method

Remarks

Reports if the video transform filter, used for image adjusting, has been inserted correctly inside the DirectShow filter graph.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoTransformIsAvailable (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.VideoPlayer.VideoTransformIsAvailable (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
FALSE | The transform filter is not available
TRUE | The transform filter is available


VideoPlayer.VideoWindowAdd method

VideoPlayer.VideoWindowAdd method

Remarks

Creates a new rendering window for the video player and links it to a given player: once created, the rendering window will stay active until the termination of the container form.

When more rendering windows are added to the same player, they will be automatically in synch during video playback.

The rendering window can be hidden or shown through the VideoPlayer.VideoWindowShow method and moved or resized through the VideoPlayer.VideoWIndowMove method.

If the video player has been attached to a video mixer through a call to the VideoPlayer.AttachToVideoMixer method, only the first rendering window will be available for preview: the other rendering windows will stay inactive until the video player is detached from the video mixer through a call to the VideoPlayer.DetachFromVideoMixer method and a new video clip is loaded into the video player.

If the given player is under control of the embedded fader, as a consequence of a call to the Fader.Init method, only the first rendering window will be used.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoWindowAdd (

nPlayer as Integer,

nUniqueID as Long,

hWndTarget as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.VideoWindowAdd (

short nPlayer,

long nUniqueID,

OLE_HANDLE hWndTarget,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nUniqueID

Unique identifier of the rendering window: you can set your own values for each video window

hWndTarget

Handle of the window/control whose surface will be used in order to render video frames; this handle must belong to a valid and existing window/control or the method call will fail.

In case you should simply need to render the video stream into a floating ActiveMovie window, make a call to the VideoPlayer.VideoStreamSendToActiveMovieWin method before loading the video clip.

nLeft

Left position of the video window, expressed in client coordinates (pixels) of the target window represented by hWndTarget

nTop

Top position of the video window, expressed in client coordinates (pixels) of the target window represented by hWndTarget

nWidth

Width of the video window, expressed in pixels

nHeight

Height of the video window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.VideoWindowChangeTarget method

VideoPlayer.VideoWindowChangeTarget method

Remarks

Changes one of the output rendering windows of the video player previously added through the VideoPlayer.VideoWindowAdd method. After this change, the positioning of the output window can be modified through the VideoPlayer.VideoWindowMove method.

Changes one of the output rendering windows of the video player. After this change, the positioning of the output window can be modified through the method.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoWindowChangeTarget (

nPlayer as Integer,

nUniqueID as Long,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.VideoPlayer.VideoWindowChangeTarget (

short nPlayer,

long nUniqueID,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nUniqueID | Unique identifier of the rendering window previously used for the call to the VideoPlayer.VideoWindowAdd method.
hWndTarget | Handle of the window/control whose surface will be used in order to render video frames; this handle must belong to a valid and existing window/control or the method call will fail.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.VideoWindowGetHWND method

VideoPlayer.VideoWindowGetHWND method

Remarks

Obtains the window handle (HWND) of the given rendering window.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoWindowGetHWND (

nPlayer as Integer,

nUniqueID as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.VideoWindowGetHWND (

short nPlayer,

long nUniqueID

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nUniqueID | Unique identifier of the rendering window previously used with the VideoPlayer.VideoWindowAdd method

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Other values | The HWND of the video rendering window


VideoPlayer.VideoWindowMove method

VideoPlayer.VideoWindowMove method

Remarks

Moves/resizes the given video player rendering window.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoWindowMove (

nPlayer as Integer,

nUniqueID as Long,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.VideoPlayer.VideoWindowMove (

short nPlayer,

long nUniqueID,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the video player.
nUniqueID | Unique identifier of the rendering window previously used with the VideoPlayer.VideoWindowAdd method
nLeft | New left position of the video window, expressed in client coordinates (pixels) of the container form
nTop | New top position of the video window, expressed in client coordinates (pixels) of the container form
nWidth | New width of the video window, expressed in pixels
nHeight | New height of the video window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VideoPlayer.VideoWindowShow method

VideoPlayer.VideoWindowShow method

Remarks

Shows/hides the given video player rendering window.

For further details about the use of the embedded video player see the VideoPlayer object section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

control.VideoPlayer.VideoWindowShowShow (

nPlayer as Integer,

nUniqueID as Long,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.VideoPlayer.VideoWindowShowShow (

short nPlayer,

long nUniqueID,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the video player.

nUniqueID

Unique identifier of the rendering window previously used with the VideoPlayer.VideoWindowAdd method

bShow

Boolean value that determines if the rendering window must be shown or hidden.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hide window
BOOL_TRUE (default) | 1 | Show window

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VolumeAutomation object

VolumeAutomation object

The VolumeAutomation object, accessible through the control's VolumeAutomation property, is internally implemented as a COM interface called IVolumeAutomation and contains methods needed to manage volume automation on sounds being played.

The VolumeAutomation object is implemented through the following methods and properties:

Methods

IsSliding

Load

PointAdd

PointEnable

PointGetCount

PointGetName

PointGetNext

PointGetParams

PointIsEnabled

PointRemove

PointSetParams

Reset

Save

Properties

CurveDesigner

PositionUnit

ScaleType

Further information about the use of volume automation can be found inside the How to manage Volume Automation tutorial.

Samples of usage of volume automation in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- VolumeAutomation


VolumeAutomation.CurveDesigner property (RO)

VolumeAutomation.CurveDesigner property (RO)

 Return to chapter overview
Type | CCurveDesigner for Visual C++ AMP3DJLib.VolumeAutomation.CurveDesigner for Visual Basic This property is Read-only
Syntax | object.VolumeAutomation.CurveDesigner [=AMP3DJLib.VolumeAutomation.CurveDesigner]
Remarks | The Curve Designer for the embedded Volume Automation object. This property encapsulates the functionality of the VolumeAutomation.CurveDesigner object and the ICurveDesigner COM interface. For details about using the Curve Designer refer to the How to create custom volume curves tutorial. For details about using Volume Automation refer to the How to manage Volume Automation tutorial.


VolumeAutomation.PositionUnit property

VolumeAutomation.PositionUnit property

Type

enumVolumeAutomationPosUnits for Visual Basic

short for Visual C++

Remarks

The unit used to define positions of volume points in Volume Automation procedures.

Supported values are the following:

Mnemonic constant | Value | Meaning
VA_POS_UNIT_SECONDS | 0 | Positions are expressed in seconds
VA_POS_UNIT_PERCENTAGE | 1 | Positions are expressed in percentage
VA_POS_UNIT_MILLISECONDS | 2 | Positions are expressed in milliseconds

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.


VolumeAutomation.ScaleType property

VolumeAutomation.ScaleType property

Type

enumVolumeScales for Visual Basic

short for Visual C++

Remarks

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

Volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

Volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.


VolumeAutomation.IsSliding method

VolumeAutomation.IsSliding method

Remarks

Checks if the given player is sliding its volume during a volume automation procedure.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.IsSliding (

nPlayer as Integer

) as Boolean

[C++]

BOOL control.VolumeAutomation.IsSliding (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
FALSE | Volume is not sliding during a volume automation procedure
TRUE | Volume is sliding during a volume automation procedure


VolumeAutomation.Load method

VolumeAutomation.Load method

Remarks

Loads a volume automation procedure from a XML-based VDJ file.

A successful call to this method will fire the VolumeAutomationLoaded event.

For details about using Volume Automation and for a reference about VDJ format refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.Load (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.VolumeAutomation.Load (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strFilename | String containing the absolute pathname of the VDJ file to load. An empty string will force the control to search for a VDJ file having the same filename of the loaded sound but with extension .vdj: if for example the loaded sound file should be named MySong.mp3, the corresponding searched VDJ file would be named MySong.vdj

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.PointAdd method

VolumeAutomation.PointAdd method

Remarks

Adds a new volume point to the volume automation procedure.

Modifications won't be immediately applied if loaded sound should be already playing and will take effect only after completing/stopping and restarting the playback session.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointAdd (

nPlayer as Integer,

strVolumePointName as String,

fPosition as Single,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.VolumeAutomation.PointAdd (

short nPlayer,

LPCTSTR strVolumePointName,

float fPosition,

float fVolumeLevel,

short nCurveType,

long nDesignerUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strVolumePointName

String representing the friendly name of the volume point to add: there is no naming convention so you are free to decide your own set of names. This name will be used in next calls that will act on this specific volume point.

fPosition

Position of the volume point expressed in the same unit set into the VolumeAutomation.PositionUnit property.

fVolumeLevel

Volume level expressed in the same unit set into the VolumeAutomation.ScaleType property

nCurveType

Type of curve applied to reach the next volume point.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_NONE | 0 | No curve is applied: volume will be changed immediately and will be kept till next volume point.
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.PointEnable method

VolumeAutomation.PointEnable method

Remarks

Enables/disables the given volume point. You can know if a volume point is enabled or disabled through the VolumeAutomation.PointIsEnabled method.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointEnable (

nPlayer as Integer,

strVolumePointName as String,

bEnable as enumBoolean

) as enumErrorCodes

[C++]

short control.VolumeAutomation.PointEnable (

short nPlayer,

LPCTSTR strVolumePointName,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strVolumePointName

String representing the friendly name of the volume point to enable/disable: this name must be identical to the corresponding one used for adding the volume point through the VolumeAutomation.PointAdd method..

bEnable

Boolean value that specifies if the volume point must be enabled or disabled.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Disables the volume point
BOOL_TRUE | 1 | Enables the volume point

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.PointGetCount method

VolumeAutomation.PointGetCount method

Remarks

Gets the number of volume points inside the current volume automation procedure.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointGetCount (

nPlayer as Integer

) as Long

[C++]

long control.VolumeAutomation.PointGetCount (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
>= 0 | The number of available volume points


VolumeAutomation.PointGetName method

VolumeAutomation.PointGetName method

Remarks

Gets the friendly name of a volume point.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointGetName (

nPlayer as Integer,

nIndex as Integer,

) as String

[C++]

LPCTSTR control.VolumeAutomation.PointGetName (

short nPlayer,

short nIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndex | Number representing the zero-based index of the volume point

Return value

Value | Meaning
Valid string | String representing the friendly name of the volume point: this name is the same used for adding the volume point through the VolumeAutomation.PointAdd method.
Empty string | An error occurred, check the LastError property value in order to see the error code meaning file


VolumeAutomation.PointGetNext method

VolumeAutomation.PointGetNext method

Remarks

Obtains the zero-based index of the next volume point.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointGetNext (

nPlayer as Integer,

nIndexVolumePoint as Long

) as enumErrorCodes

[C++]

short control.VolumeAutomation.PointGetNext (

short nPlayer,

long *nIndexVolumePoint

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIndexVolumePoint | Reference that, on return from the method call, will contain the zero-based index of the next volume point inside the volume automation procedure.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.PointGetParams method

VolumeAutomation.PointGetParams method

Remarks

Obtains parameters for the given volume point.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointGetParams (

nPlayer as Integer,

strVolumePointName as String,

fPosition as Single,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves

) as enumErrorCodes

[C++]

short control.VolumeAutomation.PointGetParams (

short nPlayer,

LPCTSTR strVolumePointName,

float *fPosition,

float *fVolumeLevel,

short *nCurveType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strVolumePointName

String representing the friendly name of the volume point to remove: this name must be identical to the corresponding one used for adding the volume point through the VolumeAutomation.PointAdd method.

fPosition

Reference that, on return from the method call, will contain the position of the volume point expressed in the same unit set into the VolumeAutomation.PositionUnit property

fVolumeLevel

Reference that, on return from the method call, will contain the volume level expressed in the same unit set into the VolumeAutomation.ScaleType property

nCurveType

Reference that, on return from the method call, will contain the type of curve applied to reach the next volume point.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_NONE | 0 | No curve is applied: volume will be changed immediately and will be kept till next volume point.
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.PointIsEnabled method

VolumeAutomation.PointIsEnabled method

Remarks

Checks if a volume point is enabled or disabled. A volume point can be enabled or disabled through the VolumeAutomation.PointEnable method.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointIsEnabled (

nPlayer as Integer,

strVolumePointName as String

) as Boolean

[C++]

BOOL control.VolumeAutomation.PointIsEnabled (

short nPlayer,

LPCTSTR strVolumePointName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strVolumePointName | String representing the friendly name of the volume point of interest: this name must be identical to the corresponding one used for adding the volume point through the VolumeAutomation.PointAdd method..

Return value

Value | Meaning
FALSE | Volume point is disabled
TRUE | Volume point is enabled


VolumeAutomation.PointRemove method

VolumeAutomation.PointRemove method

Remarks

Removes an existing volume point.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointRemove (

nPlayer as Integer,

strVolumePointName as String

) as enumErrorCodes

[C++]

short control.VolumeAutomation.PointRemove (

short nPlayer,

LPCTSTR strVolumePointName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strVolumePointName | String representing the friendly name of the volume point to remove: this name must be identical to the corresponding one used for adding the volume point through the VolumeAutomation.PointAdd method.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.PointSetParams method

VolumeAutomation.PointSetParams method

Remarks

Modifies parameters for the given existing volume point.

Modifications won't be immediately applied if loaded sound should be already playing and will take effect only after completing/stopping and restarting the playback session.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.PointSetParams (

nPlayer as Integer,

strVolumePointName as String,

fPosition as Single,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.VolumeAutomation.PointSetParams (

short nPlayer,

LPCTSTR strVolumePointName,

float fPosition,

float fVolumeLevel,

short nCurveType,

long nDesignerUniqueId

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strVolumePointName

String representing the friendly name of the volume point to remove: this name must be identical to the corresponding one used for adding the volume point through the VolumeAutomation.PointAdd method.

fPosition

Position of the volume point expressed in the same unit set into the VolumeAutomation.PositionUnit property.

fVolumeLevel

Volume level expressed in the same unit set into the VolumeAutomation.ScaleType property

nCurveType

Type of curve applied to reach the next volume point.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_NONE | 0 | No curve is applied: volume will be changed immediately and will be kept till next volume point.
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

nDesignerUniqueId

Unique identifier of the curve editor control containing custom curve settings to apply. This unique identifier is returned by a previous call to the VolumeAutomation.CurveDesigner.Create method.

The custom curve designer manages a windowed control, whose visual aspect can be defined programmatically, which allows designing volume curves based upon Bézier curves whose shape is defined through the manual positioning of 2 control points (displayed in cyan color on the graphic below). For further information about the use of the embedded CurveDesigner refer to the tutorial How to create custom volume curves.

This parameter is ignored if the nScaleType parameter above has been set to a value different from VOLUME_CURVE_CUSTOM.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.Reset method

VolumeAutomation.Reset method

Remarks

Resets the current volume automation procedure for the given player.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.Reset (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.VolumeAutomation.Reset (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.Save method

VolumeAutomation.Save method

Remarks

Saves the current volume automation procedure into a XML-based VDJ file.

For details about using Volume Automation and for a reference about VDJ format refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.Save (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.VolumeAutomation.Save (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
strFilename | String containing the absolute pathname of the destination XML file

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The method call was successful
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.CurveDesigner object

VolumeAutomation.CurveDesigner object

The CurveDesigner object, accessible through the control's VolumeAutomation.CurveDesigner property, is internally implemented as a COM interface called ICurveDesigner and contains methods needed to manage the embedded Curve Designer used for designing custom shaped curves in volume automation.

The CurveDesigner object is implemented through the following methods:

Methods

Create

Destroy

DisplayCurveType

GetGraphicalSettings

GetPoints

Move

Refresh

SetBackPictureFromFile

SetBackPictureFromHandle

SetGraphicalSettings

SetPoints

Show

Data structures

CURVE_DESIGNER_SETTINGS

Further information about the use of the curve designer can be found inside the How to create custom volume curves tutorial.

Further information about the use of Volume Automation can be found inside the How to manage Volume Automation tutorial.

Samples of usage of volume automation in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- VolumeAutomation


VolumeAutomation.CurveDesigner.Create method

VolumeAutomation.CurveDesigner.Create method

Remarks

Creates a new instance of the VolumeAutomation.CurveDesigner object on the given parent window.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.Create (

hWndParent as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as Long

[C++]

long control.VolumeAutomation.CurveDesigner.Create (

OLE_HANDLE hWndParent,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of the parent window
nTop | Top position of the window, expressed in client coordinates (pixels) of the parent window
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Other values | Unique identifier of the new curve designer


VolumeAutomation.CurveDesigner.Destroy method

VolumeAutomation.CurveDesigner.Destroy method

Remarks

Destroys the given curve designer.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.Destroy (

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.Destroy (

long nDesignerUniqueId

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VolumeAutomation.CurveDesigner.DisplayCurveType method

VolumeAutomation.CurveDesigner.DisplayCurveType method

Remarks

Displays a specific type of predefined curve on the designer window.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.DisplayCurveType (

nDesignerUniqueId as Long,

nCurveType as enumVolumeCurves

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.DisplayCurveType (

long nDesignerUniqueId,

short nCurveType

);

Parameter

Description

nDesignerUniqueId

Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method

nCurveType

Type of curve to display.

Supported values are the following:

Mnemonic constant | Value | Meaning
VOLUME_CURVE_NONE | 0 | No curve is applied.
VOLUME_CURVE_LINEAR | 1 | Linear curve
VOLUME_CURVE_EXPONENTIAL | 2 | Exponential curve
VOLUME_CURVE_COSINE | 3 | Cosine curve
VOLUME_CURVE_SMOOTH | 4 | Smooth curve
VOLUME_CURVE_CUSTOM | 5 | Custom Bézier curve.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VolumeAutomation.CurveDesigner.GetGraphicalSettings method

VolumeAutomation.CurveDesigner.GetGraphicalSettings method

Remarks

Retrieves the current graphical settings for the given curve designer. Settings can be modified through the VolumeAutomation.CurveDesigner.SetGraphicalSettings method.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.GetGraphicalSettings (

nDesignerUniqueId as Long,

pParamData as Long

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.GetGraphicalSettings (

long nDesignerUniqueId,

void *pParamData

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
pParamData | Address of a structure of type CURVE_DESIGNER_SETTINGS that receives in output graphical settings of the curve designer.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.CurveDesigner.GetPoints method

VolumeAutomation.CurveDesigner.GetPoints method

Remarks

Retrieves positions of Bézier curve control points (right and left) inside the curve designer. Control points can be modified programmatically through the VolumeAutomation.CurveDesigner.SetPoints method or through the mouse by dragging provided "handles".

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.GetPoints (

nDesignerUniqueId as Long,

nLeftX as Integer,

nLeftY as Integer,

nRightX as Integer,

nRightY as Integer

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.GetPoints (

long nDesignerUniqueId,

short *nLeftX,

short *nLeftY,

short *nRightX,

short *nRightY

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
nLeftX | Reference that, on return from the method call, will contain the horizontal position, expressed in percentage of the designer's area, of the left control point
nLeftY | Reference that, on return from the method call, will contain the vertical position, expressed in percentage of the designer's area, of the left control point
nRightX | Reference that, on return from the method call, will contain the horizontal position, expressed in percentage of the designer's area, of the right control point
nRightY | Reference that, on return from the method call, will contain the vertical position, expressed in percentage of the designer's area, of the right control point

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.CurveDesigner.Move method

VolumeAutomation.CurveDesigner.Move method

Remarks

Moves/resizes the given curve designer.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.Move (

nDesignerUniqueId as Long,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.Move (

long nDesignerUniqueId,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
nLeft | Left position of the window, expressed in client coordinates (pixels) of the parent window
nTop | Top position of the window, expressed in client coordinates (pixels) of the parent window
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VolumeAutomation.CurveDesigner.Refresh method

VolumeAutomation.CurveDesigner.Refresh method

Remarks

Refreshes the given curve designer.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.Refresh (

nDesignerUniqueId as Long

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.Refresh (

long nDesignerUniqueId

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VolumeAutomation.CurveDesigner.SetBackPictureFromFile method

VolumeAutomation.CurveDesigner.SetBackPictureFromFile method

Remarks

Sets a background picture from a picture file in BMP format.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.SetBackPictureFromFile (

nDesignerUniqueId as Long,

strPathname as String

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.SetBackPictureFromFile (

long nDesignerUniqueId,

LPCTSTR strPathname

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
strPathname | Absolute pathname of the BMP file to load. An empty pathname will reset an eventual picture set through a previous call to this method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VolumeAutomation.CurveDesigner.SetBackPictureFromHandle method

VolumeAutomation.CurveDesigner.SetBackPictureFromHandle method

 Return to chapter overview

Remarks

Sets a background picture from an existing bitmap handle (HBITMAP).

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.SetBackPictureFromHandle (

nDesignerUniqueId as Long,

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.SetBackPictureFromHandle (

long nDesignerUniqueId,

OLE_HANDLE hBitmap

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
hBitmap | Handle of the bitmap to apply. If this parameter is set to 0 an eventual picture set through a previous call to this method will be reset.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VolumeAutomation.CurveDesigner.SetGraphicalSettings method

VolumeAutomation.CurveDesigner.SetGraphicalSettings method

Remarks

Modifies graphical settings for the given curve designer. Current settings can be obtained through the VolumeAutomation.CurveDesigner.GetGraphicalSettings method.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.SetGraphicalSettings (

nDesignerUniqueId as Long,

pParamData as Long

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.SetGraphicalSettings (

long nDesignerUniqueId,

long pParamData

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
pParamData | Address of a structure of type CURVE_DESIGNER_SETTINGS containing graphical settings of the curve designer.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.CurveDesigner.SetPoints method

VolumeAutomation.CurveDesigner.SetPoints method

Remarks

Modifies positions of Bézier curve control points (right and left) inside the curve designer. Control points positions can be obtained VolumeAutomation.CurveDesigner.GetPoints method.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.SetPoints (

nDesignerUniqueId as Long,

nLeftX as Integer,

nLeftY as Integer,

nRightX as Integer,

nRightY as Integer

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.SetPoints (

long nDesignerUniqueId,

short nLeftX,

short nLeftY,

short nRightX,

short nRightY

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
nLeftX | The horizontal position, expressed in percentage of the designer's area, of the left control point
nLeftY | The vertical position, expressed in percentage of the designer's area, of the left control point
nRightX | The horizontal position, expressed in percentage of the designer's area, of the right control point
nRightY | The vertical position, expressed in percentage of the designer's area, of the right control point

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


VolumeAutomation.CurveDesigner.Show method

VolumeAutomation.CurveDesigner.Show method

Remarks

Shows/hides the given curve designer.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Syntax

[Visual Basic]

control.VolumeAutomation.CurveDesigner.Show (

nDesignerUniqueId as Long,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.VolumeAutomation.CurveDesigner.Show (

long nDesignerUniqueId,

short bShow

);

Parameter

Description

nDesignerUniqueId

Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method

bShow

Boolean value that specifies if it must show/hide the given curve designer.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Hides the curve designer window
BOOL_TRUE | Shows the curve designer window

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


CURVE_DESIGNER_SETTINGS structure

CURVE_DESIGNER_SETTINGS structure

The CURVE_DESIGNER_SETTINGS class describes the graphical settings applied to a specific curve designer. The current settings can be obtained through the VolumeAutomation.CurveDesigner.GetGraphicalSettings method and modified through the VolumeAutomation.CurveDesigner.SetGraphicalSettings method.

For details about using the Curve Designer refer to the How to create custom volume curves tutorial.

For details about using Volume Automation refer to the How to manage Volume Automation tutorial.

Visual C++ definition

typedef struct

{

 short     bAppearance3d;

 short     bFadeIn;

 OLE_COLOR colorCurveLine;

 OLE_COLOR colorBackground;

 OLE_COLOR colorHandles;

 OLE_COLOR colorHandlesBorder;

 OLE_COLOR colorHandleLines;

 OLE_COLOR colorBorder;

 short     nCurveLineWidth;

 short     bHandleLinesVisible;

} CURVE_DESIGNER_SETTINGS;

Visual Basic definition

Public Type CURVE_DESIGNER_SETTINGS

bAppearance3d as Boolean

bFadeIn as Boolean

colorCurveLine as OLE_COLOR

colorBackground as OLE_COLOR

colorHandles as OLE_COLOR

colorHandlesBorder as OLE_COLOR

colorHandleLines as OLE_COLOR

colorBorder as OLE_COLOR

nCurveLineWidth as Integer

bHandleLinesVisible as Boolean

End Type

Member

Description

bAppearance3d

Boolean value that specifies if the curve designer is displayed with 3D borders.

Supported values are the following:

Value | Meaning
false (default) | Doesn't display 3D borders
true | Displays 3D borders

bFadeIn

Boolean value that specifies if the structure represents a fade-in or a fade-out

Supported values are the following:

Value | Meaning
false (default) | Displays a fade-out curve
true | Displays a fade-in curve

colorCurveLine

The color used for rendering the fade line

colorBackground

The color used as a background

colorHandles

The color used for rendering tracking handles

colorHandlesBorder

The color used for rendering the border of the tracking handles

colorHandleLines

The color for rendering the lines going from the tracking handles to the fade point

colorBorder

The color for rendering the border

nCurveLineWidth

Width of the fade line expressed in pixels

bHandleLinesVisible

Boolean value that specifies if dashed lines going from the tracking handles to the fade point are visible.

Supported values are the following:

Value | Meaning
false (default) | Lines are hidden
true | Lines are visible

Below you can see a zoomed curve designer with various configurable elements:


VST object

VST object

The VST object, accessible through the control's VST property, is internally implemented as a COM interface called IVST and contains methods needed to apply Steinberg''s Virtual Studio Technology (VST) effects and instruments.

The VST object is implemented through the following methods:

EditorGetInfo

EditorMove

EditorShow

EffectEnable

EffectFlush

EffectFree

EffectLoad

GetInfo

GetInfoString

GetType

InstrumentEventApply

InstrumentEventRawApply

InstrumentFree

InstrumentLoad

ProgramsGetCount

ProgramGetCurrent

ProgramSetCurrent

ProgramNameGet

ProgramNameSet

ProgramParamGetDefaultValue

ProgramParamGetInfo

ProgramParamGetValue

ProgramParamSetValue

ProgramParamsGetCount

For further details about managing VST effects and instruments refer to the How to manage VST effects tutorial.

A sample of use of the VST object in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- VstEffects


VST.EditorGetInfo method

VST.EditorGetInfo method

Remarks

If available, obtains information about the editor (user interface) of the given VST. You are free to define your own set of information about a certain editor.

The editor can be shown, hidden or moved using the VST.EditorShow method.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.EditorGetInfo (

nPlayer as Integer,

nIdVST as Long,

pParamData as Long

) as enumErrorCodes

[C++]

short control.VST.EditorGetInfo (

short nPlayer,

long nIdVST,

long pParamData

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdVST

Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.

pParamData

Pointer in memory to a data structure of type VST_EDITOR_INFO containing information about the VST editor.

The VST_EDITOR_INFO data structure is defined in C++ as follows:

typedef struct

{

 short   bIsEditorAvailable;

 short   bIsEditorVisible;

 short   nEditorLeft;

 short   nEditorTop;

 short   nEditorWidth;

 short   nEditorHeight;

} VST_EDITOR_INFO;

Member name | Description
bIsEditorAvailable | Boolean flag that specifies if the VST editor is available
bIsEditorVisible | Boolean flag that specifies if the VST editor is currently visible or hidden
nEditorLeft | Editor left position, within the container client area, expressed in pixels
nEditorTop | Editor top position, within the container client area, expressed in pixels
nEditorWidth | Editor width expressed in pixels
nEditorHeight | Editor height expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.EditorMove method

VST.EditorMove method

Remarks

If available, moves the editor (user interface) of the given VST.

Information about the VST editor can be obtained through the VST.EditorGetInfo method.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.EditorMove (

nPlayer as Integer,

nIdVST as Long,

leftPos as Long,

topPos as Long

) as enumErrorCodes

[C++]

short control.VST.EditorMove (

short nPlayer,

long nIdDsp,

long leftPos,

long topPos

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.
leftPos | Left position, respect to the container window client area, expressed in pixels
topPos | Top position, respect to the container window client area, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.EditorShow method

VST.EditorShow method

Remarks

If available, shows/hides or moves the editor (user interface) of the given VST.

Information about the VST editor can be obtained through the VST.EditorGetInfo method.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.EditorShow (

nPlayer as Integer,

nIdVST as Long,

bShow as enumBoolean,

hWndParent as OLE_HANDLE,

leftPos as Long,

topPos as Long

) as enumErrorCodes

[C++]

short control.VST.EditorShow (

short nPlayer,

long nIdDsp,

short bShow,

OLE_HANDLE hWndParent,

long leftPos,

long topPos

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdVST

Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.

bShow

Show/hide flag.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Hides the editor window
BOOL_TRUE | Shows the editor window

hWndParent

Handle of the window (HWND) that will be parent of the editor's window.

leftPos

Left position, respect to the container window client area, expressed in pixels

topPos

Top position, respect to the container window client area, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.EffectEnable method

VST.EffectEnable method

Remarks

Enables/disables the given VST effect.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.EffectEnable (

nPlayer as Integer,

nIdVST as Long,

bEnable as enumBoolean,

nPriority as Long

) as enumErrorCodes

[C++]

short control.VST.EffectEnable (

short nPlayer,

long nIdVST,

short bEnable,

long nPriority

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdVST

Unique identifier of the VST effect as returned by the VST.EffectLoad method.

bEnable

Boolean flag that specifies if the VST effect must be enabled or disabled.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Disables the VST effect
BOOL_TRUE | Enables the VST effect

nPriority

VST effect priority level inside the chain of DirectX effects, custom DSP effects and VST effects. Effects with higher priority are applied before effects with lower priority; in case more effects should have the same priority, they would be invoked in the same order that they were added..

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.EffectFlush method

VST.EffectFlush method

Remarks

Resets contents of VST's buffers.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.EffectFlush (

nPlayer as Integer,

nIdVST as Long

) as enumErrorCodes

[C++]

short control.VST.EffectFlush (

short nPlayer,

long nIdVST

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.EffectFree method

VST.EffectFree method

Remarks

Discards from memory a previously loaded VST effect.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.EffectFree (

nIdVST as Long

) as enumErrorCodes

[C++]

short control.VST.EffectFree (

long nIdVST

);

Parameter | Description
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad method. Passing -1 will cause discarding from memory all of the loaded VST effects.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.EffectLoad method

VST.EffectLoad method

Remarks

Loads a VST effect from an external dynamic-link library (DLL) file. For VST instruments use the VST.InstrumentLoad method.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.EffectLoad (

nPlayer as Integer,

strPathname as String,

bEnable as enumBoolean

) as Long

[C++]

long control.VST.EffectLoad (

short nPlayer,

LPCTSTR strPathname,

short bEnable

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

strPathname

String representing the filename or absolute pathname of the DLL file containing the VST effect.

If the string specifies a path but the file does not exist in the specified directory, the function fails. When specifying a path, be sure to use backslashes (\), not forward slashes (/).

If the string does not specify a path, the function uses the standard search strategy of the LoadLibrary Windows API to find the file.

bEnable

Boolean flag that specifies if the VST effect must be immediately enabled after loading.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Doesn't enable the VST effect after loading
BOOL_TRUE | Enables the VST effect after loading

Return value

Value

Meaning

0

An error occurred: see the LastError property for further error details or for a list of the possible error values.

In case the value of the LastError property should be ERR_VST_NOT_COMPATIBLE, meaning that there was an attempt to load a VST Instrument, the player would assume an undetermined status so there would be the need to reload the sound again inside the player through a call the CloseSound method followed by a new LoadSound call.

Other values

Numeric value representing the unique identifier of the VST effect: this unique identifier will be used in order to invoke further methods related to the use of the loaded VST effect.


VST.GetInfo method

VST.GetInfo method

Remarks

Obtains information about the VST.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.GetInfo (

nPlayer as Integer,

nIdVST as Long,

pParamData as Long

) as enumErrorCodes

[C++]

short control.VST.GetInfo (

short nPlayer,

long nIdVST,

long *pParamData

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdVST

Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.

pParamData

Address of a data structure of type VST_EFFECT_INFO that receives the information about the VST effect.

The VST_EFFECT_INFO data structure is defined in C++ as follows:

typedef struct

{

 long    nRegisteredUniqueID;

 long    nVersion;

 long    nVstVersion;

 long    nVstMaxSupportedVersion;

 long    nInputChannels;

 long    nOutputChannels;

 long    nInitialDelay;

 long    ptrUnderlyingAEffect;

} VST_EFFECT_INFO;

Member name | Description
nRegisteredUniqueID | Unique identifier of the VST effect: this unique identifier is assigned and registered at Steinberg
nVersion | Effect version
nVstVersion | The VST version the effect was written for
nVstMaxSupportedVersion | The max VST version (currently 2.4) supported by the control
nInputChannels | Max number of supported input channels
nOutputChannels | Max number of supported output channels
nInitialDelay | Plugin latency expressed in samples
ptrUnderlyingAEffect | The underlying AEffect object (see aeffectx.h in the VST SDK for further details)

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.GetInfoString method

VST.GetInfoString method

Remarks

Obtains a descriptive information string from the VST.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.GetInfoString (

nPlayer as Integer,

nIdVST as Long,

nInfo as enumVstInfo

) as String

[C++]

LPCTSTR control.VST.GetInfoString (

short nPlayer,

long nIdVST,

short nInfo

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdVST

Unique identifier of the VST effect as returned by the VST.Load method.

nInfo

Index of the requested string.

Supported values are the following:

Mnemonic constant | Value | Meaning
VST_INFO_EFFECT_NAME | 0 | Friendly name of the VST
VST_INFO_VENDOR_NAME | 1 | Name of the VST developer/vendor
VST_INFO_PRODUCT_NAME | 2 | Name of the product

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the requested information


VST.GetType method

VST.GetType method

Remarks

Obtains the type of VST plugin.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.GetType (

nIdVST as Long,

nType as enumVstType

) as enumErrorCodes

[C++]

short control.VST.GetType (

long nIdVST,

short *nType

);

Parameter

Description

nIdVST

Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.

nType

Reference that, on return from the method call, will contain the type of VST plugin.

Supported values are the following:

Mnemonic constant | Value | Meaning
VST_TYPE_INSTRUMENT | 0 | VST Instrument
VST_TYPE_EFFECT | 1 | VST effect

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.InstrumentEventApply method

VST.InstrumentEventApply method

Remarks

Applies a specific single MIDI event to the VST instrument. Applying multiple events at the same time, as seen for the MIDI object, is not supported.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.VST.InstrumentEventApply (

nPlayer as Integer,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Integer,

nMidiParam2 as Integer,

nMidiChannel as Integer

) as enumErrorCodes

[C++]

short control.VST.InstrumentEventApply (

short nPlayer,

short nMidiEvent,

short nMidiParam1,

short nMidiParam2,

short nMidiChannel

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that hosts the VST instrument

nMidiEvent

MIDI event to apply.

Supported values, with related parameters, are the following:

Mnemonic constant | Value | Meaning
MIDI_EVENT_NOTE | 1 | Presses or releases a key note. nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: velocity; 0 means key released while values from 1 to 127 mean pressure
MIDI_EVENT_PROGRAM | 2 | Modifies a preset or instrument. nMidiParam1: the preset program number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHANPRES | 3 | Modifies the channel pressure. nMidiParam1: the pressure level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PITCH | 4 | Modifies the pitch wheel position. nMidiParam1: the pitch wheel position; can range from 0 to 16383 nMidiParam2: not used
MIDI_EVENT_PITCHRANGE | 5 | Modifies the pitch wheel range (MIDI RPN 0). nMidiParam1: the pitch wheel range nMidiParam2: not used
MIDI_EVENT_DRUMS | 6 | Switches between melody channels and the rhythm (drums) channel. nMidiParam1: if set to 0 melody channels are used, if set to 1 the rhythm channel is used. nMidiParam2: not used
MIDI_EVENT_FINETUNE | 7 | Sets the fine tuning (MIDI RPN 1). nMidiParam1: fine tuning in cents, can range from 0 to 16383. 0 means a fine tuning of -100, 8192 means normal while 16383 means a fine tuning of +100. nMidiParam2: not used
MIDI_EVENT_COARSETUNE | 8 | Sets the coarse tuning (MIDI RPN 2). nMidiParam1: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63. nMidiParam2: not used
MIDI_EVENT_MASTERVOL | 9 | Sets the master volume. nMidiParam1: can range from 0 to 16383 where 0 means silence and 16383 means max volume. nMidiParam2: not used
MIDI_EVENT_BANK | 10 | Selects the bank to use (MIDI controller 0). nMidiParam1: the bank number from 0 to 127 nMidiParam2: not used
MIDI_EVENT_MODULATION | 11 | Sets the modulation (MIDI controller 1). nMidiParam1: the modulation level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_VOLUME | 12 | Sets the volume (MIDI controller 7). nMidiParam1: the volume level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PAN | 13 | Sets the pan position (MIDI controller 10). nMidiParam1: the pan position from 0 to 128. 0 means left, 64 means middle, 127 means right while 128 sets a random position. nMidiParam2: not used
MIDI_EVENT_EXPRESSION | 14 | Sets the expression level (MIDI controller 11). nMidiParam1: the expression level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_SUSTAIN | 15 | Sets the sustain pedal or switch (MIDI controller 64). nMidiParam1: from 0 to 63 the sustain is off while from 64 to 127 the sustain is on. nMidiParam2: not used
MIDI_EVENT_SOUNDOFF | 16 | Stops all sounds (MIDI controller 120). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_RESET | 17 | Reset controllers to their default values (MIDI controller 121). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_NOTESOFF | 18 | Releases all key notes (MIDI controller 123). nMidiParam1: not used nMidiParam2: not used
MIDI_EVENT_PORTAMENTO | 19 | Sets the portamento switch (MIDI controller 65). nMidiParam1: from 0 to 63 the portamento is off while from 64 to 127 the portamento is on. nMidiParam2: not used
MIDI_EVENT_PORTATIME | 20 | Sets the portamento time (MIDI controller 5). nMidiParam1: the portamento time from 0 to 127 nMidiParam2: not used
MIDI_EVENT_PORTANOTE | 21 | Sets the portamento start key (MIDI controller 84). nMidiParam1: the key number from 1 to 127; 60 means middle C nMidiParam2: not used
MIDI_EVENT_MODE | 22 | Switches between poly and mono modes (MIDI controllers 126 and 127) nMidiParam1: 0 means poly while 1 means mono nMidiParam2: not used
MIDI_EVENT_REVERB | 23 | Sets the reverb level (MIDI controller 91). nMidiParam1: the reverb level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CHORUS | 24 | Sets the chorus level (MIDI controller 93). nMidiParam1: the chorus level from 0 to 127 nMidiParam2: not used
MIDI_EVENT_CUTOFF | 25 | Sets the cutoff of the low-pass filter (MIDI controller 74, NRPN 120h). nMidiParam1: cutoff level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RESONANCE | 26 | Sets the resonance of the low-pass filter (MIDI controller 71, NRPN 121h). nMidiParam1: resonance level, can range from 0 to 127. 0 means a level of -64, 64 means normal while 127 means a level of +63. nMidiParam2: not used
MIDI_EVENT_RELEASE | 27 | Sets the release time (MIDI controller 72, NRPN 166h). nMidiParam1: release time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_ATTACK | 28 | Sets the attack time (MIDI controller 73, NRPN 163h). nMidiParam1: attack time, can range from 0 to 127. 0 means a time of -64, 64 means normal while 127 means a time of +63. nMidiParam2: not used
MIDI_EVENT_REVERB_TIME | 32 | Sets the reverb time. nMidiParam1: reverb time in milliseconds. nMidiParam2: not used
MIDI_EVENT_REVERB_DELAY | 33 | Sets the reverb delay. nMidiParam1: reverb delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_REVERB_LOCUTOFF | 34 | Sets the cutoff of the reverb low-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_HIGCUTOFF | 35 | Sets the cutoff of the reverb high-pass filter. nMidiParam1: cutoff in Hertz; 0 means no cutoff. nMidiParam2: not used
MIDI_EVENT_REVERB_LEVEL | 36 | Sets the reverb level. nMidiParam1: reverb level; 0 means no reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_DELAY | 37 | Sets the chorus delay. nMidiParam1: chorus delay in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_DEPTH | 38 | Sets the chorus depth. nMidiParam1: chorus depth in 10ths of millisecond. nMidiParam2: not used
MIDI_EVENT_CHORUS_RATE | 39 | Sets the chorus rate. nMidiParam1: chorus in 100ths of Hertz. nMidiParam2: not used
MIDI_EVENT_CHORUS_FEEDBACK | 40 | Sets the level of the chorus feedback.. nMidiParam1: the chorus feedback level, can range from 0 to 200. 0 means -100%, 100 means that feedback is off while 200 means +100%. nMidiParam2: not used
MIDI_EVENT_CHORUS_LEVEL | 41 | Sets the chorus level. nMidiParam1: chorus level; 0 means no chorus, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_CHORUS_REVERB | 42 | Sets the chorus reverb level. nMidiParam1: chorus reverb level; 0 means no chorus reverb, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_DRUM_FINETUNE | 50 | Sets the fine tuning of a drum key (MIDI NRPN 19knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: fine tune in cents, can range from 0 to 127. 0 means -100, 64 means normal while 127 means +100.
MIDI_EVENT_DRUM_COARSETUNE | 51 | Sets the coarse tuning of a drum key (MIDI NRPN 18knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: coarse tuning in semitones, can range from 0 to 127. 0 means a tuning of -64, 64 means normal while 127 means a fine tuning of +63.
MIDI_EVENT_DRUM_PAN | 52 | Sets the pan position of a drum key (MIDI NRPN 1Cknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the pan position from 0 to 127. 0 means left, 64 means middle while 127 means right. .
MIDI_EVENT_DRUM_REVERB | 53 | Sets the reverb level of a drum key (MIDI NRPN 1Dknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the reverb level from 0 to 128.
MIDI_EVENT_DRUM_CHORUS | 54 | Sets the chorus level of a drum key (MIDI NRPN 1Eknh) nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: the chorus level from 0 to 128.
MIDI_EVENT_DRUM_CUTOFF | 55 | Sets the cutoff of the low-pass filter of a drum key (MIDI NRPN 14knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: cutoff level from 0 to 127
MIDI_EVENT_DRUM_RESONANCE | 56 | Sets the resonance of the low-pass filter of a drum key (MIDI NRPN 15knh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: resonance level from 0 to 127
MIDI_EVENT_DRUM_LEVEL | 57 | Sets the level of a drum key (MIDI NRPN 1Aknh). nMidiParam1: the key number from 0 to 127; 60 means middle C nMidiParam2: level from 0 to 127; 127 means full level.
MIDI_EVENT_SOFT | 60 | Sets the soft pedal or switch (MIDI controller 67). nMidiParam1: from 0 to 63 the soft pedal is off while from 64 to 127 the soft pedal is on. nMidiParam2: not used
MIDI_EVENT_SYSTEM | 61 | Sets the system mode, resetting everything to the system's defaults. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used
MIDI_EVENT_TEMPO | 62 | Sets the tempo (MIDI meta event 81). nMidiParam1: tempo in microseconds per quarter note. nMidiParam2: not used
MIDI_EVENT_SCALETUNING | 63 | Sets the tuning of a note in every octave. nMidiParam1: tuning change in cents, can range from 0 to 16383. 0 means a tuning of -100, 8192 means normal while 16383 means a tuning of +100. nMidiParam2: note; can range from 0 to 11 where 0 is note C
MIDI_EVENT_CONTROL | 64 | Unhandled controller. This has no effect on the MIDI stream, but can be useful for custom processing purposes with the MidiStreamEventNotification event.
MIDI_EVENT_CHANPRES_VIBRATO | 65 | Sets the maximum effect of channel pressure on vibrato depth. nMidiParam1: vibrato depth effect in cents (0=none, 128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_CHANPRES_PITCH | 66 | Sets the maximum effect of channel pressure on pitch. nMidiParam1: pitch effect in semitones (0=-24, 24=none, 48=+24). . nMidiParam2: not used
MIDI_EVENT_CHANPRES_FILTER | 67 | Sets the maximum effect of channel pressure on filter cutoff. nMidiParam1: filter cutoff effect in cents (0=-9600, 9600=none, 19200=+9600). nMidiParam2: not used
MIDI_EVENT_CHANPRES_VOLUME | 68 | Sets the maximum effect of channel pressure on volume. nMidiParam1: volume effect percentage (0=-100, 100=none, 200=+100). nMidiParam2: not used
MIDI_EVENT_MODRANGE | 69 | Sets the modulation/vibrato depth range (MIDI RPN 5). nMidiParam1: vibrato depth in cents (128=100, 256=200, etc). nMidiParam2: not used
MIDI_EVENT_BANK_LSB | 70 | Selects the bank LSB to use (MIDI controller 32). nMidiParam1: bank number LSB (0-127). nMidiParam2: not used
MIDI_EVENT_MIX_VOLUME_LEVEL | Hex 10000 | Sets the volume level at mixing time, meaning that the level will not be affected by eventual MIDI_EVENT_VOLUME events inside a MIDI file. nMidiParam1: volume level; 0 means silence, 100 applies a 0 dB level, 200 applies a +6 dB level. nMidiParam2: not used
MIDI_EVENT_TRANSPOSE | Hex 10001 | Transposes all notes. nMidiParam1: amount of transposition in semitones, can range from 0 to 200. 0 means -100, 100 means normal while 200 means +100. nMidiParam2: not used
MIDI_EVENT_SYSTEMEX | Hex 10002 | Sets the system mode, resetting everything to the system's defaults including MIDI channels allocated through the MIDI.ChannelsSet method. nMidiParam1: type of system mode, can assume the following values: 0 = System default 1 = General MIDI 1 2 = General MIDI 2 3 = Yamaha XG 4 = Roland GS nMidiParam2: not used

nMidiParam1

The number representing the first parameter related to the event (see the MIDI events table above for details)

nMidiParam2

The number representing the second parameter related to the event (see the MIDI events table above for details)

nMidiChannel

The MIDI channel on which the event is applied.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VST.InstrumentEventRawApply method

VST.InstrumentEventRawApply method

Remarks

Applies a single raw MIDI event to the VST instrument. Applying multiple events at the same time, as seen for the MIDI object, is not supported.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

For further details about the use of MIDI protocol see the MIDI object section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

control.VST.InstrumentEventRawApply (

nPlayer as Integer,

nByte0 as Byte,

nByte1 as Byte,

nByte2 as Byte

) as enumErrorCodes

[C++]

short control.VST.InstrumentEventRawApply (

short nPlayer,

BYTE nByte0,

BYTE nByte1,

BYTE nByte2

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that hosts the VST instrument
nByte0 | First byte of the raw sequence
nByte1 | Second byte of the raw sequence
nByte2 | Third byte of the raw sequence

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VST.InstrumentFree method

VST.InstrumentFree method

Remarks

Frees the VST instrument plugin.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.InstrumentFree (

nPlayer as Integer

) as Long

[C++]

long control.VST.InstrumentFree (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that hosts the VST instrument

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.InstrumentLoad method

VST.InstrumentLoad method

Remarks

Loads a VST instrument plugin into the given player from an external dynamic-link library (DLL) file. For VST effects use the VST.EffectLoad method.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.InstrumentLoad (

nPlayer as Integer,

strPathname as String,

nFrequency as Long,

nChannels as Integer

) as Long

[C++]

long control.VST.InstrumentLoad (

short nPlayer,

LPCTSTR strPathname,

long nFrequency,

short nChannels

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that hosts the VST instrument

strPathname

String representing the filename or absolute pathname of the DLL file containing the VST instrument.

If the string specifies a path but the file does not exist in the specified directory, the function fails. When specifying a path, be sure to use backslashes (\), not forward slashes (/).

If the string does not specify a path, the function uses the standard search strategy of the LoadLibrary Windows API to find the file.

nFrequency

Sample rate of the audio stream

nChannels

Number of channels of the audio stream

Return value

Value | Meaning
0 | An error occurred: see the LastError property for further error details or for a list of the possible error values.
Other values | Numeric value representing the unique identifier of the VST instrument: this unique identifier will be used in order to invoke further methods related to the use of the loaded VST instrument.


VST.ProgramGetCurrent method

VST.ProgramGetCurrent method

Remarks

Obtains the index of the embedded program currently selected into the VST.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramGetCurrent (

nPlayer as Integer,

nIdVST as Long

) as Integer

[C++]

short control.VST.ProgramGetCurrent (

short nPlayer,

long nIdVST

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | Zero-based index of the selected embedded program


VST.ProgramSetCurrent method

VST.ProgramSetCurrent method

Remarks

Selects one of the embedded programs available inside the VST.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramSetCurrent (

nPlayer as Integer,

nIdVST as Long,

nProgramIndex as Integer

) as enumErrorCodes

[C++]

short control.VST.ProgramSetCurrent (

short nPlayer,

long nIdVST,

short nProgramIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.
nProgramIndex | Zero-based index of the program

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.ProgramNameGet method

VST.ProgramNameGet method

Remarks

Obtains the name of the given program.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramNameGet (

nPlayer as Integer,

nIdVST as Long,

nProgramIndex as Integer

) as String

[C++]

LPCTSTR control.VST.ProgramNameGet (

short nPlayer,

long nIdVST,

short nProgramIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.
nProgramIndex | Zero-based index of the program

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the name of the given program


VST.ProgramNameSet method

VST.ProgramNameSet method

Remarks

Sets the name of the given program.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramNameSet (

nPlayer as Integer,

nIdVST as Long,

nProgramIndex as Integer,

strName as String

) as enumErrorCodes

[C++]

short control.VST.ProgramNameSet (

short nPlayer,

long nIdVST,

short nProgramIndex,

LPCTSTR strName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.Load method.
nProgramIndex | Zero-based index of the program
strName | New program name

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.ProgramParamGetDefaultValue method

VST.ProgramParamGetDefaultValue method

Remarks

Obtains the default value for the specific parameter related to the given program.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramParamGetDefaultValue (

nPlayer as Integer,

nIdVST as Long,

nProgramIndex as Integer,

nParamIndex as Integer,

fValue as Single

) as Integer

[C++]

short control.VST.ProgramParamGetDefaultValue (

short nPlayer,

long nIdVST,

short nProgramIndex,

short nParamIndex,

float *fValue

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.
nProgramIndex | Zero-based index of the program
nParamIndex | Zero-based index of the parameter
fValue | Reference that, after returning from the method call, will contain the default value of the given parameter

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.ProgramParamGetInfo method

VST.ProgramParamGetInfo method

Remarks

Obtains specific information about the given parameter.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramParamGetInfo (

nPlayer as Integer,

nIdVST as Long,

nProgramIndex as Integer,

nParamIndex as Integer,

nInfo as enumVstParamInfo

) as String

[C++]

LPCTSTR control.VST.ProgramParamGetInfo (

short nPlayer,

long nIdVST,

short nProgramIndex,

short nParamIndex,

short nInfo

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdVST

Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.

nProgramIndex

Zero-based index of the program

nParamIndex

Zero-based index of the parameter

nInfo

Type of requested information.

Supported values are the following:

Mnemonic constant | Value | Meaning
VST_PARAM_INFO_NAME | 0 | VST Parameter Name, for example Time, Gain, RoomType, etc.
VST_PARAM_INFO_LABEL | 1 | VST Parameter Label. This usually represents the unit of measure for the parameter, for example dB, type, sec., etc.
VST_PARAM_INFO_DISPLAY | 2 | VST Parameter Display. This usually represents the current value of the parameter in a readable format but it's not guaranteed that all VSTs available on the marker will always use this parameter for this specific purpose.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | String containing the requested information


VST.ProgramParamGetValue method

VST.ProgramParamGetValue method

Remarks

Obtains the current value for the specific parameter related to the given program.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramParamGetValue (

nPlayer as Integer,

nIdVST as Long,

nProgramIndex as Integer,

nParamIndex as Integer,

fValue as Single

) as Integer

[C++]

short control.VST.ProgramParamGetValue (

short nPlayer,

long nIdVST,

short nProgramIndex,

short nParamIndex,

float *fValue

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nIdVST

Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.

nProgramIndex

Zero-based index of the program

nParamIndex

Zero-based index of the parameter

fValue

Reference that, after returning from the method call, will contain the current value of the given parameter.

Values returned by this method are always in the range between 0.0 and 1.0, however, from the view of a VST effect, they may represent completely different values. In general, this value represents the ratio between the minimum and maximum values that the parameter could assume and not the "real" value of the parameter; if for example a certain parameter should have values inside the range 0-256, a value of 128 would be returned as 0.5.

Unfortunately the VST SDK doesn't provide information about "real" minimum and maximum values but only the ratio or, in alternative, the current value in a readable format through a string returned by the call to the VST.ProgramParamGetInfo method having the nInfo parameter set to VST_PARAM_INFO_DISPLAY.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.ProgramParamSetValue method

VST.ProgramParamSetValue method

Remarks

Sets the new value for the specific parameter related to the given program.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramParamSetValue (

nPlayer as Integer,

nIdVST as Long,

nProgramIndex as Integer,

nParamIndex as Integer,

fValue as Single

) as enumErrorCodes

[C++]

short control.VST.ProgramParamSetValue (

short nPlayer,

long nIdVST,

short nProgramIndex,

short nParamIndex,

float fValue

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.
nProgramIndex | Zero-based index of the program
nParamIndex | Zero-based index of the parameter
fValue | The new value of the given parameter. Values must be always in the range between 0.0 and 1.0, however, from the view of a VST effect, they may represent completely different values. In general, this value represents the ratio between the minimum and maximum values that the parameter could assume and not the "real" value of the parameter; if for example a certain parameter should have values inside the range 0-256, a value of 128 would be returned as 0.5.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VST.ProgramParamsGetCount method

VST.ProgramParamsGetCount method

Remarks

Obtains the number of parameters related to the given program.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramParamsGetCount (

nPlayer as Integer,

nIdVST as Long,

nProgramIndex as Integer

) as Integer

[C++]

short control.VST.ProgramParamsGetCount (

short nPlayer,

long nIdVST,

short nProgramIndex

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.
nProgramIndex | Zero-based index of the program

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | Number of parameters


VST.ProgramsGetCount method

VST.ProgramsGetCount method

Remarks

Obtains the number of programs embedded into the VST.

For further details about methods related to the use of VST effects refer to the VST COM object.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

control.VST.ProgramsGetCount (

nPlayer as Integer,

nIdVST as Long

) as Integer

[C++]

short control.VST.ProgramsGetCount (

short nPlayer,

long nIdVST

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nIdVST | Unique identifier of the VST effect as returned by the VST.EffectLoad or VST.InstrumentLoad methods.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value >= 0 | Number of embedded programs


VUMeter object

VUMeter object

The VUMeter object, accessible through the control's VUMeter property, is internally implemented as a COM interface called IVUMeter and contains information needed to render the embedded VU-Meter visual feedback.

It can be used at Run-time in order to create the embedded VU-Meter and to change its graphic settings. For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section

The VUMeter object is implemented through the following methods and properties:

Methods

Create

KeepCountOfVolume

Resize

Show

SetHwnd

SetBackPictureFromFile

SetBackPictureFromHandle

Properties

BandType

HasPeaks

ColorBands

ColorPeaks

ColorBackground

ZoomPerc

The following code snippets show how to create and change this object in your code. These examples assume that you have placed a control named MyPlayer on a form or dialog and that you want to change a couple of graphic settings (Bands and Background colors).

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Microsoft Visual Basic (5.0 and 6.0)

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual J#.NET

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Properties and methods of the control are accessible through the control wrapper class CAmp3dj contained inside the amp3dj.cpp and amp3dj.h files: these wrapper files are automatically generated when you insert the control inside your project so, in order to access the wrapper functions, you will have to insert the following line of code somewhere in your code.

#include "amp3dj.h"

The VUMeter object is defined by the control wrapper class CVUMeter contained inside the vumeter.cpp and vumeter.h files: also these wrapper files are automatically generated when you insert the control inside your project so, in order to access this object, you will have to insert the following line of code somewhere in your code.

#include "vumeter.h"

Here follows the code needed to perform the requested operation of initialising the VU-Meter object and changing some of its properties.

// declare a VUMeter object

CVUMeter vumeter;

// init the object with the control's VUMeter reference

vumeter = MyPlayer.GetVUMeter ();

// create the VU-meter for player 0 over an existing control

vumeter.Create (0, (OLE_HANDLE) GetDlgItem (IDC_PICTURE)->GetSafeHwnd ());

// again for player 0, set the VU-meter bands color to blue and background color to white

vumeter.SetColorBands (0, RGB (0, 0, 255));

vumeter.SetColorBackground (0, RGB (255, 255, 255));

As you can see the access to the VUMeter properties ColorBands and ColorBackground are wrapped by the SetColorBands and SetColorBackground functions declared inside the wrapper class CVUMeter.

Microsoft Visual Basic (5.0 and 6.0)

Here follows the code needed to perform the requested operations

' create the VU-meter on player 0 over an existing control

MyPlayer.VUMeter.Create 0, Picture1.hWnd

' set the blue color for VU-meter bands of player 0

MyPlayer.VUMeter.ColorBands(0) = RGB(0, 0, 255)

' set the white color for VU-meter background of player 0

MyPlayer.VUMeter.ColorBackground(0) = RGB(255, 255, 255)

Microsoft Visual Basic.NET

Here follows the code needed to perform the requested operations

' create the VU-meter on player 0 over an existing control

MyPlayer.VUMeter.Create(0, PictureBox1.Handle.ToInt32())

' set the blue color for VU-meter bands of player 0

MyPlayer.VUMeter.ColorBands(0) = Convert.ToUInt32(RGB(0, 0, 255))

' set the white color for VU-meter background of player 0

MyPlayer.VUMeter.ColorBackground(0) = Convert.ToUInt32(RGB(255, 255, 255))

Microsoft Visual C#.NET

Here follows the code needed to perform the requested operations

// create the VU-meter on player 0 over an existing control

MyPlayer.VUMeter.Create(0, pictureBox1.Handle.ToInt32());

// set the blue color for VU-meter bands of player 0

MyPlayer.VUMeter.set_ColorBands (0, Convert.ToUlong (ColorTranslator.ToWin32 (Color.Blue)));

// set the white color for VU-meter background of player 0

MyPlayer.VUMeter.set_ColorBackground(0, Convert.ToUlong (ColorTranslator.ToWin32 (Color.White)));

Microsoft Visual J#.NET

Here follows the code needed to perform the requested operations

// create the VU-meter on player 0  over an existing control

MyPlayer.get_VUMeter ().Create ((short) 0, (int) pictureBox1.get_Handle().ToInt32());

// set the blue color for VU-meter bands of player 0

System.Ulong colorBlue = (System.UInt32) ColorTranslator.ToWin32 (Color.get_Blue ());

MyPlayer.get_VUMeter ().set_ColorBands ((short) 0, colorBlue);

// set the white color for VU-meter background of player 0

System.Ulong colorWhite = (System.UInt32) ColorTranslator.ToWin32 (Color.get_White ());

MyPlayer.get_VUMeter ().set_ColorBackground((short) 0, colorWhite);

As you can see, in J#.NET the access to the control properties is made through the use of wrapper functions (automatically generated when you insert the control inside your project) with the "get_" and "set_" prefixes. Intellisense will help you finding the right wrapper function.


VUMeter.BandType property

VUMeter.BandType property

Type

short for Visual C++

enumVuBandsMode for Visual Basic

Syntax

object.VUMeter.BandType (nPlayer as integer) [=Integer]

Remarks

Determines, for the given player, if the embedded VU-Meter visual feedback will have, for Stereo songs, a mix of the Left and Right channel on a single "band" or if there will be a "band" for each channel (default).

Supported values are the following:

Mnemonic constant | Value | Meaning
VU_BAND_LEFTRIGHT (default) | 0 | Left and Right channel VU values are displayed into two separated Bands
VU_BAND_MIXED | 1 | Left and Right channel VU values are mixed into one single Band

See also

VUMeter COM object.

VUMeter property

How to use the embedded Visual Feedbacks section.


VUMeter.ColorBackground property

VUMeter.ColorBackground property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.VUMeter.ColorBackground (nPlayer as integer) [=long]
Remarks | Sets the color of the VU-Meter background for the given player.
See also | VUMeter COM object. VUMeter property How to use the embedded Visual Feedbacks section.


VUMeter.ColorBands property

VUMeter.ColorBands property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.VUMeter.ColorBands (nPlayer as integer) [=long]
Remarks | Sets the VU-Meter "bands" color for the given player.
See also | VUMeter COM object. VUMeter property How to use the embedded Visual Feedbacks section.


VUMeter.ColorPeaks property

VUMeter.ColorPeaks property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.VUMeter.ColorPeaks (nPlayer as integer) [=long]
Remarks | Sets the VU-Meter "peaks" color for the given player.
See also | VUMeter COM object. VUMeter property How to use the embedded Visual Feedbacks section.


VUMeter.HasPeaks property

VUMeter.HasPeaks property

Type | short for Visual C++ enumBoolean for Visual Basic
Syntax | object.VUMeter.HasPeaks (nPlayer as integer) [=Integer]
Remarks | Determines, for the given player, if the embedded VU-Meter visual feedback will display graphic "peaks" over the "bands".
See also | VUMeter COM object. VUMeter property How to use the embedded Visual Feedbacks section.


VUMeter.ZoomPerc property

VUMeter.ZoomPerc property

Type | short for Visual C++ integer for Visual Basic
Syntax | object.VUMeter.ZoomPerc (nPlayer as integer) [=integer]
Remarks | Sets the height zoom percentage of bands drawn for the given player. By default set to 100%, can assume values in the range from 5% to 500%
See also | VUMeter COM object. VUMeter property How to use the embedded Visual Feedbacks section.


VUMeter.Create method

VUMeter.Create method

Remarks

Creates the VU-Meter object: once created, the VU-Meter will stay active until the termination of the container application: being a graphical object, the VU-Meter needs to be associated to an existing window that will be used as a surface for the graphic rendering: this window can be changed at a later time through the VUMeter.SetHwnd method.

Once created, by default the VU-Meter is still not visible: you must make a call to the VUMeter.Show method in order to display it.

Note that you can have a different VU-Meter for each of the allocated players-

For further details about using the embedded VU-Meter refer to the VUMeter object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.VUMeter.Create (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.VUMeter.Create (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the VU-Meter
hWndTarget | Handle of the window whose surface will be used in order to render the VU-Meter graphics: if you want to implement your own VU-Meter graphics, catching the VUMeterValueChange event, you can set this parameter to 0.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VUMeter.Resize method

VUMeter.Resize method

Remarks

Resizes the embedded VU-Meter, useful when a resize of the hosting window occurs. This method has no effect without a previous call to the VUMeter.Create method.

For further details about using the embedded VU-Meter refer to the VUMeter object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.VUMeter.Resize (

nPlayer as Integer,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.VUMeter.Resize (

short nPlayer,

long nWidth,

long nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the VU-Meter
nWidth | New width of the VU-Meter expressed in pixels
nHeight | New height of the VU-Meter expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VuMeter.KeepCountOfVolume method

VuMeter.KeepCountOfVolume method

Remarks

Specifies if the VU-Meter must keep count of the volume set into the DirectSound buffer of the given player, through a previous call to the StreamVolumeDirectSoundBufferSet method, in order to calculate the volume level. This method has no effect without a previous call to the VUMeter.Create method.

For further details about using the embedded VU-Meter refer to the VUMeter object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.VUMeter.KeepCountOfVolume (

nPlayer as Integer,

bKeepCountOfVolume as enumBoolean

) as enumErrorCodes

[C++]

short control.VUMeter.KeepCountOfVolume (

short nPlayer,

short bKeepCountOfVolume

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the VU-Meter

bKeepCountOfVolume

Boolean flag that specifies if the VU-Meter must keep count of volume.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't keep count of volume set through the StreamVolumeDirectSoundBufferSet method: in this case the VU-Meter will always display the original volume level of the sound being played.
BOOL_TRUE (default) | 1 | Keeps count of volume: in this case any change to the player's volume performed through the StreamVolumeDirectSoundBufferSet method will be reflected into the visualization of the VU-meter and into values reported by the VUMeterValueChange event.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VUMeter.SetBackPictureFromFile method

VUMeter.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the embedded VU-Meter refer to the VUMeter object section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.VUMeter.SetBackPictureFromFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.VUMeter.SetBackPictureFromFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the VU-Meter
strPathname | Absolute pathname of the picture file to load. Accepted graphic formats are BMP, JPEG, GIF, TIFF and PNG. An empty pathname will reset an eventual picture set through a previous call to this method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VUMeter.SetBackPictureFromHandle method

VUMeter.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle (HBITMAP).

For further details about using the embedded VU-Meter refer to the VUMeter object section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.VUMeter.SetBackPictureFromHandle (

nPlayer as Integer,

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.VUMeter.SetBackPictureFromHandle (

short nPlayer,

OLE_HANDLE hBitmap

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the VU-Meter
hBitmap | Handle of the bitmap to apply. If this parameter is set to 0 an eventual picture set through a previous call to this method will be reset.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VUMeter.SetHwnd method

VUMeter.SetHwnd method

Remarks

Changes the HWND of the window used as a surface for the graphic rendering.

For further details about using the embedded VU-Meter refer to the VUMeter object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.VUMeter.SetHwnd (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.VUMeter.SetHwnd (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the VU-Meter
hWndTarget | Handle of the window whose surface will be used in order to render the VU-Meter graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


VUMeter.Show method

VUMeter.Show method

Remarks

Shows/hides the embedded VU-Meter. This method has no effect without a previous call to the VUMeter.Create method.

For further details about using the embedded VU-Meter refer to the VUMeter object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.VUMeter.Show (

nPlayer as Integer,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.VUMeter.Show (

short nPlayer,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the VU-Meter

bShow

Boolean value that specifies to the player if it must show/hide the VU-Meter.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the VU-Meter graphics
BOOL_TRUE | 1 | Shows the VU-Meter graphics

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI object

WASAPI object

The WASAPI object, accessible through the component's WASAPI property, is internally implemented as a COM interface called IASIO and contains methods needed to manage WASAPI.

The WASAPI objectclass is implemented through the following methods:

AttachCaptureDeviceToPlayer

DeviceChannelsGet

DeviceCoreAudioIndexGet

DeviceGetCount

DeviceGetDesc

DeviceIsFormatSupported

DeviceIsStarted

DeviceLatencyGet

DeviceMuteGet

DeviceMuteSet

DeviceSharedFormatGet

DeviceStartExcusive

DeviceStartShared

DeviceStop

DeviceVolumeGet

DeviceVolumeSet

Further information about WASAPI can be found inside the How to manage audio flow through WASAPI tutorial.

Samples of WASAPI usage in Visual C++ and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- WasapiInputPlayer

- WasapiSpeakersManager


WASAPI.AttachInputDeviceToPlayer method

WASAPI.AttachInputDeviceToPlayer method

Remarks

Attaches an input device (capture or loopback) to a player for immediate playback of incoming audio data.

When the selected input device is a loopback device, this method gives the possibility to mirror the output of a specific render device to a different render device with a very low latency: in this specific case it's strongly recommended that you avoid playing audio data taken from a specific loopback device to the corresponding render device or you may experience a very annoying echo effect.

An attached device can be detached from the player by invoking the CloseSound method or by loading a new sound through the LoadSound method or similar.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.AttachInputDeviceToPlayer (

nPlayer as Integer,

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes

) as enumErrorCodes

[C++]

short control.WASAPI.AttachInputDeviceToPlayer (

short nPlayer,

short nDeviceIndex,

short nDeviceType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

nDeviceIndex

Number representing the zero-based index of the WASAPI capture device.

This index is related to WASAPI capture devices enumerated through the WASAPI.DeviceGetCount and WASAPI.DeviceGetDesc methods having the nDeviceType parameter set to WASAPI_DEVICE_TYPE_CAPTURE..

nDeviceType

The type of input device used to obtain audio data.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device. Not being an input device, when this setting is applied audio data will be automatically taken from the corresponding loopback device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceChannelsGet method

WASAPI.DeviceChannelsGet method

Remarks

Obtains the number of channels for the given WASAPI device.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceChannelsGet (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nChannelsCount as Integer

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceChannelsGet (

short nDeviceIndex,

short nDeviceType,

short *nChannelsCount

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

nChannelsCount

Reference that, on return from the method call, will contain the number of channels for the given device.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceCoreAudioIndexGet method

WASAPI.DeviceCoreAudioIndexGet method

Remarks

Obtains the zero-based index inside the list of CoreAudio devices of a given WASAPI device.

While the list of CoreAudio devices, depending upon the value of the nStateMask parameter of the CoreAudioDevices.Enum method, may not contain devices unplugged or disabled, the list of WASAPI devices will always contain all of the devices installed inside the system, also if currently unplugged or disabled: this methods allows creating a one-to-one correspondence between WASAPI devices and CoreAudio devices.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceCoreAudioIndexGet (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nIndexCoreAudio as Long

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceCoreAudioIndexGet (

short nDeviceIndex,

short nDeviceType,

long *nIndexCoreAudio

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.

nIndexCoreAudio

Reference that, on return from the method call, will contain the zero-based index of the CoreAudio device corresponding to the given WASAPI device.

If the returned value should be set to -1, this would mean that the given WASAPI device wasn't enumerated by a previous call to the CoreAudioDevices.Enum method, probably because currently disabled or unplugged.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceGetCount method

WASAPI.DeviceGetCount method

Remarks

Retrieves the number of WASAPI devices currently installed inside the system.

The friendly name of each WASAPI device can be obtained using the WASAPI.DeviceGetDesc method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceGetCount (

nDeviceType as enumWasapiDeviceTypes,

nDevicesCount as Integer

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceGetCount (

short nDeviceType,

short *nDevicesCount

);

Parameter

Description

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

nDevicesCount

Reference that, on return from the method call, will contain the number of devices for the given device type.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceGetDesc method

WASAPI.DeviceGetDesc method

Remarks

Retrieves the friendly description of the requested WASAPI device. This method is useful when you have to fill a combo box with the friendly names of available WASAPI devices.

The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceGetDesc (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes

) as String

[C++]

LPCTSTR control.WASAPI.DeviceGetDesc (

short nDeviceIndex,

short nDeviceType

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device whose friendly name must be retrieved

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

Return value

Value | Meaning
Empty string | The value of the nDeviceIndex parameter was out of range. Use the value returned by the WASAPI.DeviceGetCount method in order to know how many WASAPI devices are currently installed inside the system.
Valid string | The string containing the friendly description of the requested device.


WASAPI.DeviceIsFormatSupported method

WASAPI.DeviceIsFormatSupported method

Remarks

Before starting a WASAPI device in exclusive mode through the WASAPI.DeviceStartExclusive method, allows checking if a certain audio format is supported by the given WASAPI device.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceIsFormatSupported (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nFrequency as Long,

nChannels as Integer

) as Boolean

[C++]

BOOL control.WASAPI.DeviceIsFormatSupported (

short nDeviceIndex,

short nDeviceType,

long nFrequency,

short nChannels

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

nFrequency

Sample rate, for example 44100

nChannels

Number of channels

Return value

Value | Meaning
FALSE | The given format is not supported
TRUE | The given format is supported


WASAPI.DeviceIsStarted method

WASAPI.DeviceIsStarted method

Remarks

Checks if the given WASAPI device has neen previously started through the WASAPI.DeviceStartExcusive or WASAPI.DeviceStartShared methods.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceIsStarted (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes

) as Boolean

[C++]

BOOL control.WASAPI.DeviceIsStarted (

short nDeviceIndex,

short nDeviceType

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

Return value

Value | Meaning
FALSE | The given WASAPI device is not started
TRUE | The given WASAPI device is started


WASAPI.DeviceLatencyGet method

WASAPI.DeviceLatencyGet method

Remarks

Obtains the latency, expressed in milliseconds, of the given WASAPI device. In order to correctly check the latency, the WASAPI device must have been previously started through one between the WASAPI.DeviceStartExcusive and WASAPI.DeviceStartShared methods.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceLatencyGet (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nLatencyMs as Long

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceLatencyGet (

short nDeviceIndex,

short nDeviceType,

long *nLatencyMs

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

nLatencyMs

Reference that, on return from the method call, will contain the latency, expressed in milliseconds, of the given WASAPI device.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceMuteGet method

WASAPI.DeviceMuteGet method

Remarks

Obtains the muting state of the audio stream that enters or leaves the given WASAPI device for the current process. The current muting state can be modified through the WASAPI.DeviceMuteSet method.

If you need to obtain the master mute for the given WASAPI device, shared by all running processes, use the CoreAudioDevices.MuteGet method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceMuteGet (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

bMute as enumBoolean

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceMuteGet (

short nDeviceIndex,

short nDeviceType,

short *bMute

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

bMute

Reference that, on return from the method call, will contain the muting state.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The audio stream is not muted
BOOL_TRUE | 1 | The audio stream is muted

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceMuteSet method

WASAPI.DeviceMuteSet method

Remarks

Sets the muting state of the audio stream that enters or leaves the given WASAPI device for the current process. The current muting state can be obtained through the WASAPI.DeviceMuteGet method.

If you need to modify the master mute for the given WASAPI device, shared by all running processes, use the CoreAudioDevices.MuteSet method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceMuteSet (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

bMute as enumBoolean

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceMuteSet (

short nDeviceIndex,

short nDeviceType,

short bMute

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

bMute

The new muting state.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The audio stream is not muted
BOOL_TRUE | 1 | The audio stream is muted

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceSharedFormatGet method

WASAPI.DeviceSharedFormatGet method

Remarks

Obtains the audio format for shared mode currently selected inside the Windows control panel for the given WASAPI device.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceSharedFormatGet (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nFrequency as Long,

nChannels as Integer

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceSharedFormatGet (

short nDeviceIndex,

short nDeviceType,

long *nFrequency,

short *nChannels

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

nFrequency

Reference that, on return from the method call, will contain the sample rate

nChannels

Reference that, on return from the method call, will contain the number of channels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceStartExclusive method

WASAPI.DeviceStartExclusive method

Remarks

Starts a WASAPI device in exclusive mode. In order to start the device in shared mode you can use the WASAPI.DeviceStartShared method. You can know if a WASAPI device is already started through the WASAPI .DeviceIsStarted method.

Loopback devices cannot be started in exclusive mode.

This method is only effective if the InitDriversType method has been invoked with the nDriverType parameter set to DRIVER_TYPE_WASAPI and must be always called at a later stage respect to the call to the InitDJSystem/InitDJSystemEx method.

This method will affect any other instance of the control inside the application. If the control should be used in conjunction with the Active Sound Recorder control, this one would be affected too.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceStartExclusive (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nSampleRate as Long,

nChannels as Integer,

nBufferLengthMs as Long,

nBufferUpdateTimeMs as Long

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceStartExclusive (

short nDeviceIndex,

short nDeviceType,

long nSampleRate,

short nChannels,

long nBufferLengthMs,

long nBufferUpdateTimeMs

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device whose friendly name must be retrieved. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.

nSampleRate

Sample rate, for example 44100

nChannels

Number of channels

nBufferLengthMs

Length of the buffer expressed in milliseconds.

This value determines the latency and if it should be too small the sound card driver may eventually adjust it to its minimum supported value. You can know if the given length has been accepted by verifying the value of the nLatencyMs parameter after calling the WASAPI.DeviceLatencyGet method.

nBufferUpdateTimeMs

Update time, expressed in milliseconds, for filling the buffer.

You can set this value to 0 in order to let the sound card driver use its default.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceStartShared method

WASAPI.DeviceStartShared method

Remarks

Starts a WASAPI device in shared mode. In order to start the device in exclusive mode you can use the WASAPI.DeviceStartExcusive method. You can know if a WASAPI device is already started through the WASAPI .DeviceIsStarted method.

This method is only effective if the InitDriversType method has been invoked with the nDriverType parameter set to DRIVER_TYPE_WASAPI and must be always called at a later stage respect to the call to the InitDJSystem/InitDJSystemEx method.

This method will affect any other instance of the control inside the application. If the control should be used in conjunction with the Active Sound Recorder control, this one would be affected too. If you should be using Active DJ Studio in conjunction with Active Sound Recorder, as seen inside the WasapiStreamMixer sample, you should prefer calling this method from Active DJ Studio so you would have a better control over the channel mode used for playback (see the nChannelMode parameter below).

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceStartShared (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nChannelMode as enumWasapiChannelModes,

nBufferLengthMs as Long,

nBufferUpdateTimeMs as Long

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceStartShared (

short nDeviceIndex,

short nDeviceType,

short nChannelMode,

long nBufferLengthMs,

long nBufferUpdateTimeMs

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device whose friendly name must be retrieved. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

nChannelMode

Channel mode.

Supported values are the following:

Mnemonic Value

Value

Meaning

WASAPI_CHANNEL_MODE_MULTI

0

Enables multichannel mode: with this mode, if the loaded sound in in Mono or in Stereo, there is the possibility to perform speakers assignment through the StreamOutputSpeakerSet method.

If the loaded song is multichannel, for example a 5.1, each channel will be automatically routed to output channels available inside the WASAPI device.

WASAPI_CHANNEL_MODE_STEREO

1

Enables stereo mode. This mode is needed when you need to send what is being played through the front speakers of a render device to a streaming server (casting session) or when the internal stream mixer of the WASAPI device needs to be used for recording purposes through the Active Sound Recorder control.

nBufferLengthMs

Length of the buffer expressed in milliseconds.

This value determines the latency and if it should be too small the sound card driver may eventually adjust it to its minimum supported value. You can know if the given length has been accepted by verifying the value of the nLatencyMs parameter after calling the WASAPI.DeviceLatencyGet method.

nBufferUpdateTimeMs

Update time, expressed in milliseconds, for filling the buffer.

You can set this value to 0 in order to let the sound card driver use its default.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceStop method

WASAPI.DeviceStop method

Remarks

Stops a WASAPI device previously started through the WASAPI.DeviceStartExcusive or WASAPI.DeviceStartShared methods. You can know if a WASAPI device is already started through the WASAPI .DeviceIsStarted method.

This method will affect any other instance of the control inside the application. If the control should be used in conjunction with the Active Sound Recorder control, this one would be affected too.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceStop (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

bReset as enumBoolean

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceStop (

short nDeviceIndex,

short nDeviceType,

short bReset

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

bReset

Boolean value indicating if the device buffer must be flushed.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The device buffer must not be reset
BOOL_TRUE | 1 | The device buffer must be reset

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceVolumeGet method

WASAPI.DeviceVolumeGet method

Remarks

Obtains the volume of the given WASAPI device for the current process. The current volume can be modified through the WASAPI.DeviceVolumeSet method.

If you need to obtain the master volume for the given WASAPI device, shared by all running processes, use the CoreAudioDevices.MasterVolumeGet method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceVolumeGet (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nScaleType as enumVolumeScales,

fVolumeLevel as Single

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceVolumeGet (

short nDeviceIndex,

short nDeviceType,

short nScaleType,

float *fVolumeLevel

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)
SCALE_LOG | 1 | The passed volume, expressed in dB, is based upon a logarithmic scale.

IMPORTANT NOTE ABOUT UNITS OF MEASURE:When dealing with values expressed in percentage the effective value can have different meaning depending upon the implementation of the sound card driver: for example, usually a percentage value of 100 is assumed as 0 dB: this is not the case when dealing with Core Audio API because, if the sound card driver allows applying a volume range from -100 dB (total silence) to +20 dB (sound amplification of +20 dB), a percentage value of 100 would mean that the applied volume is +20 dB. The range of volume values accepted by the sound card driver can be obtained by calling the CoreAudioDevices.MasterVolumeGet method.

IMPORTANT NOTE ABOUT CONVERSION BETWEEN UNITS OF MEASURE: When setting a volume expressed in percentage through one of our component's methods, the value displayed inside the "Sound" applet of the Control Panel may report a value slightly different respect to the one effectively set: this issue is due to a rounding problem when converting from percentage to dB (all values are stored in dB inside the driver); if this should be a problem for you, in order to avoid this minor issue you should always use dB as unit of measure when calling our component's methods and to set the "Sound" applet of the Control Panel to display values in dB instead of the percentage default.

fVolumeLevel

Reference that, on return from the method call, will contain the volume level for the current process (the meaning of the returned value depends upon the nScaleType parameter).

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WASAPI.DeviceVolumeSet method

WASAPI.DeviceVolumeSet method

Remarks

Sets the volume of the given WASAPI device for the current process. The current volume can be obtained through the WASAPI.DeviceVolumeGet method.

If you need to modify the master volume for the given WASAPI device, shared by all running processes, use the CoreAudioDevices.MasterVolumeSet method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

Further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

Syntax

[Visual Basic]

control.WASAPI.DeviceVolumeSet (

nDeviceIndex as Integer,

nDeviceType as enumWasapiDeviceTypes,

nScaleType as enumVolumeScales,

fVolumeLevel as Single

) as enumErrorCodes

[C++]

short control.WASAPI.DeviceVolumeSet (

short nDeviceIndex,

short nDeviceType,

short nScaleType,

float fVolumeLevel

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_RENDER | 0 | Audio rendering device.
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR | 0 | The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)
SCALE_LOG | 1 | The passed volume, expressed in dB, is based upon a logarithmic scale.

IMPORTANT NOTE ABOUT UNITS OF MEASURE:When dealing with values expressed in percentage the effective value can have different meaning depending upon the implementation of the sound card driver: for example, usually a percentage value of 100 is assumed as 0 dB: this is not the case when dealing with Core Audio API because, if the sound card driver allows applying a volume range from -100 dB (total silence) to +20 dB (sound amplification of +20 dB), a percentage value of 100 would mean that the applied volume is +20 dB. The range of volume values accepted by the sound card driver can be obtained by calling the CoreAudioDevices.MasterVolumeGet method.

IMPORTANT NOTE ABOUT CONVERSION BETWEEN UNITS OF MEASURE: When setting a volume expressed in percentage through one of our component's methods, the value displayed inside the "Sound" applet of the Control Panel may report a value slightly different respect to the one effectively set: this issue is due to a rounding problem when converting from percentage to dB (all values are stored in dB inside the driver); if this should be a problem for you, in order to avoid this minor issue you should always use dB as unit of measure when calling our component's methods and to set the "Sound" applet of the Control Panel to display values in dB instead of the percentage default.

fVolumeLevel

Number representing the volume level for the current process (the meaning of this value depends upon the nScaleType parameter).

The range of acceptable values, expressed in dB, to apply can be determined by checking the fLevelMinIndB and fLevelMaxIndB parameters of the CoreAudioDevices.MasterVolumeGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform object

Waveform object

The Waveform object, accessible through the control's Waveform property, is internally implemented as a COM interface called IWaveform and contains information needed to render the embedded Waveform visual feedback or, in alternative, to generate the full sound's waveform bitmap before starting the sound's playback...

It can be used at Run-time in order to create the embedded Waveform and to change its graphic settings.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

The Waveform object is implemented through the following methods and properties:

Methods

Create

Resize

Show

SetHwnd

AnalyzeFullSound

AnalyzeAbort

BitmapViewDrawToHdc

BitmapViewGetWidth

BitmapViewSaveToFile

BitmapViewSaveToMemory

BitmapViewVerticalLineAdd

BitmapViewVerticalLineRemove

PeaksBufferGet

PeaksBufferLengthGet

PeaksLoad

PeaksLoadFromMemory

PeaksSave

SetBackPictureFromFile

SetBackPictureFromHandle

Properties

ColorBackground

ColorLine

UpdateResolution

UseHalfColorForPeaks

ZoomPerc

The following code snippets show how to create and change this object in your code. These examples assume that you have placed a control named MyPlayer on a form or dialog and that you want to change a couple of graphic settings (Line and Background colors).

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Microsoft Visual Basic (5.0 and 6.0)

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual J#.NET

Microsoft Visual C++ (4.0, 5.0 and 6.0)

Properties and methods of the control are accessible through the control wrapper class CAmp3dj contained inside the amp3dj.cpp and amp3dj.h files: these wrapper files are automatically generated when you insert the control inside your project so, in order to access the wrapper functions, you will have to insert the following line of code somewhere in your code.

#include "amp3dj.h"

The Waveform object is defined by the control wrapper class CWaveform contained inside the waveform.cpp and waveform.h files: also these wrapper files are automatically generated when you insert the control inside your project so, in order to access this object, you will have to insert the following line of code somewhere in your code.

#include "waveform.h"

Here follows the code needed to perform the requested operation of initialising the Waveform object and changing some of its properties.

// declare a Waveform object

CWaveform waveform;

// init the object with the control's Waveform reference

waveform = MyPlayer.GetWaveform ();

// create the Waveform for player 0 over an existing control

waveform.Create (0, (OLE_HANDLE) GetDlgItem (IDC_PICTURE)->GetSafeHwnd ());

// again for player 0, set the Waveform line color to blue and background color to white

waveform.SetColorLine (0, RGB (0, 0, 255));

waveform.SetColorBackground (0, RGB (255, 255, 255));

As you can see the access to the Waveform properties ColorLine and ColorBackground are wrapped by the SetColorLine and SetColorBackground functions declared inside the wrapper class CWaveform.

Microsoft Visual Basic (5.0 and 6.0)

Here follows the code needed to perform the requested operations

' create the Waveform on player 0 over an existing control

MyPlayer.Waveform.Create 0, Picture1.hWnd

' set the blue color for Waveform line of player 0

MyPlayer.Waveform.ColorLine(0) = RGB(0, 0, 255)

' set the white color for Waveform background of player 0

MyPlayer.Waveform.ColorBackground(0) = RGB(255, 255, 255)

Microsoft Visual Basic.NET

Here follows the code needed to perform the requested operations

' create the Waveform on player 0 over an existing control

MyPlayer.Waveform.Create(0, PictureBox1.Handle.ToInt32())

' set the blue color for Waveform line of player 0

MyPlayer.Waveform.ColorLine(0) = Convert.ToUInt32(RGB(0, 0, 255))

' set the white color for Waveform background of player 0

MyPlayer.Waveform.ColorBackground(0) = Convert.ToUInt32(RGB(255, 255, 255))

Microsoft Visual C#.NET

Here follows the code needed to perform the requested operations

// create the Waveform on player 0 over an existing control

MyPlayer.Waveform.Create(0, pictureBox1.Handle.ToInt32());

// set the blue color for Waveform line of player 0

MyPlayer.Waveform.set_ColorLine (0, Convert.ToUlong (ColorTranslator.ToWin32 (Color.Blue)));

// set the white color for Waveform background of player 0

MyPlayer.Waveform.set_ColorBackground(0, Convert.ToUlong (ColorTranslator.ToWin32 (Color.White)));

Microsoft Visual J#.NET

Here follows the code needed to perform the requested operations

// create the Waveform on player 0 over an existing control

MyPlayer.get_Waveform ().Create ((short) 0, (int) pictureBox1.get_Handle().ToInt32());

// set the blue color for Waveform line of player 0

System.Ulong colorBlue = (System.UInt32) ColorTranslator.ToWin32 (Color.get_Blue ());

MyPlayer.get_Waveform ().set_ColorLine ((short) 0, colorBlue);

// set the white color for Waveform background of player 0

System.Ulong colorWhite = (System.UInt32) ColorTranslator.ToWin32 (Color.get_White ());

MyPlayer.get_Waveform ().set_ColorBackground((short) 0, colorWhite);

As you can see, in J#.NET the access to the control properties is made through the use of wrapper functions (automatically generated when you insert the control inside your project) with the "get_" and "set_" prefixes. Intellisense will help you finding the right wrapper function.


Waveform.ColorBackground property

Waveform.ColorBackground property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Waveform.ColorBackground [=long]
Remarks | Determines the color of the Waveform background.
See also | Waveform COM object. Waveform property How to use the embedded Visual Feedbacks tutorial. How to obtain the sound's waveform tutorial.


Waveform.ColorLine property

Waveform.ColorLine property

Type | OLE_COLOR for Visual C++ long for Visual Basic
Syntax | object.Waveform.ColorLine [=long]
Remarks | Determines the color of the Waveform line.
See also | Waveform COM object. Waveform property How to use the embedded Visual Feedbacks tutorial. How to obtain the sound's waveform tutorial.


Waveform.UpdateResolution property

Waveform.UpdateResolution property

Type

short for Visual C++

enumWaveformUpdateRes for Visual Basic

Syntax

object.Waveform.UpdateResolution [=Integer]

Remarks

Determines how frequently vertical lines are drawn on the screen (by default every 30 milliseconds).

Supported values are the following:

Mnemonic constant | Value | Meaning
UPDATE_RES_LOW | 0 | Low resolution: the Waveform is updated every 60 milliseconds
UPDATE_RES_MEDIUM (default) | 1 | Medium resolution: the Waveform is updated every 30 milliseconds
UPDATE_RES_HIGH | 2 | High resolution: the Waveform is updated every 15 milliseconds

See also

Waveform COM object.

Waveform property

How to use the embedded Visual Feedbacks tutorial.

How to obtain the sound's waveform tutorial.


Waveform.UseHalfColorForPeaks property

Waveform.UseHalfColorForPeaks property

Type

short for Visual C++

enumBoolean for Visual Basic

Syntax

object.Waveform.UseHalfColorForPeaks [=long]

Remarks

When generating the waveform bitmap view through one of the following methods: Waveform.BitmapViewSaveToFile, Waveform.BitmapViewSaveToMemory and Waveform.BitmapViewDrawToHdc determines if the waveform line must be drawn using only the color set inside the Waveform.ColorLine property or if waveform's peaks should be drawn using a second color which is half the intensity of the color set through the Waveform.ColorLine property.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Don't use half color for drawing waveform peaks
BOOL_TRUE (default) | 1 | Use half color for drawing waveform peaks

See also

Waveform COM object.

Waveform property

How to use the embedded Visual Feedbacks tutorial.

How to obtain the sound's waveform tutorial.


Waveform.ZoomPerc property

Waveform.ZoomPerc property

Type | short for Visual C++ integer for Visual Basic
Syntax | object.Waveform.ZoomPerc [=integer]
Remarks | Determines the height zoom percentage of waveform's lines. By default set to 100%, can assume values in the range from 5% to 500%
See also | Waveform COM object. Waveform property How to use the embedded Visual Feedbacks section.


Waveform.AnalyzeAbort method

Waveform.AnalyzeAbort method

Remarks

Aborts a running analysis of the loaded sound.

This method call will generate a WaveAnalisysStop event.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.AnalyzeAbort (

nPlayer as Integer

) as enumErrorCodes

[C++]

short control.Waveform.AnalyzeAbort (

short nPlayer

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Waveform.AnalyzeFullSound method

Waveform.AnalyzeFullSound method

Remarks

Starts the analysis of the sound loaded inside the given player in order to allow the creation of bitmaps of the sound's waveform. During the analysis phase, the container application will be notified about the current advancement through the following events: WaveAnalysisStart, WaveAnalysisPerc and WaveAnalysisDone: after receiving the WaveAnalysisDone event, it will be possible calculating the width in pixels of a bitmap view through the Waveform.BitmapViewGetWidth method and creating bitmaps of the waveform through the Waveform.BitmapViewSaveToFile and Waveform.BitmapViewSaveToMemory methods.

NOTE: Remember that a call to a method of a certain ActiveX control should be never performed from within a management function of an event generated by the same ActiveX control: see the How to synchronize the container application with the control tutorial for further details.

Started analysis can be aborted through the Waveform.AnalyzeAbort method.

This method doesn't need a previous call to the Waveform.Create method.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.AnalyzeFullSound (

nPlayer as Integer,

nResolution as enumWaveformResolutions

) as enumErrorCodes

[C++]

short control.Waveform.AnalyzeFullSound (

short nPlayer,

short nResolution

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the Waveform

nResolution

Number representing the resolution used in order to analyze the sound.

Higher resolutions will allow a higher analysis quality but will require more memory and will generate larger bitmaps.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVEFORM_RES_MINIMUM | 0 | Minimum resolution, faster calculation time. Each line on the analyzer is the average for 8192 PCM samples. Useful for very long sound files
WAVEFORM_RES_VERY_LOW | 1 | Very low resolution. Each line on the analyzer is the average for 4096 PCM samples.
WAVEFORM_RES_LOW | 2 | Low resolution. Each line on the analyzer is the average for 2048 PCM samples.
WAVEFORM_RES_MIDDLE | 3 | Middle resolution. Each line on the analyzer is the average for 1024 PCM samples.
WAVEFORM_RES_HIGH | 4 | High resolution. Each line on the analyzer is the average for 512 PCM samples.
WAVEFORM_RES_VERY_HIGH | 5 | Very high resolution. Each line on the analyzer is the average for 256 PCM samples.
WAVEFORM_RES_MAXIMUM | 6 | Maximum resolution. Each line on the analyzer is the average for 128 PCM samples. Useful for very small sound files whose duration is under 1 second.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Waveform.BitmapViewGetWidth method

Waveform.BitmapViewGetWidth method

Remarks

Given a range in milliseconds, calculates the number of pixels required for displaying the waveform's view.

The returned value can be assigned to the nBitmapWidth parameter of the Waveform.BitmapViewSaveToFile and Waveform.BitmapViewSaveToMemory methods.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the Waveform.AnalyzeFullSound method and waiting its completion through the WaveAnalysisDone event.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.BitmapViewGetWidth (

nPlayer as Integer,

nStartPos as Long,

nEndPos as Long

) as Long

[C++]

long control.Waveform.BitmapViewGetWidth (

short nPlayer,

long nStartPos,

long nEndPos

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
nStartPos | Number representing the sound's position, expressed in milliseconds, where the waveform's view begins. The value 0 represents the sound's beginning.
nEndPos | Number representing the sound's position, expressed in milliseconds, where the waveform's view ends. The value -1 represents the sound's end.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
Value > 0 | The method call was successful and the returned value represents the width in pixels of the waveform's view


Waveform.BitmapViewDrawToHdc method

Waveform.BitmapViewDrawToHdc method

Remarks

Renders the bitmap view of the given waveform range inside a graphical Device Context (HDC).

Before calling this method it's mandatory performing a previous sound's analysis through a call to the Waveform.AnalyzeFullSound method and waiting its completion through the WaveAnalysisDone event.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.BitmapViewDrawToHdc (

hDC as OLE_HANDLE,

nPosLeft as Long,

nPosTop as Long,

nWidth as Long,

nHeight as Long,

nWaveformStereoMode as enumWaveformStereoModes,

bUseHalfColorsForPeaks as enumBoolean,

bShowVerticalLines as enumBoolean,

nStartPos as Long,

nEndPos as Long

) as enumErrorCodes

[C++]

short control.Waveform.BitmapViewDrawToHdc (

OLE_HANDLE hDC,

long nPosLeft,

long nPosTop,

long nWidth,

long nHeight,

short nWaveformStereoMode,

short bUseHalfColorsForPeaks,

short bShowVerticalLines,

long nStartPos,

long nEndPos

);

Parameter

Description

hDC

Handle to the output graphical Device Context

nPosLeft

Horizontal left position, expressed in pixels, of the destination rectangle where the bitmap will be rendered on the Device Context

nPosTop

Vertical top position, expressed in pixels, of the destination rectangle where the bitmap will be rendered on the Device Context

nWidth

Width, expressed in pixels, of the destination rectangle on the Device Context

nHeight

Height, expressed in pixels, of the destination rectangle on the Device Context

nWaveformStereoMode

Visualization mode used for displaying stereo sounds

Supported values are the following:

Mnemonic constant | Value | Meaning
STEREO_MODE_CHANNELS_BOTH | 0 | Right and left channels are displayed separately on two different panes as seen on the pictures A and B above.
STEREO_MODE_CHANNELS_LEFT | 1 | Only the left channel content is displayed on a single pane
STEREO_MODE_CHANNELS_RIGHT | 2 | Only the right channel content is displayed on a single pane
STEREO_MODE_CHANNELS_MIXED | 3 | Right and left channels contents are mixed together and displayed on a single pane

bUseHalfColorsForPeaks

Boolean value that determines if waveform peaks will have a half intensity color.

Supported values are the following:

Mnemonic constant | Value | Meaning
False | 0 | Doesn't use half color for peaks
True (default) | 1 | Uses half color for peaks

bShowVerticalLines

Boolean value that determines if eventual vertical lines, added through previous calls to the WaveformAnalyzer.BitmapViewVerticalLineAdd method, should be rendered as well.

Supported values are the following:

Mnemonic constant | Value | Meaning
False | 0 | Doesn't render vertical lines
True (default) | 1 | Renders vertical lines

nStartPos

Number representing the sound's position, expressed in milliseconds, where the waveform visualization begins.

The value 0 represents the sound's beginning.

This position can assume negative values as well; if for example you should need to display a 10 seconds range (10000 milliseconds), with the beginning of the sound on the center of the device context, you could set this value to -5000 and the nEndPos parameter to 5000; in this case position 0 of the sound would be rendered exactly on the center of the device context.

On the screenshots below you can see two portions of the same sound; in the first case the vertical white line represents the position 0 ms of the song ranging from -5000 ms to +5000 ms; as you can see, the negative portion on the left, where no sound exists, is rendered as absence of audible sound.

In this seconds case the vertical white line represents the position 5000 ms of the song ranging from 0 ms to +10000 ms

nEndPos

Number representing the sound's position, expressed in milliseconds, where the waveform visualization ends.

The value -1 represents the sound's end.

This position can assume values higher respect the effective sound duration; for portions of sounds outside of the effective duration, the waveform is rendered as absence of audible sound as seen above for the nStartPos parameter when rendering negative positions.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


Waveform.BitmapViewSaveToFile method

Waveform.BitmapViewSaveToFile method

Remarks

Creates a graphic file containing the bitmap view of the analysed sound waveform: the view can represent the full sound's waveform or portions of it.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the Waveform.AnalyzeFullSound method and waiting its completion through the WaveAnalysisDone event.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.BitmapViewSaveToFile (

nPlayer as Integer,

nStartPos as Long,

nEndPos as Long,

nBitmapWidth as Integer,

nBitmapHeight as Integer,

nWaveformType as enumWaveformTypes,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as long

) as enumErrorCodes

[C++]

short control.Waveform.BitmapViewSaveToFile (

short nPlayer,

long nStartPos,

long nEndPos,

long nBitmapWidth,

long nBitmapHeight,

short nWaveformType,

LPCTSTR strPathname,

short nFormat,

long nFormatParameter

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the Waveform

nStartPos

Number representing the sound's position, expressed in milliseconds, where the waveform visualization begins.

The value 0 represents the sound's beginning.

nEndPos

Number representing the sound's position, expressed in milliseconds, where the waveform visualization ends.

The value -1 represents the sound's end.

nBitmapWidth

Number representing the generated bitmap width, expressed in pixels. A value of -1 indicates no width constraints: in this case the control will generate a bitmap large enough in order to contain the full sound's waveform.

nBitmapHeight

Number representing the generated bitmap height, expressed in pixels.

nWaveformType

The type of rendered waveform, related to the sound's channels.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVEFORM_TYPE_LEFT | 0 | The bitmap contains sound data for the left channel
WAVEFORM_TYPE_RIGHT | 1 | The bitmap contains sound data for the right channel
WAVEFORM_TYPE_MIXED | 2 | The bitmap contains sound data for left and right mixed channels

strPathname

String containing the absolute pathname of the file where the waveform will be saved.

nFormat

Graphic format used to save the bitmap.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_BMP | 0 | BMP format
GRAPHIC_FORMAT_JPEG | 1 | JPEG format
GRAPHIC_FORMAT_PNG | 2 | PNG format
GRAPHIC_FORMAT_GIF | 3 | GIF format
GRAPHIC_FORMAT_TIFF | 4 | TIFF format

nFormatParameter

Eventual parameters required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful


Waveform.BitmapViewSaveToMemory method

Waveform.BitmapViewSaveToMemory method

Remarks

Creates a view (in form of memory bitmap referenced by a HBITMAP) of the waveform for the sound loaded inside the given player: the view can represent the full sound's waveform or portions of it.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the Waveform.AnalyzeFullSound method and waiting its completion through the WaveAnalysisDone event.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.BitmapViewSaveToMemory (

nPlayer as Integer,

nStartPos as Long,

nEndPos as Long,

nBitmapWidth as Integer,

nBitmapHeight as Integer,

nWaveformType as enumWaveformTypes

) as Long

[C++]

long control.Waveform.BitmapViewSaveToMemory (

short nPlayer,

long nStartPos,

long nEndPos,

long nBitmapWidth,

long nBitmapHeight,

short nWaveformType

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the Waveform

nStartPos

Number representing the sound's position, expressed in milliseconds, where the waveform visualization begins.

The value 0 represents the sound's beginning.

nEndPos

Number representing the sound's position, expressed in milliseconds, where the waveform visualization ends.

The value -1 represents the sound's end.

nBitmapWidth

Number representing the generated bitmap width, expressed in pixels. A value of -1 indicates no width constraints: in this case the control will generate a bitmap large enough in order to contain the full sound's waveform.

nBitmapHeight

Number representing the generated bitmap height, expressed in pixels.

nWaveformType

The type of rendered waveform, related to the sound's channels.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVEFORM_TYPE_LEFT | 0 | The bitmap contains sound data for the left channel
WAVEFORM_TYPE_RIGHT | 1 | The bitmap contains sound data for the right channel
WAVEFORM_TYPE_MIXED | 2 | The bitmap contains sound data for left and right mixed channels

Return value

Value | Meaning
0 | An error occurred (check the LastError property for error details)
Value is not 0 | The method call was successful and the returned value represents the handle (HBITMAP) of the waveform's bitmap stored in memory. When the returned HBITMAP is no more needed or before exiting the container application, in order to avoid memory leaks this handle should be deleted using the DeleteObject Windows API.


Waveform.BitmapViewVerticalLineAdd method

Waveform.BitmapViewVerticalLineAdd method

Remarks

Adds a new vertical line that will be displayed when rendering the waveform's graphics through the Waveform.BitmapViewDrawToHdc method. This line can be removed at any time by using the Waveform.BitmapViewVerticalLineRemove method.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.BitmapViewVerticalLineAdd (

nUniqueId as Integer,

nPosition as Long,

color as OLE_COLOR,

nMode as enumWaveformLineModes,

nWidth as Integer

) as enumErrorCodes

[C++]

short control.Waveform.BitmapViewVerticalLineAdd (

short nUniqueId,

long nPosition,

OLE_COLOR color,

short nMode,

short nWidth

);

Parameter

Description

nUniqueId

Unique identification number assigned to this new line.

nPosition

Initial position expressed in milliseconds

color

Color of the line

nMode

Line mode used for rendering the line.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
LINE_MODE_DOTTED | 0 | Dotted line (applied only if the nWidth parameter below is set to 1)
LINE_MODE_DASHED | 1 | Dashed line (applied only if the nWidth parameter below is set to 1)
LINE_MODE_SOLID | 2 | Solid line

nWidth

Width of the line expressed in pixels. In case the parameter should be set to a value higher than 1, the nMode parameter above would be automatically set to LINE_MODE_SOLID.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.BitmapViewVerticalLineRemove method

Waveform.BitmapViewVerticalLineRemove method

Remarks

Removes the given line previously added through the Waveform.BitmapViewVerticalLineAdd method.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.BitmapViewVerticalLineRemove (

nUniqueId as Integer

) as enumErrorCodes

[C++]

short control.Waveform.BitmapViewVerticalLineRemove (

short nUniqueId

);

Parameter | Description
nUniqueId | Unique identification number of the line to remove.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.Create method

Waveform.Create method

Remarks

Creates the Waveform object: once created, the Waveform will stay active until the termination of the container application: being a graphical object, the Waveform needs to be associated to an existing window that will be used as a surface for the graphic rendering: this window can be changed at a later time through the Waveform.SetHwnd method.

Once created, by default the Waveform is still not visible: you must make a call to the Waveform.Show method in order to display it.

Note that you can have a different Waveform for each of the allocated players.

For further details about using the embedded Waveform refer to the Waveform object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Waveform.Create (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Waveform.Create (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
hWndTarget | Handle of the window whose surface will be used in order to render the Waveform graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.PeaksBufferGet method

Waveform.PeaksBufferGet method

Remarks

Fills two buffers with min and max waveform peaks for the given range. The size of each buffer can be obtained with a previous call to the Waveform.PeaksBufferLengthGet method.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the Waveform.AnalyzeFullSound method and waiting its completion through the WaveAnalysisDone event.

For further details about using the embedded Waveform refer to the Waveform object section.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.PeaksBufferGet (

nPlayer as Integer,

nChannel as Integer,

nStartPos as Long,

nEndPos as Long,

bValueInPerc as enumBoolean,

pBufferMin as Variant,

pBufferMax as Variant,

nBufferLength as Long

) as enumErrorCodes

[C++]

short control.Waveform.PeaksBufferGet (

short nPlayer,

short nChannel,

long nStartPos,

long nEndPos,

short bValueInPerc,

const VARIANT FAR& pBufferMin,

const VARIANT FAR& pBufferMax,

long nBufferLength

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the waveform.

nChannel

Number representing the audio channel we are interested in. Can be a value between 0 and 7.

nStartPos

Number representing the start position, expressed in milliseconds, where we want to get waveform's peaks.

The value 0 represents the sound's beginning.

nEndPos

Number representing the end position, expressed in milliseconds, where we want to get waveform's peaks.

The value -1 represents the sound's end.

bValueInPerc

Boolean value that specifies if the given buffers should be filled with values expressed in percentage.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Given buffers will be filled with values from 0 to 32767 for the pBufferMax buffer and from 0 to -32768 for the pBufferMin buffer.
BOOL_TRUE | 1 | Given buffers will be filled with values expressed in percentage

pBufferMin

Variant parameter containing the pointer to the buffer that, on return from the method call, will contain the min waveform peaks.

pBufferMax

Variant parameter containing the pointer to the buffer that, on return from the method call, will contain the max waveform peaks.

nBufferLength

Length in bytes of the given buffers previously obtained through the Waveform.PeaksBufferLengthGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful

Samples

Below you can find a couple of samples that demonstrate how to load waveform peaks in Visual Basic 6 and Visual C++ 6.

Visual Basic 6

' memory buffers must be declared as global variables

Dim m_bufferMin() As Integer

Dim m_bufferMax() As Integer

Private Sub Command1_Click()

 Erase m_bufferMin

 Erase m_bufferMax

 ' get the size in bytes of the buffers

 Dim nBufferLength As Long

 Amp3dj1.Waveform.PeaksBufferLengthGet 0, nStartPosInMs, nEndPosInMs, nBufferLength

 ReDim m_bufferMin(nBufferLength/2)

 ReDim m_bufferMax(nBufferLength/2)

 ' fill the buffers with peaks data

 Amp3dj1.Waveform.PeaksBufferGet 0, 0, nStartPosInMs, nEndPosInMs, BOOL_TRUE, VarPtr(m_bufferMin(0)), VarPtr(m_bufferMax(0)), nBufferLength

End Sub

Visual C++ 6 with MFC

// memory buffers must be declared as global variables

short *m_bufferMin = NULL;

short *m_bufferMax = NULL;

void CMyDialog::OnButton1()

{

 if (m_bufferMin != NULL)

   delete m_bufferMin;

 if (m_bufferMax != NULL)

   delete m_bufferMax;

 // get the size in bytes of the buffers

 long nBufferLength;

 m_ctrlActiveDJ.GetWaveform().PeaksBufferLengthGet (0, nStartPosInMs, nEndPosInMs, nBufferLength);

 m_bufferMin = new short[nBufferLength/2];

 m_bufferMax = new short[nBufferLength/2];

 // fill the buffers with peaks data

 Amp3dj1.GetWaveform().PeaksBufferGet (0, 0, nStartPosInMs, nEndPosInMs, TRUE, m_bufferMin, m_bufferMax, nBufferLength);

}


Waveform.PeaksBufferLengthGet method

Waveform.PeaksBufferLengthGet method

Remarks

Given a range in milliseconds, obtains the size in bytes required by the buffer in order to store related waveform peaks. Once the size is known, you may allocate a buffer to pass to the Waveform.PeaksBufferGet method.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the Waveform.AnalyzeFullSound method and waiting its completion through the WaveAnalysisDone event.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.PeaksBufferLengthGet (

nPlayer as Integer,

nStartPos as Long,

nEndPos as Long,

nBufferLength as Long

) as enumErrorCodes

[C++]

short control.Waveform.PeaksBufferLengthGet (

short nPlayer,

long nStartPos,

long nEndPos,

long nBufferLength

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
nStartPos | Number representing the start position, expressed in milliseconds, where we want to get waveform's peaks. The value 0 represents the sound's beginning.
nEndPos | Number representing the end position, expressed in milliseconds, where we want to get waveform's peaks. The value -1 represents the sound's end.
nBufferLength | Reference that, on return from the method call, will contain the size in bytes needed for storing requested peaks into a buffer.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.PeaksLoad method

Waveform.PeaksLoad method

Remarks

Loads the analyzed sound's peaks from a file of type PKW generated by a previous call to the Waveform.PeaksSave method: this avoids the need to perform a new time consuming full analysis of the sound's waveform for a sound file whose contents have not been changed.

In case the peaks file should be available inside a memory buffer, it could be loaded through the Waveform.PeaksLoadFromMemory method.

This method will generate the same WaveAnalysisStart and WaveAnalysisDone events as seen when calling the Waveform.AnalyzeFullSound method.

For further details about using the embedded Waveform refer to the Waveform object section.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.PeaksLoad (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.Waveform.PeaksLoad (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
strPathname | Absolute pathname of the source file, usually with .PKW extension. If this pathname should be left empty, the control would automatically search the file inside the same path of the analyzed sound file changing the extension of the file name in .PKW. If for example the loaded sound file should be named MySong.mp3, the corresponding searched PKW file would be MySong.pkw

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.PeaksLoadFromMemory method

Waveform.PeaksLoadFromMemory method

Remarks

Loads the analyzed sound's peaks from a file of type PKW generated by a previous call to the Waveform.PeaksSave method and stored into a memory buffer: this avoids the need to perform a new time consuming full analysis of the sound's waveform for a sound file whose contents have not been changed.

This method will generate the same WaveAnalysisStart and WaveAnalysisDone events as seen when calling the Waveform.AnalyzeFullSound method.

For further details about using the embedded Waveform refer to the Waveform object section.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.PeaksLoadFromMemory (

nPlayer as Integer,

pBuffer as Variant,

nBufferLen as Long

) as enumErrorCodes

[C++]

short control.Waveform.PeaksLoadFromMemory (

short nPlayer,

const VARIANT FAR& pBuffer,

long nBufferLen

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the waveform
pBuffer | Variant parameter containing the pointer to waveform peaks previously loaded in memory.
nBufferLen | Length in bytes of the given buffer

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.PeaksSave method

Waveform.PeaksSave method

Remarks

Saves the analyzed sound's peaks into a file of type PKW: storing peaks inside a file, which will be accessible through a call to the Waveform.PeaksLoad method, avoids the need to perform a new time consuming full analysis of the sound's waveform for a sound file whose contents have not been changed.

For further details about using the embedded Waveform refer to the Waveform object section.

For further details about generating a waveform bitmap of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

control.Waveform.PeaksSave (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.Waveform.PeaksSave (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
strPathname | Absolute pathname of the destination file, usually with .PKW extension. If this pathname should be left empty, the control would automatically save peaks into the same path of the loaded and analyzed sound file changing the extension of the file name in .PKW. If for example the loaded sound file should be named MySong.mp3, the corresponding PKW file would be named MySong.pkw

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.Resize method

Waveform.Resize method

Remarks

Resizes the embedded Waveform, useful when a resize of the hosting window occurs. This method has no effect without a previous call to the Waveform.Create method.

For further details about using the embedded Waveform refer to the Waveform object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Waveform.Resize (

nPlayer as Integer,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.Waveform.Resize (

short nPlayer,

long nWidth,

long nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
nWidth | New width of the Waveform expressed in pixels
nHeight | New height of the Waveform expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.SetBackPictureFromFile method

Waveform.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the embedded Waveform refer to the Waveform object section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Waveform.SetBackPictureFromFile (

nPlayer as Integer,

strPathname as String

) as enumErrorCodes

[C++]

short control.Waveform.SetBackPictureFromFile (

short nPlayer,

LPCTSTR strPathname

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
strPathname | Absolute pathname of the picture file to load. Accepted graphic formats are BMP, JPEG, GIF, TIFF and PNG. An empty pathname will reset an eventual picture set through a previous call to this method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.SetBackPictureFromHandle method

Waveform.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle (HBITMAP).

For further details about using the embedded Waveform refer to the Waveform object section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Waveform.SetBackPictureFromHandle (

nPlayer as Integer,

hBitmap as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Waveform.SetBackPictureFromHandle (

short nPlayer,

OLE_HANDLE hBitmap

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
hBitmap | Handle of the bitmap to apply. If this parameter is set to 0 an eventual picture set through a previous call to this method will be reset.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.SetHwnd method

Waveform.SetHwnd method

Remarks

Changes the HWND of the window used as a surface for the graphic rendering.

For further details about using the embedded Waveform refer to the Waveform object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Waveform.SetHwnd (

nPlayer as Integer,

hWndTarget as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.Waveform.SetHwnd (

short nPlayer,

OLE_HANDLE hWndTarget

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the Waveform
hWndTarget | Handle of the window whose surface will be used in order to render the Waveform graphics.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


Waveform.Show method

Waveform.Show method

Remarks

Shows/hides the embedded Waveform. This method has no effect without a previous call to the Waveform.Create method.

For further details about using the embedded Waveform refer to the Waveform object section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

control.Waveform.Show (

nPlayer as Integer,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.Waveform.Show (

short nPlayer,

short bShow

);

Parameter

Description

nPlayer

Number representing the zero-based index of the player that will use the Waveform

bShow

Boolean value that specifies to the player if it must show/hide the Waveform.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Hides the Waveform graphics
BOOL_TRUE | 1 | Shows the Waveform graphics

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller object

WaveformScroller object

The WaveformScroller object, accessible through the control's WaveformScroller property, is internally implemented as a COM interface called IWaveformScroller and contains information needed to render a waveform that will scroll during playback.

It can be used at Run-time in order to create a waveform scroller and to change its graphical settings. For details about using waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

The WaveformScroller object is implemented through the following methods:

Methods

Create

Destroy

GetViewLength

Move

PlaybackOnScrollEnable

PlaybackOnScrollInfoGet

Refresh

SetBackPictureFromFile

SetBackPictureFromHandle

SetCursor

SettingsGet

SettingsSet

SettingsParamGet

SettingsParamSet

SetViewLength

Show

Data structures

WSCROLLER_SETTINGS

Samples of use of the WaveformScroller object in Visual C++ 6 and Visual Basic 6 can be found inside the following samples installed with the product's setup package:

- WaveformScroll


WaveformScroller.Create method

WaveformScroller.Create method

Remarks

Creates a new instance of the WaveformScroller object for the given player on the given parent window.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.Create (

nPlayer as Integer,

hWndParent as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as OLE_HANDLE

[C++]

OLE_HANDLE control.WaveformScroller.Create (

short nPlayer,

OLE_HANDLE hWndParent,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will use the waveform scroller
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Other values | Handle (HWND) of the new waveform scroller


WaveformScroller.Destroy method

WaveformScroller.Destroy method

Remarks

Destroys an existing waveform scroller control.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.Destroy (

hWndWaveformScroller as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.WaveformScroller.Destroy (

OLE_HANDLE hWndWaveformScroller

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.GetViewLength method

WaveformScroller.GetViewLength method

Remarks

Obtains the current length of the waveform scroller's view in terms of displayed milliseconds. The view length can be modified through the WaveformScroller.SetViewLength method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.GetViewLength (

hWndWaveformScroller as OLE_HANDLE,

nLengthInMs as Long

) as enumErrorCodes

[C++]

short control.WaveformScroller.GetViewLength (

OLE_HANDLE hWndWaveformScroller,

long *nLengthInMs

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
nLengthInMs | Reference that, on return from the method call, will contain the length of the view expressed in milliseconds.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.Move method

WaveformScroller.Move method

Remarks

Moves or resizes an existing waveform scroller control.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.Move (

hWndWaveformScroller as OLE_HANDLE,

nLeft as Long,

nTop as Long,

nWidth as Long,

nHeight as Long

) as enumErrorCodes

[C++]

short control.WaveformScroller.Move (

OLE_HANDLE hWndWaveformScroller,

long nLeft,

long nTop,

long nWidth,

long nHeight

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
nLeft | Left position of the window, expressed in parent's client coordinates (pixels)
nTop | Top position of the window, expressed in parent's client coordinates (pixels)
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.PlaybackOnScrollEnable method

WaveformScroller.PlaybackOnScrollEnable method

Remarks

Enables/disables playback of audio data during the manual scroll of the waveform through the mouse.

Current settings can be obtained through the WaveformScroller.PlaybackOnScrollInfoGet method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.PlaybackOnScrollEnable (

hWndWaveformScroller as OLE_HANDLE,

bEnable as enumBoolean,

nScrollSensitivity as Long

) as enumErrorCodes

[C++]

short control.WaveformScroller.PlaybackOnScrollEnable (

OLE_HANDLE hWndWaveformScroller,

short bEnable,

long nScrollSensitivity

);

Parameter

Description

hWndWaveformScroller

Handle of the control returned by a previous call to the WaveformScroller.Create method

bEnable

Boolean value that specifies if playback is enabled or disabled.

Supported values are the following:

Value | Meaning
BOOL_FALSE (default) | Playback is disabled
BOOL_TRUE | Playback is enabled

nScrollSensitivity

Scroll sensitivity expressed in percentage.

Default value is 100, meaning that audio data will be played at the same rate of the waveform scrolling during mouse movement: values lower than 100 will decrease the speed of playback while values higher than 100 will increase the speed of playback.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.PlaybackOnScrollInfoGet method

WaveformScroller.PlaybackOnScrollInfoGet method

Remarks

Obtains information about playback's support during the manual scroll of the waveform through the mouse.

Current settings can be modified through the WaveformScroller.PlaybackOnScrollEnable method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.PlaybackOnScrollInfoGet (

hWndWaveformScroller as OLE_HANDLE,

bEnable as enumBoolean,

nScrollSensitivity as Long

) as enumErrorCodes

[C++]

short control.WaveformScroller.PlaybackOnScrollInfoGet (

OLE_HANDLE hWndWaveformScroller,

short *bEnable,

long *nScrollSensitivity

);

Parameter

Description

hWndWaveformScroller

Handle of the control returned by a previous call to the WaveformScroller.Create method

bEnable

Reference that, on return from the method call, will contain the boolean value that specifies if playback is enabled or disabled.

Supported values are the following:

Value | Meaning
BOOL_FALSE (default) | Playback is disabled
BOOL_TRUE | Playback is enabled

nScrollSensitivity

Reference that, on return from the method call, will contain the scroll sensitivity expressed in percentage.

Default value is 100, meaning that audio data will be played at the same rate of the waveform scrolling during mouse movement: values lower than 100 will decrease the speed of playback while values higher than 100 will increase the speed of playback.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.Refresh method

WaveformScroller.Refresh method

Remarks

Refreshes an existing waveform scroller control.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.Refresh (

hWndWaveformScroller as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.WaveformScroller.Refresh (

OLE_HANDLE hWndWaveformScroller

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.SetBackPictureFromFile method

WaveformScroller.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.SetBackPictureFromFile (

hWndWaveformScroller as OLE_HANDLE,

strPathname as String,

nMode as enumBitmapModes

) as enumErrorCodes

[C++]

short control.WaveformScroller.SetBackPictureFromFile (

OLE_HANDLE hWndWaveformScroller,

LPCTSTR strPathname,

short nMode

);

Parameter

Description

hWndWaveformScroller

Handle of the control returned by a previous call to the WaveformScroller.Create method

strPathname

Absolute pathname of the picture file to load. Accepted graphic formats are BMP, JPEG, GIF, TIFF and PNG.

An empty pathname will reset an eventual picture set through a previous call to this method.

nMode

Bitmap mode.

Supported values are the following:

Mnemonic constant | Value | Meaning
BITMAP_MODE_TOP_LEFT | 0 | Bitmap will be drawn in top-left position on the destination rectangle
BITMAP_MODE_CENTER | 1 | Bitmap will be drawn in centered position on the destination rectangle
BITMAP_MODE_STRETCH | 2 | Bitmap will be stretched in order to fit the destination rectangle
BITMAP_MODE_TILE | 3 | Bitmap will be tiled in order to fill the destination rectangle

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.SetBackPictureFromHandle method

WaveformScroller.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.SetBackPictureFromHandle (

hWndWaveformScroller as OLE_HANDLE,

hBitmap as OLE_HANDLE,

nMode as enumBitmapModes

) as enumErrorCodes

[C++]

short control.WaveformScroller.SetBackPictureFromHandle (

OLE_HANDLE hWndWaveformScroller,

OLE_HANDLE hBitmap,

short nMode

);

Parameter

Description

hWndWaveformScroller

Handle of the control returned by a previous call to the WaveformScroller.Create method

hBitmap

Handle (HBITMAP) of the bitmap to apply. If this parameter is set to 0 an eventual picture set through a previous call to this method will be reset.

nMode

Bitmap mode.

Supported values are the following:

Mnemonic constant | Value | Meaning
BITMAP_MODE_TOP_LEFT | 0 | Bitmap will be drawn in top-left position on the destination rectangle
BITMAP_MODE_CENTER | 1 | Bitmap will be drawn in centered position on the destination rectangle
BITMAP_MODE_STRETCH | 2 | Bitmap will be stretched in order to fit the destination rectangle
BITMAP_MODE_TILE | 3 | Bitmap will be tiled in order to fill the destination rectangle

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.SetCursor method

WaveformScroller.SetCursor method

Remarks

Sets the cursor to display, from an existing cursor handle (HCURSOR), when the mouse hovers the control's area.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.SetCursor (

hWndWaveformScroller as OLE_HANDLE,

hCursor as OLE_HANDLE

) as enumErrorCodes

[C++]

short control.WaveformScroller.SetCursor (

OLE_HANDLE hWndWaveformScroller,

OLE_HANDLE hCursor

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
hCursor | Handle of the cursor to apply. If this parameter is set to 0 an eventual cursor set through a previous call to this method will be reset.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.SettingsGet method

WaveformScroller.SettingsGet method

Remarks

Retrieves the current graphical settings for the given waveform scroller. Settings can be modified through the WaveformScroller.SettingsSet method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.SettingsGet (

hWndWaveformScroller as IntPtr,

ByRef settings as Long

) as enumErrorCodes

[C++]

short control.WaveformScroller.SettingsGet (

IntPtr hWndWaveformScroller,

void *settings

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
settings | Address of a structure of type WSCROLLER_SETTINGS that, on return from the method call, will contain the waveform scroller current settings.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


WaveformScroller.SettingsSet method

WaveformScroller.SettingsSet method

Remarks

Modifies the graphical settings for the given graphic bar. Current settings can be obtained through the WaveformScroller.SettingsGet method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.SettingsSet (

hWndWaveformScroller as IntPtr,

settings as Long

) as enumErrorCodes

[C++]

short control.WaveformScroller.SettingsSet (

IntPtr hWndWaveformScroller,

void *settings

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
settings | Address of a structure of type WSCROLLER_SETTINGS containing the waveform scroller new settings.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


WaveformScroller.SettingsParamGet method

WaveformScroller.SettingsParamGet method

Remarks

Retrieves one of the current graphical settings for the given waveform scroller. Single settings can be modified through the WaveformScroller.SettingsParamSet method.

This method is an alternative to the WaveformScroller.SettingsGet method and it's provided with the purpose of allowing single settings retrieval when dealing with languages like JavaScript where data structures are not easy to implement.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.SettingsParamGet (

hWndWaveformScroller as OLE_HANDLE,

nParam as short

) as String

[C++]

BSTR control.WaveformScroller.SettingsParamGet (

OLE_HANDLE hWndWaveformScroller,

short nParam

);

Parameter

Description

hWndWaveformScroller

Handle of the control returned by a previous call to the WaveformScroller.Create method

nParam

Numeric identifier of the requested parameter.

Supported values are the following:

Numeric value | Meaning
0 | nStereoVisualizationMode field of the WSCROLLER_SETTINGS data structure
1 | colorWaveLinePeak field of the WSCROLLER_SETTINGS data structure
2 | colorWaveLineCenter field of the WSCROLLER_SETTINGS data structure
3 | nWaveLineIntensityFactor field of the WSCROLLER_SETTINGS data structure
4 | colorWaveBackground field of the WSCROLLER_SETTINGS data structure
5 | bUseHalfColorsForPeaks field of the WSCROLLER_SETTINGS data structure
6 | bAppearance3d field of the WSCROLLER_SETTINGS data structure
7 | colorPositionLine field of the WSCROLLER_SETTINGS data structure
8 | colorBorder field of the WSCROLLER_SETTINGS data structure
9 | bPositionLineShow field of the WSCROLLER_SETTINGS data structure
10 | nPositionLineDashStyle field of the WSCROLLER_SETTINGS data structure
11 | nPositionLineWidth field of the WSCROLLER_SETTINGS data structure
12 | nPositionLineHighCap field of the WSCROLLER_SETTINGS data structure
13 | nPositionLineLowCap field of the WSCROLLER_SETTINGS data structure
14 | nPositionLineDashCap field of the WSCROLLER_SETTINGS data structure
15 | nPositionLineTranspFactor field of the WSCROLLER_SETTINGS data structure
16 | nGraphicItemsMask field of the WSCROLLER_SETTINGS data structure
17 | nUpdateSpeed field of the WSCROLLER_SETTINGS data structure
18 | fVerticalZoomFactor field of the WSCROLLER_SETTINGS data structure

Return value

Value | Meaning
Empty string | An error occurred: see the LastError property for further error details or for a list of the possible error values.
Valid string | String containing the value of the requested parameter.


WaveformScroller.SettingsParamSet method

WaveformScroller.SettingsParamSet method

Remarks

Sets one of the graphical settings for the given waveform scroller. Value of single settings can be obtained through the WaveformScroller.SettingsParamGet method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.SettingsParamSet (

hWndWaveformScroller as OLE_HANDLE,

pParamData as Long,

strValue as String

) as enumErrorCodes

[C++]

short control.WaveformScroller.SettingsParamSet (

OLE_HANDLE hWndWaveformScroller,

void *pParamData,

LPCTSTR strValue

);

Parameter

Description

hWndWaveformScroller

Handle of the control returned by a previous call to the WaveformScroller.Create method

nParam

Numeric identifier of the requested parameter.

Supported values are the following:

Numeric value | Meaning
0 | nStereoVisualizationMode field of the WSCROLLER_SETTINGS data structure
1 | colorWaveLinePeak field of the WSCROLLER_SETTINGS data structure
2 | colorWaveLineCenter field of the WSCROLLER_SETTINGS data structure
3 | nWaveLineIntensityFactor field of the WSCROLLER_SETTINGS data structure
4 | colorWaveBackground field of the WSCROLLER_SETTINGS data structure
5 | bUseHalfColorsForPeaks field of the WSCROLLER_SETTINGS data structure
6 | bAppearance3d field of the WSCROLLER_SETTINGS data structure
7 | colorPositionLine field of the WSCROLLER_SETTINGS data structure
8 | colorBorder field of the WSCROLLER_SETTINGS data structure
9 | bPositionLineShow field of the WSCROLLER_SETTINGS data structure
10 | nPositionLineDashStyle field of the WSCROLLER_SETTINGS data structure
11 | nPositionLineWidth field of the WSCROLLER_SETTINGS data structure
12 | nPositionLineHighCap field of the WSCROLLER_SETTINGS data structure
13 | nPositionLineLowCap field of the WSCROLLER_SETTINGS data structure
14 | nPositionLineDashCap field of the WSCROLLER_SETTINGS data structure
15 | nPositionLineTranspFactor field of the WSCROLLER_SETTINGS data structure
16 | nGraphicItemsMask field of the WSCROLLER_SETTINGS data structure
17 | nUpdateSpeed field of the WSCROLLER_SETTINGS data structure
18 | fVerticalZoomFactor field of the WSCROLLER_SETTINGS data structure

strValue

String representing the numerical value to set: the multimedia engine will manage converting the string into the corresponding numerical value.

Return value

Value | Meaning
enumErrorCodes.NOERROR (0) | The call was successful.
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


WaveformScroller.SetViewLength method

WaveformScroller.SetViewLength method

Remarks

Sets the length of the waveform scroller's view in terms of displayed milliseconds. The current length of the view can be obtained through the WaveformScroller.GetViewLength method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.SetViewLength (

hWndWaveformScroller as OLE_HANDLE,

nLengthInMs as Long

) as enumErrorCodes

[C++]

short control.WaveformScroller.SetViewLength (

OLE_HANDLE hWndWaveformScroller,

long nLengthInMs

);

Parameter

Description

hWndWaveformScroller

Handle of the control returned by a previous call to the WaveformScroller.Create method

nLengthInMs

Length of the view in milliseconds; by default this value is set to 10000, meaning that the waveform scroller will display 10 seconds of sound.

This value must be big enough to guarantee that one pixel on the view is provided for each millisecond of sound: if the provided value should be smaller, the component would automatically adapt it and the updated length in milliseconds could be verified through the WaveformScroller.GetViewLength method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformScroller.Show method

WaveformScroller.Show method

Remarks

Shows/hides an existing waveform scroller control.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

control.WaveformScroller.Show (

hWndWaveformScroller as OLE_HANDLE,

bShow as enumBoolean

) as enumErrorCodes

[C++]

short control.WaveformScroller.Show (

OLE_HANDLE hWndWaveformScroller,

short bShow

);

Parameter

Description

hWndWaveformScroller

Handle of the control returned by a previous call to the WaveformScroller.Create method

bShow

Boolean value that specifies if it must show/hide the given graphic bar control.

Supported values are the following:

Value | Meaning
BOOL_FALSE | Hides the graphic bar window
BOOL_TRUE | Shows the graphic bar window

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WSCROLLER_SETTINGS stucture

WSCROLLER_SETTINGS structure

The WSCROLLER_SETTINGS data structure describes the graphical settings applied to a specific waveform scroller. Graphical settings related to a specific waveform scroller can be retrieved and modified through the WaveformScroller.SettingsGet and WaveformScroller.SettingsSet methods.

For further details about methods of the Waveform scroller refer to the WaveformScroller class.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Visual C++ definition

typedef struct

{

     long nStereoVisualizationMode;

     OLE_COLOR colorWaveLinePeak;

     OLE_COLOR colorWaveLineCenter;

     short nWaveLineIntensityFactor;

     OLE_COLOR colorWaveBackground;

     short bUseHalfColorsForPeaks;

     short bAppearance3d;

     OLE_COLOR colorPositionLine;

     OLE_COLOR colorBorder;

     short bPositionLineShow;

     long nPositionLineDashStyle;

     short nPositionLineWidth;

     long nPositionLineHighCap;

     long nPositionLineLowCap;

     long nPositionLineDashCap;

     short nPositionLineTranspFactor;

     long nGraphicItemsMask;

     long nUpdateSpeed;

     float fVerticalZoomFactor;

} WSCROLLER_SETTINGS;

Visual Basic definition

Public Type WSCROLLER_SETTINGS

    nStereoVisualizationMode as enumWaveformStereoModes

    colorWaveLinePeak as OLE_COLOR

    colorWaveLineCenter as OLE_COLOR

    nWaveLineIntensityFactor as Integer

    colorWaveBackground as OLE_COLOR

    bUseHalfColorsForPeaks as Boolean

    bAppearance3d as Boolean

    colorPositionLine as OLE_COLOR

    colorBorder as OLE_COLOR

    bPositionLineShow as Boolean

    nPositionLineDashStyle as enumWaveformLineDashStyles

    nPositionLineWidth as Integer

    nPositionLineHighCap as enumLineCaps

    nPositionLineLowCap as enumLineCaps

    nPositionLineDashCap as enumLineDashCaps

    nPositionLineTranspFactor as Integer

    nGraphicItemsMask as enumGraphicItemMaskValues

    nUpdateSpeed as enumWaveScrollerAutoUpdate

    fVerticalZoomFactor as Single

End Type

Member

Description

nStereoVisualizationMode

Visualization mode used for displaying stereo sounds

Supported values are the following:

Mnemonic constant | Value | Meaning
STEREO_MODE_CHANNELS_BOTH | 0 | Right and left channels are displayed separately .
STEREO_MODE_CHANNELS_LEFT | 1 | Only the left channel content is displayed on
STEREO_MODE_CHANNELS_RIGHT | 2 | Only the right channel content is displayed
STEREO_MODE_CHANNELS_MIXED (default) | 3 | Right and left channels contents are mixed together

colorWaveLinePeak

Color used for rendering peaks of the waveform line. See screenshot above.

colorWaveLineCenter

Color used for rendering the center of the waveform line. See screenshot above.

nWaveLineIntensityFactor

Factor of gradient intensity of the waveform line.

This value can range from 0 to 100 with a default value of 50. Values outside of this range will be automatically capped to the nearest valid value.

On the screenshot below you can appreciate the difference between the default value 50 (on the left) and a value of 20 (on the right):

colorWaveBackground

The color used to render the waveform background (default is set to Black). See screenshot above.

bUseHalfColorsForPeaks

Boolean value that specifies if waveform peaks will have a half intensity color.

This field is ignored when colors set into the colorWaveLinePeak and colorWaveLineCenter fields are different.

Supported values are the following:

Value | Meaning
False | Don't use half color for drawing waveform peaks
True (default) | Use half color for drawing waveform peaks

bAppearance3d

Boolean value that specifies if the waveform scroller is displayed with 3D borders.

Supported values are the following:

Value | Meaning
False | Doesn't display 3D borders
True (default) | Displays 3D borders

colorPositionLine

The color used to render the central playback position line (default is set to White). See screenshot above.

colorBorder

The color used to render the border (only when the bAppearance3d parameter is set to False) (default is set to Black)

bPositionLineShow

Boolean value that specifies if the central playback position line must be shown or hidden.

Supported values are the following:

Value | Meaning
False | Hides the playback position line
True (default) | Shows the playback position line

nPositionLineDashStyle

Dash style of the line that indicates a selected position on the waveform.

Supported values are the following:

Mnemonic constant | Value | Meaning
LINE_DASH_STYLE_SOLID | 0 | Solid line.
LINE_DASH_STYLE_DASH | 1 | Dashed line.
LINE_DASH_STYLE_DOT | 2 | Dotted line.
LINE_DASH_STYLE_DASH_DOT | 3 | Alternating dash-dot line line.
LINE_DASH_STYLE_DASH_DOT_DOT | 4 | Alternating dash-dot-dot line line.

nPositionLineWidth

Width in pixels of the position line.

nPositionLineHighCap

Type of cap for the high end of the position line.

Supported values are the following:

Mnemonic constant | Value | Meaning
LINE_CAP_SQUARE | 0 | Specifies a square cap.
LINE_CAP_ROUND | 1 | Specifies a circular cap.
LINE_CAP_TRIANGLE | 2 | Specifies a triangular cap.
LINE_CAP_SQUARE_ANCHOR | 3 | Specifies that the line ends are anchored with a square.
LINE_CAP_ROUND_ANCHOR | 4 | Specifies that the line ends are anchored with a circle.
LINE_CAP_DIAMOND_ANCHOR | 5 | Specifies that the line ends are anchored with a diamond.
LINE_CAP_ARROW_ANCHOR | 6 | Specifies that the line ends are anchored with arrowheads.

nPositionLineLowCap

Type of cap for the low end of the position line.

Supported values are the same as seen for the nPositionLineHighCap field above.

nPositionLineDashCap

Type of dash/dot cap for the position line.

Supported values are the following:

Mnemonic constant | Value | Meaning
LINE_DASH_CAP_FLAT | 0 | Specifies a square cap that squares off both ends of each dash.
LINE_DASH_CAP_ROUND | 1 | Specifies a circular cap that rounds off both ends of each dash.
LINE_DASH_CAP_TRIANGLE | 2 | Specifies a triangular cap that points both ends of each dash.

nPositionLineTranspFactor

Transparent factor applied to the position line.

This value can range from 0 (total opacity) to 255 (total transparency). Values outside of this range will be automatically capped to the nearest valid value.

nGraphicItemsMask

Combination of values determining the mask of graphic items that must be drawn over the waveform scroller.

Supported values are the following:

Mnemonic constant | Value | Meaning
MASK_GRAPHIC_ITEM_NONE (default) | 0 | No graphic item is drawn
MASK_GRAPHIC_ITEM_VERTICAL_LINE | 1 | Draws vertical lines

nUpdateSpeed

Value that determines how much frequently the waveform is updated during playback. The higher the update speed, the higher the needed CPU amount.

Supported values are the following:

Mnemonic constant | Value | Meaning
WAVEFORMSCROLLER_UPDATE_ULTRA_FAST | 0 | .Update occurs every 15 milliseconds
WAVEFORMSCROLLER_UPDATE_VERY_FAST | 1 | .Update occurs every 30 milliseconds
WAVEFORMSCROLLER_UPDATE_FAST (default) | 2 | .Update occurs every 45 milliseconds
WAVEFORMSCROLLER_UPDATE_MIDDLE | 3 | .Update occurs every 60 milliseconds
WAVEFORMSCROLLER_UPDATE_SLOW | 4 | .Update occurs every 75 milliseconds
WAVEFORMSCROLLER_UPDATE_VERY_SLOW | 5 | .Update occurs every 90 milliseconds
WAVEFORMSCROLLER_UPDATE_ULTRA_SLOW | 6 | .Update occurs every 105 milliseconds

fVerticalZoomFactor

Factor applied to vertical zooming operations. can assume values ranging from 0.5 to 5. Values outside of this range will be automatically capped to the nearest valid value. The default value is set to 1.

- Values smaller than 1 will vertically zoom-out the waveform, reducing its vertical size

- Value 1 will display the waveform without zooming

- Values higher than 1 will vertically zoom-in the waveform, increasing its vertical size


ZIP object

ZIP object

The ZIP object, accessible through the control's ZIP property, allows managing archive files in ZIP format.

It can be used at Run-time in order to create, open and modify ZIP files. For details about using ZIP management refer to the How to manage ZIP files tutorial.

The ZIP object is implemented through the following methods:

Methods

Close

Create

EntriesCountGet

EntryAdd

EntryAddFromMemory

EntryExtractToFile

EntryExtractToMemory

EntryNameGet

EntryRemove

EntryUncompressedSizeGet

IsProtected

Open

Save

Samples of use of the ZIP object in Visual Basic 6 and Visual C++ 6 can be found inside the following samples installed with the product's setup package:

- ZipPlayer


ZIP.Close method

ZIP.Close method

Remarks

Closes a ZIP file session previously opened through the ZIP.Open method.

Without a previous call to the ZIP.Save method, a call to this method ignores and discards eventual modifications operated on the ZIP file.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.Close (

) as enumErrorCodes

[C++]

short control.ZIP.Close (

);

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.Create method

ZIP.Create method

Remarks

Creates a brand new ZIP file session.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.Create (

strZipFilePathname as String,

nEncryptionType as enumZipEncryptionTypes,

strPassword as String,

bReplaceExisting as enumBoolean

) as enumErrorCodes

[C++]

short control.ZIP.Create (

LPCTSTR strZipFilePathname,

short nEncryptionType,

LPCTSTR strPassword,

short bReplaceExisting

);

Parameter

Description

strZipFilePathname

String representing the absolute pathname of the ZIP file to open.

nEncryptionType

The type of protection/encryption to apply.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
ZIP_ENCRYPT_NONE | 0 | No encryption is applied. The strPassword parameter below is ignored when this option is chosen.
ZIP_ENCRYPT_PWD_20 | 1 | ZIP 2.0 compatible (weak/portable)
ZIP_ENCRYPT_AES_128 | 2 | 128 bits AES encryption (strong)
ZIP_ENCRYPT_AES_192 | 3 | 192 bits AES encryption (strong)
ZIP_ENCRYPT_AES_256 | 4 | 256 bits AES encryption (stronger)

strPassword

String containing the optional password to set for future files extraction or adding operations; leave it empty if not needed.

bReplaceExisting

Boolean value that specifies if an eventual ZIP file having the same pathname should be replaced or simply opened.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Doesn't replace an eventual existing ZIP file, in which case the method call would have the same effect as the ZIP.Open method
BOOL_TRUE | 1 | Replaces an eventual existing ZIP file with a new empty one

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.EntriesCountGet method

ZIP.EntriesCountGet method

Remarks

Obtains the number of entries inside the ZIP file previously opened through the ZIP.Open method or created through the ZIP.Create method.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.EntriesCountGet (

nCount as Long

) as enumErrorCodes

[C++]

short control.ZIP.EntriesCountGet (

long *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the the number of entries.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.EntryAdd method

ZIP.EntryAdd method

Remarks

Adds one or more file entries to a ZIP file session previously opened through the ZIP.Open method or created through the ZIP.Create method.

This method only updates the ZIP session: to update or rewrite the ZIP file the ZIP.Save method would need to be called.

A successful call to this method will fire the ZipOperationStart event followed by a number of ZipOperationPerc events and finally by the ZipOperationDone event.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.EntryAdd (

strSourcePath as String,

bRecurseDirs as enumBoolean,

bAddExtraPath as enumBoolean

) as enumErrorCodes

[C++]

short control.ZIP.EntryAdd (

LPCTSTR strSourcePath,

short bRecurseDirs,

short bAddExtraPath

);

Parameter

Description

strSourcePath

String representing the absolute pathname of the file(s) or folder to add to the ZIP file.

It's allowed using the "*" and "?" wildcard characters where "*" means 0 or more of any character and "?" means any single character.

bRecurseDirs

Boolean flag determining if eventual sub-directories of the given path should be traversed and added to the directory tree.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | Eventual sub-directories are not traversed
BOOL_TRUE | 1 | Eventual sub-directories are traversed and contained files are added to the ZIP session

bAddExtraPath

Boolean flag determining if absolute path will be included in the zip entry filenames as relative paths.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The relative path of each zipped file is not added to the final entry name.
BOOL_TRUE | 1 | The relative path of each zipped file is added to the final entry name.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.EntryAddFromMemory method

ZIP.EntryAddFromMemory method

Remarks

Adds a new entry from a memory buffer to the ZIP file session previously opened through the ZIP.Open method or created through the ZIP.Create method.

This method only updates the ZIP session: to update or rewrite the ZIP file the ZIP.Save method would need to be called.

A successful call to this method will fire the ZipOperationStart event followed by a number of ZipOperationPerc events and finally by the ZipOperationDone event.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.EntryAddFromMemory (

strEntryName as String,

pBuffer as variant,

nBufferLength as Long

) as enumErrorCodes

[C++]

short control.ZIP.EntryAddFromMemory (

LPCTSTR strEntryName,

const VARIANT FAR& pBuffer,

long nBufferLength

);

Parameter | Description
strEntryName | String representing the name assigned to the entry when added to the ZIP file. Can be also a relative path.
pBuffer | Memory buffer containing data of the new entry
nBufferLength | Length of the memory buffer expressed in bytes

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.EntryExtractToFile method

ZIP.EntryExtractToFile method

Remarks

Extracts into a file on disk a specific entry available inside a ZIP file session previously opened through the ZIP.Open method or created through the ZIP.Create method.

A successful call to this method will fire the ZipOperationStart event followed by a number of ZipOperationPerc events and finally by the ZipOperationDone event.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.EntryExtractToFile (

strEntryName as String,

strPassword as String,

strDestPath as String,

bAddRelativePathToDest as enumBoolean

) as enumErrorCodes

[C++]

short control.ZIP.EntryExtractToFile (

LPCTSTR strEntryName,

LPCTSTR strPassword,

LPCTSTR strDestPath,

short bAddRelativePathToDest

);

Parameter

Description

strEntryName

String representing the name of the entry to extract.

strPassword

String containing the optional password for accessing the requested entry; leave it empty if not needed.

strDestPath

String representing the destination path on disk for the given entry

bAddRelativePathToDest

Boolean flag determining if the relative path of the given entry should be added to the destination path.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The relative path of the entry is not added. If for example the strEntryName parameter should be "first_dir/second_dir/myFile.mp3" and the strDestPath parameter should be "c:\myfolder", the final pathname of the extracted file would be "c:\myfolder\myFile.mp3"
BOOL_TRUE | 1 | The relative path of the entry is added. If for example the strEntryName parameter should be "first_dir/second_dir/myFile.mp3" and the strDestPath parameter should be "c:\myfolder", the final pathname of the extracted file would be "c:\myfolder\first_dir\second_dir\myFile.mp3"

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.EntryExtractToMemory method

ZIP.EntryExtractToMemory method

Remarks

Extracts into a memory buffer a specific entry available inside a ZIP file session previously opened through the ZIP.Open method or created through the ZIP.Create method.

A successful call to this method will fire the ZipOperationStart event followed by a number of ZipOperationPerc events and finally by the ZipOperationDone event.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.EntryExtractToMemory (

strEntryName as String,

strPassword as String,

pBuffer as variant,

nBufferLength as Long

) as enumErrorCodes

[C++]

short control.ZIP.EntryExtractToMemory (

LPCTSTR strEntryName,

LPCTSTR strPassword,

const VARIANT FAR& pBuffer,

long nBufferLength

);

Parameter | Description
strEntryName | String representing the name of the entry to extract.
strPassword | String containing the optional password for accessing the requested entry; leave it empty if not needed.
pBuffer | Destination memory buffer where data of the entry are stored
nBufferLength | Length of the memory buffer expressed in bytes. The exact size in bytes required for storing the requested uncompressed entry can be determined through a previous call to the ZIP.EntryUncompressedSizeGet method

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.EntryNameGet method

ZIP.EntryNameGet method

Remarks

Obtains the name of a specific entry inside the ZIP file previously opened through the ZIP.Open method or created through the ZIP.Create method.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.EntryNameGet (

nEntryIndex as Long,

bIsDirectory as enumBoolean

) as string

[C++]

short control.ZIP.EntryNameGet (

long nEntryIndex,

long *bIsDirectory

);

Parameter

Description

nEntryIndex

Number representing the zero-based index of the entry. The total number of entries available inside the ZIP file can be obtained through the ZIP.EntriesCountGet method.

bIsDirectory

Reference that, on return from the method call, will specify if the requested entry is a file or a directory.

Supported values are the following:

Mnemonic constant | Value | Meaning
BOOL_FALSE | 0 | The requested entry is a file
BOOL_TRUE | 1 | The requested entry is a directory

Return value

Value | Meaning
Empty string | The value of the nEntryIndex parameter was out of range. Use the value returned by the ZIP.EntriesCountGet method in order to know how many entries are effectively available inside the ZIP file.
Valid string | The string containing the name of the requested entry.


ZIP.EntryRemove method

ZIP.EntryRemove method

Remarks

Removes a specific entry from the ZIP file session.

This method only updates the ZIP session: to update or rewrite the ZIP file the ZIP.Save method would need to be called.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.EntryRemove (

nEntryIndex as Long

) as enumErrorCodes

[C++]

short control.ZIP.EntryRemove (

long nEntryIndex

);

Parameter | Description
nEntryIndex | Number representing the zero-based index of the entry to remove. The total number of entries available inside the ZIP file can be obtained through the ZIP.EntriesCountGet method.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.EntryUncompressedSizeGet method

ZIP.EntryUncompressedSizeGet method

Remarks

Obtains the uncompressed size of a specific entry available inside a ZIP file session previously opened through the ZIP.Open method or created through the ZIP.Create method.

This method should be invoked before using the ZIP.EntryExtractToMemory method in order to understand the exact size of the buffer needed for storing the entry.

As a second feature, this method allows understanding if an entry with a specific name already exists.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.EntryExtractToMemory (

strEntryName as String,

nSize as Long

) as enumErrorCodes

[C++]

short control.ZIP.EntryUncompressedSizeGet (

LPCTSTR strEntryName,

long *nSize

);

Parameter | Description
strEntryName | String representing the name of the entry of interest.
nSize | Reference that, on return from the method call, will contain the size, expressed in bytes, of the uncompressed entry.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.IsProtected method

ZIP.IsProtected method

Remarks

Checks if the ZIP file, previously opened through the ZIP.Open method, is protected through password or through AES encryption.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.IsProtected (

bHasPassword as enumBoolean,

bHasEncryption as enumBoolean

) as enumErrorCodes

[C++]

short control.ZIP.IsProtected (

long *bHasPassword,

long *bHasEncryption

);

Parameter | Description
bHasPassword | Reference that, on return from the method call, will contain a boolean value specifying if the file is password protected
bHasEncryption | Reference that, on return from the method call, will contain a boolean value specifying if the file is protected through AES encryption

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


ZIP.Open method

ZIP.Open method

Remarks

Opens a ZIP file session. An opened ZIP session can be closed at a later time through the ZIP.Close method.

A call to this method is mandatory in order to extract or add entries from or to the ZIP file.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.Open (

strZipFilePathname as String,

strPassword as String

) as enumErrorCodes

[C++]

short control.ZIP.Open (

LPCTSTR strZipFilePathname,

LPCTSTR strPassword

);

Parameter | Description
strZipFilePathname | String representing the absolute pathname of the ZIP file to open.
strPassword | String containing the optional password to set for future files extraction or adding operations; leave it empty if not needed.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


ZIP.Save method

ZIP.Save method

Remarks

Saves a ZIP file session previously opened through the ZIP.Open or ZIP.Create methods.

For further details about methods for ZIP management refer to the ZIP object.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

control.ZIP.Save (

) as enumErrorCodes

[C++]

short control.ZIP.Save (

);

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


APPENDIX A - ID3 GENRES LIST

APPENDIX A - ID3 GENRES LIST

Here follows the table of the supported values of the genre field for MP3 Tag version 1.x with the corresponding descriptive string.

0 - Blues

1 - Classic Rock

2 - Country

3 - Dance

4 - Disco

5 - Funk

6 - Grunge

7 - Hip-Hop

8 - Jazz

9 - Metal

10 - New Age

11 - Oldies

12 - Other

13 - Pop

14 - R&B

15 - Rap

16 - Reggae

17 - Rock

18 - Techno

19 - Industrial

20 - Alternative

21 - Ska

22 - Death Metal

23 - Pranks

24 - Soundtrack

25 - Euro-Techno

26 - Ambient

27 - Trip-Hop

28 - Vocal

29 - Jazz+Funk

30 - Fusion

31 - Trance

32 - Classical

33 - Instrumental

34 - Acid

35 - House

36 - Game

37 - Sound Clip

38 - Gospel

39 - Noise

40 - Alternative Rock

41 - Bass

42 - Soul

43 - Punk

44 - Space

45 - Meditative

46 - Instrumental Pop

47 - Instrumental Rock

48 - Ethnic

49 - Gothic

50 - Darkwave

51 - Techno-Industrial

52 - Electronic

53 - Pop-Folk

54 - Eurodance

55 - Dream

56 - Southern Rock

57 - Comedy

58 - Cult

59 - Gangsta

60 - Top 40

61 - Christian Rap

62 - Pop/Funk

63 - Jungle

64 - Native US

65 - Cabaret

66 - New Wave

67 - Psychadelic

68 - Rave

69 - Showtunes

70 - Trailer

71 - Lo-Fi

72 - Tribal

73 - Acid Punk

74 - Acid Jazz

75 - Polka

76 - Retro

77 - Musical

78 - Rock & Roll

79 - Hard Rock

80 - Folk

81 - Folk-Rock

82 - National Folk

83 - Swing

84 - Fast Fusion

85 - Bebob

86 - Latin

87 - Revival

88 - Celtic

89 - Bluegrass

90 - Avantgarde

91 - Gothic Rock

92 - Progressive Rock

93 - Psychedelic Rock

94 - Symphonic Rock

95 - Slow Rock

96 - Big Band

97 - Chorus

98 - Easy Listening

99 - Acoustic

100 - Humour

101 - Speech

102 - Chanson

103 - Opera

104 - Chamber Music

105 - Sonata

106 - Symphony

107 - Booty Bass

108 - Primus

109 - Porn Groove

110 - Satire

111 - Slow Jam

112 - Club

113 - Tango

114 - Samba

115 - Folklore

116 - Ballad

117 - Power Ballad

118 - Rhythmic Soul

119 - Freestyle

120 - Duet

121 - Punk Rock

122 - Drum Solo

123 - Acapella

124 - Euro-House

125 - Dance Hall

126 - Goa

127 - Drum & Bass

128 - Club - House

129 - Hardcore

130 - Terror

131 - Indie

132 - BritPop

133 - Negerpunk

134 - Polsk Punk

135 - Beat

136 - Christian Gangsta Rap

137 - Heavy Metal

138 - Black Metal

139 - Crossover

140 - Contemporary Christian

141 - Christian Rock

142 - Merengue

143 - Salsa

144 - Thrash Metal

145 - Anime

146 - JPop

147 - Synthpop

148 and further - Unknown


APPENDIX B - Guidelines for DirectShow configuration through K-Lite

APPENDIX B - Guidelines for DirectShow configuration through K-Lite

 Return to chapter overview

As already mentioned inside the How to play video files through DirectShow tutorial, DirectShow includes by default a limited number of filters for decoding some common media file formats such as MPEG-1, MP3, Windows Media Audio, Windows Media Video, MIDI, media containers such as AVI, ASF, WAV, some splitters/demultiplexers, multiplexers, source and sink filters and some static image filters. However, DirectShow's standard format repertoire can be easily expanded by means of a variety of commercial and open source third-party filters. Such filters enable DirectShow to support virtually any container format and any audio or video codec.

One of the best packages containing most audio and video codecs for DirectShow is the K-Lite Codec Pack, a free collection of DirectShow filters, VFW/ACM codecs and tools available in both x86 and x64 versions. This package is updated quite frequently and really well supported and maintained. It can be downloaded for free from the following link.

Once installed, you can configure most aspects of DirectShow through a set of powerful but easy to use configuration tools. by default, the installation will create a menu item under the sequence "Start/All programs/K-Lite Codec Pack" (this sequence is for the English versions of Windows so it could look a bit different when using other languages); under this menu item you will find the following sub-items:

· Media Player Classic: this is a multimedia application and a valid open source alternative to Microsoft's Windows Media Player
· Configuration: this sub-item is the starting point to configure DirectShow codecs installed by K-Lite: this tutorial will most deal with it.
· Help: contains K-Lite documentation
· Tools: this sub-item contains a set of tools that can be useful when dealing with DirectShow.
· Uninstall: allows uninstalling K-Lite and all related codecs, filters and tools from the system

IMPORTANT NOTE ABOUT X86 AND X64 VERSIONS OF WINDOWS: K-Lite Codec Pack comes with both x86 and x64 versions of its codecs and configuration tools so, when running on a x64 version of Windows, it's very important being sure that the x64 version is installed and that the configuration is performed using the x64 version of the configuration tools. It's also important to note that the availability of the x86 version of K-Lite could be still needed in case the container application should be compiled specifically for "x86", as in the case of application compiled through Visual Basic 6, and run on a x64 version of Windows.

Configuration of video codecs

If FFDSHOW, a portion of the K-Lite Codec pack, is installed inside the system (you can know if FFDSHOW is installed by querying the VideoFiltersFfdShowIsAvailable method), the configuration of video codecs becomes probably the most important aspect of video playback because it allows deciding the transform filter used to decode and render the video stream of supported video formats; configuration can be managed in two ways:

· programmatically through the usage of the VideoFiltersFfdShowDecoderGet and VideoFiltersFfdShowDecoderSet methods.
· manually through the "ffdshow video decoder" tool installed by K-Lite: this tool can be launched through the Windows menu "Start/All programs/K-Lite Codec Pack/Configuration/ffdshow video decoder" and its user interface will appear like this:

As already mentioned, by default Windows comes with a set of codecs/decoders, mostly contained inside the Quartz.dll library installed by DirectShow or inside Windows Media components. When a video decoder is not available by default in Windows, ffdshow will try using its own decoder while, when a decoder for a certain format is already installed, the ffdshow decoder will result "disabled" as seen on the screenshot above for the MPEG1 and MPEG2 formats.

In order to enable the ffdshow decoder for a specific format, you will simply have to click the corresponding "Decoder" column on the format specific row and choose one of the available decoders installed by ffdshow as seen on the screenshot below for the MPEG2 format:

When dealing with Windows 7, it's strongly recommended that you set "libavcodec" decoder for both MPEG1 and MPEG2 formats. Windows 7 default decoders, like "MPEG VIDEO DECODER" for MPEG1 and "Microsoft DTV-DVD Video Decoder" for MPEG2, are not compatible with certain features of our component like adding the clip to a video mixer or loading a video clip from a memory buffer: for this reason these system default codecs are automatically blacklisted by our component: in case of need, you can disable this blacklist by using the VideoFiltersBlacklistDisable method.

The mentioned black-list can be expanded programmatically by adding other filters that you don't want to be used when generating the filters graph: this can be achieved through the VideoFiltersBlacklistItemAdd method; items in black-list can be removed at any time through the VideoFiltersBlacklistItemRemove method; the list can be reset through the VideoFiltersBlacklistReset method.


Amp3dj_0000d0

Copyright © 2001-2018 MultiMedia Soft

Amp3dj_0000d0

 Return to chapter overview


Amp3dj_000013

Copyright © 2001-2018 MultiMedia Soft

Amp3dj_000013

 Return to chapter overview


Senza titolo 52

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 52

Return to chapter overview


Senza titolo 55

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 55

Return to chapter overview


Senza titolo 58

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 58

Return to chapter overview


Senza titolo 61

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 61

Return to chapter overview


Senza titolo 64

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 64

Return to chapter overview


Senza titolo 67

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 67

Return to chapter overview


Senza titolo 136

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 136

Return to chapter overview


Senza titolo 17

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 17

Return to chapter overview


Senza titolo 25

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 25

Return to chapter overview


Senza titolo 28

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 28

Return to chapter overview


Senza titolo 31

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 31

Return to chapter overview


Senza titolo 34

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 34

Return to chapter overview


Senza titolo 37

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 37

Return to chapter overview


Senza titolo 40

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 40

Return to chapter overview


Senza titolo 43

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 43

Return to chapter overview


Senza titolo 46

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 46

Return to chapter overview


Senza titolo 49

Copyright © 2001-2018 MultiMedia Soft

Senza titolo 49

Return to chapter overview