Introduction

Copyright © 2005-2018 MultiMedia Soft

Introduction

Return to chapter overview

Audio DJ Studio API for .NET is a .NET class developed by MultiMedia Soft that makes it easy to add sound playback and mixing capabilities to your applications; thanks to the integration with DirectShow codecs and with the BASS library, both adding decoding capabilities for the most common sound formats such as MP3, WAV, Ogg Vorbis and many others, Audio DJ Studio API for .NET allows creating powerful multimedia applications with stunning playback capabilities.

Audio DJ Studio API for .NET 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 and video tracks loaded inside a playlist with an accurate and configurable fade-in/fade-out.

Derived from the experience with the Audio DJ Studio for .NET Winform component, this API can be used not only for developing Winform or WPF applications but also for developing console applications, Windows services, server-side ASP.NET web applications or any other application not requiring a user interface. Thanks to COM interoperability, the API can be invoked from legacy development environments such as Visual Basic 6 and Unmanaged Visual C++ with our without MFC.

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

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

Supported .NET frameworks

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
· Integration with Microsoft's Speech API, allowing to apply sound effects and output redirection to the sound stream generated by the SetOutputToAudioStream function of an instance of the System.Speech.Synthesis.SpeechSynthesizer class (requires .NET framework v. 3.0)

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 | - FLAC
- 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 Audio Sound Recorder API for .NET 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 Audio Sound Recorder API for .NET and Audio Sound Editor API for .NET

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

Supported .NET frameworks

· NET Framework 2.0
· NET Framework 3.0
· NET Framework 3.5
· NET Framework 4.0
· NET Framework 4.5
· NET Framework 4.6

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 2005-2018. ALL RIGHTS RESERVED

MultiMedia Soft product specifications are subject to change without notice.

Trademarks

Audio Sound Editor API for .NET is a registered trademark of MultiMedia Soft.

Audio Sound Editor for .NET is a registered trademark of MultiMedia Soft.

Audio Sound Recorder for .NET is a registered trademark of MultiMedia Soft.

Audio Sound Recorder API for .NET is a registered trademark of MultiMedia Soft.

Audio DJ Studio for .NET is a registered trademark of MultiMedia Soft.

Audio DJ Studio API for .NET is a registered trademark of MultiMedia Soft.

Windows 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 "Audio DJ Studio API for .NET" component (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 class assembly

AudioDjStudioApi.dll if your application was targeted for .NET framework 2.0, 3.0 or 3.5 and the reference to AudioDjStudioApi was used inside the project

AudioDjStudioApiF4.dll if your application was targeted for .NET framework 4.0 or higher and the reference to AudioDjStudioApiF4 was used inside the project

- the x86 version of the multimedia engine AdjMmsEng.dll

- the x64 version of the multimedia engine AdjMmsEng64.dll

· If compiling specifically for x86

- the class assembly

AudioDjStudioApi.dll if your application was targeted for .NET framework 2.0, 3.0 or 3.5 and the reference to AudioDjStudioApi was used inside the project

AudioDjStudioApiF4.dll if your application was targeted for .NET framework 4.0 or higher and the reference to AudioDjStudioApiF4 was used inside the project

- the x86 version of the multimedia engine AdjMmsEng.dll

· If compiling specifically for x64

- the class assembly

AudioDjStudioApi.dll if your application was targeted for .NET framework 2.0, 3.0 or 3.5 and the reference to AudioDjStudioApi was used inside the project

AudioDjStudioApiF4.dll if your application was targeted for .NET framework 4.0 or higher and the reference to AudioDjStudioApiF4 was used inside the project

- the x64 version of the multimedia engine AdjMmsEng64.dll

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

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

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.

Important note about usage of the API through COM interoperability

If you are going to use the API with legacy development environments like Visual Basic 6 or unmanaged Visual C++, which can talk to the API through COM interoperability, during redistribution on target machines you need to register the API assembly on the target system registry through the RegAsm.exe utility provided by Microsoft.

It's very important to remember that there are two versions of RegAsm.exe, one for assemblies compiled against version 2 of the .NET framework and one for assemblies compiled against version 4 of the .NET framework. You can locate the appropriate version of the RegAsm.exe utility inside your system using the following schema:

.NET framework version | RegAsm.exe default installation path on your development system | Assembly to register
2.0 / 3.0 / 3.5 | C:\Windows\Microsoft.NET\Framework\v2.0.50727\RegAsm.exe | AudioDjStudioApi.dll
4.0 and higher | C:\Windows\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe | AudioDjStudioApiF4.dll

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 API 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.

How to create a "ClickOnce" setup containing our component using Visual Studio .NET

· Inside the "Solution Explorer" open "References"
· Locate and select the reference to AudioDjStudioApi
· Inside the "Properties" window locate the "Copy Local" property and set it to "True"

· Inside the "Solution Explorer" right-click the project name
· From the context menu select "Properties..."
· Select the "Publish" tab
· Click the "Application Files..." button
· For the AudioDjStudioApi.dll (or AudioDjStudioApiF4.dll) assembly, verify that inside the "Publish status" column the default "Include" option is selected

· Inside the "Solution Explorer" right-click the project name
· From the context menu select "Add\Existing Item..."
· Inside the "Objects of type" combobox select "Executable files"
· Locate the directory where AdjMmsEng.dll and AdjMmsEng64.dll are installed (by default should be under "C:\Program Files\Audio DJ Studio API for .NET\Redist")
· Select AdjMmsEng.dll and AdjMmsEng64.dll and press the "Add" button
· for both of them change the "Copy to Output Directory" property to "Copy always"
· Rebuild the ClickOnce package


Product history

Product history

Version 10.1.1.0

Important note about rebuilding of the container application

In order to optimize some of the features internal to the API and in order to fix an issue that caused a parameter overflow, we were forced to slightly change the internal architecture of the API itself.

For this reason, when upgrading from version 9.1.2.0 or lower, there is the need to rebuild the EXE file of the container application before redistributing the upgrade to your final customers.

In case your code should be using the OnMidiStreamEvents event and/or the CallbackForMidiStreamEvents delegate, there may be the need to slightly change your original source code as well because their 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 Audio Sound Editor API for .NET 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 (class)

New methods

GetPlayerHandle

PlayListCurrIndexGet

PlayListExecOrderTableGet

SetProxyConfiguration

New classes

· SoundComposerMan

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

Version 9.1.3.0

New features

· The OnMidiStreamEvents event and the CallbackForMidiStreamEvents delegate 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.1.0

New features

· Added the possibility to determine if the container application is a Windows service

New methods

ContainerIsWindowsService


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 our 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 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 API to your projects

Adding the API to a C# project

Adding the API to a Visual Basic .NET project

Adding the API to an ASP.NET web application with C# code-behind

Adding the API to an unmanaged Visual C++ project

Adding the API to a Visual Basic 6 project

How to use the API in your projects

How to use the API in a Windows service

How to synchronize the container application with the API

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 integrate with Microsoft's Speech API

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 stream 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 Audio Sound Recorder API for .NET

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 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 enumerated types


How to install the API on your development PC

How to install the API on your development PC

This product has been developed for usage with versions of Visual Studio 2005 or higher and requires the availability of .NET Framework version 2.0 or higher.

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 adjstudnetapi_X.exe file and follow the contained instructions: note that "X" represents a code related to the purchased edition (adjstudnetapi_t.exe for the trial version).
· Once the setup package has installed all the needed files, it will automatically register our component inside the Global Assembly Cache.
· From now on you will be able to add the control to your .NET based projects. For details about inserting the control into a project, take a look to the How to add the control to your projects section.


How to add the API to your projects

How to add the API to your projects

Adding the API to a C# project

Adding the API to a Visual Basic .NET project

Adding the API to an ASP.NET web application with C# code-behind

Adding the API to an unmanaged Visual C++ project

Adding the API to a Visual Basic 6 project


Adding the API to a C# project

Adding the API to a C# project

Find below required steps:

· Open the project you are working on
· Inside the "Solution Explorer" right-click the mouse button on the "References" item
· From the context menu select the "Add reference..." menu item; this will open the "Add reference" dialog box.

· Select the ".NET" tab and, on the list of installed components, find the component named "Audio DJ Studio API" as displayed below and, if your application targets .NET framework versions 2.0, 3.0 or 3.5, select "Audio DJ Studio API v2" or, if your application targets .NET framework 4, select "Audio DJ Studio API v4"

· Pressing the "OK" button will bring you again to your project working area and the References item of the Solution Explorer will appear like this:

if you selected "Audio DJ Studio API v2" or like this

if you selected "Audio DJ Studio API v4"

· At this point we need to create a new instance of the component's class and, before starting sound playback management, to initialize the component: for this purpose it's mandatory a call to the InitSoundSystem method. The code snippet below shows how to perform instancing and initialization of the component

Visual C#

// instance the API as a global variable

AudioDjStudioApi.AudioDjStudioApiObj m_audioAPI = new AudioDjStudioApi.AudioDjStudioApiObj();

// initialize the API at the beginning of your code

m_audioAPI.InitSoundSystem (1, 0, 0, 0, 0);

· You can now start developing your code around the control as described inside the How to use the API in your projects section

IMPORTANT: Before exiting the container application, in order to avoid memory leaks, it's recommended that you explicitly call the Dispose method of the API.


Adding the API to a Visual Basic .NET project

Adding the API to a Visual Basic .NET project

Find below required steps:

· Open the project you are working on
· Open the project properties and select the "References" tab then click the "Add..." button

· Select the ".NET" tab and, on the list of installed components, find the component named "Audio DJ Studio API" as displayed below and, if your application targets .NET framework versions 2.0, 3.0 or 3.5, select "Audio DJ Studio API v2" or, if your application targets .NET framework 4, select "Audio DJ Studio API v4"

· Pressing the "OK" button will bring you again to your project working area and the References item of the Solution Explorer will appear like this:

if you selected "Audio DJ Studio API v2" or like this

if you selected "Audio DJ Studio API v4"

· At this point we need to create a new instance of the component's class and, before starting sound playback management, to initialize the component: for this purpose it's mandatory a call to the InitSoundSystem method. The code snippet below shows how to perform instancing and initialization of the component

Visual Basic .NET

' instance the API as a global variable

Dim  m_audioAPI As AudioDjStudioApi.AudioDjStudioApiObj = New AudioDjStudioApi.AudioDjStudioApiObj()

' initialize the API at the beginning of your code

m_audioAPI.InitSoundSystem (1, 0, 0, 0, 0)

· You can now start developing your code around the control as described inside the How to use the API in your projects section

IMPORTANT: Before exiting the container application, in order to avoid memory leaks, it's recommended that you explicitly call the Dispose method of the API.


Adding the API to an ASP.NET web application with C# code-behind

Adding the API to an ASP.NET web application with C# code-behind

 Return to chapter overview

Find below required steps:

· Open the project you are working on
· Inside the "Solution Explorer" right-click the mouse button on the "References" item
· From the context menu select the "Add reference..." menu item; this will open the "Add reference" dialog box.

· Select the ".NET" tab and, on the list of installed components, find the component named "Audio DJ Studio API" as displayed below and, if your application targets .NET framework versions 2.0, 3.0 or 3.5, select "Audio DJ Studio API v2" or, if your application targets .NET framework 4, select "Audio DJ Studio API v4"

· Pressing the "OK" button will bring you again to your project working area and the References item of the Solution Explorer will appear like this:

if you selected "Audio DJ Studio API v2" or like this

if you selected "Audio DJ Studio API v4"

· inside the properties of the added reference, be sure to set the "Copy local" property to "True" and the "Specific version" property to "False"

· now we can start coding so we need to create a new instance of the component's class inside the C# code-behind of our web page that will instance and use and, finally, we need to initialize the component: for this purpose it's mandatory a call to the InitSoundSystem method. The code below shows how to perform instancing and initialization of the component inside the Page_Load function:

Visual C#

using System;

using System.Collections.Generic;

using System.Web;

using System.Web.UI;

using System.Web.UI.WebControls;

// add the namespace of the API

using AudioDjStudioApi;

namespace WebApplication1

{

 public partial class _Default : System.Web.UI.Page

 {

  // instance the API as a global variable

  AudioDjStudioApi.AudioDjStudioApiObj m_audioAPI = new AudioDjStudioApi.AudioDjStudioApiObj();

   protected void Page_Load (object sender, EventArgs e)

   {

    // initialize the API

    m_audioAPI.InitSoundSystem (1, 0, 0, 0, 0);

     ....

   }

 }

}

· In order to work on the server, the API needs to find multimedia engines AdjMmsEng.dll and AdjMmsEng64.dll: for this purpose you should add them to the project. By default, during the publishing phase, the assembly of the web application and assemblies of referenced APIs are installed on the server inside the "bin" sub-folder of the web application's main folder: our multimedia engine should be installed there too. Usually the "bin" folder is not visible on the "Solution explorer" window so we should make it visible by selecting the "Project/Show All Files" menu item of Visual Studio. At this point we could see the "bin" folder like this:

· In order to add our multimedia engines to the project, right click the "bin" folder and select the "Include In Project" menu item from the context menu and finally right click again the "bin" folder and select the "Add > Existing Item..." menu item as seen below:

at this point locate the position where multimedia engines AdjMmsEng.dll and AdjMmsEng64.dll are installed on your development PC and use the "Add As Link" option as seen below:

· Now all is ready for publishing the web application on the server: multimedia engines will be automatically copied in the same API's folder and will be available for interacting with the AudioDjStudioApi.dll assembly.

· You can now start developing your code around the API as described inside the How to use the API in your projects section. Below you will find a code snippet that, given a sound file stored inside the server, will analyze its waveform, will generate a picture of the waveform itself and will display the picture on the web page.

Visual C#

using System;

using System.Collections.Generic;

using System.Web;

using System.Web.UI;

using System.Web.UI.WebControls;

// add the namespace of the API

using AudioDjStudioApi;

namespace WebApplication1

{

 public partial class _Default : System.Web.UI.Page

 {

  // instance the API as a global variable

  AudioDjStudioApi.AudioDjStudioApiObj m_audioAPI = new AudioDjStudioApi.AudioDjStudioApiObj();

   protected void Page_Load (object sender, EventArgs e)

   {

    // initialize the API

    m_audioAPI.InitSoundSystem (1, 0, 0, 0, 0);

    // load the file into the API

     string strPath = Request.PhysicalApplicationPath;

     strPath += "myfile.mp3";

     m_audioAPI.LoadSound (0, strPath);

    // display the sound duration

     form1.InnerHtml += "Sound Duration: ";

     form1.InnerHtml += m_audioAPI.SoundDurationStringGet (0, true, true, ":", ".", 3, false) + "<BR>";

    // analyze the sound's waveform

     m_audioAPI.DisplayWaveform.AnalyzeFullSound (0, enumWaveformResolutions.WAVEFORM_RES_MIDDLE);

    // set the color for the waveform to yellwo

     m_audioAPI.DisplayWaveform.set_ColorLine (0, Color.Yellow);

    // generate the bitmap in GIF format and store it into the server

     strPath = Request.PhysicalApplicationPath;

     strPath += "bitmap.gif";

     m_audioAPI.DisplayWaveform.BitmapViewSaveToFile (0, 0, -1, 200, 50, enumWaveformTypes.WAVEFORM_TYPE_MIXED,

                                                     strPath, enumGraphicFormats.GRAPHIC_FORMAT_GIF, 0);

    // display the bitmap on the web page

     form1.InnerHtml += "<BR><BR>";

     form1.InnerHtml += "<img src=\"./bitmap.gif\" alt=\"My waveform\">";

     ...

    // dispose the API

     m_audioAPI.Dispose ();

   }

 }

}

IMPORTANT: Before exiting the container application, in order to avoid memory leaks, it's recommended that you explicitly call the Dispose method of the API.


Adding the API to an unmanaged Visual C++ project

Adding the API to an unmanaged Visual C++ project

The .NET runtime allows unmanaged COM aware clients to seamlessly access .NET Components through the "COM Interoperability" and through the tools provided by the framework. This ensures that COM aware clients can talk to .NET components, as if they were talking to classic COM Components: "Audio DJ Studio API for .NET" API allows this interoperability with unmanaged Visual C++ through a certain number of steps.

· The first step is to import the type library of the API, which contains all of the needed information for allowing the COM client to talk with the API, by adding the following statements at the beginning of your code:

Visual C++

#pragma warning(push)

#pragma warning(disable:4146)

#pragma warning(disable:4786)

#pragma warning(disable:4278)

#import "mscorlib.tlb"

#import "..\\..\\..\\bin\release\\AudioDjStudioApi.tlb"

#pragma warning(pop)

using namespace AudioSoundDjStudioApi;

when using MFC (Microsoft Foundation Classes) a good place to add this code is usually the "stdadx.h" header file. It must be remarked that this specific code will make use of the AudioSoundDjStudioApi.dll assembly which is compiled against version 2.0 of the .NET framework: this means that the target machine will need the presence of version 3.5 of the .NET framework in order to allow the container application to run; in case it shouldn't be available, the Windows system will raise a message allowing the possibility to proceed with the related installation.

In case you should prefer relying upon the AudioSoundDjStudioApiF4.dll assembly, which is compiled against version 4 of the .NET framework, allowing to run on Windows systems where version 3.5 of the .NET framework is not installed by default (as seen for Windows 8 and 10) the code to use would be very similar:

Visual C++

#pragma warning(push)

#pragma warning(disable:4146)

#pragma warning(disable:4786)

#pragma warning(disable:4278)

#import "mscorlib.tlb"

#import "..\\..\\..\\bin\release\\AudioDjStudioApiF4.tlb"

#pragma warning(pop)

using namespace AudioDjStudioApiF4;

Please, note that the usage of the relative path for the ".tlb" file is in this case related to the path of the samples installed by our setup package: in your case you could eventually enter the absolute pathname that may vary depending upon the installation folder of the "Audio DJ Studio API for .NET" API whose default is "C:\Program Files\Audio DJ Studio API for .NET\bin\release").

· The second step is to declare the variable that will instance the API inside the client application

Visual C++

IAudioDjStudioApiObjPtr m_ptrAudioApi;

where IAudioDjStudioApiObjPtr is the COM interface used to drive the API.

· The third step is to initialize the COM subsystem, create an instance of the API inside the code and, finally, initialize the API

Visual C++

// initialize COM

CoInitialize (NULL);

// create an instance of the API and obtain its pointer

CoCreateInstance(__uuidof(AudioDjStudioApiObj), NULL,

                CLSCTX_ALL, __uuidof(IAudioDjStudioApiObj), (void**)&m_ptrAudioApi);

// init the API

m_ptrAudioApi->InitSoundSystem (1, 0, 0, 0, 0);

· The next optional step is to set the callbacks that allow the client application to be informed about events occurring inside the API. For example we could need to be informed about the status of a specific player:

Visual C++

// manages the CallbackForPlayersEvents delegate

void WINAPI CallbackForPlayersEvents (long nEvent, short nPlayer, long nData1, long nData2,

                                     float fData3, char *pBufferUnicode, long nBufferLength)

{

   switch (nEvent)

   {

       case enumPlayerEvents_EV_SOUND_STOPPED:

           printf ("\rStatus: Sound stopped    ");

           break;

       case enumPlayerEvents_EV_SOUND_PAUSED:

           printf ("\rStatus: Sound paused    ");

           break;

       case enumPlayerEvents_EV_SOUND_PLAYING:

           printf ("\rStatus: Sound playing...");

           break;

       default:

           return;

   }

}

in order to allow the API to invoke these callbacks when needed, you need to call the following statement:

Visual C++

// init callbacks for events

m_ptrAudioApi->CallbackForPlayersEventsSetPtr (UINT_PTR (CallbackForPlayersEvents));

please, note the usage of the "Ptr" version of the CallbackForPlayersEventsSet methods: the "Ptr" version of these methods allows passing the address of the callback function as a pointer because the COM client is totally unaware about .NET delegates.

At this point you could add all of the needed code in order to allow the API loading and editing audio files: see the How to use the API in your projects tutorial for related guidelines.

· The final step, immediately before exiting the client application, is to dispose the API and un-initialize the COM subsystem

Visual C++

// dispose the API and all of the allocated resources

m_ptrAudioApi->Dispose ();

// uninitialize COM

CoUninitialize ();

Note about the usage of Unicode

Due to the fact that all of the strings passed/returned to/from the API are in Unicode, when dealing with Visual C++ projects it's strongly recommended to set Unicode as character set inside the project's properties as seen on the image below:


Adding the API to a Visual Basic 6 project

Adding the API to a Visual Basic 6 project

The .NET runtime allows unmanaged COM aware clients to seamlessly access .NET Components through the "COM Interoperability" and through the tools provided by the framework. This ensures that COM aware clients can talk to .NET components, as if they were talking to classic COM Components: "Audio DJ Studio API for .NET" API allows this interoperability with Visual Basic 6 through a certain number of steps.

· The first step is to add a reference to the API: after having loaded your Visual Basic 6 project, select the "Project\References..." menu item; on the "References" form, scroll down the list of installed references until you find "Audio DJ Studio API for .NET"

As you can see there are two versions of the API:

1. the one ending with "v2" refers to the AudioDJStudioApi.dll assembly which is compiled against version 2.0 of the .NET framework: this means that the target machine will need the presence of version 3.5 of the .NET framework in order to allow the container application to run; in case it shouldn't be available, the Windows system will raise a message allowing the possibility to proceed with the related installation.
2. the one ending with "v4" refers to the AudioDJStudioApi.dll assembly which is compiled against version 4 of the .NET framework, allowing to run on Windows systems where version 3.5 of the .NET framework is not installed by default (as seen for Windows 8 and 10) the code to use would be very similar:

Decide which best fits your need and check the respective checkbox, then press the "OK" button.

· Declare the API as a global variable inside the code of the form that will use it:

Visual Basic 6

' declare the API

Public WithEvents DJStudioApi As AudioDJStudioApi.AudioDJStudioApiObj

where "DJStudioApi" represents our global variable: you may obviously use a name of your choice.

The "WithEvents" statement allows the application to receive events from the API through COM interoperability: see the Events for Visual Basic 6 COM interoperability section for a list of supported events and for related guidelines.

· On the loading of your application's form, instance and initialize the API:

Visual Basic 6

' instance the API

Set DJStudioApi = New AudioDJStudioApi.AudioDJStudioApiObj

' init the control

DJStudioApi.InitSoundSystem 1, 0, 0, 0, 0

' enable events for COM clients like VB6 (callback delegates functions are not managed correctly by VB6)

DJStudioApi.COMEventsEnable

· The next optional step is to allow the client application to be informed about events occurring inside the API. For example we could need to be informed about the status of a specific player:

Visual Basic 6

Private Sub DJStudioApi_OnPlayersEvents(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)

   Select Case nEvent

       Case enumPlayerEvents.enumPlayerEvents_EV_SOUND_STOPPED

           Debug.Print "Sound stopped"

       Case enumPlayerEvents.enumPlayerEvents_EV_SOUND_PAUSED

           Debug.Print "Sound paused"

       Case enumPlayerEvents.enumPlayerEvents_EV_SOUND_PLAYING

           Debug.Print "Sound playing"

   End Select

End Sub

At this point you could add all of the needed code in order to allow the API loading and editing audio files: see the How to use the API in your projects tutorial for related guidelines.

· The final step, immediately before exiting the client application, is to dispose the API

Visual C++

' dispose the API and all of the allocated resources

DJStudioApi.Dispose

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


How to use the API in your projects

How to use the API 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 Audio 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 C# and VB.NET 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\Audio DJ Studio API for .NET\Samples".

We have already seen in a previous tutorial how to add the API to various development environments like C#, Visual Basic .NET, Visual C++ (unmanaged) and Visual Basic 6, how to create a new instance of the component's class and, before starting sound playback, how to initialize the component.

Starting from version 4.0, Audio 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 component needs to be initialized: for this purpose it's mandatory a call to the InitSoundSystem method; the best place to call this initialization method is usually the container form initialization function: for example, when using Visual C#, it will be the Form_Load function. When the API is no more needed, usually when the container application is closed, it's recommended invoking the Dispose method that frees all of the allocated resources and closes communication with the underlying drivers.

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 API on multiple container forms within the same application, it would be highly recommended hosting and initializing, through the InitSoundSystem method, an instance of the API 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 API 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 InitSoundSystem method are the following:

· synchronizing the component 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.

Each player allocated through the InitSoundSystem method generates an audio stream which, after being modified through special effects, can be sent to different destinations; till version 3.x of the component, 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 summarizes the old situation:

Starting from version 4.0, the component 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 3.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 Audio Sound Recorder API for .NET component, directly to an output file whose format can be predisposed inside Audio Sound Recorder API for .NET 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 4.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 mixers: usually every sound card have a mixer which can be used in order to set the card volumes; you can access these information using the following methods:

MixerGetCount to get the number of mixers currently installed: usually one mixer is available for every installed sound card.

MixerGetDesc to retrieve a friendly description of a 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 CoreAudioDevicesMan class: 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)

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 Analyzer, Oscilloscope and Waveform 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

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:

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 container application is notified about occurring events through a set of callback delegates: 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 use the API in a Windows service

How to use the API in a Windows service

Microsoft Windows services enable you to create long-running executable applications that run in their own Windows sessions. These services can be automatically started when the computer boots, can be paused and restarted, and do not show any user interface. For security reasons, Windows Vista introduced a new concept called “Session 0 Isolation” which doesn't allow these services to create other windows nor communicate with existing ones through messages; for this reason Windows services can only communicate with other applications through a client/server mechanism such as remote procedure call (RPC) or Windows Communication Foundation (WCF) .

The limitation described above means that the API cannot be used to create the following user interface objects on an eventual client application that would use the Windows service as an audio server:

· Visual feedbacks like VU-Meter, Spectrum, Waveform and Oscilloscope: (although VU-Meter and Spectrum visualizations could be still implemented on the client side by managing the CallbackForPlayersEvents delegate and by invoking the Spectrum.GetTable method and with partial support for analyzing the sound's waveform in order to create bitmaps of the waveform in various graphic formats)
· Waveform scroller
· Graphic bars manager
· Enhanced spectrum
· Curve designer
· Fader curves display
· Video player and mixer
· User interface of VST effects and instruments
· MIDI virtual keyboards

If you should need using the mentioned objects, you would need to instance them directly into the client application.

The tutorial How to add the API to your projects instructs about steps needed for adding a reference to the API to a project: most of the steps described can be applied also when using the API for developing a Windows service. Once the reference to the API has been added, you can proceed normally as described inside the tutorial How to use the API in your projects.

The architecture of the multimedia engine (AdjMmsEng.dll and AdjMmsEng64.dll) of our audio components is internally based upon windows messages so, when instanced by one of our audio components from a Windows service, needs to be instructed to work differently: this can be achieved by invoking the ContainerIsWindowsService method; it's recommended invoking this method immediately before invoking the InitSoundSystem method ONLY when the container application is a Windows service.

When an application needs to connect to the Windows service containing the API for starting audio related operations and for receiving feedback about results and operations advancement, there is the need to create a bidirectional communication channel. The API's setup package comes with a C# sample (named "AudioDjWindowsService" available inside the folder "WindowsService") implementing client/server communication through the usage of Windows Communication Foundation (or WCF which can be implemented quite easily when developing in C# and Visual Studio) between a very basic Windows service and a client application having its own user interface; the communication is implemented through "named pipes" which are well wrapped within the WCF framework. Depending upon your background, you could obviously use a totally different way to let your application communicate with the Windows service.

Let's see a step by step procedure that could be followed when the Windows service needs to operate as a server for a client application:

Creating the project of the Windows service in Visual Studio

Defining and implementing a duplex contract inside the Windows service

Allowing the API to be invoked from the client

Creating the WCF endpoint (server side)

Defining and implementing the same duplex contract inside the client application

Running the Windows service and launching the client application

Creating the project of the Windows service in Visual Studio

Visual Studio comes with a template for creating projects that implement Windows services; the MSDN documentation can be used as a starting reference for this purpose. Once the project is created, we can start adding needed references and namespaces for accessing functionalities that help implementing WCF communication.

The first operation is to add a reference to the System.ServiceModel assembly, then we can add its namespace to the code of the Windows service:

Visual C#

using System.ServiceModel;

Defining and implementing a duplex contract inside the Windows service

A duplex contract allows clients and servers to communicate with each other independently so that either can initiate calls to the other and consists of two one-way contracts between the client and the server and does not require that the method calls be correlated. Use this kind of contract when your service must query the client for more information or explicitly raise events on the client.

In our case the server side is implemented by the Windows service (hereinafter referred to as "server") and the client side is implemented by the application having its own user interface (hereinafter referred to as "client").

The first thing to do inside the code of the server is defining the interface that makes up the server side of the duplex contract.

Visual C#

// WCF contract for sending commands from the client application to the Windows service

[ServiceContract(CallbackContract = typeof(IAudioDjStudioServiceCallback), SessionMode = SessionMode.Allowed)]

public interface IAudioDjStudioService

{

[OperationContract]

enumErrorCodes PipeLoadSound(short nPlayer, string strPathname);

[OperationContract]

enumErrorCodes PipePlaySound(short nPlayer);

[OperationContract]

enumErrorCodes PipePauseSound(short nPlayer);

[OperationContract]

enumErrorCodes PipeStopSound(short nPlayer);

[OperationContract]

void PipeGetPlayerStatus (short nPlayer, ref enumPlayerStatus nStatus);

[OperationContract]

string PipeGetPlayerSoundPosition (short nPlayer);

[OperationContract]

string PipeGetPlayerSoundDuration (short nPlayer);

[OperationContract]

enumErrorCodes PipeSetVolume(short nPlayer, int nValue);

[OperationContract]

void PipeClose ();

}

methods defined inside this contract, and implemented inside the server's code, will be invoked by the client application; as you can see, the interface of this contract, that we have named IAudioDjStudioService, is linked to another interface, named IAudioDjStudioServiceCallback, that makes up the client side of the duplex contract:

Visual C#

// WCF contract for sending events from the Windows service to the client application

[ServiceContract(SessionMode = SessionMode.Allowed)]

public interface IAudioDjStudioServiceCallback

{

[OperationContract(IsOneWay=true)]

void PipeSendPlayerStatus (short nPlayer, enumPlayerStatus nStatus);

[OperationContract(IsOneWay=true)]

void PipeSendVuMeterValues (short nPlayer, short nLeft, short nRight);

}

Through this callback interface the server can send information to the client about the current status of the API, about advancement of lengthy operations and so on. As you may easily understand, methods of this interface will be implemented inside the code of the client.

Allowing the API to be invoked from the client

Now that the contract has been defined, we need to allow the API to be linked to the same. For this purpose we can create a class, arbitrarily named AudioDjStudioApiInstance, derived from our API AudioDjStudioApi.AudioDjStudioApiObj, that implements methods defined inside the IAudioDjStudioService interface of the contract:

Visual C#

// class that implements the API and contract interfaces for WCF communication with the client application

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]

public class AudioDjStudioApiInstance : AudioDjStudioApi.AudioDjStudioApiObj, IAudioDjStudioService

{

....

}

Initialization of the API and connection to the client through the IAudioDjStudioServiceCallback callback interface can be implemented inside the constructor of the API:

Visual C#

// class that implements the API and contract interfaces for WCF communication with the client application

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]

public class AudioDjStudioApiInstance : AudioDjStudioApi.AudioDjStudioApiObj, IAudioDjStudioService

{

// declare the WCF pipe channel callback

IAudioDjStudioServiceCallback        callback = null;

public AudioDjStudioApiInstance ()

{

// initialize the API with 2 players

this.ContainerIsWindowsService ();

this.InitSoundSystem (2, 0, 0, 0, 0);

...

// set the WCF pipe channel callback

callback = OperationContext.Current.GetCallbackChannel<IAudioDjStudioServiceCallback>();

}

}

Once defined, we can implement methods of the primary IAudioDjStudioService interface inside the server's code and add management of events generated by the API (in this case we will add management for the CallbackForPlayersEvents delegate):

Visual C#

// class that implements the API and contract interfaces for WCF communication with the client application

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]

public class AudioDjStudioApiInstance : AudioDjStudioApi.AudioDjStudioApiObj, IAudioDjStudioService

{

// declare the WCF pipe channel callback

IAudioDjStudioServiceCallback        callback = null;

// declare management functions for callback delegates

CallbackForPlayersEvents addrCallbackForPlayersEvents;

void PlayerCallback(enumPlayerEvents nEvent, short nPlayer, Int32 nData1, Int32 nData2, float fData3, IntPtr pBufferUnicode, Int32 nBufferLength)

{

// notify the client application through the instance of the WCF pipe channel callback

switch (nEvent)

{

case enumPlayerEvents.EV_SOUND_LOADED:

callback.PipeSendPlayerStatus (nPlayer, enumPlayerStatus.SOUND_STOPPED);

break;

case enumPlayerEvents.EV_SOUND_STOPPED:

callback.PipeSendPlayerStatus (nPlayer, enumPlayerStatus.SOUND_STOPPED);

break;

case enumPlayerEvents.EV_SOUND_PLAYING:

callback.PipeSendPlayerStatus (nPlayer, enumPlayerStatus.SOUND_PLAYING);

break;

case enumPlayerEvents.EV_SOUND_PAUSED:

callback.PipeSendPlayerStatus (nPlayer, enumPlayerStatus.SOUND_PAUSED);

break;

case enumPlayerEvents.EV_SOUND_CLOSED:

callback.PipeSendPlayerStatus (nPlayer, enumPlayerStatus.SOUND_NONE);

break;

case enumPlayerEvents.EV_VUMETER:

callback.PipeSendVuMeterValues (nPlayer, (short) nData1, (short) nData2);

break;

default:

return;

}

}

{

// class constructor

public AudioDjStudioApiInstance ()

{

// initialize the API with 2 players

this.ContainerIsWindowsService ();

this.InitSoundSystem (2, 0, 0, 0, 0);

// create the empty VU meter so we will receive level notifications

this.DisplayVUMeter.Create(0, IntPtr.Zero);

this.DisplayVUMeter.Create(1, IntPtr.Zero);

// set the player's callback

addrCallbackForPlayersEvents = new CallbackForPlayersEvents(PlayerCallback);

this.CallbackForPlayersEventsSet(addrCallbackForPlayersEvents);

... do other stuffs

// set the WCF pipe channel callback

callback = OperationContext.Current.GetCallbackChannel<IAudioDjStudioServiceCallback>();

}

public enumErrorCodes PipeLoadSound(short nPlayer, string strPathname)

{

// invoke the LoadSound method of the API

return this.LoadSound (nPlayer, strPathname);

}

public enumErrorCodes PipePlaySound(short nPlayer)

{

// invoke the PlaySound method of the API

return this.PlaySound (nPlayer);

}

public enumErrorCodes PipePauseSound(short nPlayer)

{

return this.PauseSound (nPlayer);

}

public enumErrorCodes PipeStopSound(short nPlayer)

{

return this.StopSound (nPlayer);

}

public void PipeGetPlayerStatus (short nPlayer, ref enumPlayerStatus nStatus)

{

nStatus = this.GetPlayerStatus (nPlayer);

}

public string PipeGetPlayerSoundPosition (short nPlayer)

{

Int32        nPositionInMs = this.GetCurrentPos (nPlayer);

string        strPos = this.FromMsToFormattedTime (nPositionInMs, true, true, ":", ".", 3);

return strPos;

}

public string PipeGetPlayerSoundDuration (short nPlayer)

{

Int32        nDurationInMs = this.GetSoundOriginalDuration (nPlayer);

string        strDuration = this.FromMsToFormattedTime (nDurationInMs, true, true, ":", ".", 3);

return strDuration;

}

public enumErrorCodes PipeSetVolume(short nPlayer, int nValue)

{

return this.StreamVolumeLevelSet (nPlayer, (float) nValue, enumVolumeScales.SCALE_LINEAR);

}

public void PipeClose ()

{

// dispose the API and deallocate its internal resources

this.Dispose();

}

}

In production code it would be obviously recommended implementing some error checking that would detect eventual error codes returned by API's methods.

Creating the WCF endpoint (server side)

At this point the server can create the WCF endpoint that allows eventual clients to connect and request services; a good place to create and open the endpoint is the OnStart override function of the Windows service while the OnStop override function is a good place to close it:

Visual C#

ServiceHost host = null;

protected override void OnStart (string[] args)

{

eventLog1.WriteEntry("In OnStart");

...

// create and open the WCF host and the endpoint for communication with client applications

host = new ServiceHost(typeof(AudioDjStudioApiInstance), new Uri("net.pipe://localhost"));

host.AddServiceEndpoint(typeof(IAudioDjStudioService), new NetNamedPipeBinding(), "PipeAudioDjStudio");

host.Open();

}

protected override void OnStop ()

{

eventLog1.WriteEntry("In OnStop");

...

// close WCF host

host.Close ();

}

The snippet above, which implements WCF communication through "named pipes", defines an arbitrary name PipeAudioDjStudio for the endpoint: you would be obviously free to define your preferred name.

Defining and implementing the same duplex contract inside the client application

After having created the client application, that in our case will be a simple Winform application with a very basic user interface, we can add code needed to implement the duplex communication with the server. Although not elegant from a coding style perspective, the easier way to define the same duplex contract inside the client application is to simply copy & paste the definition of the IAudioDjStudioService and IAudioDjStudioServiceCallback interfaces inside the namespace of the client application. A more elegant solution, less prone to eventual errors, would be creating an assembly containing the definition of both interfaces and adding a reference to the new assembly in both client and server projects.

Also in this case we need to add a reference to the System.ServiceModel assembly, then we can add its namespace to the code of our client's form.

Once copied the definition of both interfaces inside the client's code, we need to make the class of our main application's form compatible with our duplex contract; for this reason we will have to change the declaration of the form's class from the following code:

Visual C#

public partial class Form1 : Form

{

public Form1 ()

{

InitializeComponent ();

}

....

}

to the following code:

Visual C#

// class that inherits contract interfaces for WCF communication with the client application

[CallbackBehavior(ConcurrencyMode = ConcurrencyMode.Reentrant, UseSynchronizationContext = false)]

public partial class Form1 : Form, IAudioDjStudioServiceCallback

{

public Form1 ()

{

InitializeComponent ();

}

....

}

Once defined, we can implement methods of the callback IAudioDjStudioServiceCallback interface and connect to the endpoint inside the client's code:

Visual C#

// class that inherits contract interfaces for WCF communication with the client application

[CallbackBehavior(ConcurrencyMode = ConcurrencyMode.Reentrant, UseSynchronizationContext = false)]

public partial class Form1 : Form, IAudioDjStudioServiceCallback

{

public Form1 ()

{

InitializeComponent ();

}

// the pipe channel proxy for WCF communication

IAudioDjStudioService pipeProxy = null;

bool        m_bIsServiceAvailable = false;

private const int Player_1 = 0;

private const int Player_2 = 1;

string        m_strStatusPlayer1 = "";

string        m_strStatusPlayer2 = "";

short        m_nVuMeterValueLeft1 = 0;

short        m_nVuMeterValueLeft2 = 0;

short        m_nVuMeterValueRight1 = 0;

short        m_nVuMeterValueRight2 = 0;

         public void PipeSendPlayerStatus (short nPlayer, enumPlayerStatus nStatus)

{

string        strStatus = "Status: ";

switch (nStatus)

{

case enumPlayerStatus.SOUND_NONE:

strStatus += "No sound loaded";

break;

case enumPlayerStatus.SOUND_PLAYING:

strStatus += "Sound playing";

break;

case enumPlayerStatus.SOUND_STOPPED:

strStatus += "Sound stopped";

break;

case enumPlayerStatus.SOUND_PAUSED:

strStatus += "Sound paused";

break;

}

if (nPlayer == Player_1)

m_strStatusPlayer1 = strStatus;

else

m_strStatusPlayer2 = strStatus;

}

public void PipeSendVuMeterValues (short nPlayer, short nLeft, short nRight)

{

if (nPlayer == Player_1)

{

m_nVuMeterValueLeft1 = nLeft;

m_nVuMeterValueRight1 = nRight;

}

else

{

m_nVuMeterValueLeft2 = nLeft;

m_nVuMeterValueRight2 = nRight;

}

}

private void Form1_Load (object sender, EventArgs e)

{

// create the WCF service and related pipe channel

var factory = new DuplexChannelFactory<IAudioDjStudioService>(new InstanceContext(this),

new NetNamedPipeBinding(),

new EndpointAddress("net.pipe://localhost/PipeAudioDjStudio"));

pipeProxy = factory.CreateChannel();

// invoke one of the contract's methods in order to see if the WCF connection with the server was successful

short        nDevices = 0;

try

{

enumPlayerStatus statusPlayer1 = enumPlayerStatus.SOUND_NONE;

pipeProxy.PipeGetPlayerStatus (Player_1, ref statusPlayer1);

}

catch (Exception)

{

MessageBox.Show ("Audio DJ Studio API Windows Service has not been started.");

Close ();

return;

}

m_bIsServiceAvailable = true;

}

private void Form1_FormClosing (object sender, FormClosingEventArgs e)

{

// close the WCF pipe channel

if (m_bIsServiceAvailable)

pipeProxy.PipeClose ();

}

....

}

Also the snippet above implements WCF communication through "named pipes", as seen for the server side code, and tries to establish a connection to the same endpoint named PipeAudioDjStudio.

You may notice that implementation of methods of the IAudioDjStudioServiceCallback callback interface store values of parameters into variables instead of using them to modify directly values of controls instanced on the user interface: this requirement is due to the fact that methods of the callback interface will be invoked from secondary threads a situation which doesn't allow accessing controls instanced on the user interface; as seen inside the sample of client application (named AudioDjWindowsServiceClient) installed by our setup package, a simple way to manage the situation would be instancing on the form a timer that would use these variables to update values of the controls on a timely basis.

Running the Windows service and launching the client application

Once both the Windows service and the client application have been compiled, you can install the Windows service on the target machine: for this purpose there are several solutions described inside the MSDN documentation. As mentioned before, the API's setup package comes with a C# sample (named "AudioDjWindowsService.exe") that is automatically installed inside the system during the installation phase: this service is not started automatically so, in order to test it in conjunction with the client application (named "AudioDjWindowsServiceClient.exe") you need to start it manually using the "Services" applet that can be launched through the "Start" Windows menu by selecting "All programs/Administrative tools/Services". Once launched, you will see something similar:

Click the evidenced item "Audio DJ Studio API Windows service" with the mouse's right button and select "Start" from the context menu: once the "Status" of the service is reported as "Started" you may launch the client application named "AudioDjWindowsServiceClient.exe" (more than one instance is allowed).

After closing the client application you may stop the Windows service by clicking again the evidenced item "Audio DJ Studio API Windows service" with the mouse's right button and by selecting "Stop" from the context menu.


How to synchronize the container application with the API

How to synchronize the container application with the API

In order to allow managing feedback coming from the API code to the container application code, Audio DJ Studio API for .NET gives the possibility to setup a certain number of callback delegates that inform about percentage of advancement of lengthy operations or about manual operations performed by the user on elements of the user interface like the waveform scroller.

Some of these callback delegates are invoked from the application's main thread while others are invoked from secondary threads. Let's see the difference between these two categories of callback delegates:

Callback delegates invoked from the application's main thread

Callback delegates invoked from secondary threads

Important note about COM interoperability with Microsoft Visual Basic 6

For applications developed using Visual Basic 6, which results totally unreliable when dealing with delegates and callbacks in general, a set of COM compatible events is provided: see the Events for Visual Basic 6 COM interoperability section for further details.

Callback delegates invoked from the application's main thread

A list of situations that notify the container application through delegates can be found on the table below:

Situations or methods calls | Corresponding callback delegates | Method for initializing the delegates
A method involving the usage of a player has been invoked, for example LoadSound LoadSoundFast PlaySound PauseSound ResumeSound StopSound CloseSound ... and many others | CallbackForPlayersEvents | CallbackForPlayersEventsSet
The Bezier curve displayed on a volume curve designer control is modified by dragging one of the control points through the mouse interaction. | CallbackCurveDesignerPointsChange | CallbackCurveDesignerPointsChangeSet
A manual scroll happens on the waveform scroller. | CallbackWaveformScrollerManualScroll | CallbackWaveformScrollerManualScrollSet
A mouse event happens on the waveform scroller. | CallbackWaveformScrollerMouseNotif | CallbackWaveformScrollerMouseNotifSet
On WIndows XP, the system default multimedia input/output device (sound card) is changed through the Windows Control Panel's multimedia settings or USB device is plugged or unplugged | CallBackDeviceChange | CallBackDeviceChangeSet

Let's see a couple of code snippets that clarify how a callback delegate can be instantiated and managed. The snippets below show how to load and start playback of a sound file and how to monitor the playback status through the player's callback:

Visual Basic .NET

Imports AudioDjStudioApi

Namespace MyApplication

   Public Partial Class Form1

       Inherits Form

       Public Sub New()

           InitializeComponent()

       End Sub

      ' instance of the API

       Private m_audioAPI As AudioDjStudioApi.AudioDjStudioApiObj = New AudioDjStudioApi.AudioDjStudioApiObj()

      ' callback delegate

       Private addrCallbackForPlayersEvents As CallbackForPlayersEvents = New CallbackForPlayersEvents(PlayerCallback)

      ' callback that manages player's events

       Private Sub Sub PlayerCallback(ByVal nEvent As enumPlayerEvents, ByVal nPlayer As Int16, _

               ByVal nData1 As Int32, ByVal nData2 As Int32, ByVal fData3 As Single, _

               ByVal pBufferUnicode As IntPtr, ByVal nBufferLength As Int32)

           Select Case nEvent

               Case enumPlayerEvents.EV_SOUND_DONE

                   Console.WriteLine("Status: Sound playback completed")

               Case enumPlayerEvents.EV_SOUND_PAUSED

                   Console.WriteLine("Status: Sound playback paused")

               Case enumPlayerEvents.EV_SOUND_PLAYING

                   Console.WriteLine("Status: Sound playing...")

               Case enumPlayerEvents.EV_SOUND_STOPPED

                   Console.WriteLine("Status: Sound stopped")

               Case Else

                   Return

           End Select

          ... do something else

       End Sub

       Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load

          ' initialize the API

           m_audioAPI.InitSoundSystem(1, 0, 0, 0, 0)

          ' predispose the callback that will notify about player's events

           m_audioAPI.CallbackForPlayersEventsSet(addrCallbackForPlayersEvents)

           ' load a sound file and start playing

           m_audioAPI.LoadSound (0, "c:\mysound.mp3")

           m_audioAPI.PlaySound (0)

          ... do other stuffs

       End Sub

   End Class

End Namespace

Visual C#

using AudioDjStudioApi;

namespace MyApplication

{

   public partial class Form1 : Form

   {

       public Form1()

       {

           InitializeComponent();

       }

      // instance of the API

       AudioDjStudioApi.AudioDjStudioApiObj m_audioAPI = new AudioDjStudioApi.AudioDjStudioApiObj();

      // callback delegate

       CallbackForPlayersEvents addrCallbackForPlayersEvents;

      // callback that manages player's events

       void PlayerCallback(enumPlayerEvents nEvent, Int16 nPlayer, Int32 nData1, Int32 nData2, float fData3,

                           IntPtr pBufferUnicode, Int32 nBufferLength)

       {

           switch (nEvent)

           {

               case enumPlayerEvents.EV_SOUND_DONE:

                   Console.WriteLine("Status: Sound playback completed");

                   break;

               case enumPlayerEvents.EV_SOUND_PAUSED:

                   Console.WriteLine("Status: Sound paused");

                   break;

               case enumPlayerEvents.EV_SOUND_PLAYING:

                   Console.WriteLine("Status: Sound playing...");

                   break;

               case enumPlayerEvents.EV_SOUND_STOPPED:

                   Console.WriteLine("Status: Sound stopped");

                   break;

           }

          ... do something else

       }

       private void Form1_Load(object sender, EventArgs e)

       {

          // initialize the API

           m_audioAPI.InitSoundSystem(1, 0, 0, 0, 0);

          // predispose the callback that will notify about player's events

           addrCallbackForPlayersEvents = new CallbackForPlayersEvents(PlayerCallback);

           m_audioAPI.CallbackForPlayersEventsSet(addrCallbackForPlayersEvents);

          // load a sound file and start playing

           m_audioAPI.LoadSound (0, @"c:\mysound.mp3");

           m_audioAPI.PlaySound (0);

          ... do other stuffs

       }

      ...

   }

  ...

}

IMPORTANT NOTE ABOUT DELEGATES AND THEIR SCOPE: When an instance of a callback delegate is passed to one of the API functions, the delegate object is not reference counted. This means that the .NET framework would not know that it might still being used by the API so the Garbage Collector might remove the delegate instance if the variable holding the delegate is not declared as global. As a general rule, make sure to always keep your delegate instance in a variable which lives as long as the API needs it by using a global variable or member.

Callback delegates invoked from secondary threads

Some method available inside Audio DJ Studio API for .NET 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 load a sound file whose duration is more than 30 minutes or to perform the waveform analysis for a song longer than 5 minutes and you will perfectly understand that this kind of tasks couldn't be completed in less than one second.

In order to avoid this kind of blocks, the API performs lengthy operations inside secondary threads executed in synchronous mode: this means that the call to a method starting a new thread will not return control to the container application till the moment in which the secondary thread has not completed its task and has been closed.

During execution of the secondary thread, advancement of the thread's task is reported to the container application through a set of callback delegates. A list of methods and situations that will start a secondary thread, with the corresponding callback delegate, can be found on the table below:

Situations or methods calls | Corresponding callback delegates | Method for initializing the delegates
Most of methods invoked on a player, for example AmazonStoreCdInfoCreate BeatsDetectRequest LoadSoundSync LoadSoundFromMemorySync LoadEncryptedSoundSync LoadEncryptedSoundFromMemorySync LoadInternetStream LoadTrackFromCd PlaySound on an Internet stream PlayListAddItemEx PlayListLoadSync RequestSoundBPM SilenceDetectionOnFile SilenceDetectionOnPlayerRequest SoundLyricsRequest VideoPlayer.LoadSync Waveform.AnalyzeFullSound | CallbackForPlayersEvents | CallbackForPlayersEventsSet
Operations related to CD drives | CallbackForCdDrivesEvents | CallbackForCdDrivesEventsSet
Notifications from CoreAudio devices | CallbackForCoreAudioEvents | CallbackForCoreAudioEventsSet
Notifications from MIDI sub-system | CallbackForMidiKeyboardEvents CallbackForMidiMarkerEvents CallbackForMidiStreamEvents | CallbackForMidiKeyboardEventsSet CallbackForMidiMarkerEventsSet CallbackForMidiStreamEventsSet
Notifications from the Downloader | CallbackForDownloaderEvents | CallbackForDownloaderEventsSet
Notifications from casting sessions | CallbackForCastingEvents | CallbackForCastingEventsSet

Let's see a couple of code snippets that clarify how a callback delegate invoked from a secondary thread can be instantiated and managed.

The snippets below show how to manage the percentage advancement of a waveform analysis of the loaded sound: in this case the API is invoked from a container form, so we must keep count of the fact that controls instanced on a form are not thread-safe so, in order to access them, we should add some further coding. The snippets below show how to manage the percentage advancement of a sound waveform analysis operation performed from inside a container form (Form1) having controls instanced on its user interface, for example a label and a progress bar, that need to be updated to inform the user about the current advancement of the waveform analysis:

Visual Basic .NET

Imports AudioDjStudioApi

Namespace MyApplication

   Public Partial Class Form1

       Inherits Form

       Public Sub New()

           InitializeComponent()

       End Sub

      ' instance of the API

       Private m_audioAPI As AudioDjStudioApi.AudioDjStudioApiObj = New AudioDjStudioApi.AudioDjStudioApiObj()

      ' callback delegate

       Private Delegate Sub CallbackForPlayersEventsDelegate(ByVal nEvent As enumPlayerEvents, ByVal nPlayer As Int16, _

               ByVal nData1 As Int32, ByVal nData2 As Int32, ByVal fData3 As Single, _

               ByVal pBufferUnicode As IntPtr, ByVal nBufferLength As Int32)

       Private addrCallbackForPlayersEvents As CallbackForPlayersEvents = New CallbackForPlayersEvents(PlayerCallback)

      ' callback that manages player's events

       Private Sub Sub PlayerCallback(ByVal nEvent As enumPlayerEvents, ByVal nPlayer As Int16, _

               ByVal nData1 As Int32, ByVal nData2 As Int32, ByVal fData3 As Single, _

               ByVal pBufferUnicode As IntPtr, ByVal nBufferLength As Int32)

          ' check if we are being invoked from a secondary thread

           If Me.InvokeRequired Then

              ' this callback is being called from a secondary thread so, in order to access controls on the form, we must

               ' call Invoke using this same function as a delegate

               Me.Invoke(New CallbackForPlayersEventsDelegate(AddressOf PlayerCallback), nEvent, nPlayer, _

                                                           nData1, nData2, fData3, pBufferUnicode, nBufferLength)

               Return

           End If

           Select Case nEvent

               Case enumPlayerEvents.EV_WAVE_ANALYSIS_START

                   labelProgress.Visible = True

                   progressBar1.Visible = True

                   labelProgress.Text = "Waveform analysis progress"

                   progressBar1.Value = 0

               Case enumPlayerEvents.EV_WAVE_ANALYSIS_PERC

                   progressBar1.Value = nData1

               Case enumPlayerEvents.EV_WAVE_ANALYSIS_DONE

                   progressBar1.Visible = False

                   labelProgress.Visible = False

               Case Else

                   Return

           End Select

          ... do something else

       End Sub

       Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load

          ' initialize the API

           m_audioAPI.InitSoundSystem(1, 0, 0, 0, 0)

          ' predispose the callback that will notify about player's events

           m_audioAPI.CallbackForPlayersEventsSet(addrCallbackForPlayersEvents)

           ' load a sound file

           Dim nResult as enumErrorCodes = m_audioAPI.LoadSound (0, "c:\mysound.mp3")

           If nResult = enumErrorCodes.NOERROR Then

              ' request full waveform analysis

               m_audioAPI.DisplayWaveform.AnalyzeFullSound (0, enumWaveformResolutions.WAVEFORM_RES_MAXIMUM)

           Else

               MessageBox.Show ("Cannot load file due to error" & nResult)

           End If

          ... do other stuffs

       End Sub

   End Class

End Namespace

Visual C#

using AudioDjStudioApi;

namespace MyApplication

{

   public partial class Form1 : Form

   {

       public Form1()

       {

           InitializeComponent();

       }

      // instance of the API

       AudioDjStudioApi.AudioDjStudioApiObj m_audioAPI = new AudioDjStudioApi.AudioDjStudioApiObj();

      // callback delegate

       delegate void CallbackForPlayersEventsDelegate(enumPlayerEvents nEvent, Int16 nPlayer,

                       Int32 nData1, Int32 nData2, float fData3, IntPtr pBufferUnicode, Int32 nBufferLength);

       CallbackForPlayersEvents addrCallbackForPlayersEvents;

      // callback that manages player's events

       void PlayerCallback(enumPlayerEvents nEvent, Int16 nPlayer, Int32 nData1, Int32 nData2, float fData3,

                           IntPtr pBufferUnicode, Int32 nBufferLength)

       {

          // check if we are being invoked from a secondary thread

           if (this.InvokeRequired)

           {

              // this callback is being called from a secondary thread so, in order to access controls on the form, we must

               // call Invoke using this same function as a delegate

               this.Invoke(new CallbackForPlayersEventsDelegate(PlayerCallback), nEvent, nPlayer, nData1, nData2, fData3, pBufferUnicode, nBufferLength);

               return;

           }

           switch (nEvent)

           {

           case enumPlayerEvents.EV_WAVE_ANALYSIS_START:

               labelProgress.Visible = true;

               progressBar1.Visible = true;

               labelProgress.Text = "Waveform analysis progress";

               progressBar1.Value = 0;

               break;

           case enumPlayerEvents.EV_WAVE_ANALYSIS_PERC:

               progressBar1.Value = nData1;

               break;

           case enumPlayerEvents.EV_WAVE_ANALYSIS_DONE:

               progressBar1.Visible = false;

               labelProgress.Visible = false;

               break;

           }

          ... do something else

       }

       private void Form1_Load(object sender, EventArgs e)

       {

          // initialize the API

           m_audioAPI.InitSoundSystem(1, 0, 0, 0, 0);

          // predispose the callback that will notify about player's events

           addrCallbackForPlayersEvents = new CallbackForPlayersEvents(PlayerCallback);

           m_audioAPI.CallbackForPlayersEventsSet(addrCallbackForPlayersEvents);

          // load a sound file

           enumErrorCodes nResult = m_audioAPI.LoadSound (0, @"c:\mysound.mp3");

           if (nResult == enumErrorCodes.NOERROR)

              // request full waveform analysis

               m_audioAPI.DisplayWaveform.AnalyzeFullSound (0, enumWaveformResolutions.WAVEFORM_RES_MAXIMUM);

           else

               MessageBox.Show ("Cannot load sound file due to error " + nResult.ToString ());

          ... do other stuffs

       }

      ...

   }

  ...

}


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 InitSoundSystem method.

A couple of possible questions:

· "In order to define the player output device, the InitSoundSystem 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 InitSoundSystem 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 InitSoundSystem method (inside the form initialisation function).

At this point you can use are the following method to load and play a sound file:

LoadSound 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

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 position of a certain amount

RewindSound to rewind the song position 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 class to load and play a video clip file:

VideoPlayer.Create to create a new video player object

VideoPlayer.Load to load a video from the hard disk

VideoPlayer.Play to playback 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 API 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 CoreAudioDevicesMan class 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 through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_STATE_CHANGED and the nData3 parameter reporting the current status: 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 through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_DEFAULT_CHANGE. 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 through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_ADDED.

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" the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_STATE_CHANGED and the nData3 parameter reporting the current status may be invoked a few times.

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 container application can be informed in real time through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_REMOVED.

After catching these events, 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 through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_VOLUME_CHANGE.

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 can be notified each time a new peak value is detected through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_VUMETER_CHANGE; 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.

A Sample of usage of CoreAudio API in Visual C#.NET and Visual Basic.NET 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

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 InitSoundSystem 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 CallbackDeviceChange delegate.

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, the CallbackDeviceChange delegate is invoked.

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 InitSoundSystem method, 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#.NET and Visual Basic.NET 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 CoreAudioDevicesMan class 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 InitSoundSystem, 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, Audio Dj Studio API for .NET gives access to WASAPI itself through the WASAPIMan class 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 output 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 InitSoundSystem 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 through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_ADDED.

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 Microphone or the Line-In jack are not physically plugged into the system; when the audio device is set to "Enabled" or "Disabled", the delegate could be invoked one or more times with the nEvent parameter set to EV_COREAUDIO_DEVICE_STATE_CHANGED and the nData3 parameter reporting the current status.

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 delegate would be invoked with the nEvent parameter set to EV_COREAUDIO_DEVICE_REMOVED.

As mentioned, the CallbackForCoreAudioEvents delegate could be invoked more than once in a very short time so, when starting the reset procedure, you should ignore the delegate for a while (typically for about 2 seconds) after the first call.

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 Audio Sound Recorder API for .NET component, directly to an output file whose format can be predisposed inside Audio Sound Recorder API for .NET itself.

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

- WasapiInputPlayer

- WasapiSpeakersManager

If the Audio Sound Suite API for .NET 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 Audio DJ Studio enumerates output devices (sound cards) supporting the DirectSound protocol: in order to let Audio 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 InitSoundSystem, 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 driver 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 InitSoundSystem 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 ASIOMan class:

· 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_MONOO, 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 Audio Sound Recorder API for .NET component, directly to an output file whose format can be predisposed inside Audio Sound Recorder API for .NET 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#.NET and Visual Basic.NET can be found inside the following samples installed with the product's setup package:

- AsioList

- AsioSpeakersManager

- AsioVideoPlayer

If the Audio Sound Suite API for .NET 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 4.0 of the component, 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 method.

In case you should need adding volume automation features to your playlist, you could use the PlayListCreatEx method passing PLAYLIST_AUTOMATION_MODE to the nMode parameter; 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_PLAYLIST_LOAD_STARTED, EV_PLAYLIST_LOAD_PERC and EV_PLAYLIST_LOAD_DONE.

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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to

EV_PLAYLIST_SOUND_LOADED. If the loading session fails, for example because the format of the item is not supported or because the item is not available inside the system, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_PLAYLIST_SOUND_LOAD_FAILED.

A 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

PlayListAddItemWithTag to add a new song to the playlist with an associated tag string: this tag string will be reported when the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_PLAYLIST_SOUND_LOADED 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#.NET and Visual Basic.NET 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 FaderObject class, implemented as an "expandable object", is dedicated to this purpose and can be accessed through the component's Fader property.

When you need using the FaderObject class 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 FaderObject class 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, 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 synchronization; 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 through the CallbackForPlayersEvents delegate which may be invoked with the nEvent parameter set to the following values:

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

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

EV_FADEIN_STARTED: occurs when the song fading-in starts playing

EV_FADEIN_COMPLETED: occurs when the fade-in is completed

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

EV_FADEOUT_COMPLETED: 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.

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 one of our samples:

Note that 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 C# and Visual Basic.NET 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 summarises 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 Audio Sound Recorder API for .NET, 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 Audio Sound Recorder API for .NET component, directly to an output file whose format can be predisposed inside Audio Sound Recorder API for .NET 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 Audio Sound Recorder API for .NET component 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 nPlayerIndex parameter for all of the methods that will modify the output stream, like preamplifier 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 nPlayerIndex parameter used with VUMeter, Spectrum, Oscilloscope and Waveform objects; this feature affects also the CallbackForPlayersEvents delegate when the nEvent parameter is set to EV_VUMETER and to EV_SPECTRUM_CHANGE: the nPlayerIndex 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 component as a source for Shoutcast/Icecast servers.

In order to save the mixed audio stream into an output file, we need to use our Audio DJ Studio component in combination with our Audio Sound Recorder API for .NET component: 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 C# and VB.NET can be found inside the following samples installed with the product's setup package:

- CastMixedStreams

- StreamMixer (requires the installation of Audio 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.

Audio DJ Studio, through the embedded VideoPlayer class and the related DisplayVideoPlayer 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 Audio 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, Audio DJ Studio gives the possibility to play more media files at the same time through the use of different players instanced by the InitSoundSystem 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; Audio 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, Audio 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 Audio 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 CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_SYNC_LOADED 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.GetDuration 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.GetPosition 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.

Audio 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.

Audio 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.

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.

Audio 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 class in Visual C# and Visual Basic.NET 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 Audio 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, Audio 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 CallbackDisplayConfigChanged delegate: 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 C# and Visual Basic.NET 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 C# and Visual Basic.NET 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, Audio 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 Audio DJ Studio, through the embedded VideoMixer class and the related DisplayVideoMixer 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 InitSoundSystem, 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 CallbackForPlayersEvents delegate having the nEvent parameter set to EV_FADING_VOLUME_CHANGED. 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 class in combination with the VideoPlayer class in Visual C# and Visual Basic.NET 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 use the video mixer

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.NET

' init the control

audioDjStudio1.InitSoundSystem (2, 0, 0, 0, 0)

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

audioDjStudio1.Fader.PlayListUseSingle(Player_1)

audioDjStudio1.Fader.Init(enumFadeTypes.FADE_SINGLE_PLAYLIST, Player_1, Player_2)

' set the audio rendering mode

audioDjStudio1.DisplayVideoPlayer.AudioRendererModeSet(Player_1, enumAudioRendererModes.AUDIO_RENDERER_MODE_CUSTOM_2)

audioDjStudio1.DisplayVideoPlayer.AudioRendererModeSet(Player_2, enumAudioRendererModes.AUDIO_RENDERER_MODE_CUSTOM_2)

Visual C#

// init the control

audioDjStudio1.InitSoundSystem (2, 0, 0, 0, 0);

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

audioDjStudio1.Fader.PlayListUseSingle(Player_1);

audioDjStudio1.Fader.Init(enumFadeTypes.FADE_SINGLE_PLAYLIST, Player_1, Player_2);

// set the audio rendering mode

audioDjStudio1.DisplayVideoPlayer.AudioRendererModeSet(Player_1, enumAudioRendererModes.AUDIO_RENDERER_MODE_CUSTOM_2);

audioDjStudio1.DisplayVideoPlayer.AudioRendererModeSet(Player_2, enumAudioRendererModes.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.NET

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

m_nMixerUniqueID = audioDjStudio1.DisplayVideoMixer.Create(m_frmMixer.Handle, _

                       0, 0, m_frmMixer.ClientSize.Width, m_frmMixer.ClientSize.Height, Color.Black)

' attach the 2 instanced players to the VideoMixer object

audioDjStudio1.DisplayVideoPlayer.AttachToVideoMixer(Player_1, m_nMixerUniqueID)

audioDjStudio1.DisplayVideoPlayer.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

m_nMixerUniqueID = audioDjStudio1.DisplayVideoMixer.Create(m_frmMixer.Handle, 0, 0,

                       m_frmMixer.ClientSize.Width, m_frmMixer.ClientSize.Height, Color.Black);

// attach the 2 instanced players to the VideoMixer object

audioDjStudio1.DisplayVideoPlayer.AttachToVideoMixer(Player_1, m_nMixerUniqueID);

audioDjStudio1.DisplayVideoPlayer.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.NET

' check the format to load

If bFormatIsPDJ = True Then

   audioDjStudio1.PlayListLoad(Player_1, strPathname, enumPlayListModes.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 :-)

   audioDjStudio1.Fader.CheckItemsDurationOnStart = False

   audioDjStudio1.PlayListLoad(Player_1, strPathname, enumPlayListModes.PLAYLIST_SPEED_MODE)

end if

' start fading

audioDjStudio1.Fader.StartManualFading

Visual C#

// check the format to load

if (bFormatsIsPDJ)

   audioDjStudio1.PlayListLoad(Player_1, strPathname, enumPlayListModes.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 :-)

   audioDjStudio1.Fader.SetCheckItemsDurationOnStart (FALSE);

   audioDjStudio1.PlayListLoad(Player_1, strPathname, enumPlayListModes.PLAYLIST_SPEED_MODE);

}

// start fading

audioDjStudio1.Fader.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.NET

Private Sub audioDjStudio1_SoundLoaded(ByVal sender As Object, ByVal e As AudioDjStudio.SoundLoadedEventArgs) Handles audioDjStudio1.SoundLoaded

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

   audioDjStudio1.DisplayVideoMixer.PlayerZOrderSet (m_nMixerUniqueID, e.nPlayerIndex, 100)

   ... do other stuffs

End Sub

Private Sub audioDjStudio1_FadeOutStarted(ByVal sender As Object, ByVal e As AudioDjStudio.PlayerEventArgs) Handles audioDjStudio1.FadeOutStarted

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

   m_nPlayerFadingOut = e.nPlayerIndex

End Sub

Private Sub audioDjStudio1_FadeOutCompleted(ByVal sender As Object, ByVal e As AudioDjStudio.PlayerEventArgs) Handles audioDjStudio1.FadeOutCompleted

   ' the player is no more fading

   m_nPlayerFadingOut = -1

End Sub

Private Sub audioDjStudio1_FadeInCompleted(ByVal sender As Object, ByVal e As AudioDjStudio.PlayerEventArgs) Handles audioDjStudio1.FadeInCompleted

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

   audioDjStudio1.DisplayVideoMixer.PlayerZOrderSet (m_nMixerUniqueID, e.nPlayerIndex, 0)

End Sub

Private Sub audioDjStudio1_FadingVolumeChanged(ByVal sender As Object, ByVal e As AudioDjStudio.FadingEventArgs) Handles audioDjStudio1.FadingVolumeChanged

   ' check if the player is fading-out

   If audioDjStudio1.GetPlayerStatus(e.nPlayerIndex) = enumPlayerStatus.SOUND_PLAYING AndAlso m_nPlayerFadingOut = e.nPlayerIndex Then

       ' raise the transparent factor on the player fading out

       audioDjStudio1.DisplayVideoMixer.PlayerAlphaSet (m_nMixerUniqueID, e.nPlayerIndex, 100 - e.fCurrVolume)

   End If

End Sub

Visual C#

private void audioDjStudio1_SoundLoaded(object sender, AudioDjStudio.SoundLoadedEventArgs e)

{

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

   audioDjStudio1.DisplayVideoMixer.PlayerZOrderSet(m_nMixerUniqueID, e.nPlayerIndex, 100);

   ... do other stuffs

}

private void audioDjStudio1_FadeOutStarted(object sender, AudioDjStudio.PlayerEventArgs e)

{

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

   m_nPlayerFadingOut = e.nPlayerIndex;

}

private void audioDjStudio1_FadeOutCompleted(object sender, AudioDjStudio.PlayerEventArgs e)

{

   // the player is no more fading

   m_nPlayerFadingOut = -1;

}

private void audioDjStudio1_FadeInCompleted(object sender, AudioDjStudio.PlayerEventArgs e)

{

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

   audioDjStudio1.DisplayVideoMixer.PlayerZOrderSet(m_nMixerUniqueID, e.nPlayerIndex, 0);

}

private void audioDjStudio1_FadingVolumeChanged(object sender, AudioDjStudio.FadingEventArgs e)

{

   // check if the player is fading-out

   if (audioDjStudio1.GetPlayerStatus(e.nPlayerIndex) == enumPlayerStatus.SOUND_PLAYING && m_nPlayerFadingOut == e.nPlayerIndex)

       // raise the transparent factor on the player fading out

       audioDjStudio1.DisplayVideoMixer.PlayerAlphaSet(m_nMixerUniqueID, e.nPlayerIndex, (int)(100.0 - e.fCurrVolume));

}

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.NET and Visual C# can be found inside the following sample installed with the product's setup package:

- VideoMixerWithFader


How to deal with MIDI protocol

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.

Audio Dj Studio API for .NET, through the MIDI property which encapsulates functionalities of the MIDIMan class, 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 of the nFileType field of the SoundInfo2 class, returned by a call to the SoundInfoGet 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 CallbackForMidiStreamEvents delegate.

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 CallbackForMidiMarkerEventsdelegate 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

Audio Dj Studio API for .NET 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 CallbackForMidiKeyboardEvents delegate.

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 CallbackForMidiStreamEvents delegate is invoked, 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 Audio 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.

Audio 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 VolumeAutomationMan class. 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
· Save the current automation procedure into a XML-based memory stream, as seen above for .vdj files, through theVolumeAutomation.SaveToMemoryStream method and to retrieve and apply the same procedure at a later time through the VolumeAutomation.LoadFromMemoryStream method.
· 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:

<?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="45.000000" CurveType="0" />

       <VolumePoint name="end" VolumeLevel="100.000000" PosPerc="55.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 CallbackForPlayersEvents delegate invoked with the nEvent parameter set to EV_VOLUME_POINT_REACHED.

A samples of volume automation management in Visual C# and Visual Basic.NET 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 3.0 of Audio 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_PLAYLIST_LOAD_STARTED, EV_PLAYLIST_LOAD_PERC and EV_PLAYLIST_LOAD_DONE.; 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 PlayListCreatEx method and passing PLAYLIST_AUTOMATION_MODE to the nMode parameter.

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 PlayListCreatEx method having its nMode parameter set to PLAYLIST_AUTOMATION_MODE.

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

PlayListAddItemWithTag to add a new song to the playlist with an associated tag string: this tag string will be reported when the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_PLAYLIST_SOUND_LOADED 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 invoke the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_CUE_POINT_REACHED. 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 class. 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 container application is notified through the CallbackCurveDesignerPointsChange delegate.

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# and Visual Basic.NET 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 component's version comes with the four embedded Visual Feedbacks listed below:

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 Label control. Note that you can have separate Visual Feedbacks for each of the allocated players.

VU-Meter

Implemented through the VUMeter class and accessible through the DisplayVUMeter 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).

ColorBands: determines the "bands" color.

ColorPeaks: determines the "peaks" color.

ColorBackground: determines the color of the background area.

HasPeaks: determines the "peaks" visibility.

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 values received through the CallbackForPlayersEvents delegate invoked with the nEvent parameter set to EV_VUMETER.

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 class and accessible through the DisplaySpectrum 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 class exposes the following properties and methods that allow the customisation of the graphic rendering:

BandWidth: determines the width in screen pixels of the "bands".

ColorBands: determines the "bands" color.

ColorPeaks: determines the "peaks" color.

ColorBackground: determines the color of the background area.

HasPeaks: determines the "peaks" visibility.

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 values obtained through the Spectrum.GetTable method which can be called after the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SPECTRUM_CHANGE.

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 class and accessible through the DisplayOscilloscope 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 class 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 class and accessible through the DisplayWaveform 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 class 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 height zoom percentage of waveform's lines.

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 C# and Visual Basic.NET 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 DisplaySpectrumEnh property which implements the SpectrumEnh class; an enhanced spectrum analyzer can be instanced for each of the players allocated through the InitSoundSystem 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# and Visual Basic.NET 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

Audio Dj Studio API for .NET 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 an object of class GRAPHIC_BAR_SETTINGS 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 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 CallbackForPlayersEvents delegate (having the nEvent parameter set to EV_VUMETER) 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 the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SPECTRUM_CHANGE, 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 GraphicBarsMan class in Visual C#.NET and Visual Basic.NET 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 class 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to:

· EV_WAVE_ANALYSIS_START: invoked when the sound's analysis begins.
· EV_WAVE_ANALYSIS_PERC: invoked several times during the analysis in order to inform the container application about the percentage of advancement.
· EV_WAVE_ANALYSIS_DONE: invoked 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: the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_WAVE_ANALYSIS_START and EV_WAVE_ANALYSIS_DONE 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 the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_WAVE_ANALYSIS_DONE, 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#.NET and Visual Basic.NET 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 class 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:

Audio Dj Studio API for .NET 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 class 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.

Once the waveform analysis has been completed, 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 container application is notified through the CallbackWaveformScrollerManualScroll delegate that specifies also 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 CallbackWaveformScrollerMouseNotif delegate.

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 Volume, Tempo or Playback rate of a certain song; for this purpose this control provides a set of methods that will help you achieving these tasks.

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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_DURATION_CHANGED. 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 C# and Visual Basic.NET can be found inside the following sample installed with the product's setup package:

- TestPlayers


How to integrate with Microsoft's Speech API

How to integrate Microsoft's Speech API

The Speech Application Programming Interface or SAPI is an API developed by Microsoft to allow the use of speech recognition and speech synthesis within Windows applications.

A managed code version of the API ships as part of the .NET Framework 3.0 and the System.Speech.Synthesis namespace is used to access the SAPI synthesizer engine to render text into speech using a voice installed inside the system; the System.Speech.Synthesis.SpeechSynthesizer.SetOutputToDefaultAudioDevice method allows to send speech directly to the system default sound card but there is no way to redirect the sound flow to a different sound card or to perform speakers assignment and, obviously, there is no way to apply any kind of special effect or to display visual feedbacks for the sound stream being sent in output.

The System.Speech.Synthesis.SpeechSynthesizer.SetOutputToAudioStream method allows sending speech to a generic System.IO.Stream object and Audio DJ Studio allows leveraging this feature in order to take full control over the sound stream of the speech; needed steps are the following:

· Create a queued stream through the StreamQueueCreate method
· Put the queued stream in playback through the PlaySound method
· Create an object of class System.Speech.AudioFormat.SpeechAudioFormatInfo having the same frequency, channels and bits per sample used for the StreamQueueCreate method
· Create an object of class System.IO.MemoryStream
· Call the System.Speech.Synthesis.SpeechSynthesizer.SetOutputToAudioStream method passing both the MemoryStream object and the SpeechAudioFormatInfo object
· Start generating the audio stream through the System.Speech.Synthesis.SpeechSynthesizer.Speak method
· Through the System.Speech.Synthesis.SpeechSynthesizer.SetOutputToNull method reset SAPI's output to the system default sound card
· Call the StreamQueuePushDataMs method passing the MemoryStream object

Due to the fact that the combination of StreamQueueCreate and StreamQueuePushDataMs methods act on a certain instanced player, once the queued stream is in playback you can apply any output redirection, speakers management, special effects and visual feedbacks as for any sound file loaded through the LoadSound method.

A sample of of integration with SAPI in Visual C# and Visual Basic.NET can be found inside the following sample installed with the product's setup package:

- TextToSpeechHelper (requires Visual Studio 2008 or higher)


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

Audio 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: Audio 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, Audio 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". Audio 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, Audio 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 Audio 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 WASAPIMan class 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 kept up-to-date about the casting session through the CallbackForCastingEvents delegate whose nEvent parameter may assume the following values:

· If the casting session has been initiated by a custom Stream Mixer, the call to the CastingStart method will generate the EV_CASTING_STREAM_MIXER_START event while the call to the CastingStop method will generate the EV_CASTING_STREAM_MIXER_STOP event.
· If the casting session has been initiated by one of the available players, the call to the CastingStart method will generate the EV_CASTING_PLAYER_START event while the call to the CastingStop method or the completion of the transmission of the loaded file will generate the EV_CASTING_PLAYER_DONE event. During the transmission of the loaded file the container application can be informed about its advancement through the EV_CASTING_PLAYER_PERC event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the CastingStart method will generate the EV_CASTING_LOOPBACK_START event while the call to the CastingStop method will generate the EV_CASTING_LOOPBACK_STOP 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 WASAPIMan class 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 the CallbackForCastingEvents delegate whose nEvent parameter may assume the following values:

· If the casting session has been initiated by a custom Stream Mixer, the call to the CastingStart method will generate the EV_CASTING_STREAM_MIXER_START event while the call to the CastingStop method will generate the EV_CASTING_STREAM_MIXER_STOP event.
· If the casting session has been initiated by one of the available players, the call to the CastingStart method will generate the EV_CASTING_PLAYER_START event while the call to the CastingStop method or the completion of the transmission of the loaded file will generate the EV_CASTING_PLAYER_DONE event. During the transmission of the loaded file the container application can be informed about its advancement through the EV_CASTING_PLAYER_PERC event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the CastingStart method will generate the EV_CASTING_LOOPBACK_START event while the call to the CastingStop method will generate the EV_CASTING_LOOPBACK_STOP 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 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 WASAPIMan class 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 the CallbackForCastingEvents delegate whose nEvent parameter may assume the following values:

· If the casting session has been initiated by a custom Stream Mixer, the call to the CastingStart method will generate the EV_CASTING_STREAM_MIXER_START event while the call to the CastingStop method will generate the EV_CASTING_STREAM_MIXER_STOP event.
· If the casting session has been initiated by one of the available players, the call to the CastingStart method will generate the EV_CASTING_PLAYER_START event while the call to the CastingStop method or the completion of the transmission of the loaded file will generate the EV_CASTING_PLAYER_DONE event. During the transmission of the loaded file the container application can be informed about its advancement through the EV_CASTING_PLAYER_PERC event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the CastingStart method will generate the EV_CASTING_LOOPBACK_START event while the call to the CastingStop method will generate the EV_CASTING_LOOPBACK_STOP 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 is notified through the CallbackForCastingEvents delegate whose nEvent parameter is set to EV_CASTING_WMA_CLIENT_CONNECT 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 C# and VB.NET can be found inside the following samples installed with the product's setup package:

- Casting

- CastMixedStreams

- CastWasapiLoopback

- StreamMixer (requires the installation of Audio Sound Suite)

- WasapiStreamMixer (requires the installation of Audio Sound Suite)


How to create and use an Equalizer

How to create and use an Equalizer

Audio DJ Studio for .NET 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 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 Audio Sound Editor API for .NET 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.

Existing equalizer's settings can be saved inside a memory stream, in the same XML format as seen for the .edj files, through the Effects.EqualizerSaveToMemoryStream method and retrieved at a later time through the Effects.EqualizerLoadFromMemoryStream method.

Audio DJ Studio for .NET 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 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 invoke the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_EQUALIZER_LOADED.

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 C# and Visual Basic.NET 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 lable 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 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 GetEAXEffectParams method and changed through the SetEAXEffectParans 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

EAX effects are mutually exclusive: you cannot have more than one EAX effect applied on a playing sound.

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 CustomDSPs class, is to give the developer the possibility to apply DSP algorithms to a recording session: 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:

private void SwapStereoChannels (IntPtr bufferSamples, Int32 bufferSamplesLength, Int32 nUserData)

{

// calculate total number of samples passed to the callback

Int32        nTotalSamples = bufferSamplesLength / sizeof (float);

// make a copy of the buffer containing samples

float[]        buffTemp = new float[nTotalSamples];

Marshal.Copy(bufferSamples, buffTemp, 0, nTotalSamples);

// loop through the buffer's copy

Int32        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;

}

// copy back modified samples into the original buffer

Marshal.Copy(buffTemp, 0, bufferSamples, nTotalSamples);

}

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 Audio Dj Studio API for .NET 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.

· 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.

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.

Audio Dj Studio API for .NET 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_VST_PARAM_CHANGED.

When the editor's user interface is resized, the container application is notified through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_VST_EDITOR_RESIZED.

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 C# and Visual Basic.NET 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

Audio Dj Studio API for .NET 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_BEATS_AVAILABLE. 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: each time the control detects a beat during playback notifies the container application through the CallbackForPlayersEvents delegate invoked with the nEvent parameter set to EV_BEAT_DETECTED.

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 CallbackForPlayersEvents delegate, invoked with the nEvent parameter set to EV_BPM_AVAILABLE, 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 CallbackForPlayersEvents delegate, invoked with the nEvent parameter set to EV_BPM_AVAILABLE, 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 C# and Visual Basic.NET 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 C# and Visual Basic.NET 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 or TriggersAddPerc methods 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, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_TRIGGER_REACHED and you will be able to discriminate the specific trigger through its nData1 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, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_CUE_POINT_REACHED allowing to discriminate the specific cue point through contents of the pBufferUnicode 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.

Existing cue points can be saved inside a memory stream, in the same XML format as seen for the .cue files, through the CuePointsSaveToMemoryStream method and retrieved at a later time through the CuePointsLoadFromMemoryStream method.

The CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_CUE_POINTS_LOADED 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 VB example below where tempo is updated after moving a trackbar control:

Private Sub trackBarTempo1_Scroll(ByVal sender As Object, ByVal e As System.EventArgs) Handles trackBarTempo1.Scroll

   ' change tempo using value set into the trackbar control: this will change the duration of the loaded sound

   AudioDjStudio1.Effects.PlaybackTempoSet (Player_1, trackBarTempo1.Value)

   ' obtain updated duration after tempo change

   Dim nUpdatedDuration As Double = 0

   AudioDjStudio1.SoundDurationGet(Player_1, nUpdatedDuration, true)

   ' obtain original duration as available before applying tempo change

   Dim nOriginalDuration as Int32 = 0

   AudioDjStudio1.GetSoundOriginalDuration(Player_1, nOriginalDuration, 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 Int32 = 5000

   ' recalculate the offset through a proportion

   Dim nOffsetUpdatedSpeed as Int32 = (nOffsetOriginalSpeed * nUpdatedDuration) / nOriginalDuration

   ' reposition the cue point based upon the updated song duration and offset

   AudioDjStudio1.CuePointsSetPos (Player_1, "CuePoint name", nUpdatedDuration - nOffsetUpdatedSpeed)

End Sub

During playback, Triggers and Cue Points will not generate the related events 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 C# and Visual Basic.NET can be found inside the following samples installed with the product's setup package:

- Triggers

A sample of use of Cue Points in Visual C# and Visual Basic.NET 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

Audio 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 perform a deeper analysis using the SoundInfoGet method

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 SoundInfoGet 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 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

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 SoundInfoGet 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 the CallbackForPlayersEvents delegate has been invoked with the nEvent parameter set to EV_LYRICS_AVAIL 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 C# and Visual Basic.NET can be found inside the following sample installed with the product's setup package:

- SoundInfo


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 TagsReaderMan class of Audio Dj Studio API for .NET allows reading the most common tag formats (in case you should need both reading and writing you may consider using our Audio Sound Editor API for .NET 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 .NET

' perform tags analysis

Dim nTagFormat As enumTagAvailable = audioDjStudio1.TagsReader.ALL_AnalyzeSoundOnPlayer(0)

If nTagFormat = enumTagAvailable.TAG_FLAG_NONE Then

   ' no tag detected

   Return

End If

' check tags availability: we use bitwise operators because more than one type of tag format could be available

If (nTagFormat And enumTagAvailable.TAG_FLAG_ID3V1) <> 0 Then

   ...

do something with ID3V1

   ...

End If

If (nTagFormat And enumTagAvailable.TAG_FLAG_ID3V2) <> 0 Then

   ...

do something with ID3V2

   ...

End If

If (nTagFormat And enumTagAvailable.TAG_FLAG_WMA) <> 0 Then

   ...

do something with WMA

   ...

End If

If (nTagFormat And enumTagAvailable.TAG_FLAG_MP4) <> 0 Then

   ...

do something with MP4

   ...

End If

Visual C#

// perform tags analysis

enumTagAvailable nTagFormat = audioDjStudio1.TagsReader.ALL_AnalyzeSoundOnPlayer(0);

if (nTagFormat == enumTagAvailable.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 & enumTagAvailable.TAG_FLAG_ID3V1) != 0)

{

   ...

   do something with ID3V1

   ...

}

if ((nTagFormat & enumTagAvailable.TAG_FLAG_ID3V2) != 0)

{

   ...

   do something with ID3V2

   ...

}

if ((nTagFormat & enumTagAvailable.TAG_FLAG_WMA) != 0)

{

   ...

   do something with WMA

   ...

}

if ((nTagFormat & enumTagAvailable.TAG_FLAG_MP4) != 0)

{

   ...

   do something with MP4

   ...

}

Some of the tag fields, such as artist, title and album, are common to all of the tag formats so Audio Dj Studio API for .NET 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 TagsReaderMan class will be related to that specific analysis.

If for example you have an instance of Audio 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 = audioDjStudio1.TagsReader.ALL_AnalyzeSoundOnPlayer(Player_A)

Dim strTitle as String = audioDjStudio1.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 = audioDjStudio1.TagsReader.ALL_AnalyzeSoundOnPlayer(Player_B)

strTitle = audioDjStudio1.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:

nTagFormat = audioDjStudio1.TagsReader.ALL_AnalyzeSoundOnPlayer(Player_A)

Dim strAuthor as String = audioDjStudio1.TagsReader.ALL_CommonFrameGet (TAG_FIELD_ARTIST)

When dealing with specific audio formats, Audio Dj Studio API for .NET allows editing 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.

Audio Dj Studio API for .NET 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 .NET

' perform tags analysis

Dim nTagFormat As enumTagAvailable

nTagFormat = audioDjStudio1.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 Int32

   nAvailablePictures = audioDjStudio1.TagsReader.ID3V2_FrameCountGet("APIC")

   ' output each picture's description

   Dim nIndex as Int32 = 0

   Do While nIndex < nAvailablePictures

      Debug.Print audioDjStudio1.TagsReader.ID3V2_PictureFrameInfoGet (nIndex, enumId3v2FrameInfo.ID3V2_FRAME_INFO_DESCRIPTION)

      nIndex += 1

   Loop

End If

Visual C#

// perform tags analysis

enumTagAvailable nTagFormat = audioDjStudio1.TagsReader.ALL_AnalyzeSoundOnPlayer(0);

if ((nTagFormat & enumTagAvailable.TAG_FLAG_ID3V2) != 0)

{

   // check the availability of embedded pictures through the search of "APIC" frames

   int nAvailablePictures = audioDjStudio1.TagsReader.ID3V2_FrameCountGet("APIC");

   // output each picture's description

   for (int nIndex = 0; nIndex < nAvailablePictures; nIndex++)

      Console.WriteLine (audioDjStudio1.TagsReader.ID3V2_PictureFrameInfoGet (nIndex, enumId3v2FrameInfo.ID3V2_FRAME_INFO_DESCRIPTION));

}

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; Audio Dj Studio API for .NET 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.NET can be found inside the following samples installed with the product's setup package:

- TagsReader


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: it's 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 InitSoundSystem 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 InitSoundSystem method or through the InitSoundSystem method itself 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 both broadcasting streams 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 the container application will be notified about the situation through the CallbackForPlayersEvents delegate having the following values for the nEvent parameter:

· EV_STREAM_CONNECTING to notify about the beginning of the connection to the server.
· In case the connection should fail, EV_STREAM_LOADED would report the failure inside the nData1 parameter.
· In case of successful connection the nEvent parameter would be set to EV_DOWNLOAD_BUFFERING with the nData1 parameter set to STREAMING_BUFFERING to notify that connection with the server was established and that buffering has begun. This would be followed by a number of EV_DOWNLOAD_PERC events to notify about buffering percentage.
· Once there will be enough data to play, EV_STREAM_LOADED would report the connection's success, 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 CallbackForPlayersEvents delegate would be invoked with the nEvent parameter set to EV_DOWNLOAD_BUFFERING and with the nData1 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 through the EV_DOWNLOAD_BUFFERING with the nData1 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 EV_DOWNLOAD_BUFFERING and with the nData1 parameter set to STREAMING_PLAYING.

After a stall situation, the Internet stream provider could also close the connection: in this case the CallbackForPlayersEvents delegate would be invoked with the nEvent parameter set to EV_SERVER_CLOSED.

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 the CallbackForPlayersEvents delegate is invoked with nEvent parameter set to EV_META_CHANGED: at this point the container application will have the possibility to perform the following sequence of tasks:

· instruct the control to retrieve tag contents through a call to the SoundInfoGet 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 generate the EV_META_CHANGED 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 the CallbackForPlayersEvents delegate would be invoked with the nEvent parameter set to EV_DOWNLOAD_COMPLETE 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 EV_STREAM_LOADED event is immediately followed by the EV_STREAM_LOADED_FROM_INET_PLS event which reports the URL of the loaded stream.
· In case the connection should fail the EV_STREAM_LOADED event would report the failure only if all of the streams contained inside the playlist should fail while the EV_STREAM_LOADED_FROM_INET_PLS event would be fired for each failing URL.
· EV_SERVER_CLOSED event would be fired only when executing the latest entry inside the playlist

A sample of access to Internet streams in Visual C# and Visual Basic.NET 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 can already use your own or third-party encryption/decryption schemas and load decrypted song's data through the LoadSoundFromMemory method; Audio Dj Studio API for .NET comes now with a 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 Audio Dj Studio API for .NET 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 Audio Sound Editor API for .NET component in place of Audio Dj Studio API for .NET.

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 through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to:

· EV_WAV_EXPORT_START invoked once at the beginning
· EV_WAV_EXPORT_PERC invoked multiple times reporting the current advancement percentage inside the nData1 parameter
· EV_WAV_EXPORT_COMPLETE invoked as soon as the exporting session is completed

As you will understand, the EV_WAV_EXPORT_COMPLETE event will notify the container application about the exported WAV file availability and will report, inside the nData1 parameter, 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 Audio Sound Recorder API for .NET

How to load and play sounds recorded by Audio Sound Recorder API for .NET

Return to chapter overview

Audio DJ Studio API for .NET can be integrated with an existing instance of Audio Sound Recorder API for .NET in order to reproduce sounds coming from one of the available input devices.

When instancing both components inside the same form, it's highly recommended initializing Audio DJ Studio first, through a call to the InitSoundSystem method and then initializing Audio Sound Recorder API through its InitRecordingSystem 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 Audio Sound Recorder API for .NET, recorded sound data will remain available inside a memory buffer or, in alternative, inside a file on the hard-disk: Audio DJ Studio API for .NET 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 Audio Sound Recorder API for .NET is still storing recorded sound data inside a file on the hard-disk, Audio DJ Studio API for .NET can obtain and load available 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.

It's important to note that this latest 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, the container application is notified through the CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to EV_CDDB_SERVERS_AVAIL: 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, the container application is notified through the CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to EV_CDDB_ALBUM_INFO_AVAIL: 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 CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to:

· EV_CD_COVER_URLS_AVAIL: 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.
· EV_CD_COVER_SMALL_FILE_AVAIL, EV_CD_COVER_MEDIUM_FILE_AVAIL and EV_CD_COVER_LARGE_FILE_AVAIL: notify that a certain CD cover picture has been downloaded from 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 container application is notified through the CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to:

· EV_CDDB_ALBUM_INFO_AVAIL: 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.
· EV_CD_COVER_URLS_AVAIL: 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.
· EV_CD_COVER_SMALL_FILE_AVAIL, EV_CD_COVER_MEDIUM_FILE_AVAIL and EV_CD_COVER_LARGE_FILE_AVAIL: notify that 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 C# and Visual Basic.NET can be found inside the following sample installed with the product's setup package:

- SoundInfo

- CdPlayerWithCddb


How to get pictures of CD covers

Copyright © 2005-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

Audio Dj Studio API for .NET 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 DelayedPlaybackMan class.

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 method
· by setting a specific date and time through the DelayedPlayback.ListAddItemByDate method

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>

Audio 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 through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_LRC_FILE_AVAILABLE which also reports, inside the nData1 parameter, 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.

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, Audio DJ Studio will automatically generate the CallbackForPlayersEvents delegate with the nEvent parameter set to one of the following values that will allow the container application and the playing sound to be synchronized with lyrics:

· Incoming Line Time Tags are reported by the EV_LRC_ADVANCETIME_FULL_LINE event which 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 EV_LRC_REALTIME_FULL_LINE event: 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 EV_LRC_REALTIME_PORTION_LINE event which 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 EV_LRC_ADVANCETIME_FULL_LINE event and the advance time used to fire the EV_LRC_REALTIME_FULL_LINE and EV_LRC_REALTIME_PORTION_LINE events; both timings are expressed in milliseconds and, by default, the EV_LRC_ADVANCETIME_FULL_LINE event is fired with an advance of 2000 milliseconds (2 seconds) while the EV_LRC_REALTIME_FULL_LINE and EV_LRC_REALTIME_PORTION_LINE events are fired with an advance of 20 milliseconds. Current settings can be obtained through the LrcNotifTimingsGet method.


How to access BASS library functionalities directly

How to access BASS library functionalities directly

For some of its many features, Audio Dj Studio API for .NET 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# and VB.NET code where we need to access, directly from our code, the BASS_ChannelSetAttribute function exported by BASS.DLL: In order to access these functions directly from your code, you will need to make some modification to your code; for gaining access to the GetProcAddress Windows API, you need to add the following statemens:

Visual Basic .NET

Imports System.Runtime.InteropServices

<DllImport("kernel32.dll")> _

Public Shared Function GetProcAddress(ByVal hModule As IntPtr, ByVal procedureName As String) As IntPtr

End Function

Visual C#

using System.Runtime.InteropServices;

[DllImport("kernel32.dll")]

public static extern IntPtr GetProcAddress(IntPtr hModule, string procedureName);

now we need to define the prototype of the BASS_ChannelSetAttribute function exported by BASS.DLL

Visual Basic .NET

<UnmanagedFunctionPointer(CallingConvention.Cdecl)> _

Private Delegate Function funcBASS_ChannelSetAttribute(ByVal handle As Int32, ByVal attrib As Int32, ByVal value As Single) As Int32

Private BASS_ChannelSetAttribute As funcBASS_ChannelSetAttribute

Visual C#

[UnmanagedFunctionPointer(CallingConvention.Cdecl)]

private delegate Int32 funcBASS_ChannelSetAttribute(Int32 handle, Int32 attrib, float value);

funcBASS_ChannelSetAttribute BASS_ChannelSetAttribute;

at this point we use GetProcAddress to get the address of the BASS_ChannelSetAttribute function, and we use the returned value in conjunction with the GetDelegateForFunctionPointer static method within the Marshal class to assign this address to a delegate that we have just defined.

Visual Basic .NET

Private Sub LoadBassFunction()

Dim hModule As Int32 = 0

audioDjStudio1.BassModuleGet(enumBassModules.MODULE_BASS, hModule)

BASS_ChannelSetAttribute = CType(Marshal.GetDelegateForFunctionPointer( _

GetProcAddress(New IntPtr(hModule), "BASS_ChannelSetAttribute"), _

GetType(funcBASS_ChannelSetAttribute)), funcBASS_ChannelSetAttribute)

End Sub

Visual C#

private void LoadBassFunction()

{

Int32 hModule = 0;

audioDjStudio1.BassModuleGet(enumBassModules.MODULE_BASS, ref hModule);

BASS_ChannelSetAttribute = (funcBASS_ChannelSetAttribute) Marshal.GetDelegateForFunctionPointer(

GetProcAddress((IntPtr)hModule, "BASS_ChannelSetAttribute"),

typeof(funcBASS_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:

Visual Basic .NET

Private Sub button1_Click(ByVal sender As Object, ByVal e As EventArgs) Handles button1.Click

Dim hStream As Int32 = 0

audioDjStudio1.BassStreamGet(0, hStream)

BASS_ChannelSetAttribute(hStream, BASS_ATTRIB_VOL, 0.5f)

End Sub

Visual C#

private void button1_Click(object sender, EventArgs e)

{

Int32        hStream = 0;

audioDjStudio1.BassStreamGet(0, ref 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 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, Audio Dj Studio API for .NET 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

Audio Dj Studio API for .NET 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_SILENCE_AVAIL.

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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_SILENCE_AVAIL.

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 the silence detection.

Differently from the 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_SILENCE_DETECTION having the nData1 parameter set to "true" and, when the silent portions ends and new audible samples are met, with the nEvent parameter set again to EV_SILENCE_DETECTION but with the nData1 parameter set to "false".

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.

During the download session, the container application is notified about the advancement through the CallbackForDownloaderEvents delegate which is invoked with the nEvent parameter set to one of the following values:

- the EV_DOWNLOADER_SESSION_STARTED event reports that the downloading session is started

- the EV_DOWNLOADER_SESSION_PROGRESS event informs about the download advancement expressed in percentage

- the EV_DOWNLOADER_SESSION_COMPLETED event reports that the downloading session is completed successfully

- the EV_DOWNLOADER_SESSION_FAILED event reports that the connection to the remote server or the access to the remote file failed

- the EV_DOWNLOADER_SESSION_STOPPED 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 EV_DOWNLOADER_SESSION_COMPLETED event, a further couple of events may be generated:

- the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_LOADED reporting 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 CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_INVALID_FILE reporting 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 MediaFileDecoderMan class 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 small piece of code (please, note that for simplicity the code below misses error checking):

C#

// create the decode stream

audioDjStudio1.MediaFileDecoder.FileOpen(@"c:\myfile.mp3");

// allocate the buffer that will receive uncompressed samples

byte[] buffer = new byte[20000];

// get the total length of the uncompressed audio track: we will use it for determining the current percentage

Int64 nFileLength = 0;

audioDjStudio1.MediaFileDecoder.FileLengthGet(ref nFileLength);

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

   audioDjStudio1.MediaFileDecoder.FileDataGet(buffer, 20000, enumDataTypes.DATA_TYPE_NATIVE, ref nBytesRead);

   // do something with the returned buffer

   [ ... ]

   // calculate the current percentage of advancement: may be useful to drive a progress bar

   nTotalBytesRead += nBytesRead;

   Int64 nPercentage = (nTotalBytesRead * 100) / nFileLength;

   // in case you want to stop/exit...

   Application.DoEvents ();

}

while (nBytesRead != 0);

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.NET

' prepare the audio stream to compose on player 0 (44100, stereo)

audioDjStudio1.SoundGenerator.StreamCreateMultiChannelEmpty (Player_0, 44100, 2)

Dim nDummyUniqueId As Int32 = 0

' add the first 3 seconds long sine tone on left channel of the stream (400 hz on channel 0)

Dim nSpeaker As Integer = 0

audioDjStudio1.SoundGenerator.StreamChannelAddTone (Player_0, _

              enumSoundGenWaveTypes.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)

audioDjStudio1.SoundGenerator.StreamChannelAddTone Player_0, _

              enumSoundGenWaveTypes.SOUNDGEN_WAVE_TYPE_SINE, nSpeaker+1, 480, 1, 3000, 0, nDummyUniqueId

' play the stream

audioDjStudio1.PlaySound Player_0

Visual C#

// prepare the audio stream to compose on player 0 (44100, stereo)

audioDjStudio1.SoundGenerator.StreamCreateMultiChannelEmpty (Player_0, 44100, 2);

Int32 nDummyUniqueId = 0;

// add the first 3 seconds long sine tone on left channel of the stream (400 hz on channel 0)

int nSpeaker = 0;

audioDjStudio1.SoundGenerator.StreamChannelAddTone (Player_0,

              enumSoundGenWaveTypes.SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 400, 1, 3000, 0, ref nDummyUniqueId);

// add the second 3 seconds long sine tone on right channel of the stream (480 hz on channel 1)

audioDjStudio1.SoundGenerator.StreamChannelAddTone (Player_0,

              enumSoundGenWaveTypes.SOUNDGEN_WAVE_TYPE_SINE, nSpeaker+1, 480, 1, 3000, 0, ref nDummyUniqueId);

// play the stream

audioDjStudio1.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.NET

' prepare the audio stream to compose on player 0 (44100, stereo)

audioDjStudio1.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

   audioDjStudio1.SoundGenerator.StreamChannelAddTone (Player_0, _

              enumSoundGenWaveTypes.SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 400, 1, 3000, 0, nDummyUniqueId)

   ' add a 3 seconds long 480 hz sine tone on the current channel

   audioDjStudio1.SoundGenerator.StreamChannelAddTone (Player_0, _

              enumSoundGenWaveTypes.SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 480, 1, 3000, 0, nDummyUniqueId)

Next nSpeaker

' play the stream

audioDjStudio1.PlaySound (Player_0)

Visual C#

' prepare the audio stream to compose on player 0 (44100, stereo)

audioDjStudio1.SoundGenerator.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

   audioDjStudio1.SoundGenerator.StreamChannelAddTone (Player_0,

              enumSoundGenWaveTypes.SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 400, 1.0f, 3000, 0, ref nDummyUniqueId);

   // add a 3 seconds long 480 hz sine tone on the current channel

   audioDjStudio1.SoundGenerator.StreamChannelAddTone (Player_0,

              enumSoundGenWaveTypes.SOUNDGEN_WAVE_TYPE_SINE, nSpeaker, 480, 1.0f, 3000, 0, ref nDummyUniqueId);

}

// play the stream

audioDjStudio1.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 words of text 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.NET 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

Audio DJ Studio API for .NET 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 CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_DONE is invoked.

· 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 CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUNDCOMPOSER_SOUNDSTART. 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 CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUNDCOMPOSER_SOUNDDONE.

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

audioDjStudio1.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

audioDjStudio1.SoundComposer.ItemSoundFileAdd (Player_1, "First sound", 0, _

                 "c:\myfolder\myfile1.mp3", False, 0, 10000, 40000, nUniqueIdFile1)

audioDjStudio1.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

audioDjStudio1.SoundComposer.ItemSoundFileVolumeSmoothingSet (Player_1, nUniqueIdFile1, 2000, 3000)

audioDjStudio1.SoundComposer.ItemSoundFileVolumeSmoothingSet (Player_1, nUniqueIdFile2, 2000, 3000)

' start playback of the final audio stream

audioDjStudio1.PlaySound (Player_1)

Visual C#

// create the audio stream on a specific player (44100, stereo)

audioDjStudio1.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;

audioDjStudio1.SoundComposer.ItemSoundFileAdd (Player_1, "First sound", 0,

                 @"c:\myfolder\myfile1.mp3", false, 0, 10000, 40000, ref nUniqueIdFile1);

audioDjStudio1.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

audioDjStudio1.SoundComposer.ItemSoundFileVolumeSmoothingSet (Player_1, nUniqueIdFile1, 2000, 3000);

audioDjStudio1.SoundComposer.ItemSoundFileVolumeSmoothingSet (Player_1, nUniqueIdFile2, 2000, 3000);

// start playback of the final audio stream

audioDjStudio1.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)

audioDjStudio1.SoundComposer.SessionCreate (Player_1, 44100, 2)

Dim nUniqueIdFile1 As Int32 = 0

Dim nUniqueIdFile2 As Int32 = 0

' add the first sound files

audioDjStudio1.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

audioDjStudio1.SoundComposer.ItemAppendNext (Player_1, nUniqueIdFile1l, 2000)

' append the second item to the previous one

audioDjStudio1.SoundComposer.ItemSoundFileAdd (Player_1, "Second sound", 0, _

                 "c:\myfolder\myfile2.wma", False, 0, 0, -1, nUniqueIdFile2)

' start playback of the final audio stream

audioDjStudio1.PlaySound (Player_1)

Visual C#

// create the audio stream on a specific player (44100, stereo)

audioDjStudio1.SoundComposer.SessionCreate (Player_1, 44100, 2);

// add the two sound files and obtain respective unique identifiers

Int32 nUniqueIdFile1 = 0;

Int32 nUniqueIdFile2 = 0;

audioDjStudio1.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

audioDjStudio1.SoundComposer.ItemAppendNext (Player_1, nUniqueIdFile1, 2000);

// append the second item to the previous one

audioDjStudio1.SoundComposer.ItemSoundFileAdd (Player_1, "Second sound", 0,

                 @"c:\myfolder\myfile2.wma", false, 0, 0, -1, ref nUniqueIdFile2);

// start playback of the final audio stream

audioDjStudio1.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)

audioDjStudio1.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)

audioDjStudio1.SoundComposer.ItemSpeechFromStringAdd (Player_1, "", nChannel, _

                 "This is a string of text to speech", 0, True, 1, 0, nDummyUniqueId)

audioDjStudio1.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

audioDjStudio1.PlaySound (Player_1)

Visual C#

// create the audio stream on a specific player (44100, stereo)

audioDjStudio1.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)

audioDjStudio1.SoundComposer.ItemSpeechFromStringAdd (Player_1, "", nChannel,

                 "This is a string of text to speech", 0, True, 1, 0, ref nDummyUniqueId);

audioDjStudio1.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

audioDjStudio1.PlaySound (Player_1);

A sample of usage of the sound composer object in Visual Basic.NET and Visual C# 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 ZipMan class 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 about the current percentage of advancement through the CallbackZipOperationPerc delegate.

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 ZipMan class in Visual C#.NET and Visual Basic.NET can be found inside the following samples installed with the product's setup package:

- ZipPlayer


How to use enumerated types

How to use enumerated types

The use of enumerated types improves the readability of your code and, thanks to the features offered by Microsoft's Intellisense, will ease the coding phase.

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
enumPlayerStatus | return value of GetPlayerStatus method
enumScaleUnits | ScaleUnits
enumFileTypes | nFileType property of the SoundInfo class and nFormat parameter of the LoadInternetStreamWithFormat method
enumTagId3Versions | nMP3TagVersion property of the SoundInfo class
enumTagTypes | nTagType parameter of the IsTagAvailable and GetTagString methods
enumTagFields | nField parameter of the GetFileTagField method
enumPlayListModes | nMode parameter of the PlayListLoad and PlayListCreatEx methods
enumPlayListFormats | nFormat parameter of the PlayListSave method
enumPlayListStrings | nString parameter of the PlayListGetItemString method
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
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 | SetEAXEffect method
enumWaveformResolutions | Waveform.AnalyzeFullSound method
enumWaveformTypes | Waveform.BitmapViewSaveToFile and Waveform.BitmapViewSaveToMemory methods
enumSpeakersConfig | GetOutputSpeakersConfig and SetOutputSpeakersConfig methods
enumSpeakers | nSpeaker parameter of the StreamOutputSpeakerSet, Effects.PreAmplifierSpeakerValueGet and Effects.reAmplifierSpeakerValueSet 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
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 Effects.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 Effects.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 Effects.FilterApply method
enumFilterTypes | nFilterType parameter of the Effects.FilterApply method
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 TagsReader.ALL_AnalyzeSoundOnPlayer and TagsReader.ALL_AnalyzeSoundFile methods
enumTagFields | nField parameter of the TagsReader.ALL_CommonFrameGet, TagsReader.ID3V1_FieldGet, TagsReader.APE_TextFieldGet, TagsReader.LYRICS3_TextFieldGet methods
enumMp4Frames | nFrameId parameter of the TagsReader.MP4_TextFrameGet method
enumOggFrames | nFrameId parameter of the TagsReader.OGG_TextFrameGet method
enumId3v2FrameInfo | nInfo parameter of the TagsReader.ID3V2_PictureFrameInfoGet, TagsReader.ID3V2_CommentFrameInfoGet, TagsReader.ID3V2_SynchLyricsFrameInfoGet, TagsReader.ID3V2_GeneralObjectFrameInfoGet, TagsReader.ID3V2_UnsynchLyricsFrameInfoGet, TagsReader.FLAC_PictureFrameInfoGet, TagsReader.WMA_PictureFrameInfoGet methods
enumId3v2PictureType | nPictureType parameter of the TagsReader.ID3V2_PictureFrameTypeGet, TagsReader.WMA_PictureFrameTypeGet, TagsReader.FLAC_PictureFrameTypeGet methods
enumId3v2ReceivedAsType | nReceivedAs parameter of the TagsReader.ID3V2_CommercialFrameReceivedAsGet method
enumId3v2CommercialInfo | nInfo parameter of the TagsReader.ID3V2_CommercialFrameInfoGet method
enumId3v2SyncLyricsType | nLyricsType parameter of the TagsReader.ID3V2_SynchLyricsFrameInfoNumGet method
enumId3v2TimeStampFormats | nTimeStampFormat parameter of the TagsReader.ID3V2_SynchLyricsFrameInfoNumGet, TagsReader.ID3V2_EventTimingsFrameEventCountGet methods
enumId3v2OwnershipInfo | nInfo parameter of the TagsReader.ID3V2_OwnershipFrameInfoGet method
enumId3v2EventTimingTypes | nEventTimingType parameter of the TagsReader.ID3V2_EventTimingsFrameEventInfoGet method
enumBextChunkField | nFieldId parameter of the TagsReader.WAV_BextChunkTextFieldGet method
enumBextChunkBinaryField | nFieldId parameter of the TagsReader.WAV_BextChunkBinaryFieldGet method
enumCartChunkTextField | nFieldId parameter of the TagsReader.WAV_CartChunkTextFieldGet method
enumCartChunkTimeMarkerField | nFieldId parameter of the TagsReader.WAV_CartChunkTimeMarkerFieldGet method
enumCoreAudioDeviceStates | nStateMask parameter of the CoreAudio.Enum method
enumCoreAudioDataFlows | nDataFlow parameter of most methods of the CoreAudioDevicesMan class
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 MIDI.MarkersEnableNotifications, MIDI.MarkersEnum and MIDI:MarkersEnumItemGet methods.
enumMidiStreamEvents | nMidiEvent parameter 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
enumCommonDialogInfo | nInfo parameter of the CommonDialogGetInfoFromLastOpen and CommonDialogGetInfoFromLastSave methods
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 enumerated types in your code. These examples assume that one instance of the control, named AudioDjStudio1, exists on a form. The purpose of this sample code is to check if a certain player is in paused state.

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual Basic.NET

After typing the code...

if (audioDjStudio1.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 AudioDjStudio.enumPlayerStatus.SOUND_PAUSED value so the complete line of code will be:

If (AudioDjStudio1.GetPlayerStatus(0) = AudioDjStudio.enumPlayerStatus.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, you must add the components namespace to your code so the following line must be inserted at the beginning of the form management file:

using AudioDjStudio;

After typing the code...

if (audioDjStudio1.GetPlayerStatus (0) = enumPlayerStatus

press the "." key on your keyboard. Note that to use Intellisense, you must add enumPlayerStatus after the equal sign in order to trigger the enumPlayerStatus enumerated type. After typing a period, Intellisense is activated.

Select the SOUND_PAUSED value so the complete line of code will be:

if (audioDjStudio1.GetPlayerStatus (0) = enumPlayerStatus.SOUND_PAUSED)

   // do something

   ....

else

   // do something else

   ....


ASIO property (RO)

ASIO property (RO)

 Return to chapter overview

Type

[Visual Basic]

Public Property ASIO As ASIOMan

[C#]

public ASIOMan ASIO {get;}

[C++]

public: __property ASIOMan* get_ASIO ();

This property is Read-only

Remarks

The object used to manage ASIO drivers.

This property encapsulates the functionality of the ASIOMan class.

Further information about the use ASIO drivers can be found inside the How to manage ASIO drivers tutorial.


CoreAudioDevices property (RO)

CoreAudioDevices property (RO)

 Return to chapter overview

Type

[Visual Basic]

Public Property CoreAudioDevices As CoreAudioDevicesMan

[C#]

public CoreAudioDevicesMan CoreAudioDevices {get;}

[C++]

public: __property CoreAudioDevicesMan* get_CoreAudioDevices ();

This property is Read-only

Remarks

The object used to manage specific functionalities of audio devices inside Windows Vista and later versions.

This property encapsulates the functionality of the CoreAudioDevicesMan class.

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.


BufferLength property

BufferLength property

Type

[Visual Basic]

Public Property BufferLength As Int16

[C#]

public Int16 BufferLength {get; set;}

[C++]

public: __property Int16 get_BufferLength();

public: __property void set_BufferLength(Int16);

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

[Visual Basic]

Public Property BufferUpdateTime As Int16

[C#]

public Int16 BufferUpdateTime {get; set;}

[C++]

public: __property Int16 get_BufferUpdateTime();

public: __property void set_BufferUpdateTime(Int16);

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

[Visual Basic]

Public Property CheckOutputDevicesLatency As Boolean

[C#]

public bool CheckOutputDevicesLatency {get; set;}

[C++]

public: __property bool get_CheckOutputDevicesLatency();

public: __property void set_CheckOutputDevicesLatency(bool);

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:

Value | Meaning
false (default) | The sound card drivers latency time won't be calculated
true | The sound card drivers latency time will be calculated: this will require the InitSoundSystem method a longer time to execute.

NOTE: This property can be set at Design-time only: changes made at Runtime will be simply ignored.


CustomDSP property (RO)

CustomDSP property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property CustomDSP As CustomDSPs

[C#]

public CustomDSPs CustomDSP {get;}

[C++]

public: __property CustomDSPs* get_CustomDSP ();

This property is Read-only

Remarks

The object used to manage custom DSPs.

This property encapsulates the functionality of the CustomDSPs class.

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

[Visual Basic]

Public Property DelayedPlaybackMan As DelayedPlayback

[C#]

public DelayedPlaybackMan DelayedPlayback {get;}

[C++]

public: __property DelayedPlaybackMan* get_DelayedPlayback ();

This property is Read-only

Remarks

The object used for managing delayed playbacks.

This property encapsulates the functionality of the DelayedPlaybackMan class.

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

[Visual Basic]

Public Property DownloaderDj As Downloader

[C#]

public DownloaderDj Downloader {get;}

[C++]

public: __property DownloaderDj* get_Downloader ();

This property is Read-only

Remarks

The object used for managing download sessions.

This property encapsulates the functionality of the DownloaderDj class.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.


DisplayOscilloscope property (RO)

DisplayOscilloscope property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property DisplayOscilloscope As Oscilloscope

[C#]

public Oscilloscope DisplayOscilloscope {get;}

[C++]

public: __property Oscilloscope* get_DisplayOscilloscope ();

This property is Read-only

Remarks

The embedded Oscilloscope object (Visual Feedback).

This property encapsulates the functionality of the Oscilloscope class.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


DisplaySpectrum property (RO)

DisplaySpectrum property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property DisplaySpectrum As Spectrum

[C#]

public Spectrum DisplaySpectrum {get;}

[C++]

public: __property Spectrum* get_DisplaySpectrum ();

This property is Read-only

Remarks

The embedded Spectrum object (Visual Feedback).

This property encapsulates the functionality of the Spectrum class.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


DisplaySpectrumEnh property (RO)

DisplaySpectrumEnh property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property DisplaySpectrumEnh As SpectrumEnh

[C#]

public SpectrumEnh DisplaySpectrumEnh {get;}

[C++]

public: __property SpectrumEnh* get_DisplaySpectrumEnh ();

This property is Read-only

Remarks

The embedded Spectrum object (Visual Feedback).

This property encapsulates the functionality of the SpectrumEnh class.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

For details about using other Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.


DisplayVideoMixer property (RO)

DisplayVideoMixer property (RO)

 Return to chapter overview

Type

[Visual Basic]

Public Property DisplayVideoMixer As VideoMixer

[C#]

public VideoMixer DisplayVideoMixer {get;}

[C++]

public: __property VideoMixer* get_DisplayVideoMixer ();

This property is Read-only

Remarks

The embedded player of video files.

This property encapsulates the functionality of the VideoMixer class.

For details about video mixing refer to the How to use the video mixer tutorial.


DisplayVideoPlayer property (RO)

DisplayVideoPlayer property (RO)

 Return to chapter overview

Type

[Visual Basic]

Public Property DisplayVideoPlayer As VideoPlayer

[C#]

public VideoPlayer DisplayVideoPlayer {get;}

[C++]

public: __property VideoPlayer* get_DisplayVideoPlayer ();

This property is Read-only

Remarks

The embedded player of video files.

This property encapsulates the functionality of the VideoPlayer class.

For details about video clips rendering refer to the How to play video files through DirectShow section.


DisplayVUMeter property (RO)

DisplayVUMeter property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property DisplayVUMeter As VUMeter

[C#]

public VUMeter DisplayVUMeter {get;}

[C++]

public: __property VUMeter* get_DisplayVUMeter ();

This property is Read-only

Remarks

The embedded VU-Meter object (Visual Feedback).

This property encapsulates the functionality of the VUMeter class

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


DisplayWaveform property (RO)

DisplayWaveform property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property DisplayWaveform As Waveform

[C#]

public Waveform DisplayWaveform {get;}

[C++]

public: __property Waveform* get_DisplayWaveform ();

This property is Read-only

Remarks

The embedded Waveform display object (Visual Feedback).

This property encapsulates the functionality of the Waveform class.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section


DisplayWaveformScroller property (RO)

DisplayWaveformScroller property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property DisplayWaveformScroller As WaveformScroller

[C#]

public WaveformScroller DisplayWaveformScroller {get;}

[C++]

public: __property WaveformScroller* get_DisplayWaveformScroller ();

This property is Read-only

Remarks

The embedded Waveform scroller display object.

This property encapsulates the functionality of 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.


Effects property (RO)

Effects property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property Effects As EffectsMan

[C#]

public EffectsMan Effects {get;}

[C++]

public: __property EffectsMan* get_Effects ();

This property is Read-only

Remarks

The object used to manage special effects to apply to loaded sounds.

This property encapsulates the functionality of the EffectsMan class.

See the How to apply special effects to a playing sound section for further details.


EnableAutoEqualiz property

EnableAutoEqualiz property

Type

[Visual Basic]

Public Property EnableAutoEqualiz As Boolean

[C#]

public bool EnableAutoEqualiz {get; set;}

[C++]

public: __property bool get_EnableAutoEqualiz();

public: __property void set_EnableAutoEqualiz(bool);

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

[Visual Basic]

Public Property EnableMixingFeatures As Boolean

[C#]

public bool EnableMixingFeatures {get; set;}

[C++]

public: __property bool get_EnableMixingFeatures();

public: __property void set_EnableMixingFeatures(bool);

Remarks

Boolean value that enables/disables applying mixing related settings to loaded sounds.

Supported values are the following:

Value | Meaning
false | 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) | Mixing related settings are enabled


EnableSpeakers property

EnableSpeakers property

Type

[Visual Basic]

Public Property EnableSpeakers As Boolean

[C#]

public bool EnableSpeakers {get; set;}

[C++]

public: __property bool get_EnableSpeakers();

public: __property void set_EnableSpeakers(bool);

Remarks

Boolean value that enables/disables speakers assignment.

Supported values are the following:

Mnemonic Value | Meaning
false (default) | Speakers assignment disabled
true | 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

[Visual Basic]

Public Property Fader As FaderObject

[C#]

public FaderObject Fader {get;}

[C++]

public: __property FaderObject* get_Fader ();

This property is Read-only

Remarks

The embedded Automatic Fader object.

This property encapsulates the functionality of the FaderObject class.

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

[Visual Basic]

Public Property GraphicBarsManager As GraphicBarsMan

[C#]

public GraphicBarsMan GraphicBarsManager {get;}

[C++]

public: __property GraphicBarsMan* get_GraphicBarsManager ();

This property is Read-only

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 GraphicBarsMan class.

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

[Visual Basic]

Public Property LastError As enumErrorCodes

[C#]

public enumErrorCodes LastError {get;}

[C++]

public: __property enumErrorCodes get_LastError();

This property is Read-only

Remarks

Each call to one of the component's methods could generate an error: in case the called method should return an unexpected value, this property could give more details about the nature of the error. 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 Audio 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 | The function name is invalid
ERR_INVALID_PLUGIN | -190 | The requested plugin is invalid
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

[Visual Basic]

Public Property MediaFileDecoder As MediaFileDecoderMan

[C#]

public MediaFileDecoderMan MediaFileDecoder {get;}

[C++]

public: __property MediaFileDecoderMan* get_MediaFileDecoder ();

This property is Read-only

Remarks

The object used for managing decoding of media files in various formats.

This property encapsulates the functionality of the MediaFileDecoderMan class.

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

[Visual Basic]

Public Property MIDI As MIDIMan

[C#]

public MIDIMan MIDI {get;}

[C++]

public: __property MIDIMan* get_MIDI ();

This property is Read-only

Remarks

The object used to manage MIDI protocol.

This property encapsulates the functionality of the MIDIMan class and the IMIDI COM interface.

Further information about management of MIDI protocol can be found inside the How to deal with MIDI protocol tutorial.


ScaleUnits property

ScaleUnits property

Type

[Visual Basic]

Public Property ScaleUnits As enumScaleUnits

[C#]

public enumScaleUnits ScaleUnits {get; set;}

[C++]

public: __property enumScaleUnits get_ScaleUnits();

public: __property void set_ScaleUnits(enumScaleUnits);

Remarks

The unit used to seek into the loaded sound when dealing with the SeekSound and PlaySound methods.

Supported values are the following:

Mnemonic value | Value | Meaning
SCALE_MILLISECONDS (default) | 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

[Visual Basic]

Public Property SoundComposer As SoundComposerMan

[C#]

public SoundComposerMan SoundComposer {get;}

[C++]

public: __property SoundComposerMan* get_SoundComposer ();

This property is Read-only

Remarks

The embedded sound composer.

This property encapsulates the functionality of the SoundComposerMan class.

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

[Visual Basic]

Public Property SoundGenerator As SoundGeneratorMan

[C#]

public SoundGeneratorMan SoundGenerator {get;}

[C++]

public: __property SoundGeneratorMan* get_SoundGenerator ();

This property is Read-only

Remarks

The embedded sound generator object.

This property encapsulates the functionality of the SoundGeneratorMan class.

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

SoundsDirectory property

Type

[Visual Basic]

Public Property SoundsDirectory As String

[C#]

public string SoundsDirectory {get; set;}

[C++]

public: __property String* get_SoundsDirectory();

public: __property void set_SoundsDirectory(String*);

Remarks

The string containing the directory path from which the LoadSound method will load, by default, the sound files.


TagsReader property (RO)

TagsReader property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property TagsReader As TagsReaderMan

[C#]

public TagsReaderMan TagsReader {get;}

[C++]

public: __property TagsReaderMan* get_TagsReader ();

This property is Read-only

Remarks

The embedded editor of tag information.

This property encapsulates the functionality of the TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.


VolumeAutomation property (RO)

VolumeAutomation property (RO)

 Return to chapter overview

Type

[Visual Basic]

Public Property VolumeAutomation As VolumeAutomationMan

[C#]

public VolumeAutomationMan VolumeAutomation {get;}

[C++]

public: __property VolumeAutomationMan* get_VolumeAutomation ();

This property is Read-only

Remarks

The object used to manage Volume Automation.

This property encapsulates the functionality of the VolumeAutomationMan class.

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

[Visual Basic]

Public Property VST As VSTs

[C#]

public VSTs VST {get;}

[C++]

public: __property VSTs* get_VST ();

This property is Read-only

Remarks

The object used to manage VST effects.

This property encapsulates the functionality of the VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.


WASAPI property (RO)

WASAPI property (RO)

 Return to chapter overview

Type

[Visual Basic]

Public Property WASAPI As WASAPIMan

[C#]

public WASAPIMan WASAPI {get;}

[C++]

public: __property WASAPIMan* get_WASAPI ();

This property is Read-only

Remarks

The object used to manage audio flow through WASAPI.

This property encapsulates the functionality of the WASAPIMan class.

Further information about WASAPI can be found inside the How to manage audio flow through WASAPI tutorial.


ZIP property (RO)

ZIP property (RO)

 Return to chapter overview

Type

[Visual Basic]

Public Property ZIP As ZipMan

[C#]

public ZipMan ZIP {get;}

[C++]

public: __property ZipMan* get_ZIP ();

This property is Read-only

Remarks

The object used to manage ZIP files.

This property encapsulates the functionality of the ZipMan class.

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 component.

Syntax

[Visual Basic]

Public Sub AboutBox (

)

[C#]

public void AboutBox (

);

[C++]

public: void 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]

Public Sub AudioExtensionAdd (

strExtension as string

)

[C#]

public void AudioExtensionAdd (

string strExtension

);

[C++]

public: void AudioExtensionAdd (

string 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 InitSoundSystem 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]

Public Function BassModuleGet (

nModule as enumBassModules,

ByRef hModule as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes BassModuleGet (

enumBassModules nModule,

ref Int32 hModule

);

[C++]

public: enumErrorCodes BassModuleGet (

enumBassModules nModule,

Int32 __gc *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]

Public Function BassPluginStreamCreateFunc (

strPluginPathname as string,

strFuncName as string,

nType as enumBassPluginStreamCreateFuncs

) as enumErrorCodes

[C#]

public enumErrorCodes BassPluginStreamCreateFunc (

string strPluginPathname,

string strFuncName,

enumBassPluginStreamCreateFuncs nType

);

[C++]

public: enumErrorCodes BassPluginStreamCreateFunc (

string strPluginPathname,

string strFuncName,

enumBassPluginStreamCreateFuncs 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]

Public Function BassStreamGet (

nPlayerIndex as Int16,

ByRef hStream as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes BassStreamGet (

Int16 nPlayerIndex,

ref Int32 hStream

);

[C++]

public: enumErrorCodes BassStreamGet (

Int16 nPlayerIndex,

Int32 __gc *hStream

);

Parameter | Description
nPlayerIndex | 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.


COMEventsEnable method

COMEventsEnable method

Remarks

Enables management of COM events for legacy COM clients like Visual Basic 6 which are not fully compatible with the usage.of delegates and callbacks.

See the Events for Visual Basic 6 COM interoperability section for the full list of available events.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic]

Public Sub COMEventsEnable (

)

[C#]

public void COMEventsEnable (

);

[C++]

public: void COMEventsEnable (

);


CommonDialogGetInfoFromLastOpen method

CommonDialogGetInfoFromLastOpen method

Remarks

Obtains further information about the file chosen through a previous call to the CommonDialogShowOpen method.

Syntax

[Visual Basic]

Public Function CommonDialogGetInfoFromLastOpen (

nInfo as enumCommonDialogInfo

) as String

[C#]

public string CommonDialogGetInfoFromLastOpen (

enumCommonDialogInfo nInfo

);

[C++]

public: string CommonDialogGetInfoFromLastOpen (

enumCommonDialogInfo 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.

Syntax

[Visual Basic]

Public Function CommonDialogGetInfoFromLastSave (

nInfo as enumCommonDialogInfo

) as String

[C#]

public string CommonDialogGetInfoFromLastSave (

enumCommonDialogInfo nInfo

);

[C++]

public: string CommonDialogGetInfoFromLastSave (

enumCommonDialogInfo 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.

Syntax

[Visual Basic]

Public Function CommonDialogShowOpen (

strDialogTitle as string,

strInitialDirectory as string,

strFilter as string,

nFilterIndex as Int32

) as String

[C#]

public string CommonDialogShowOpen (

string strDialogTitle,

string strInitialDirectory,

string strFilter,

ref Int32 nFilterIndex

);

[C++]

public: string CommonDialogShowOpen (

string strDialogTitle,

string strInitialDirectory,

string strFilter,

Int32 __gc *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. For example: "MP3 Files (*.mp3)|*.Mp3|WMA Files (*.wma)|*.wma|All Files (*.*)|*.*"
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.

Syntax

[Visual Basic]

Public Function CommonDialogShowSave (

strDialogTitle as string,

strInitialDirectory as string,

strFilter as string,

nFilterIndex as Int32

) as String

[C#]

public string CommonDialogShowSave (

string strDialogTitle,

string strInitialDirectory,

string strFilter,

ref Int32 nFilterIndex

);

[C++]

public: string CommonDialogShowSave (

string strDialogTitle,

string strInitialDirectory,

string strFilter,

Int32 __gc *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. For example: "MP3 Files (*.mp3)|*.Mp3|WMA Files (*.wma)|*.wma"
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.


ConsoleWait method

ConsoleWait method

Remarks

Utility function which allows waiting for a given amount of time when running the API from a console application.

This call avoids taking too much CPU while waiting for a keystroke without blocks on the console application.

Syntax

[Visual Basic]

Public Sub ConsoleWait (

nWaitTimeMs as Int32

)

[C#]

public void ConsoleWait (

Int32 nWaitTimeMs

);

[C++]

public: void ConsoleWait (

Int32 nWaitTimeMs

);

Parameter | Description
nWaitTimeMs | Time to wait expressed in milliseconds


ContainerIsWindowsService method

ContainerIsWindowsService method

Remarks

Utility function which informs the multimedia engine about the fact that the container application is a Windows service: without this call most of the callback delegates, notifying about events occurring during the API lifetime, will not be invoked so no synchronization will occur.

It's recommended invoking this method immediately before invoking the InitSoundSystem method ONLY when the container application is a Windows service.

For further details about using the component from a Windows service see the How to use the API in a Windows service tutorial.

Syntax

[Visual Basic]

Public Sub ContainerIsWindowsService (

)

[C#]

public void ContainerIsWindowsService (

);

[C++]

public: void ContainerIsWindowsService (

);


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]

Public Function DirectShowAutoLoadEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DirectShowAutoLoadEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes DirectShowAutoLoadEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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
false (default) | 0 | DirectShow usage is disabled
true | 1 | DirectShow usage 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


Dispose method

Dispose method

Remarks

Disposes all of the resources allocated by the API. A call to this method is recommended before exiting the container application.

Syntax

[Visual Basic]

Public Sub Dispose (

)

[C#]

public void Dispose (

);

[C++]

public: void Dispose (

);


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]

Public Function ForceSpeakersAssignment (

nOutputIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ForceSpeakersAssignment (

Int16 nOutputIndex

);

[C++]

public: enumErrorCodes ForceSpeakersAssignment (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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.


GetControlVersion method

GetControlVersion method

Remarks

Retrieves the version of the control.

Syntax

[Visual Basic]

Public Function GetControlVersion (

) as String

[C#]

public string GetControlVersion (

);

[C++]

public: string GetControlVersion (

);

Return value

String containing the control's version.


GetEngineVersion method

GetEngineVersion method

Remarks

Retrieves the version of the multimedia engine.

Syntax

[Visual Basic]

Public Function GetEngineVersion (

) as String

[C#]

public string GetEngineVersion (

);

[C++]

public: string 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 SoundInfoGet 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]

Public Function GetFileTagField (

nPlayerIndex as Int16,

nField as enumTagFields

) as Int16

[C#]

public Int16 GetFileTagField (

Int16 nPlayerIndex,

enumTagFields nField

);

[C++]

public: Int16 GetFileTagField (

Int16 nPlayerIndex,

enumTagFields nField

);

Parameter

Description

nPlayerIndex

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 | An error occurred (see the LastError property for further error details)
Valid string | The requested string


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] in which hh is for hours, mm is for minutes, ss is for seconds and ms are 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]

Public Function FromMsToFormattedTime (

fTimeInMs as double,

bShowHour as Boolean,

bShowMs as Boolean,

strHourSeparator as String,

strMsSeparator as String,

nNumberOfMsDigits as Int32

) as String

[C#]

public string FromMsToFormattedTime (

double fTimeInMs,

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits

);

[C++]

public: string FromMsToFormattedTime (

double fTimeInMs,

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits

);

Parameter

Description

fTimeInMs

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:

Value | Meaning
false | Doesn't show hour value
true | Shows hour value

bShowMs

Boolean value that specifies the player to avoid displaying the 'milliseconds' position field.

Supported values are the following:

Value | Meaning
false | Doesn't show milliseconds value
true | 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


GetMaxAvailablePlayers method

GetMaxAvailablePlayers method

Remarks

Retrieves the maximum number of players that can be allocated by the control.

Syntax

[Visual Basic]

Public Function GetMaxAvailablePlayers (

) as Int16

[C#]

public Int16 GetMaxAvailablePlayers (

);

[C++]

public: Int16 GetMaxAvailablePlayers (

);

Return value

Number representing the maximum number of players.


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]

Public Function GetMp3Tag2Data (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetMp3Tag2Data (

Int16 nPlayerIndex,

byte [] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes GetMp3Tag2Data (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
pBuffer | 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 method call was successful.

Sample

Below you can find a couple of samples that demonstrate how to load into a memory buffer the ID3V2 tag contents in Visual Basic.NET and Visual C# .

Visual Basic.NET

' declare the memory buffer (cannot be a local variable)

Dim m_byteBuffer() As Byte

Private Sub ButtonReadTag_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click

 ' load sound and obtain info

 AudioDjStudio1.LoadSound(0, "c:\mp3_sounds\bb.mp3")

 AudioDjStudio1.ReadSoundInfo2(0)

 ' check if the ID3V2 tag is available

 If AudioDjStudio1.IsTagAvailable(0, AudioDjStudio.enumTagTypes.TAGTYPE_ID3V2) > 0 Then

     ' get the tag size in bytes

     Dim nTagLength As Int32

     nTagLength = AudioDjStudio1.GetMp3Tag2Size(0)

     ' allocate the receiving buffer

     ReDim m_byteBuffer(nTagLength)

     ' read tag data

     AudioDjStudio1.GetMp3Tag2Data(0, m_byteBuffer, nTagLength)

     ' now you could parse tag data

     ' .

     ' .

     ' .

 End If

End Sub

Visual C#.NET

// declare the memory buffer (cannot be a local variable)

byte[] m_byteBuffer = null;

private void buttonReadTag_Click(object sender, System.EventArgs e)

{

 // load sound and obtain info

 audioDjStudio1.LoadSound (0, "c:\\mysound.mp3");

 audioDjStudio1.ReadSoundInfo2 (0);

 // check if the ID3V2 tag is available

 if (audioDjStudio1.IsTagAvailable (0, enumTagTypes.TAGTYPE_ID3V2) > 0)

 {

     // get the tag size in bytes

     Int32  nTagLength = audioDjStudio1.GetMp3Tag2Size (0);

     // allocate the receiving buffer

     m_byteBuffer = new byte[nTagLength];

     // read tag data

     audioDjStudio1.GetMp3Tag2Data (0, m_byteBuffer, (Int32) nTagLength);

     // now you could parse tag data

     // .

     // .

     // .

 }

}


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]

Public Function GetMp3Tag2Size (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 GetMp3Tag2Size (

Int16 nPlayerIndex

);

[C++]

public: Int32 GetMp3Tag2Size (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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


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 SoundInfoGet 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]

Public Function GetTagString (

nPlayerIndex as Int16,

nTagType as enumTagTypes,

nStringIndex as Int16

) as Int16

[C#]

public Int16 GetTagString (

Int16 nPlayerIndex,

enumTagTypes nTagType,

Int16 nStringIndex

);

[C++]

public: Int16 GetTagString (

Int16 nPlayerIndex,

enumTagTypes nTagType,

Int16 nStringIndex

);

Parameter

Description

nPlayerIndex

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]

Public Function GetWavChunkBinaryInfo (

nPlayerIndex as Int16,

nInfoField as enumWavChunkBinaryInfo

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetWavChunkBinaryInfo (

Int16 nPlayerIndex,

enumWavChunkBinaryInfo nInfoField,

byte [] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes GetWavChunkBinaryInfo (

Int16 nPlayerIndex,

enumWavChunkBinaryInfo nInfoField,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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

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 method 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]

Public Function GetWavChunkNumericInfo (

nPlayerIndex as Int16,

nInfoField as enumWavChunkNumericInfo

) as Int32

[C#]

public Int32 GetWavChunkNumericInfo (

Int16 nPlayerIndex,

enumWavChunkNumericInfo nInfoField

);

[C++]

public: Int32 GetWavChunkNumericInfo (

Int16 nPlayerIndex,

enumWavChunkNumericInfo nInfoField

);

Parameter

Description

nPlayerIndex

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]

Public Function GetWavChunkStringInfo (

nPlayerIndex as Int16,

nInfoField as enumWavChunkStringInfo

) as String

[C#]

public string GetWavChunkStringInfo (

Int16 nPlayerIndex,

enumWavChunkStringInfo nInfoField

);

[C++]

public: string GetWavChunkStringInfo (

Int16 nPlayerIndex,

enumWavChunkStringInfo nInfoField

);

Parameter

Description

nPlayerIndex

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


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]

Public Function HwMixingEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes HwMixingEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes HwMixingEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

Time, expressed in milliseconds, to convert to a formatted string

bEnable

Boolean value that specifies the player to enable/disable the use of Hardware mixing.

Supported values are the following:

Value | Meaning
false | Doesn't use Hardware mixing
true | Uses Hardware mixing

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method 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]

Public Function HwMixingIsSupported (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool HwMixingIsSupported (

Int16 nPlayerIndex

);

[C++]

public: bool HwMixingIsSupported (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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


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 Audio Sound Recorder API for .NET 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]

Public Function InitDriversType (

nDriverType as enumDriverTypes

) as enumErrorCodes

[C#]

public enumErrorCodes InitDriversType (

enumDriverTypes nDriverType

);

[C++]

public: enumErrorCodes InitDriversType (

enumDriverTypes 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


InitSoundSystem method

InitSoundSystem method

Remarks

Initializes the control: the call to this 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 and 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).

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]

Public Function InitSoundSystem (

nTotalPlayers as Int16,

nOutput0 as Int16,

nOutput1 as Int16,

nOutput2 as Int16,

nOutput3 as Int16,

) As Int16

[C#]

public Int16 InitSoundSystem (

Int16 nTotalPlayers,

Int16 nOutput0,

Int16 nOutput1,

Int16 nOutput2,

Int16 nOutput3,

);

[C++]

public: Int16 InitSoundSystem (

Int16 nTotalPlayers,

Int16 nOutput0,

Int16 nOutput1,

Int16 nOutput2,

Int16 nOutput3,

);

Parameter | Description
nTotalPlayers | Number of players (*) that must be allocated by the control.
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.
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 (*)

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 InitSoundSystem method with the following parameters:

nTotalPlayers = 4 (*)

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.


InitSoundSystemEx method

InitSoundSystemEx method

Remarks

Initializes the control: the call to this 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]

Public Function InitSoundSystemEx (

nTotalPlayers as Int16,

nOutput0 as Int16,

nOutput1 as Int16,

nOutput2 as Int16,

nOutput3 as Int16,

nBufferLength as Int16

) As Int16

[C#]

public Int16 InitSoundSystemEx (

Int16 nTotalPlayers,

Int16 nOutput0,

Int16 nOutput1,

Int16 nOutput2,

Int16 nOutput3,

Int16 nBufferLength

);

[C++]

public: Int16 InitSoundSystemEx (

Int16 nTotalPlayers,

Int16 nOutput0,

Int16 nOutput1,

Int16 nOutput2,

Int16 nOutput3,

Int16 nBufferLength

);

Parameter | Description
nTotalPlayers | Number of players (*) that must be allocated by the control.
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.
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 (*)

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 InitSoundSystem method with the following parameters:

nTotalPlayers = 4 (*)

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.


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]

Public Function InternetSettingsGet (

nSetting as enumInternetSetting,

ByRef nSettingValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes InternetSettingsGet (

enumInternetSetting nSetting,

ref Int32 nSettingValue

);

[C++]

public: enumErrorCodes InternetSettingsGet (

enumInternetSetting nDriverType,

Int32 __gc *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]

Public Function InternetSettingsSet (

nSetting as enumInternetSetting,

nSettingValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes InternetSettingsSet (

enumInternetSetting nSetting,

Int32 nSettingValue

);

[C++]

public: enumErrorCodes 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]

Public Function IsDirectShowLoadedFile (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool IsDirectShowLoadedFile (

Int16 nPlayerIndex

);

[C++]

public: bool IsDirectShowLoadedFile (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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


IsDirectX8Available method

IsDirectX8Available 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]

Public Function IsDirectX8Available (

) as Boolean

[C#]

public bool IsDirectX8Available (

);

[C++]

public: bool IsDirectX8Available (

);

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]

Public Function IsEAXAvailable (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool IsEAXAvailable (

Int16 nPlayerIndex

);

[C++]

public: bool IsEAXAvailable (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player

Return value

Value | Meaning
false | EAX effects are not available on the output device associated to the given player
true | EAX effects are available on the selected output device associated to 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]

Public Function IsEAXAvailableOnOutputDevice (

nOutputIndex as Int16

) as Boolean

[C#]

public bool IsEAXAvailableOnOutputDevice

Int16 nOutputIndex

);

[C++]

public: bool IsEAXAvailableOnOutputDevice (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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


IsFromInternet method

IsFromInternet method

Remarks

Verifies if the loaded sound comes from an Internet stream or from a local file.

Syntax

[Visual Basic]

Public Function IsFromInternet (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool IsFromInternet (

Int16 nPlayerIndex

);

[C++]

public: bool IsFromInternet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player

Return value

Value | Meaning
false | The loaded song comes from a local file
true | The loaded sound comes from an Internet stream


IsShoutcast method

IsShoutcast method

Remarks

Verifies if the loaded sound (usually from an Internet stream) contains Shoutcast information

Syntax

[Visual Basic]

Public Function IsShoutcast (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool IsShoutcast (

Int16 nPlayerIndex

);

[C++]

public: bool IsShoutcast (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player

Return value

Value | Meaning
false | The loaded song doesn't contain Shoutcast information
true | The loaded song contains Shoutcast information


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]

Public Function IsTagAvailable (

nPlayerIndex as Int16,

nTagType as enumTagTypes

) as Int16

[C#]

public Int16 IsTagAvailable (

Int16 nPlayerIndex,

enumTagTypes nTagType

);

[C++]

public: Int16 IsTagAvailable (

Int16 nPlayerIndex,

enumTagTypes nTagType

);

Parameter

Description

nPlayerIndex

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]

Public Function IsWavChunkAvailable (

nPlayerIndex as Int16,

strChunkId as String

) as Int16

[C#]

public Int16 IsWavChunkAvailable (

Int16 nPlayerIndex,

string strChunkId

);

[C++]

public: Int16 IsWavChunkAvailable (

Int16 nPlayerIndex,

string strChunkId

);

Parameter

Description

nPlayerIndex

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]

Public Function IsWmaAvailable (

) as Boolean

[C#]

public bool IsWmaAvailable (

);

[C++]

public: bool IsWmaAvailable (

);

Return value

Value | Meaning
false | WMA is not available
true | WMA is available


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 false.

Once the BPM has been calculated, the container application will be notified about the detected BPM through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_BPM_AVAILABLE.

For further details about BPM detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

Public Function RequestSoundBPM (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes RequestSoundBPM (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes RequestSoundBPM (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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 uring the export session, the container application will be notified about the exporting advancement through through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to:

· EV_WAV_EXPORT_START invoked once at the beginning
· EV_WAV_EXPORT_PERC invoked multiple times reporting the current advancement percentage inside the nData1 parameter
· EV_WAV_EXPORT_COMPLETE invoked once at the end

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]

Public Function RequestSoundExportToWav (

nPlayerIndex as Int16,

strPathname as string,

nStartPosInMs as Int32,

nFinalPosInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes RequestSoundExportToWav (

Int16 nPlayerIndex,

string strPathname,

Int32 nStartPosInMs,

Int32 nFinalPosInMs

);

[C++]

public: enumErrorCodes RequestSoundExportToWav (

Int16 nPlayerIndex,

string strPathname,

Int32 nStartPosInMs,

Int32 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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0 | The method call was successful.


ResetControl method

ResetControl method

Remarks

Re-initializes 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 InitSoundSystem method and shares the same parameters.

Syntax

[Visual Basic]

Public Function ResetControl (

nTotalPlayers as Int16,

nOutput0 as Int16,

nOutput1 as Int16,

nOutput2 as Int16,

nOutput3 as Int16,

) As Int16

[C#]

public Int16 ResetControl (

Int16 nTotalPlayers,

Int16 nOutput0,

Int16 nOutput1,

Int16 nOutput2,

Int16 nOutput3,

);

[C++]

public: Int16 ResetControl (

Int16 nTotalPlayers,

Int16 nOutput0,

Int16 nOutput1,

Int16 nOutput2,

Int16 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
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.
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.

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; if this value is smaller than the value set through the nTotalPlayers parameter, check the maximum number of players supported by the control you purchased.


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 CallbackDeviceChange delegate (on Windows XP) or through CallbackForCoreAudioEvents delegate (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 CallbackForCoreAudioEvents delegate 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]

Public Sub ResetEngine (

)

[C#]

public void ResetEngine (

);

[C++]

public: void 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 false.

When the automatic BPM detection is enabled, the container application will be notified about the detected BPM through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_BPM_AVAILABLE.

When the automatic BPM detection is disabled, the loaded song BPM can be requested at any time using the RequestSoundBPM method.

Syntax

[Visual Basic]

Public Sub SetAutomaticBPM (

bAutomatic as Boolean

)

[C#]

public void SetAutomaticBPM (

bool bAutomatic

);

[C++]

public: void SetAutomaticBPM (

bool bAutomatic

);

Parameter

Description

bAutomatic

Boolean value that specifies to execute the automatic BPM detection

Supported values are the following:

Value | Meaning
false | Automatic BPM detection is disabled
true | 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]

Public Sub SetNetAgent (

strNetAgent as string

)

[C#]

public void SetNetAgent (

string strNetAgent

);

[C++]

public: void SetNetAgent (

string 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]

Public Sub SetProxyConfiguration (

bUseProxy as Boolean,

strHost as String,

nPort as Int32,

strUsername as String,

strPassword as String

)

[C#]

public void SetProxyConfiguration (

bool bUseProxy,

string strHost,

Int32 nPort,

string strUsername,

string strPassword

);

[C++]

public: void SetProxyConfiguration (

bool bUseProxy,

string strHost,

Int32 nPort,

string strUsername,

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

Value | Meaning
false (default) | Don't use a proxy server
true | 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]

Public Sub SetRewindOnEOF (

bRewind as Boolean

)

[C#]

public void SetRewindOnEOF (

bool bRewind

);

[C++]

public: void SetRewindOnEOF (

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

Value | Meaning
false | Automatic rewind is disabled
true (default) | Automatic rewind is enabled

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 "false".

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

Public Function SilenceDetectionOnFile (

strPathname as String,

nThresholdInitial as Int32,

nThresholdFinal as Int32,

ByRef nInitialPosition as Int32,

ByRef nFinalPosition as Int32,

ByRef nSoundDuration as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SilenceDetectionOnFile (

string strPathname,

Int32 nThresholdInitial,

Int32 nThresholdFinal,

ref Int32 nInitialPosition,

ref Int32 nFinalPosition,

ref Int32 nSoundDuration

);

[C++]

public: enumErrorCodes SilenceDetectionOnFile (

string strPathname,

Int32 nThresholdInitial,

Int32 nThresholdFinal,

Int32 __gc *nInitialPosition,

Int32 __gc *nFinalPosition,

Int32 __gc *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.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.

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 "false".

For further details about silence detection management see the How to detect silent portions of sound files tutorial.

Syntax

[Visual Basic]

Public Function SilenceDetectionOnPlayer (

nPlayerIndex as Int16,

nThresholdInitial as Int32,

nThresholdFinal as Int32,

ByRef nInitialPosition as Int32,

ByRef nFinalPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SilenceDetectionOnPlayer (

Int16 nPlayerIndex,

Int32 nThresholdInitial,

Int32 nThresholdFinal,

ref Int32 nInitialPosition,

ref Int32 nFinalPosition

);

[C++]

public: enumErrorCodes SilenceDetectionOnPlayer (

Int16 nPlayerIndex,

Int32 nThresholdInitial,

Int32 nThresholdFinal,

Int32 __gc *nInitialPosition,

Int32 __gc *nFinalPosition

);

Parameter | Description
nPlayerIndex | 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.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 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_SILENCE_AVAIL.

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]

Public Sub SilenceDetectionOnPlayerLoadAutoSet (

bAutomatic as Boolean,

nThresholdInitial as Int32,

nThresholdFinal as Int32

)

[C#]

public void SilenceDetectionOnPlayerLoadAutoSet (

bool bAutomatic,

Int32 nThresholdInitial,

Int32 nThresholdFinal

);

[C++]

public: void SilenceDetectionOnPlayerLoadAutoSet (

bool bAutomatic,

Int32 nThresholdInitial,

Int32 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 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_SILENCE_AVAIL.

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]

Public Function SilenceDetectionOnPlayerRequest (

nPlayerIndex as Int16,

nThresholdInitial as Int32,

nThresholdFinal as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SilenceDetectionOnPlayerRequest (

Int16 nPlayerIndex,

Int32 nThresholdInitial,

Int32 nThresholdFinal

);

[C++]

public: enumErrorCodes SilenceDetectionOnPlayerRequest (

Int16 nPlayerIndex,

Int32 nThresholdInitial,

Int32 nThresholdFinal

);

Parameter | Description
nPlayerIndex | 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.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]

Public Function SilenceDetectionRealTimeEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SilenceDetectionRealTimeEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes SilenceDetectionRealTimeEnable (

Int16 nPlayerIndex,

bool 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
false | Realtime silence detection is disabled (default)
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]

Public Function SilenceDetectionRealTimeParamsSet (

nPlayerIndex as Int16,

nSilenceThreshold as Int32,

nSilenceMinLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SilenceDetectionRealTimeParamsSet (

Int16 nPlayerIndex,

Int32 nSilenceThreshold,

Int32 nSilenceMinLength

);

[C++]

public: enumErrorCodes SilenceDetectionRealTimeParamsSet (

Int16 nPlayerIndex,

Int32 nSilenceThreshold,

Int32 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.


SoundInfoGet method

SoundInfoGet 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]

Public SoundInfoGet (

nPlayerIndex as Int16,

byref info as SoundInfo2

) as Int16

[C#]

public Int16 SoundInfoGet (

Int16 nPlayerIndex,

ref SoundInfo2 info

);

[C++]

public: Int16 SoundInfoGet (

Int16 nPlayerIndex,

SoundInfo2 __gc* info

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
info | Reference to a SoundInfo2 class instance that will contain information about the loaded song

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.

Sample

Below you can find some sample that demonstrates how to get information about a loaded song.

Visual Basic.NET

' load a song inside player 0

AudioDjStudio1.LoadSound(0, "c:\mysong.mp3")

' instantiate a SoundInfo2 object and fill it with song information

Dim info As New AudioDjStudio.SoundInfo2

AudioDjStudio1.SoundInfoGet(0, info)

Visual C#.NET

// load a song inside player 0

audioDjStudio1.LoadSound (0, "c:\\mysong.mp3");

// instantiate a SoundInfo2 object and fill it with song information

AudioDjStudio.SoundInfo2  info = new AudioDjStudio.SoundInfo2 ();

audioDjStudio1.SoundInfoGet (0, ref info);

Visual C++.NET

// load a song inside player 0

audioDjStudio1->LoadSound (0, "c:\\mysong.mp3");

// instantiate a SoundInfo2 object and fill it with song information

AudioDjStudio::SoundInfo2 *info = new AudioDjStudio::SoundInfo2 ();

audioDjStudio1->SoundInfoGet (0, &info);


SoundLyricsGet method

SoundLyricsGet method

Remarks

Retrieves lyrics text previously requested through the SoundLyricsRequest method.

This method must be called only after the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_LYRICS_AVAIL and only if no error is reported by the event itself.

Syntax

[Visual Basic]

Public Function SoundLyricsGet (

nPlayerIndex as Int16

) as String

[C#]

public string SoundLyricsGet (

Int16 nPlayerIndex

);

[C++]

public: string SoundLyricsGet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_LYRICS_AVAIL and, if found, lyrics text can be retrieved through the SoundLyricsGet method.

Syntax

[Visual Basic]

Public Function SoundLyricsRequest (

nPlayerIndex as Int16,

strArtist as String,

strTitle as String

) as enumErrorCodes

[C#]

public enumErrorCodes SoundLyricsRequest (

Int16 nPlayerIndex,

string strArtist,

string strTitle

);

[C++]

public: enumErrorCodes SoundLyricsRequest (

Int16 nPlayerIndex,

string strArtist,

string strTitle

);

Parameter | Description
nPlayerIndex | 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 get the error code
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 may be added in the future to this blacklist.

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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Sub VideoFiltersBlacklistDisable (

bAutomatic as Boolean

)

[C#]

public void VideoFiltersBlacklistDisable (

bool bAutomatic

);

[C++]

public: void VideoFiltersBlacklistDisable (

bool bAutomatic

);

Parameter

Description

bAutomatic

Boolean value that specifies if the blacklist must be disabled.

Supported values are the following:

Value | Meaning
false (default) | Blacklist is enabled
true | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Sub VideoFiltersBlacklistItemAdd (

strCLSID as String

) as enumErrorCodes

[C#]

public enumErrorCodes VideoFiltersBlacklistItemAdd (

string strCLSID

);

[C++]

public: enumErrorCodes VideoFiltersBlacklistItemAdd (

string 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 get the error code
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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Sub VideoFiltersBlacklistItemRemove (

strCLSID as String

) as enumErrorCodes

[C#]

public enumErrorCodes VideoFiltersBlacklistItemRemove (

string strCLSID

);

[C++]

public: enumErrorCodes VideoFiltersBlacklistItemRemove (

string 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 get the error code
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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Sub VideoFiltersBlacklistReset (

) as enumErrorCodes

[C#]

public enumErrorCodes VideoFiltersBlacklistReset (

);

[C++]

public: enumErrorCodes VideoFiltersBlacklistReset (

);

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 get the error code
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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Function VideoFiltersFfdShowIsAvailable (

) as Boolean

[C#]

public bool VideoFiltersFfdShowIsAvailable (

);

[C++]

public: bool 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Function VideoFiltersFfdShowDecoderGet (

strVideoFormat as string,

ByRef nDecoder as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes VideoFiltersFfdShowDecoderGet (

string strVideoFormat,

ref Int16 nDecoder

);

[C++]

public: enumErrorCodes VideoFiltersFfdShowDecoderGet (

string strVideoFormat,

Int16 __gc *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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Function VideoFiltersFfdShowDecoderSet (

strVideoFormat as string,

nDecoder as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes VideoFiltersFfdShowDecoderSet (

string strVideoFormat,

Int16 nDecoder

);

[C++]

public: enumErrorCodes VideoFiltersFfdShowDecoderSet (

string strVideoFormat,

Int16 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.NOERROR (0 | The method call was successful.


BeatsDetectEnableRT method

BeatsDetectEnableRT method

Remarks

Enables/disables real-time detection (during playback) of beats positions. The CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_BEAT_DETECTED 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]

Public Function BeatsDetectEnableRT (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes BeatsDetectEnableRT (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes BeatsDetectEnableRT (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Beats detection is disabled
true | Beats 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.


BeatsDetectGetBeatPos method

BeatsDetectGetBeatPos 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.

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]

Public Function BeatsDetectGetBeatPos (

nPlayerIndex as Int16,

nBeatIndex as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes BeatsDetectGetBeatPos (

Int16 nPlayerIndex,

Int32 nBeatIndex

);

[C++]

public: enumErrorCodes BeatsDetectGetBeatPos (

Int16 nPlayerIndex,

Int32 nBeatIndex

);

Parameter | Description
nPlayerIndex | 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 | The number of detected beats


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]

Public Function BeatsDetectGetBeatsCount (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes BeatsDetectGetBeatsCount (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes BeatsDetectGetBeatsCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function BeatsDetectGetParams (

nPlayerIndex as Int16,

ByRef fBandwidth as Single,

ByRef fCenterFreq as Single,

ByRef fBeatReleaseTime as Single

) as enumErrorCodes

[C#]

public enumErrorCodes BeatsDetectGetParams (

Int16 nPlayerIndex,

ref float fBandwidth,

ref float fCenterFreq,

ref float fBeatReleaseTime

);

[C++]

public: enumErrorCodes BeatsDetectGetParams (

Int16 nPlayerIndex,

float __gc *fBandwidth,

float __gc *fCenterFreq,

float __gc *fBeatReleaseTime

);

Parameter | Description
nPlayerIndex | 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 is notified through the CallbackForPlayersEvents delegate having the nEvent parameter set to EV_BEATS_AVAILABLE.

For further details about beats detection refer to the How to detect beats positions and BPM tutorial.

Syntax

[Visual Basic]

Public Function BeatsDetectRequest (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes BeatsDetectRequest (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes BeatsDetectRequest (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function BeatsDetectSetParams (

nPlayerIndex as Int16,

fBandwidth as Single,

fCenterFreq as Single,

fBeatReleaseTime as Single

) as enumErrorCodes

[C#]

public enumErrorCodes BeatsDetectSetParams (

Int16 nPlayerIndex,

float fBandwidth,

float fCenterFreq,

float fBeatReleaseTime

);

[C++]

public: enumErrorCodes BeatsDetectSetParams (

Int16 nPlayerIndex,

float fBandwidth,

float fCenterFreq,

float fBeatReleaseTime

);

Parameter | Description
nPlayerIndex | 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]

Public Function BeatsDetectSetRange (

nPlayerIndex as Int16,

nStartPosition as Int32,

nEndPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes BeatsDetectSetRange (

Int16 nPlayerIndex,

Int32 nStartPosition,

Int32 nEndPosition

);

[C++]

public: enumErrorCodes BeatsDetectSetRange (

Int16 nPlayerIndex,

Int32 nStartPosition,

Int32 nEndPosition

);

Parameter | Description
nPlayerIndex | 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]

Public Function CastingCreateFromPlayer (

nPlayerIndex as Int16,

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 Int32,

nChannels as Int16

) as Int32

[C#]

public Int32 CastingCreateFromPlayer (

Int16 nPlayerIndex,

string strServer,

string strPassword,

string strIcecastMountName,

enumEncodingFormats nEncodeFormat,

string strName,

string strURL,

string strGenre,

string strHeaders,

string strIcecastDescription,

enumCastEncodeModes nEncodeMode,

float fEncodeValue,

Int32 nResampleFrequency,

Int16 nChannels

);

[C++]

public: Int32 CastingCreateFromPlayer (

Int16 nPlayerIndex,

string strServer,

string strPassword,

string strIcecastMountName,

enumEncodingFormats nEncodeFormat,

string strName,

string strURL,

string strGenre,

string strHeaders,

string strIcecastDescription,

enumCastEncodeModes nEncodeMode,

float fEncodeValue,

Int32 nResampleFrequency,

Int16 nChannels

);

Parameter

Description

nPlayerIndex

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]

Public Function CastingCreateFromStreamMixer (

nStreamMixerID as Int16,

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 Int32,

nChannels as Int16

) as Int32

[C#]

public Int32 CastingCreateFromStreamMixer (

Int16 nStreamMixerID,

string strServer,

string strPassword,

string strIcecastMountName,

enumEncodingFormats nEncodeFormat,

string strName,

string strURL,

string strGenre,

string strHeaders,

string strIcecastDescription,

enumCastEncodeModes nEncodeMode,

float fEncodeValue,

Int32 nResampleFrequency,

Int16 nChannels

);

[C++]

public: Int32 CastingCreateFromStreamMixer (

Int16 nStreamMixerID,

string strServer,

string strPassword,

string strIcecastMountName,

enumEncodingFormats nEncodeFormat,

string strName,

string strURL,

string strGenre,

string strHeaders,

string strIcecastDescription,

enumCastEncodeModes nEncodeMode,

float fEncodeValue,

Int32 nResampleFrequency,

Int16 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function CastingCreateFromWasapiLoopback (

nDeviceIndex as Int16,

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 Int32,

nChannels as Int16

) as Int32

[C#]

public Int32 CastingCreateFromWasapiLoopback (

Int16 nDeviceIndex,

string strServer,

string strPassword,

string strIcecastMountName,

enumEncodingFormats nEncodeFormat,

string strName,

string strURL,

string strGenre,

string strHeaders,

string strIcecastDescription,

enumCastEncodeModes nEncodeMode,

float fEncodeValue,

Int32 nResampleFrequency,

Int16 nChannels

);

[C++]

public: Int32 CastingCreateFromWasapiLoopback (

Int16 nDeviceIndex,

string strServer,

string strPassword,

string strIcecastMountName,

enumEncodingFormats nEncodeFormat,

string strName,

string strURL,

string strGenre,

string strHeaders,

string strIcecastDescription,

enumCastEncodeModes nEncodeMode,

float fEncodeValue,

Int32 nResampleFrequency,

Int16 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]

Public Function CastingGetXmlStatistics (

nCastingUniqueID as Int32

) as String

[C#]

public string CastingGetXmlStatistics (

Int32 nCastingUniqueID

);

[C++]

public: string CastingGetXmlStatistics (

Int32 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]

Public Function CastingIsActive (

nCastingUniqueID as Int32

) as Boolean

[C#]

public bool CastingIsActive (

Int32 nCastingUniqueID

);

[C++]

public: bool CastingIsActive (

Int32 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]

Public Function CastingSendMetaData (

nCastingUniqueID as Int32,

nType as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CastingSendMetaData (

Int32 nCastingUniqueID,

Int32 nType,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes CastingSendMetaData (

Int32 nCastingUniqueID,

Int32 nType,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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]

Public Function CastingSendMetaDataString (

nCastingUniqueID as Int32,

nType as Int32,

strMetadata as String

) as enumErrorCodes

[C#]

public enumErrorCodes CastingSendMetaDataString (

Int32 nCastingUniqueID,

Int32 nType,

string strMetadata

);

[C++]

public: enumErrorCodes CastingSendMetaDataString (

Int32 nCastingUniqueID,

Int32 nType,

string 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]

Public Function CastingSetTitle (

nCastingUniqueID as Int32,

strTitle as String,

strURL as String

) as enumErrorCodes

[C#]

public enumErrorCodes CastingSetTitle (

Int32 nCastingUniqueID,

string strTitle,

string strURL

);

[C++]

public: enumErrorCodes CastingSetTitle (

Int32 nCastingUniqueID,

string strTitle,

string 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 these methods will cause the engine to invoke the CallbackForCastingEvents delegate with its nEvent parameter set to one of the following values:

· If the casting session has been initiated by a custom Stream Mixer, the call to the CastingStart method will generate the EV_CASTING_STREAM_MIXER_START event while the call to the CastingStop method will generate the EV_CASTING_STREAM_MIXER_STOP event.
· If the casting session has been initiated by one of the available players, the call to the CastingStart method will generate the EV_CASTING_PLAYER_START event while the call to the CastingStop method or the completion of the transmission of the loaded file will generate the EV_CASTING_PLAYER_DONE event. During the transmission of the loaded file the container application can be informed about its advancement through the EV_CASTING_PLAYER_PERC event.
· If the casting session has been initiated by a WASAPI loopback device, the call to the CastingStart method will generate the EV_CASTING_LOOPBACK_START event while the call to the CastingStop method will generate the EV_CASTING_LOOPBACK_STOP 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function CastingStart (

nCastingUniqueID as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CastingStart (

Int32 nCastingUniqueID

);

[C++]

public: enumErrorCodes CastingStart (

Int32 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 cause the engine to invoke the CallbackForCastingEvents delegate with its nEvent parameter set to one of the following values::

· If the casting session has been initiated by a custom Stream Mixer, the EV_CASTING_STREAM_MIXER_STOP event.
· If the casting session has been initiated by one of the available players, the EV_CASTING_PLAYER_DONE event.
· If the casting session has been initiated by a WASAPI loopback device, the EV_CASTING_LOOPBACK_STOP 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]

Public Function CastingStop (

nCastingUniqueID as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CastingStop (

Int32 nCastingUniqueID

);

[C++]

public: enumErrorCodes CastingStop (

Int32 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]

Public Function CastingWmaConnectedIPGetCount (

nCastingUniqueID as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CastingWmaConnectedIPGetCount (

Int32 nCastingUniqueID

);

[C++]

public: enumErrorCodes CastingWmaConnectedIPGetCount (

Int32 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]

Public Function CastingWmaConnectedIPGetDesc (

nCastingUniqueID as Int32,

nIndexIP as Int32

) as String

[C#]

public string CastingWmaConnectedIPGetDesc (

Int32 nCastingUniqueID,

Int32 nIndexIP

);

[C++]

public: string CastingWmaConnectedIPGetDesc (

Int32 nCastingUniqueID,

Int32 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]

Public Function CastingWmaGetInfo (

nCastingUniqueID as Int32,

ByRef nConnectedClients as Int32,

ByRef nOutputPort as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CastingWmaGetInfo (

Int32 nCastingUniqueID,

ref Int32 nConnectedClients,

ref Int32 nOutputPort

);

[C++]

public: enumErrorCodes CastingWmaGetInfo (

Int32 nCastingUniqueID,

Int32 __gc *nConnectedClients,

Int32 __gc *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]

Public Function CastingWmaNetworkOpenForPlayer (

nPlayerIndex as Integer,

strOutputPort as String

nMaxClients as Int32

nBitrate as Int32

) as Int32

[C#]

public Int32 CastingWmaNetworkOpenForPlayer (

Int16 nPlayerIndex,

string strOutputPort,

Int32 nMaxClients,

Int32 nBitrate

);

[C++]

public: Int32 CastingWmaNetworkOpenForPlayer (

Int16 nPlayerIndex,

string strOutputPort,

Int32 nMaxClients,

Int32 nBitrate

);

Parameter | Description
nPlayerIndex | 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 player.

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]

Public Function CastingWmaNetworkOpenForStreamMixer (

nStreamMixerID as Int16,

strOutputPort as String

nMaxClients as Int32

nBitrate as Int32

) as Int32

[C#]

public Int32 CastingWmaNetworkOpenForStreamMixer (

Int16 nStreamMixerID,

string strOutputPort,

Int32 nMaxClients,

Int32 nBitrate

);

[C++]

public: Int32 CastingWmaNetworkOpenForStreamMixer (

Int16 nStreamMixerID,

string strOutputPort,

Int32 nMaxClients,

Int32 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function CastingWmaNetworkOpenFromWasapiLoopback (

nDeviceIndex as Int16,

strOutputPort as String

nMaxClients as Int32

nBitrate as Int32

) as Int32

[C#]

public Int32 CastingWmaNetworkOpenFromWasapiLoopback (

Int16 nDeviceIndex,

string strOutputPort,

Int32 nMaxClients,

Int32 nBitrate

);

[C++]

public: Int32 CastingWmaNetworkOpenFromWasapiLoopback (

Int16 nDeviceIndex,

string strOutputPort,

Int32 nMaxClients,

Int32 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]

Public Function CastingWmaPubPointOpenForPlayer (

nPlayerIndex as Int16,

strUrlPublishingPoint as String,

strUsername as String,

strPassword as String

nBitrate as Int32

) as Int32

[C#]

public Int32 CastingWmaPubPointOpenForPlayer (

Int16 nPlayerIndex,

string strUrlPublishingPoint,

string strUsername,

string strPassword,

Int32 nBitrate

);

[C++]

public: Int32 CastingWmaPubPointOpenForPlayer (

Int16 nPlayerIndex,

string strUrlPublishingPoint,

string strUsername,

string strPassword,

Int32 nBitrate

);

Parameter | Description
nPlayerIndex | 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]

Public Function CastingWmaPubPointOpenForStreamMixer (

nStreamMixerID as Int16,

strUrlPublishingPoint as String,

strUsername as String,

strPassword as String

nBitrate as Int32

) as Int32

[C#]

public Int32 CastingWmaPubPointOpenForStreamMixer (

Int16 nStreamMixerID,

string strUrlPublishingPoint,

string strUsername,

string strPassword,

Int32 nBitrate

);

[C++]

public: Int32 CastingWmaPubPointOpenForStreamMixer (

Int16 nStreamMixerID,

string strUrlPublishingPoint,

string strUsername,

string strPassword,

Int32 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function CastingWmaPubPointOpenFromWasapiLoopback (

nDeviceIndex as Int16,

strUrlPublishingPoint as String,

strUsername as String,

strPassword as String

nBitrate as Int32

) as Int32

[C#]

public Int32 CastingWmaPubPointOpenFromWasapiLoopback (

Int16 nDeviceIndex,

string strUrlPublishingPoint,

string strUsername,

string strPassword,

Int32 nBitrate

);

[C++]

public: Int32 CastingWmaPubPointOpenFromWasapiLoopback (

Int16 nDeviceIndex,

string strUrlPublishingPoint,

string strUsername,

string strPassword,

Int32 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]

Public Function CastingWmaSetTag (

nCastingUniqueID as Int32,

strTagName as String,

strTagText as String

) as enumErrorCodes

[C#]

public enumErrorCodes CastingWmaSetTag (

Int32 nCastingUniqueID,

string strTagName,

string strTagText

);

[C++]

public: enumErrorCodes CastingWmaSetTag (

Int32 nCastingUniqueID,

string strTagName,

string 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]

Public Function WmaBitrateCount (

nFrequency as Int32,

nChannels as Int16

) as Int16

[C#]

public Int16 WmaBitrateCount (

Int32 nFrequency,

Int16 nChannels

);

[C++]

public: Int16 WmaBitrateCount (

Int32 nFrequency,

Int16 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]

Public Function WmaBitrateGet (

nFrequency as Int32,

nChannels as Int16,

nIndexBitrate as Int16

) as Int32

[C#]

public Int32 WmaBitrateGet (

Int32 nFrequency,

Int16 nChannels,

Int16 nIndexBitrate

);

[C++]

public: Int32 WmaBitrateGet (

Int32 nFrequency,

Int16 nChannels,

Int16 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

Remarks

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]

Public Function CddbGetAlbumInfo (

nCdDriveIndex as integer,

nInfo as enumCddbAlbumInfo

) as String

[C#]

public string CddbGetAlbumInfo (

short nCdDriveIndex,

enumCddbAlbumInfo nInfo

);

[C++]

public: string CddbGetAlbumInfo (

short nCdDriveIndex,

enumCddbAlbumInfo 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 | 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 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 before being notified about servers availability through the CallbackForCdDrivesEvents delegate having the nEvent parameter set to EV_CDDB_SERVERS_AVAIL.

See the How to get CD album information from a CDDB server tutorial for further details.

Syntax

[Visual Basic]

Public Function CddbGetServerName (

nServerIndex as integer

) as String

[C#]

public string CddbGetServerName (

short nServerIndex

);

[C++]

public: string CddbGetServerName (

short nServerIndex

);

Parameter | Description
nServerIndex | Number representing the zero-based index of the CDDB server.

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 CDDB server's friendly name


CddbSetProxyDetails method

CddbSetProxyDetails method

Remarks

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]

Public Sub CddbSetProxyDetails (

strHost as string,

nPort as Int32,

strUsername as string,

strPassword as string

)

[C#]

public void CddbSetProxyDetails (

string strHost,

Int32 nPort,

string strUsername,

string strPassword

);

[C++]

public: void CddbSetProxyDetails (

string strHost,

Int32 nPort,

string strUsername,

string 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


CddbGetTrackTitle method

CddbGetTrackTitle method

Remarks

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]

Public Function CddbGetTrackTitle (

nCdDriveIndex as integer,

nTrackIndex as integer

) as String

[C#]

public string CddbGetTrackTitle (

short nCdDriveIndex,

short nTrackIndex

);

[C++]

public: string 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 | 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 CD track title


CddbRequestAlbumInfo method

CddbRequestAlbumInfo method

Remarks

Requests the CDDB album info for the CD currently inside the given CD drive: this call needs an active Internet connection.

When CD info is available the container application is notified through the CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to EV_CDDB_ALBUM_INFO_AVAIL: 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 container application is notified through the CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to:

· EV_CD_COVER_URLS_AVAIL so it will be possible getting the URLs of the CD cover pictures from the Amazon Web Service using the GetCdCoverPictureURL method.
· EV_CD_COVER_SMALL_FILE_AVAIL, EV_CD_COVER_MEDIUM_FILE_AVAIL and EV_CD_COVER_LARGE_FILE_AVAIL so it will be possible 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]

Public Function CddbRequestAlbumInfo (

nCdDriveIndex as Int16,

nServerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes CddbRequestAlbumInfo (

Int16 nCdDriveIndex,

Int16 nServerIndex

);

[C++]

public: enumErrorCodes CddbRequestAlbumInfo (

Int16 nCdDriveIndex,

Int16 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 last error.
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


CddbRequestServersList method

CddbRequestServersList method

Remarks

Requests the list of available CDDB servers and returns immediately.

When the list will be available, the container application is notified through the CallbackForCdDrivesEvents delegate having the nEvent parameter set to EV_CDDB_SERVERS_AVAIL: at this point it will be possible requesting each CDDB server's friendly name using the CddbGetServerName method.

See the How to get CD album information from a CDDB server tutorial for further details.

Syntax

[Visual Basic]

Public Function CddbRequestServersList (

) as enumErrorCodes

[C#]

public enumErrorCodes CddbRequestServersList (

);

[C++]

public: enumErrorCodes CddbRequestServersList (

);

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.


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]

Public Function CdNavigateToPurchasePage (

) as enumErrorCodes

[C#]

public enumErrorCodes CdNavigateToPurchasePage (

);

[C++]

public: enumErrorCodes CdNavigateToPurchasePage (

);

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.


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 is available the container application is notified through the CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to EV_CDDB_ALBUM_INFO_AVAIL: 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 container application is notified through the CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to:

· EV_CD_COVER_URLS_AVAIL so it will be possible getting the URLs of the CD cover pictures from the Amazon Web Service using the GetCdCoverPictureURL method.
· EV_CD_COVER_SMALL_FILE_AVAIL, EV_CD_COVER_MEDIUM_FILE_AVAIL and EV_CD_COVER_LARGE_FILE_AVAIL so it will be possible 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]

Public Function CdRequestAlbumInfo (

strArtist as string,

strAlbum as string,

strAmazonDeveloperCode as string

) as enumErrorCodes

[C#]

public enumErrorCodes CdRequestAlbumInfo (

string strArtist,

string strAlbum,

string strAmazonDeveloperCode

);

[C++]

public: enumErrorCodes CdRequestAlbumInfo (

string strArtist,

string strAlbum,

string 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 last error.
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]

Public Sub EnableCdMonitor (

bEnable as Boolean

)

[C#]

public void EnableCdMonitor (

bool bEnable

);

[C++]

public: void 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:

Value | Meaning
false (default) | Available CD drives won't be monitored. In this condition the GetCdStatus method will not work and the CallbackForCdDrivesEvents delegate having the nEvent parameter set to EV_CD_STATUS_CHANGED is not invoked.
true | 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]

Public Sub EnableCdTracksPrebuff (

bEnable as Boolean

)

[C#]

public void EnableCdTracksPrebuff (

bool bEnable

);

[C++]

public: void 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 | Meaning
false | Pre-buffering is disabled
true (default) | 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]

Public Function GetCdCoverPictureFile (

nCdDriveIndex as Int16

nCoverSize as enumCdCoverSizes

) as String

[C#]

public string GetCdCoverPictureFile (

Int16 nCdDriveIndex,

enumCdCoverSizes nCoverSize

);

[C++]

public: string GetCdCoverPictureFile (

Int16 nCdDriveIndex,

enumCdCoverSizes nCoverSize

);

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]

Public Function GetCdCoverPictureURL (

nCdDriveIndex as Int16

nCoverSize as enumCdCoverSizes

) as String

[C#]

public string GetCdCoverPictureURL (

Int16 nCdDriveIndex,

enumCdCoverSizes nCoverSize

);

[C++]

public: string GetCdCoverPictureURL (

Int16 nCdDriveIndex,

enumCdCoverSizes nCoverSize

);

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.

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

Syntax

[Visual Basic]

Public Function GetCdDriveDesc (

nDriveIndex as Int16

) as String

[C#]

public string GetCdDriveDesc (

Int16 nDriveIndex

);

[C++]

public: string GetCdDriveDesc (

Int16 nDriveIndex

);

Parameter | Description
nDriveIndex | Number representing the zero-based index of the CD drive whose friendly name must be retrieved

Return value

Value | Meaning
Empty string | The value of the nDriveIndex 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:\".

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

Syntax

[Visual Basic]

Public Function GetCdDriveLetter (

nDriveIndex as Int16

) as String

[C#]

public string GetCdDriveLetter (

Int16 nDriveIndex

);

[C++]

public: string GetCdDriveLetter (

Int16 nDriveIndex

);

Parameter | Description
nDriveIndex | Number representing the zero-based index of the CD drive whose letter must be retrieved

Return value

Value | Meaning
Empty string | The value of the nDriveIndex 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]

Public Function GetCdDrivesCount (

) as Int16

[C#]

public Int16 GetCdDrivesCount (

);

[C++]

public: Int16 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.

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

Syntax

[Visual Basic]

Public Function GetCdIdentification (

nDriveIndex as Int16,

nIdentType as enumCdIdCodes

) as enumErrorCodes

[C#]

public enumErrorCodes GetCdIdentification (

Int16 nDriveIndex,

enumCdIdCodes nIdentType

);

[C++]

public: enumErrorCodes GetCdIdentification (

Int16 nDriveIndex,

enumCdIdCodes nIdentType

);

Parameter

Description

nDriveIndex

Number representing the zero-based index of the involved CD drive

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.

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

Syntax

[Visual Basic]

Public Function GetCdNumTracks (

nDriveIndex as Int16

) as Int16

[C#]

public Int16 GetCdNumTracks (

Int16 nDriveIndex

);

[C++]

public: Int16 GetCdNumTracks (

Int16 nDriveIndex

);

[Visual Basic]

control.GetCdNumtracks (nDrive as integer) as integer

[C++]

short control.GetCdNumtracks (short nDrive);

Parameter

Description

nDriveIndex

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.

The total number of available CD drives can be obtained using the GetCdDrivesCount method.

Syntax

[Visual Basic]

Public Function GetCdStatus (

nDriveIndex as Int16

) as enumCdStatus

[C#]

public enumCdStatus GetCdStatus (

Int16 nDriveIndex

);

[C++]

public: enumCdStatus GetCdStatus (

Int16 nDriveIndex

);

Parameter | Description
nDriveIndex | Number representing the zero-based index of the involved CD drive

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.

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.

Syntax

[Visual Basic]

Public Function GetCdTrackDuration (

nDriveIndex as Int16,

nTrackIndex as Int16

) as Int32

[C#]

public Int32 GetCdTrackDuration (

Int16 nDriveIndex,

Int16 nTrackIndex

);

[C++]

public: Int32 GetCdTrackDuration (

Int16 nDriveIndex,

Int16 nTrackIndex

);

Parameter | Description
nDriveIndex | Number representing the zero-based index of the involved CD drive
nTrackIndex | 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)
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.

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.

Syntax

[Visual Basic]

Public Function GetCdTrackDurationMs (

nDriveIndex as Int16,

nTrackIndex as Int16

) as Int32

[C#]

public Int32 GetCdTrackDurationMs (

Int16 nDriveIndex,

Int16 nTrackIndex

);

[C++]

public: Int32 GetCdTrackDurationMs (

Int16 nDriveIndex,

Int16 nTrackIndex

);

Parameter | Description
nDriveIndex | Number representing the zero-based index of the involved CD drive
nTrackIndex | 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)
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 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.

Syntax

[Visual Basic]

Public Function GetCdTrackPathname (

nDriveIndex as Int16,

nTrackIndex as Int16

) as String

[C#]

public string GetCdTrackPathname (

Int16 nDriveIndex,

Int16 nTrackIndex

);

[C++]

public: string GetCdTrackPathname (

Int16 nDriveIndex,

Int16 nTrackIndex

);

Parameter | Description
nDriveIndex | Number representing the zero-based index of the involved CD drive
nTrackIndex | Number representing the one-based index of the CD audio track

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]

Public Function PerformActionOnCd (

nDriveIndex as Int16,

nAction as enumCdActions

) as enumErrorCodes

[C#]

public enumErrorCodes PerformActionOnCd (

Int16 nDriveIndex,

enumCdActions nAction

);

[C++]

public: enumErrorCodes PerformActionOnCd (

Int16 nDriveIndex,

enumCdActions nAction

);

Parameter

Description

nDriveIndex

Number representing the zero-based index of the involved CD drive

nAction

The action to perform.

Supported values are the following:

Mnemonic value | 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 method call was successful.


CallbackCurveDesignerPointsChangeSet method

CallbackCurveDesignerPointsChangeSet method

Remarks

Sets the function of the CallbackCurveDesignerPointsChange callback delegate which notifies when the curve inside a curve designer control is modified by dragging one of the control points through the mouse interaction.

Syntax

[Visual Basic]

Public Function CallbackCurveDesignerPointsChangeSet (

function as CallbackCurveDesignerPointsChange

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackCurveDesignerPointsChangeSet (

CallbackCurveDesignerPointsChange function

);

[C++]

public: enumErrorCodes CallbackCurveDesignerPointsChangeSet (

CallbackCurveDesignerPointsChange function

);

Parameter | Description
function | Callback function

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackCurveDesignerPointsChangeSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackDeviceChangeSet method

CallbackDeviceChangeSet method

Remarks

Sets a callback for receiving notification 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 method is only intended for usage with Windows XP and earlier versions. When dealing with Windows Vista and higher versions it's recommended using the CallbackForCoreAudioEvents callback.

Syntax

[Visual Basic]

Public Function CallbackDeviceChangeSet (

function as CallbackDeviceChange

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackDeviceChangeSet (

CallbackDeviceChange function

);

[C++]

public: enumErrorCodes CallbackDeviceChangeSet (

CallbackDeviceChange function

);

Parameter | Description
function | Pointer to the callback function that will receive the event. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackDeviceChangeSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackDisplayConfigChangedSet method

CallbackDisplayConfigChangedSet method

Remarks

Sets a callback for receiving notification whenever whenever the configuration of the system display is changed.

Syntax

[Visual Basic]

Public Function CallbackDisplayConfigChangedSet (

function as CallbackDisplayConfigChanged

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackDisplayConfigChangedSet (

CallbackDisplayConfigChanged function

);

[C++]

public: enumErrorCodes CallbackDisplayConfigChangedSet (

CallbackDisplayConfigChanged function

);

Parameter | Description
function | Pointer to the callback function that will receive the event. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackDisplayConfigChangedSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackForCastingEventsSet method

CallbackForCastingEventsSet method

Remarks

Sets the callback function which notifies about casting events.

Syntax

[Visual Basic]

Public Function CallbackForCastingEventsSet (

function as CallbackForCastingEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForCastingEventsSet (

CallbackForCastingEvents function

);

[C++]

public: enumErrorCodes CallbackForCastingEventsSet (

CallbackForCastingEvents function

);

Parameter | Description
function | Callback function that will receive events generated by the casting manager. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackForCastingEventsSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.

Syntax

[Visual Basic]

Public Function CallbackForCdDrivesEventsSet (

function as CallbackForCdDrivesEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForCdDrivesEventsSet (

CallbackForCdDrivesEvents function

);

[C++]

public: enumErrorCodes CallbackForCdDrivesEventsSet (

CallbackForCdDrivesEvents function

);

Parameter | Description
function | 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.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackForCdDrivesEventsSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


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.

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]

Public Function CallbackForCoreAudioEventsSet (

function as CallbackForCoreAudioEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForCoreAudioEventsSet (

CallbackForCoreAudioEvents function

);

[C++]

public: enumErrorCodes CallbackForCoreAudioEventsSet (

CallbackForCoreAudioEvents function

);

Parameter | Description
function | 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.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackForCoreAudioEventsSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackForDownloaderEventsSet method

CallbackForDownloaderEventsSet method

Remarks

Sets the callback function which notifies about downloader events.

Syntax

[Visual Basic]

Public Function CallbackForDownloaderEventsSet (

function as CallbackForDownloaderEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForDownloaderEventsSet (

CallbackForDownloaderEvents function

);

[C++]

public: enumErrorCodes CallbackForDownloaderEventsSet (

CallbackForDownloaderEvents function

);

Parameter | Description
function | Callback function that will receive events generated by the downloader. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackForDownloaderEventsSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackForMidiKeyboardEventsSet method

CallbackForMidiKeyboardEventsSet method

Remarks

Sets a callback for receiving notification of events generated by the virtual piano keyboard.

Syntax

[Visual Basic]

Public Function CallbackForMidiKeyboardEventsSet (

function as CallbackForMidiKeyboardEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForMidiKeyboardEventsSet (

CallbackForMidiKeyboardEvents function

);

[C++]

public: enumErrorCodes CallbackForMidiKeyboardEventsSet (

CallbackForMidiKeyboardEvents function

);

Parameter | Description
function | Callback function that will receive events generated by the virtual piano keyboard. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackForMidiKeyboardEventsSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackForMidiMarkerEventsSet method

CallbackForMidiMarkerEventsSet method

Remarks

Sets a callback for receiving notification of events generated by instanced players, allowing to synchronize players themselves with the container application.

Syntax

[Visual Basic]

Public Function CallbackForMidiMarkerEventsSet (

function as CallbackForMidiMarkerEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForMidiMarkerEventsSet (

CallbackForMidiMarkerEvents function

);

[C++]

public: enumErrorCodes CallbackForMidiMarkerEventsSet (

CallbackForMidiMarkerEvents function

);

Parameter | Description
function | Callback function that will receive MIDI markers related events. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackForMidiMarkerEventsSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackForMidiStreamEventsSet method

CallbackForMidiStreamEventsSet method

Remarks

Sets a callback for receiving notification of events generated by instanced players, allowing to synchronize players themselves with the container application.

Syntax

[Visual Basic]

Public Function CallbackForMidiStreamEventsSet (

function as CallbackForMidiStreamEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForMidiStreamEventsSet (

CallbackForMidiStreamEvents function

);

[C++]

public: enumErrorCodes CallbackForMidiStreamEventsSet (

CallbackForMidiStreamEvents function

);

Parameter | Description
function | Callback function that will receive MIDI events related events. Remember that callback functions must be as fast as possible in order to avoid slowing down overall performances.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackForMidiStreamEventsSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


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.

Syntax

[Visual Basic]

Public Function CallbackForPlayersEventsSet (

function as CallbackForPlayersEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForPlayersEventsSet (

CallbackForPlayersEvents function

);

[C++]

public: enumErrorCodes CallbackForPlayersEventsSet (

CallbackForPlayersEvents function

);

Parameter | Description
function | 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.

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackForPlayersEventsSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackWaveformScrollerManualScrollSet method

CallbackWaveformScrollerManualScrollSet method

Remarks

Sets the function of the CallbackWaveformScrollerManualScroll callback delegate which notifies about manual movements 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]

Public Function CallbackWaveformScrollerManualScrollSet (

function as CallbackWaveformScrollerManualScroll

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformScrollerManualScrollSet (

CallbackWaveformScrollerManualScroll function

);

[C++]

public: enumErrorCodes CallbackWaveformScrollerManualScrollSet (

CallbackWaveformScrollerManualScroll function

);

Parameter | Description
function | Callback function

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackWaveformScrollerManualScrollSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackWaveformScrollerMouseNotifSet method

CallbackWaveformScrollerMouseNotifSet method

Remarks

Sets the function of the CallbackWaveformScrollerMouseNotif callback delegate which notifies about mouse actions 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]

Public Function CallbackWaveformScrollerMouseNotifSet (

function as CallbackWaveformScrollerMouseNotif

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformScrollerMouseNotifSet (

CallbackWaveformScrollerMouseNotif function

);

[C++]

public: enumErrorCodes CallbackWaveformScrollerMouseNotifSet (

CallbackWaveformScrollerMouseNotif function

);

Parameter | Description
function | Callback function

when using the API from Unmanaged C++ through COM interaction, where the client application is totally unaware about .NET delegates, you should use the "Ptr" version of the method which allows passing the pointer to the callback function:

[Unmanaged C++]

enumErrorCodes CallbackWaveformScrollerMouseNotifSetPtr (

(UINT_PTR) functionPointer

);

Parameter | Description
functionPointer | Pointer to the callback function. See the Adding the API to an unmanaged Visual C++ project tutorial for details about usage of the "Ptr" version of these methods.

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.


CallbackZipOperationPercSet method

CallbackZipOperationPercSet method

Remarks

Sets the function of the CallbackZipOperationPerc callback delegate which notifies about the percentage of advancement of a ZIP operation.

For further details about methods for ZIP management refer to the ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function CallbackZipOperationPercSet (

function as CallbackZipOperationPerc

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackZipOperationPercSet (

CallbackZipOperationPerc function

);

[C++]

public: enumErrorCodes CallbackZipOperationPercSet (

CallbackZipOperationPerc function

);

Parameter | Description
function | Callback function

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.


CuePointsAdd method

CuePointsAdd method

Remarks

Adds a cue point to the given player: when the cue point is reached, the container application is notified through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_CUE_POINT_REACHED.

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]

Public Function CuePointsAdd (

nPlayerIndex as Int16,

strCuePointName as string,

nCuePointPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CuePointsAdd (

Int16 nPlayerIndex,

string strCuePointName,

Int32 nCuePointPos

);

[C++]

public: enumErrorCodes CuePointsAdd (

Int16 nPlayerIndex,

string strCuePointName,

Int32 nCuePointPos

);

Parameter | Description
nPlayerIndex | 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.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]

Public Function CuePointsEnable (

nPlayerIndex as Int16,

strCuePointName as string,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes CuePointsEnable (

Int16 nPlayerIndex,

string strCuePointName,

bool bEnable

);

[C++]

public: enumErrorCodes CuePointsEnable (

Int16 nPlayerIndex,

string strCuePointName,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | Disable cue point
true (default) | Enable cue point

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.


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]

Public Function CuePointsGetCount (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 CuePointsGetCount (

Int16 nPlayerIndex

);

[C++]

public: Int32 CuePointsGetCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function CuePointsGetName (

nPlayerIndex as Int16,

nIndex as Int32

) as Int32

[C#]

public Int32 CuePointsGetName (

Int16 nPlayerIndex,

Int32 nIndex

);

[C++]

public: Int32 CuePointsGetName (

Int16 nPlayerIndex,

Int32 nIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function CuePointsGetPos (

nPlayerIndex as Int16,

strCuePointName as string

) as Int32

[C#]

public Int32 CuePointsGetPos (

Int16 nPlayerIndex,

string strCuePointName

);

[C++]

public: Int32 CuePointsGetPos (

Int16 nPlayerIndex,

string strCuePointName

);

Parameter | Description
nPlayerIndex | 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]

Public Function CuePointsIsEnabled (

nPlayerIndex as Int16,

strCuePointName as string

) as Boolean

[C#]

public bool CuePointsIsEnabled (

Int16 nPlayerIndex,

string strCuePointName

);

[C++]

public: bool CuePointsIsEnabled (

Int16 nPlayerIndex,

string strCuePointName

);

Parameter | Description
nPlayerIndex | 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 | Meaning
false | Cue point is disabled
true (default) | 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]

Public Function CuePointsLoadFromFile (

nPlayerIndex as Int16,

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes CuePointsLoadFromFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes CuePointsLoadFromFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the source 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.


CuePointsLoadFromMemoryStream method

CuePointsLoadFromMemoryStream method

Remarks

Loads a set of cue points from a memory stream containing the needed XML code into the given player. Existing cue points can be saved inside a memory stream through the CuePointsSaveToMemoryStream method.

See the How to add Triggers and Cue Points to a player section for further details about cue points and about the needed XML format.

Syntax

[Visual Basic]

Public Function CuePointsLoadFromMemoryStream (

nPlayerIndex as Int16,

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes CuePointsLoadFromMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

[C++]

public: enumErrorCodes CuePointsLoadFromMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
ms | Memory stream containing Cue Points in XML format

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]

Public Function CuePointsRemove (

nPlayerIndex as Int16,

strCuePointName as string

) as enumErrorCodes

[C#]

public enumErrorCodes CuePointsRemove (

Int16 nPlayerIndex,

string strCuePointName

);

[C++]

public: enumErrorCodes CuePointsRemove (

Int16 nPlayerIndex,

string strCuePointName

);

Parameter | Description
nPlayerIndex | 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.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]

Public Function CuePointsSaveToFile (

nPlayerIndex as Int16,

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes CuePointsSaveToFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes CuePointsSaveToFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
strPathname | String containing the absolute pathname of the destination 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.


CuePointsSaveToMemoryStream method

CuePointsSaveToMemoryStream method

Remarks

Saves existing cue points into a memory stream in XML format. These cue points can be loaded at a later time through the CuePointsLoadFromMemoryStream method.

See the How to add Triggers and Cue Points to a player section for further details about cue points and about the needed XML format.

Syntax

[Visual Basic]

Public Function CuePointsSaveToMemoryStream (

nPlayerIndex as Int16,

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes CuePointsSaveToMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

[C++]

public: enumErrorCodes CuePointsSaveToMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
ms | Memory stream for storing Cue Points in XML format

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]

Public Function CuePointsSetPos (

nPlayerIndex as Int16,

strCuePointName as string,

nCuePointPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CuePointsSetPos (

Int16 nPlayerIndex,

string strCuePointName,

Int32 nCuePointPos

);

[C++]

public: enumErrorCodes CuePointsSetPos (

Int16 nPlayerIndex,

string strCuePointName,

Int32 nCuePointPos

);

Parameter | Description
nPlayerIndex | 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.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]

Public Function LrcIdTagGet (

nPlayerIndex as Int16,

nTagType as enumLrcFileIdTags

) as string

[C#]

public string LrcIdTagGet (

Int16 nPlayerIndex,

enumLrcFileIdTags nTagType

);

[C++]

public: string LrcIdTagGet (

Int16 nPlayerIndex,

enumLrcFileIdTags 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]

Public Function LrcLoad (

nPlayerIndex as Int16,

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes LrcLoad (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes LrcLoad (

Int16 nPlayerIndex,

string 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]

Public Function LrcNotifEnableGet (

) as Boolean

[C#]

public bool LrcNotifEnableGet (

);

[C++]

public: bool 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]

Public Sub LrcNotifEnableSet (

bEnable as Boolean

)

[C#]

public void LrcNotifEnableSet (

bool bEnable

);

[C++]

public: void LrcNotifEnableSet (

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

Value | Meaning
false | Lyrics notifications and auto-loading of LRC files are disabled
true | 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]

Public Function LrcNotifTimingsGet (

ByRef nAdvanceTimeFullLine as Int32,

ByRef nRealTimeCompensation as Int32

) as string

[C#]

public string LrcNotifTimingsGet (

ref Int32 nAdvanceTimeFullLine,

ref Int32 nRealTimeCompensation

);

[C++]

public: string LrcNotifTimingsGet (

Int32 __gc *nAdvanceTimeFullLine,

Int32 __gc *nRealTimeCompensation

);

Parameter | Description
nAdvanceTimeFullLine | Reference that, on return from the method call, will contain the advance time, expressed in milliseconds, used to invoke the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_LRC_ADVANCETIME_FULL_LINE
nRealTimeCompensation | Reference that, on return from the method call, will contain the time compensation, expressed in milliseconds, used to invoke the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_LRC_REALTIME_FULL_LINE and EV_LRC_REALTIME_PORTION_LINE.

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


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]

Public Function LrcNotifTimingsSet (

nAdvanceTimeFullLine as Int32,

nRealTimeCompensation as Int32

) as string

[C#]

public string LrcNotifTimingsSet (

Int32 nAdvanceTimeFullLine,

Int32 nRealTimeCompensation

);

[C++]

public: string LrcNotifTimingsSet (

Int32 nAdvanceTimeFullLine,

Int32 nRealTimeCompensation

);

Parameter | Description
nAdvanceTimeFullLine | The advance time, expressed in milliseconds, used to invoke the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_LRC_ADVANCETIME_FULL_LINE
nRealTimeCompensation | The time compensation, expressed in milliseconds, used to invoke the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_LRC_REALTIME_FULL_LINE and EV_LRC_REALTIME_PORTION_LINE.

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


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]

Public Function LrcTimeTagsEnhGetAt (

nPlayerIndex as Int16,

nIndex as Int32,

ByRef nPosition as Int32,

ByRef nDuration as Int32

) as string

[C#]

public string LrcTimeTagsEnhGetAt (

Int16 nPlayerIndex,

Int32 nIndex,

ref Int32 nPosition,

ref Int32 nDuration

);

[C++]

public: string LrcTimeTagsEnhGetAt (

Int16 nPlayerIndex,

Int32 nIndex,

Int32 __gc *nPosition,

Int32 __gc *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 line of text


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]

Public Function LrcTimeTagsEnhGetCount (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 LrcTimeTagsEnhGetCount (

Int16 nPlayerIndex

);

[C++]

public: Int32 LrcTimeTagsEnhGetCount (

Int16 nPlayerIndex

);

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]

Public Function LrcTimeTagsSimpleGetAt (

nPlayerIndex as Int16,

nIndex as Int32,

ByRef nPosition as Int32

) as string

[C#]

public string LrcTimeTagsSimpleGetAt (

Int16 nPlayerIndex,

Int32 nIndex,

ref Int32 nPosition

);

[C++]

public: string LrcTimeTagsSimpleGetAt (

Int16 nPlayerIndex,

Int32 nIndex,

Int32 __gc *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]

Public Function LrcTimeTagsSimpleGetCount (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 LrcTimeTagsSimpleGetCount (

Int16 nPlayerIndex

);

[C++]

public: Int32 LrcTimeTagsSimpleGetCount (

Int16 nPlayerIndex

);

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]

Public Function GetOutputDeviceDesc (

nOutputIndex as Int16

) as String

[C#]

public string GetOutputDeviceDesc (

Int16 nOutputIndex

);

[C++]

public: string GetOutputDeviceDesc (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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 nOutputIndex 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).

Syntax

[Visual Basic]

Public GetOutputDeviceDriverType (

nOutputIndex as Int16

) as enumDriverTypes

[C#]

public enumDriverTypes GetOutputDeviceDriverType (

Int16 nOutputIndex

);

[C++]

public: enumDriverTypes GetOutputDeviceDriverType (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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]

Public GetOutputDeviceLatency (

nOutputIndex as Int16

) as Int16

[C#]

public Int16 GetOutputDeviceLatency (

Int16 nOutputIndex

);

[C++]

public: Int16 GetOutputDeviceLatency (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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)
Value > 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]

Public GetOutputDeviceMinBufferLength (

nOutputIndex as Int16

) as Int16

[C#]

public Int16 GetOutputDeviceMinBufferLength (

Int16 nOutputIndex

);

[C++]

public: Int16 GetOutputDeviceMinBufferLength (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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)
Value > 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]

Public Function GetOutputDevicesCount (

) as Int16

[C#]

public Int16 GetOutputDevicesCount (

);

[C++]

public: Int16 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]

Public Function GetOutputDeviceUniqueID (

nOutputIndex as Int16

) as String

[C#]

public string GetOutputDeviceUniqueID (

Int16 nOutputIndex

);

[C++]

public: string GetOutputDeviceUniqueID (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | Number representing the zero-based index of the output device whose unique ID must be retrieved

Return value

Value | Meaning
Empty string | The value of the nOutputIndex 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]

Public GetOutputSpeakersConfig (

nOutputIndex as Int16

) as enumSpeakersConfig

[C#]

public enumSpeakersConfig GetOutputSpeakersConfig (

Int16 nOutputIndex

);

[C++]

public: enumSpeakersConfig GetOutputSpeakersConfig (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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]

Public Function GetOutputSpeakersCount (

nOutputIndex as Int16

) as Int16

[C#]

public Int16 GetOutputSpeakersCount (

Int16 nOutputIndex

);

[C++]

public: Int16 GetOutputSpeakersCount (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MixerGetCount (

) as Int16

[C#]

public Int16 MixerGetCount (

);

[C++]

public: Int16 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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MixerGetDesc (

nIndex as Int16

) as String

[C#]

public string MixerGetDesc (

Int16 nIndex

);

[C++]

public: string MixerGetDesc (

Int16 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 GetMixersCount 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 through 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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MixerMuteGet (

nIndex as Int16,

nComponentType as enumComponentTypes,

ByRef bMute as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MixerMuteGet (

Int16 nIndex,

enumComponentTypes nComponentType,

ref bool bMute

);

[C++]

public: enumErrorCodes MixerMuteGet (

Int16 nIndex,

enumComponentTypes nComponentType,

bool __gc *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
false | The audio stream is not muted
true | The audio stream is muted

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


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 through 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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MixerMuteSet (

nIndex as Int16,

nComponentType as enumComponentTypes,

bMute as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MixerMuteSet (

Int16 nIndex,

enumComponentTypes nComponentType,

bool bMute

);

[C++]

public: enumErrorCodes MixerMuteSet (

Int16 nIndex,

enumComponentTypes nComponentType,

bool 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
false | The audio stream is not muted
true | The audio stream is muted

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


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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MixerVolumeGet (

nIndex as Int16,

nComponentType as enumComponentTypes,

ByRef nValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes MixerVolumeGet (

Int16 nIndex,

enumComponentTypes nComponentType,

ref Int32 nValue

);

[C++]

public: enumErrorCodes MixerVolumeGet (

Int16 nIndex,

enumComponentTypes nComponentType,

Int32 __gc *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.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MixerVolumeSet (

nIndex as Int16,

nComponentType as enumComponentTypes,

nValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes MixerVolumeSet (

Int16 nIndex,

enumComponentTypes nComponentType,

Int32 nValue

);

[C++]

public: enumErrorCodes MixerVolumeSet (

Int16 nIndex,

enumComponentTypes nComponentType,

Int32 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.NOERROR (0) | The method call was successful


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]

Public SetOutputSpeakersConfig (

nOutputIndex as Int16,

nNewConfig as enumSpeakersConfig

) as enumErrorCodes

[C#]

public enumErrorCodes SetOutputSpeakersConfig (

Int16 nOutputIndex,

enumSpeakersConfig nNewConfig

);

[C++]

public: enumErrorCodes SetOutputSpeakersConfig (

Int16 nOutputIndex,

enumSpeakersConfig nNewConfig

);

Parameter

Description

nOutputIndex

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]

Public Function AmazonStoreCdInfoCreate (

nPlayerIndex as Int16,

strAmazonDeveloperCode as String

) as enumErrorCodes

[C#]

public enumErrorCodes AmazonStoreCdInfoCreate (

Int16 nPlayerIndex,

string strAmazonDeveloperCode

);

[C++]

public: enumErrorCodes AmazonStoreCdInfoCreate (

Int16 nPlayerIndex,

string 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]

Public Function AmazonStoreCdInfoGet (

nPlayerIndex as Int16,

nInfo as enumAmazonStoreInfo

) as enumErrorCodes

[C#]

public enumErrorCodes AmazonStoreCdInfoGet (

Int16 nPlayerIndex,

enumAmazonStoreInfo nInfo

);

[C++]

public: enumErrorCodes AmazonStoreCdInfoGet (

Int16 nPlayerIndex,

enumAmazonStoreInfo nInfo

);

Parameter

Description

nPlayerIndex

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

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]

Public Function AmazonStoreCdCoverPictureFileGet (

nPlayerIndex as Int16,

nCoverSize as enumCdCoverSizes

) as String

[C#]

public string AmazonStoreCdCoverPictureFileGet (

Int16 nPlayerIndex,

enumCdCoverSizes nCoverSize

);

[C++]

public: string AmazonStoreCdCoverPictureFileGet (

Int16 nPlayerIndex,

enumCdCoverSizes nCoverSize

);

Parameter

Description

nPlayerIndex

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]

Public Function AmazonStoreCdNavigateToUrl (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes AmazonStoreCdNavigateToUrl (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes AmazonStoreCdNavigateToUrl (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function AmazonStoreCdTrackTitleGet (

nPlayerIndex as Int16,

nTrackIndex as Int32

) as String

[C#]

public string AmazonStoreCdTrackTitleGet (

Int16 nPlayerIndex,

Int32 nTrackIndex

);

[C++]

public: string AmazonStoreCdTrackTitleGet (

Int16 nPlayerIndex,

Int32 nTrackIndex

);

Parameter | Description
nPlayerIndex | 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_CLOSED.

Syntax

[Visual Basic]

Public Function CloseSound (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes CloseSound (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes CloseSound (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


CopyExportedWavToMemory method

CopyExportedWavToMemory method

Remarks

After calling the RequestSoundExportToWav method, in order to export the loaded song into a WAV file stored in memory, 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]

Public Function CopyExportedWavToMemory (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CopyExportedWavToMemory (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes CopyExportedWavToMemory (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
pBuffer | Buffer where WAV memory file contents will be copied
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 method call was successful.


DcOffsetRemovalEnable method

DcOffsetRemovalEnable method

Remarks

Enables/disables real-time DC offset removal of songs in playback..

Syntax

[Visual Basic]

Public Function DcOffsetRemovalEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DcOffsetRemovalEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes DcOffsetRemovalEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Disables DC Offset removal
true | Enables DC Offset removal

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]

Public Function ForwardSound (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ForwardSound (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes ForwardSound (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


GetCurrentPercentage method

GetCurrentPercentage method

Remarks

Gets the percentage of performed song during a playback session with the specified player.

Syntax

[Visual Basic]

Public Function GetCurrentPercentage (

nPlayerIndex as Int16

) as Int16

[C#]

public Int16 GetCurrentPercentage (

Int16 nPlayerIndex

);

[C++]

public: Int16 GetCurrentPercentage (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 play session with the specified player.

Syntax

[Visual Basic]

Public Function GetCurrentPercentageFloat (

nPlayerIndex as Int16

) as Single

[C#]

public float GetCurrentPercentageFloat (

Int16 nPlayerIndex

);

[C++]

public: float GetCurrentPercentageFloat (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


GetEAXEffectParams method

GetEAXEffectParams 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 SetEAXEffectParams method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function GetEAXEffectParams (

nOutputIndex as Int16,

ByRef nEffect as enumEaxEffects,

ByRef fReverbVolume as Single,

ByRef fReverbDecayTime as Single,

ByRef fReverbDecayHFRatio as Single

) as enumErrorCodes

[C#]

public enumErrorCodes GetEAXEffectParams (

Int16 nOutputIndex,

ref enumEaxEffects nEffect,

ref float fReverbVolume,

ref float fReverbDecayTime,

ref float fReverbDecayHFRatio

);

[C++]

public: enumErrorCodes GetEAXEffectParams (

Int16 nOutputIndex,

enumEaxEffects __gc *nEffect,

float __gc *fReverbVolume,

float __gc *fReverbDecayTime,

float __gc *fReverbDecayHFRatio

);

Parameter

Description

nOutputIndex

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.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]

Public Function GetEAXEffectWetDryMix (

nPlayerIndex as Int16,

ByRef fWetDryMixRatio as Single

) as enumErrorCodes

[C#]

public enumErrorCodes GetEAXEffectWetDryMix (

Int16 nPlayerIndex,

ref float fWetDryMixRatio

);

[C++]

public: enumErrorCodes GetEAXEffectWetDryMix (

Int16 nPlayerIndex,

float __gc *fWetDryMixRatio

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player whose volume will change
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


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]

Public Function GetFormattedSoundFileDuration (

strFileName as String

) as enumErrorCodes

[C#]

public enumErrorCodes GetFormattedSoundFileDuration (

string strFileName

);

[C++]

public: enumErrorCodes GetFormattedSoundFileDuration (

string strFileName

);

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]

Public Function GetForwardRewindGranularity (

nPlayerIndex as Int16,

ByRef fGranularity as Single

) as enumErrorCodes

[C#]

public enumErrorCodes GetForwardRewindGranularity (

Int16 nPlayerIndex,

ref float fGranularity

);

[C++]

public: enumErrorCodes GetForwardRewindGranularity (

Int16 nPlayerIndex,

float __gc *fGranularity

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fGranularity | Reference 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.NOERROR (0) | The method call was successful.


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]

Public Function GetLoadedSoundFile (

nPlayerIndex as Int16

) as String

[C#]

public string GetLoadedSoundFile (

Int16 nPlayerIndex

);

[C++]

public: string GetLoadedSoundFile (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function GetMp3BitrateType (

nPlayerIndex as Int16

) as enumMp3BitrateTypes

[C#]

public enumMp3BitrateTypes GetMp3BitrateType (

Int16 nPlayerIndex

);

[C++]

public: enumMp3BitrateTypes GetMp3BitrateType (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 Audio Sound Editor API for .NET component.

Syntax

[Visual Basic]

Public Function GetPlayerHandle (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 GetPlayerHandle (

Int16 nPlayerIndex

);

[C++]

public: Int32 GetPlayerHandle (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function GetPlayerSpeakersCount (

nPlayerIndex as Int16

) as Int16

[C#]

public Int16 GetPlayerSpeakersCount (

Int16 nPlayerIndex

);

[C++]

public: Int16 GetPlayerSpeakersCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player.

Return value

Value | Meaning
Value > 0 | The number of available speakers
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]

Public Function GetPlayerStatus (

nPlayerIndex as Int16

) as enumPlayerStatus

[C#]

public enumPlayerStatus GetPlayerStatus (

Int16 nPlayerIndex

);

[C++]

public: enumPlayerStatus GetPlayerStatus (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function GetSampleRate (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 GetSampleRate (

Int16 nPlayerIndex

);

[C++]

public: Int32 GetSampleRate (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function GetSoundFileDuration (

strFileName as String

) as enumErrorCodes

[C#]

public enumErrorCodes GetSoundFileDuration (

string strFileName

);

[C++]

public: enumErrorCodes GetSoundFileDuration (

string strFileName

);

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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

For further details about encrypted songs usage check the How to protect your music through encryption section.

Syntax

[Visual Basic]

Public Function LoadEncryptedSound (

nPlayerIndex as Int16,

strFileName as String,

strDecriptionKey as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadEncryptedSound (

Int16 nPlayerIndex,

string strFileName,

string strDecriptionKey

);

[C++]

public: enumErrorCodes LoadEncryptedSound (

Int16 nPlayerIndex,

string strFileName,

string strDecriptionKey

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the name 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

For further details about encrypted songs usage check the How to protect your music through encryption section.

Syntax

[Visual Basic]

Public Function LoadEncryptedSoundFromMemory (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

strDecriptionKey as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadEncryptedSoundFromMemory (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

string strDecriptionKey

);

[C++]

public: enumErrorCodes LoadEncryptedSoundFromMemory (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

string strDecriptionKey

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the sound
pBuffer | Buffer containing encrypted sound data
nBufferLength | 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.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_SYNC_LOADED.

For further details about encrypted songs usage check the How to protect your music through encryption section.

Syntax

[Visual Basic]

Public Function LoadEncryptedSoundFromMemorySync (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

strDecriptionKey as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadEncryptedSoundFromMemorySync (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

string strDecriptionKey

);

[C++]

public: enumErrorCodes LoadEncryptedSoundFromMemorySync (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

string strDecriptionKey

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the sound
pBuffer | Buffer containing encrypted sound data
nBufferLength | 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.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_SYNC_LOADED.

For further details about encrypted songs usage check the How to protect your music through encryption section.

Syntax

[Visual Basic]

Public Function LoadEncryptedSoundSync (

nPlayerIndex as Int16,

strFileName as String,

strDecriptionKey as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadEncryptedSoundSync (

Int16 nPlayerIndex,

string strFileName,

string strDecriptionKey

);

[C++]

public: enumErrorCodes LoadEncryptedSoundSync (

Int16 nPlayerIndex,

string strFileName,

string strDecriptionKey

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the sound
strFilename | String containing the name 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_DOWNLOAD_BUFFERING.

In case you should be downloading a single file (not a radio stream), once the download completes the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOAD_COMPLETE: 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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_STREAM_LOADED.

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]

Public Function LoadInternetStream (

nPlayerIndex as Int16,

strURL as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadInternetStream (

Int16 nPlayerIndex,

string strURL

);

[C++]

public: enumErrorCodes LoadInternetStream (

Int16 nPlayerIndex,

string strURL

);

Parameter | Description
nPlayerIndex | 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 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

(**) 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_DOWNLOAD_BUFFERING.

n case you should be downloading a single file (not a radio stream), once the download completes the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOAD_COMPLETE: 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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_STREAM_LOADED.

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]

Public Function LoadInternetStreamEx (

nPlayerIndex as Int16,

strURL as String,

nFormat as enumFileTypes,

nOffsetInSizePerc as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes LoadInternetStreamEx (

Int16 nPlayerIndex,

string strURL,

enumFileTypes nFormat,

Int32 nOffsetInSizePerc

);

[C++]

public: enumErrorCodes LoadInternetStreamEx (

Int16 nPlayerIndex,

string strURL,

enumFileTypes nFormat,

Int32 nOffsetInSizePerc

);

Parameter

Description

nPlayerIndex

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

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.

The passed value is expressed in percentage of the original file size: this means that, 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 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

(**) 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 song file can be a stream, a MOD music file or a CD audio track. If the file is in RAW format use the LoadSoundFromRawFile method.

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.

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 "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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

Syntax

[Visual Basic]

Public Function LoadSound (

nPlayerIndex as Int16,

strFileName as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSound (

Int16 nPlayerIndex,

string strFileName

);

[C++]

public: enumErrorCodes LoadSound (

Int16 nPlayerIndex,

string strFileName

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the sound
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
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. A less detailed analysis is 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.

The song 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.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

Syntax

[Visual Basic]

Public Function LoadSoundFast (

nPlayerIndex as Int16,

strFileName as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFast (

Int16 nPlayerIndex,

string strFileName

);

[C++]

public: enumErrorCodes LoadSoundFast (

Int16 nPlayerIndex,

string strFileName

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the sound
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.
bFast | Flag that determines if

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


LoadSoundInMono method

LoadSoundInMono method

Remarks

Loads a song from the specified file and convert it to Mono: only MP3, MP2 and MP1 formats will be converted from Stereo to Mono while other Stereo formats will fail.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

Syntax

[Visual Basic]

Public Function LoadSoundInMono (

nPlayerIndex as Int16,

strFileName as String,

bFast as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundInMono (

Int16 nPlayerIndex,

string strFileName,

bool bFast

);

[C++]

public: enumErrorCodes LoadSoundInMono (

Int16 nPlayerIndex,

string strFileName,

bool bFast

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the sound
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.
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.

(*) 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).


LoadSoundForEAX method

LoadSoundForEAX method

Remarks

Loads a song from the specified file with EAX compatible settings (Mono). The song file can be a stream or a MOD music file.

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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

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]

Public Function LoadSoundForEAX (

nPlayer as Int16,

strFileName as String,

bFast as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundForEAX (

Int16 nPlayer,

string strFileName,

bool bFast

);

[C++]

public: enumErrorCodes LoadSoundForEAX (

Int16 nPlayer,

string strFileName,

bool bFast

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
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.
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.

(*) 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).


LoadSoundFromEditingSession method

LoadSoundFromEditingSession method

Remarks

Loads a sound from the given instance of Audio Sound Editor for .NET or from the given instance of Audio Sound Editor API for .NET .

Syntax

[Visual Basic]

Public Function LoadSoundFromEditingSession (

nPlayerIndex as Int16,

hWndEditorCtrl as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFromEditingSession (

Int16 nPlayerIndex,

IntPtr hWndEditorCtrl

);

[C++]

public: enumErrorCodes LoadSoundFromEditingSession (

Int16 nPlayerIndex,

IntPtr hWndEditorCtrl

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
hWndEditorCtrl | The value of the Handle property of an instance of Audio Sound Editor for .NET or Audio Sound Editor API for .NET

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.


LoadSoundFromMemory method

LoadSoundFromMemory method

Remarks

Loads a sound file stored in memory. 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

Syntax

[Visual Basic]

Public Function LoadSoundFromMemory (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFromMemory (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes LoadSoundFromMemory (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the memory sound
pBuffer | Buffer containing sound data
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.

Sample

Below you can find a couple of samples that demonstrate how to load a sound stored in memory in Visual Basic.NET and Visual C# : in these samples the file is taken from a file and its contents are stored in memory.

Visual Basic.NET

' declare the memory buffer (cannot be a local variable)

Dim m_byteBuffer() As Byte

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click

 Dim openFileDialog1 As New OpenFileDialog

 If openFileDialog1.ShowDialog() <> DialogResult.OK Then

     Return

 End If

 ' put the song file into a stream

 Dim streamFile As FileStream

 streamFile = New FileStream(openFileDialog1.FileName, FileMode.Open)

 Dim binReader As BinaryReader

 binReader = New BinaryReader(streamFile)

 ' reallocate the memory buffer space and store the song

 ReDim m_byteBuffer(streamFile.Length)

 binReader.Read(m_byteBuffer, 0, streamFile.Length)

 If AudioDjStudio1.LoadSoundFromMemory(0, m_byteBuffer, streamFile.Length) = AudioDjStudio.enumErrorCodes.NOERROR Then

     ' do domething

     ....

 End If

End Sub

Visual C#.NET

// declare the memory buffer (cannot be a local variable)

byte[] m_byteBuffer = null;

private void buttonLoad1_Click(object sender, System.EventArgs e)

{

 OpenFileDialog openFileDialog1 = new OpenFileDialog();

 if (openFileDialog1.ShowDialog() != DialogResult.OK)

     return;

 // put the song file into a stream

 FileStream      streamFile = new FileStream (openFileDialog1.FileName, FileMode.Open);

 BinaryReader    binReader = new BinaryReader (streamFile);

 //  allocate the memory buffer space and store the song

 m_byteBuffer = new byte[streamFile.Length];

 binReader.Read (m_byteBuffer, 0, (int) streamFile.Length);

 // load song from memory buffer

 if (audioDjStudio1.LoadSoundFromMemory (0, m_byteBuffer, (Int32) streamFile.Length) == enumErrorCodes.NOERROR)

 {

     // do something

     ...

 }

}


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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_SYNC_LOADED.

Syntax

[Visual Basic]

Public Function LoadSoundFromMemorySync (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFromMemorySync (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes LoadSoundFromMemorySync (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the memory sound
pBuffer | Buffer containing sound data
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 method call was successful.


LoadSoundFromRawFile method

LoadSoundFromRawFile method

Remarks

Loads a song from the specified file in RAW format.

RAW files cannot be used in the following situations:

· inside playlists
· with the automatic fader
· BPM calculation
· initial and final silence positions detection
· loading from Internet stream
· tempo, playback rate and pitch change

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

Syntax

[Visual Basic]

Public Function LoadSoundFromRawFile (

nPlayerIndex as Int16,

strFileName as String,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as bool,

nFrequency as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFromRawFile (

Int16 nPlayerIndex,

string strFileName,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

[C++]

public: enumErrorCodes LoadSoundFromRawFile (

Int16 nPlayerIndex,

string strFileName,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the sound
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.

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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

Syntax

[Visual Basic]

Public Function LoadSoundFromRawMemory (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as Boolean,

nFrequency as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFromRawMemory (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

[C++]

public: enumErrorCodes LoadSoundFromRawMemory (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will load the memory sound
pBuffer | Buffer containing sound data
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
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: 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 method call was successful.


LoadSoundFromRecordingSession method

LoadSoundFromRecordingSession method

Remarks

Loads a sound recorded by an instance of the Audio Sound Recorder for .NET Winform component or by another instance of the Audio Sound Recorder API for .NET component.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

For further details about the integration between Audio Dj Studio API for .NET and Audio Sound Recorder API for .NET, check the How to load and play sounds recorded by Audio Sound Recorder API section.

Syntax

[Visual Basic]

Public Function LoadSoundFromRecordingSession (

nPlayerIndex as Int16,

hWndRecorderCtrl as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFromRecordingSession (

Int16 nPlayerIndex,

IntPtr hWndRecorderCtrl,

);

[C++]

public: enumErrorCodes LoadSoundFromRecordingSession (

Int16 nPlayerIndex,

IntPtr hWndRecorderCtrl,

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
hWndRecorderCtrl | The value of the Handle property of an instance of Audio Sound Recorder for .NET or Audio Sound Recorder API for .NET

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.


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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

For further details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function LoadSoundFromZip (

nPlayerIndex as Int16,

strZipPathname as String,

strPassword as String,

strEntryName as String,

bFailOnLowMemory as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFromZip (

Int16 nPlayerIndex,

string strZipPathname,

string strPassword,

string strEntryName,

bool bFailOnLowMemory

);

[C++]

public: enumErrorCodes LoadSoundFromZip (

Int16 nPlayerIndex,

string strZipPathname,

string strPassword,

string strEntryName,

bool bFailOnLowMemory

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
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.
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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

For further details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function LoadSoundFastFromZip (

nPlayerIndex as Int16,

strZipPathname as String,

strPassword as String,

strEntryName as String,

bFailOnLowMemory as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundFastFromZip (

Int16 nPlayerIndex,

string strZipPathname,

string strPassword,

string strEntryName,

bool bFailOnLowMemory

);

[C++]

public: enumErrorCodes LoadSoundFastFromZip (

Int16 nPlayerIndex,

string strZipPathname,

string strPassword,

string strEntryName,

bool bFailOnLowMemory

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
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.
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.


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, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_SYNC_LOADED.

Accepted audio formats are the same as seen inside the LoadSound method.

Syntax

[Visual Basic]

Public Function LoadSoundSync (

nPlayer as Int16,

strFileName as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundSync (

Int16 nPlayer,

string strFileName

);

[C++]

public: enumErrorCodes LoadSoundSync (

Int16 nPlayer,

string strFileName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the player that will load the sound
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
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: 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).


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, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_SYNC_LOADED.

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]

Public Function LoadSoundSyncFromZip (

nPlayerIndex as Int16,

strZipPathname as String,

strPassword as String,

strEntryName as String,

bFailOnLowMemory as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundSyncFromZip (

Int16 nPlayerIndex,

string strZipPathname,

string strPassword,

string strEntryName,

bool bFailOnLowMemory

);

[C++]

public: enumErrorCodes LoadSoundSyncFromZip (

Int16 nPlayerIndex,

string strZipPathname,

string strPassword,

string strEntryName,

bool bFailOnLowMemory

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
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.
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.


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 CallbackForCdDrivesEvents delegate which is invoked with the nEvent parameter set to:

· EV_CD_READ_TRACK_START invoked once at the beginning
· EV_CD_READ_TRACK_PERC invoked multiple times reporting the current advancement percentage inside the nData1 parameter
· EV_CD_READ_TRACK_STOP invoked once the reading is completed

Syntax

[Visual Basic]

Public Function LoadTrackFromCd (

nPlayerIndex as Int16,

nDriveIndex as Int16,

nTrackIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes LoadTrackFromCd (

Int16 nPlayerIndex,

Int16 nDriveIndex,

Int16 nTrackIndex

);

[C++]

public: enumErrorCodes LoadTrackFromCd (

Int16 nPlayerIndex,

Int16 nDriveIndex,

Int16 nTrackIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nDriveIndex | Number representing the zero-based index of the involved CD drive
nTrackIndex | 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 method 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PAUSED.

Syntax

[Visual Basic]

Public Function PauseSound (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PauseSound (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PauseSound (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Once the sound has been performed completely, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE.

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.

Syntax

[Visual Basic]

Public Function PlaySound (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlaySound (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlaySound (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Syntax

[Visual Basic]

Public Function PlaySoundLoop (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlaySoundLoop (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlaySoundLoop (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method call was successful


PlaySoundRange method

PlaySoundRange method

Remarks

Plays a specific range of the song 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Once the sound has been performed completely, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE..

Syntax

[Visual Basic]

Public Function PlaySound (

nPlayerIndex as Int16,

nFromPosition as Int32,

nToPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlaySound (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition

);

[C++]

public: enumErrorCodes PlaySound (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will play the sound
nFromPosition | Range starting point expressed in the unit specified by the ScaleUnits property.
nToPosition | Range ending point expressed 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.NOERROR (0) | The method call was successful


PlaySoundRangeLoop method

PlaySoundRangeLoop method

Remarks

Plays in loop mode a specific range of the song 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Each loop completion invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_RANGE_LOOP_DONE

Once the sound has been performed completely, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE..

Syntax

[Visual Basic]

Public Function PlaySoundRangeLoop (

nPlayerIndex as Int16,

nFromPosition as Int32,

nToPosition as Int32,

nLoopCount as Int32,

) as enumErrorCodes

[C#]

public enumErrorCodes PlaySoundRangeLoop (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition,

Int32 nLoopCount

);

[C++]

public: enumErrorCodes PlaySoundRangeLoop (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition,

Int32 nLoopCount

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will play the sound
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.NOERROR (0) | The method call was successful


PlaySoundDisableLoop method

PlaySoundDisableLoop method

Remarks

Disables an eventual loop, set by a previous call to PlaySoundLoop or PlaySoundEnableLoop methods, without stopping the current playback: playback will terminate when reaching the eventual end of the range established by the call to the PlaySoundRangeLoop or PlaySoundEnableLoop methods.

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]

Public Function PlaySoundDisableLoop (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlaySoundDisableLoop (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlaySoundDisableLoop (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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 of 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Each loop completion invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_RANGE_LOOP_DONE : the only exception is the completion of the latest loop where the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE.

Syntax

[Visual Basic]

Public Function PlaySoundEnableLoop (

nPlayerIndex as Int16,

nFromPosition as Int32,

nToPosition as Int32,

nLoopCount as Int32,

) as enumErrorCodes

[C#]

public enumErrorCodes PlaySoundEnableLoop (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition,

Int32 nLoopCount

);

[C++]

public: enumErrorCodes PlaySoundEnableLoop (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition,

Int32 nLoopCount

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will play the sound
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.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.

Syntax

[Visual Basic]

Public Function PlaySoundMoveFinalPos (

nPlayerIndex as Int16

nToPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlaySoundMoveFinalPos (

Int16 nPlayerIndex,

Int32 nToPosition

);

[C++]

public: enumErrorCodes PlaySoundMoveFinalPos (

Int16 nPlayerIndex,

Int32 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


PlaySoundFromRecorderEx method

PlaySoundFromRecorderEx method

Remarks

Activates the given instance of Audio Sound Recorder API for .NET 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

For further details about the integration between Audio Dj Studio API for .NET and Audio Sound Recorder API for .NET, check the How to load and play sounds recorded by Audio Sound Recorder API section.

Syntax

[Visual Basic]

Public Function PlaySoundFromRecorderEx (

nPlayerIndex as Int16,

hWndRecorderCtrl as IntPtr,

bMono as Boolean,

nInputDevice as Int16,

nInputChannel as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlaySoundFromRecorderEx (

Int16 nPlayerIndex,

IntPtr hWndRecorderCtrl,

bool bMono,

Int16 nInputDevice,

Int16 nInputChannel

);

[C++]

public: enumErrorCodes PlaySoundFromRecorderEx (

Int16 nPlayerIndex,

IntPtr hWndRecorderCtrl,

bool bMono,

Int16 nInputDevice,

Int16 nInputChannel

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

hWndRecorderCtrl

Window handle to the instance of the Audio Sound Recorder API for .NET control

bMono

Boolean value that specifies to play incoming sound data in Mono or Stereo.

Supported values are the following:

Value | Meaning
false | Play sound data in Stereo
true | 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 Audio Sound Recorder API for .NET in order to know how many input devices are currently installed on the system and the GetInputDeviceDesc method of Audio Sound Recorder API for .NET 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.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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Syntax

[Visual Basic]

Public Function ResumeSound (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ResumeSound (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes ResumeSound (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function RewindSound (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes RewindSound (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes RewindSound (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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 player should be "stopped", a call to this method will move the playback position and will automatically put the player in "paused" state.

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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE..

Syntax

[Visual Basic]

Public Function SeekSound (

nPlayerIndex as Int16,

nOffset as UInt32

) as enumErrorCodes

[C#]

public enumErrorCodes SeekSound (

Int16 nPlayerIndex,

UInt32 nOffset

);

[C++]

public: enumErrorCodes SeekSound (

Int16 nPlayerIndex,

UInt32 nOffset

);

Parameter | Description
nPlayerIndex | 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 "true".

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.


SetEAXEffect method

SetEAXEffect method

Remarks

Applies/removes a specific EAX effect, using default parameters, to the given output device. If you need to apply the EAX effect with different reverb parameters, use the SetEAXEffectParams method.

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 GetEAXEffectParams 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]

Public Function SetEAXEffect (

nOutputIndex as Int16,

nEffect as enumEaxEffects

) as enumErrorCodes

[C#]

public enumErrorCodes SetEAXEffect (

Int16 nOutputIndex,

enumEaxEffects nEffect

);

[C++]

public: enumErrorCodes SetEAXEffect (

Int16 nOutputIndex,

enumEaxEffects nEffect

);

Parameter

Description

nOutputIndex

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.NOERROR (0) | The method call was successful.


SetEAXEffectParams method

SetEAXEffectParams method

Remarks

Applies/removes a certain 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 GetEAXEffectParams 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]

Public Function SetEAXEffectParams (

nOutputIndex as Int16,

nEffect as enumEaxEffects,

fReverbVolume as Single,

fReverbDecayTime as Single,

fReverbDecayHFRatio as Single

) as enumErrorCodes

[C#]

public enumErrorCodes SetEAXEffectParams (

Int16 nOutputIndex,

enumEaxEffects nEffect,

float fReverbVolume,

float fReverbDecayTime,

float fReverbDecayHFRatio

);

[C++]

public: enumErrorCodes SetEAXEffectParams (

Int16 nOutputIndex,

enumEaxEffects nEffect,

float fReverbVolume,

float fReverbDecayTime,

float fReverbDecayHFRatio

);

Parameter

Description

nOutputIndex

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.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]

Public Function SetEAXEffectPresets (

nOutputIndex as Int16,

nEffect as enumEaxEffects

) as enumErrorCodes

[C#]

public enumErrorCodes SetEAXEffectPresets (

Int16 nOutputIndex,

enumEaxEffects nEffect

);

[C++]

public: enumErrorCodes SetEAXEffectPresets (

Int16 nOutputIndex,

enumEaxEffects nEffect

);

Parameter

Description

nOutputIndex

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.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]

Public Function SetEAXEffectWetDryMix (

nPlayerIndex as Int16,

fWetDryMixRatio as Single

) as enumErrorCodes

[C#]

public enumErrorCodes SetEAXEffectWetDryMix (

Int16 nPlayerIndex,

float fWetDryMixRatio

);

[C++]

public: enumErrorCodes SetEAXEffectWetDryMix (

Int16 nPlayerIndex,

float fWetDryMixRatio

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player whose volume will change
fWetDryMixRatio | Floating point value representing the wet/dry mix ratio expressed in percentage. 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 returned 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]

Public Function SetForwardRewindGranularity (

nPlayerIndex as Int16,

fGranularity as Single

) as enumErrorCodes

[C#]

public enumErrorCodes SetForwardRewindGranularity (

Int16 nPlayerIndex,

float fGranularity

);

[C++]

public: enumErrorCodes SetForwardRewindGranularity (

Int16 nPlayerIndex,

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.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]

Public Function SetSampleRate (

nPlayerIndex as Int16,

nSampleRate as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetSampleRate (

Int16 nPlayerIndex,

Int32 nSampleRate

);

[C++]

public: enumErrorCodes SetSampleRate (

Int16 nPlayerIndex,

Int32 nSampleRate

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nValue | 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.NOERROR (0) | The method 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]

Public Function SetSmoothingTimeOnSeekOps (

nPlayerIndex as Int16,

nSmoothTime as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetSmoothingTimeOnSeekOps (

Int16 nPlayerIndex,

Int32 nSmoothTime

);

[C++]

public: enumErrorCodes SetSmoothingTimeOnSeekOps (

Int16 nPlayerIndex,

Int32 nSmoothTime

);

Parameter

Description

nPlayerIndex

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.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.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function SoundDurationGet (

nPlayerIndex as Int16,

ByRef fDuration as Double,

bKeepCountOfRateChange as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SoundDurationGet (

Int16 nPlayerIndex,

ref double fDuration,

bool bKeepCountOfRateChange

);

[C++]

public: enumErrorCodes SoundDurationGet (

Int16 nPlayerIndex,

double __gc *fDuration,

bool bKeepCountOfRateChange

);

Parameter

Description

nPlayerIndex

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 duration must keep count of eventual playback rate changes set through previous calls to the Effects.PlaybackTempSet or Effects.PlaybackRateSet methods.

Supported values are the following:

Mnemonic constant | Meaning
false | Don't keep count of playback rate changes
true | Keep count of playback rate changes

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.


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]

Public Function SoundDurationStringGet (

nPlayerIndex as Int16,

bShowHour as Boolean,

bShowMs as Boolean,

strHourSeparator as String,

strMsSeparator as String,

nNumberOfMsDigits as Int32,

bKeepCountOfRateChange as Boolean

) as String

[C#]

public string SoundDurationStringGet (

Int16 nPlayerIndex,

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits,

bool bKeepCountOfRateChange

);

[C++]

public: string SoundDurationStringGet (

Int16 nPlayerIndex,

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits,

bool bKeepCountOfRateChange

);

Parameter

Description

nPlayerIndex

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:

false | Doesn't show hour value
true | Shows hour value

bShowMs

Boolean value that specifies the player to avoid displaying the 'milliseconds' position field.

Supported values are the following:

false | Doesn't show milliseconds value
true | 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 | Meaning
false | Doesn't keep count of playback rate changes
true | 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]

Public Function SoundPositionGet (

nPlayerIndex as Int16,

ByRef fPosition as double,

bKeepCountOfRateChange as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SoundPositionGet (

Int16 nPlayerIndex,

ref double fPosition,

bool bKeepCountOfRateChange

);

[C++]

public: enumErrorCodes SoundPositionGet (

Int16 nPlayerIndex,

double __gc *fPosition,

bool bKeepCountOfRateChange

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | Don't keep count of playback rate changes
true | Keep count of playback rate changes

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.


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]

Public Function SoundPositionStringGet (

nPlayerIndex as Int16,

bShowHour as Boolean,

bShowMs as Boolean,

strHourSeparator as String,

strMsSeparator as String,

nNumberOfMsDigits as Int32,

bKeepCountOfRateChange as Boolean

) as String

[C#]

public string SoundPositionStringGet (

Int16 nPlayerIndex,

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits,

bool bKeepCountOfRateChange

);

[C++]

public: string SoundPositionStringGet (

Int16 nPlayerIndex,

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits,

bool bKeepCountOfRateChange

);

Parameter

Description

nPlayerIndex

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:

false | Doesn't show hour value
true | Shows hour value

bShowMs

Boolean value that specifies the player to avoid displaying the 'milliseconds' position field.

Supported values are the following:

false | Doesn't show milliseconds value
true | 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 | Meaning
false | Doesn't keep count of playback rate changes
true | 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_STOPPED.

Syntax

[Visual Basic]

Public Function StopSound (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StopSound (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes StopSound (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


StopSoundFromRecorder method

StopSoundFromRecorder method

Remarks

Stops a playback previously activated through a call to the PlaySoundFromRecorderEx method.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_STOPPED.

For further details about the integration between Audio Dj Studio API for .NET and Audio Sound Recorder API for .NET, check the How to load and play sounds recorded by Audio Sound Recorder API section.

Syntax

[Visual Basic]

Public Function StopSoundFromRecorder (

nPlayerIndex as Int16,

hWndRecorderCtrl as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes StopSoundFromRecorder (

Int16 nPlayerIndex,

IntPtr hWndRecorderCtrl,

);

[C++]

public: enumErrorCodes StopSoundFromRecorder (

Int16 nPlayerIndex,

IntPtr hWndRecorderCtrl,

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
hWndRecorderCtrl | Window handle to the instance of the Audio Sound Recorder API for .NET control

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.


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]

Public Function StreamBalanceGet (

nPlayerIndex as Int16,

ByRef fValue as float

) as enumErrorCodes

[C#]

public enumErrorCodes StreamBalanceGet (

Int16 nPlayerIndex,

ref float fValue

);

[C++]

public: enumErrorCodes StreamBalanceGet (

Int16 nPlayerIndex,

float __gc *fValue

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nValue | Reference that, on return from the method call, will contain the volume balance value in the range from -50 to 50. The value 0 means that the balance is centred

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


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]

Public Function StreamBalanceSet (

nPlayerIndex as Int16,

fValue as float

) as enumErrorCodes

[C#]

public enumErrorCodes StreamBalanceSet (

Int16 nPlayerIndex,

float fValue

);

[C++]

public: enumErrorCodes StreamBalanceSet (

Int16 nPlayerIndex,

float fValue

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nValue | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamMixerCreate (

nOutput as Int16,

nFrequency as Int32,

nChannels as Int16

) as Int32

[C#]

public Int32 StreamMixerCreate (

Int16 nOutput,

Int32 nFrequency,

Int16 nChannels

);

[C++]

public: Int32 StreamMixerCreate (

Int16 nOutput,

Int32 nFrequency,

Int16 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 Audio Sound Recorder API for .NET component, 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 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]

Public Function StreamMixerCreateWithSurround (

nOutput as Int16,

nFrequency as Int32,

nChannels as Int16

) as Int32

[C#]

public Int32 StreamMixerCreateWithSurround (

Int16 nOutput,

Int32 nFrequency,

Int16 nChannels

);

[C++]

public: Int32 StreamMixerCreateWithSurround (

Int16 nOutput,

Int32 nFrequency,

Int16 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 Audio Sound Recorder component, 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]

Public StreamMixerGetIdFromOutput (

nOutputIndex as Int16

) as Int16

[C#]

public Int16 StreamMixerGetIdFromOutput (

Int16 nOutputIndex

);

[C++]

public: Int16 StreamMixerGetIdFromOutput (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | 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)
Value > 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 InitSoundSystem 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]

Public Function StreamMixerPlayerAdd (

nStreamMixerID as Int32,

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamMixerPlayerAdd (

Int32 nStreamMixerID,

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes StreamMixerPlayerAdd (

Int32 nStreamMixerID,

Int16 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


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 InitSoundSystem 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]

Public Function StreamMixerPlayerAddToSpeaker (

nStreamMixerID as Int32,

nPlayerIndex as Int16,

nSpeaker as enumSpeakers

) as enumErrorCodes

[C#]

public enumErrorCodes StreamMixerPlayerAddToSpeaker (

Int32 nStreamMixerID,

Int16 nPlayerIndex,

enumSpeakers nSpeaker

);

[C++]

public: enumErrorCodes StreamMixerPlayerAddToSpeaker (

Int32 nStreamMixerID,

Int16 nPlayerIndex,

enumSpeakers nSpeaker

);

Parameter

Description

nStreamMixerID

Unique identifier of the stream mixer created by a previous call to the StreamMixerCreateWithSurround method

nPlayerIndex

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 InitSoundSystem 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]

Public Function StreamMixerPlayerRemove (

nStreamMixerID as Int32,

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamMixerPlayerRemove (

Int32 nStreamMixerID,

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes StreamMixerPlayerRemove (

Int32 nStreamMixerID,

Int16 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 InitSoundSystem 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]

Public Function StreamOutputDeviceGet (

nPlayerIndex as Int16

) as Int16

[C#]

public Int16 StreamOutputDeviceGet (

Int16 nPlayerIndex

);

[C++]

public: Int16 StreamOutputDeviceGet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 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 InitSoundSystem 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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_OUTPUT_DEVICE_CHANGED.

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 output devices management, take a look to the How to work with multiple output devices and speakers section.

IMPORTANT NOTE WHEN DEALING WITH VIDEO PLAYBACK: when playing a video clip through the VideoPlayer class, 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]

Public Function StreamOutputDeviceSet (

nPlayerIndex as Int16,

nOutputIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamOutputDeviceSet (

Int16 nPlayerIndex,

Int16 nOutputIndex

);

[C++]

public: enumErrorCodes StreamOutputDeviceSet (

Int16 nPlayerIndex,

Int16 nOutputIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nOutputIndex | 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.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]

Public StreamOutputSpeakerGet (

nPlayerIndex as Int16

) as enumSpeakers

[C#]

public enumSpeakers StreamOutputSpeakerGet (

Int16 nPlayerIndex

);

[C++]

public: enumSpeakers StreamOutputSpeakerGet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public StreamOutputSpeakerSet (

nPlayerIndex as Int16,

nNewSpeaker as enumSpeakers

) as enumErrorCodes

[C#]

public enumErrorCodes StreamOutputSpeakerSet (

Int16 nPlayerIndex,

enumSpeakers nNewSpeaker

);

[C++]

public: enumErrorCodes StreamOutputSpeakerSet (

Int16 nPlayerIndex,

enumSpeakers nNewSpeaker

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nNewSpeaker

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]

Public StreamOutputSpeakersRearAndCenterSwap (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamOutputSpeakersRearAndCenterSwap (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes StreamOutputSpeakersRearAndCenterSwap (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public StreamOutputSpeakerSwap (

nPlayerIndex1 as Int16,

nPlayerIndex2 as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamOutputSpeakerSwap (

Int16 nPlayerIndex1,

Int16 nPlayerIndex2

);

[C++]

public: enumErrorCodes StreamOutputSpeakerSwap (

Int16 nPlayerIndex1,

Int16 nPlayerIndex2

);

Parameter | Description
nPlayerIndex1 | Number representing the zero-based index of the first involved player
nPlayerIndex2 | 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 EV_VUMETER event of the CallbackForPlayersEvents delegate 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 EV_VUMETER 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 EV_VUMETER event.

Syntax

[Visual Basic]

Public StreamPeakLevelsGet (

nPlayerIndex as Int16,

tPeakLevels() as Single,

nLengthInMs as Int32,

bRms as Boolean,

bStereo as Boolean,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes StreamPeakLevelsGet (

Int16 nPlayerIndex,

float[] tPeakLevels,

Int32 nLengthInMs,

bool bRms,

bool bStereo,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes StreamPeakLevelsGet (

Int16 nPlayerIndex,

float[] tPeakLevels,

Int32 nLengthInMs,

bool bRms,

bool bStereo,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

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
false | Use peak levels.
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
false | Get mono levels, allowing to retrieve a separate level for each channel.
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.NOERROR (0) | The method call was successful.


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.

When version 3.0 or higher of the .NET framework is available, this method and the StreamQueuePushData method can be used in conjunction with the System.Speech.Synthesis.SpeechSynthesizer class in order to provide a mean for redirecting the output or applying special effect and visual feedbacks to the output of the System.Speech.Synthesis.SpeechSynthesizer.SetOutputToAudioStream method. See the How to integrate Microsoft's Speech API tutorial for details.

Syntax

[Visual Basic]

Public Function StreamQueueCreate (

nPlayerIndex as Int16,

nFrequency as Int32,

nChannels as Int16,

nBitsPerSample as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamQueueCreate (

Int16 nPlayerIndex,

Int32 nFrequency,

Int16 nChannels

Int16 nBitsPerSample

);

[C++]

public: enumErrorCodes StreamQueueCreate (

Int16 nPlayerIndex,

Int32 nFrequency,

Int16 nChannels

Int16 nBitsPerSample

);

Parameter | Description
nPlayerIndex | 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 method call was successful.


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]

Public Function StreamQueueBufferedDataGet (

nPlayerIndex as Int16,

ByRef nDataLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamQueueBufferedDataGet (

Int16 nPlayerIndex,

ref Int32 nDataLength

);

[C++]

public: enumErrorCodes StreamQueueBufferedDataGet (

Int16 nPlayerIndex,

Int32 __gc *nDataLength

);

Parameter | Description
nPlayerIndex | 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 method call was successful.


StreamQueuePushData method

StreamQueuePushData method

Remarks

Pushes uncompressed PCM data taken from a memory buffer into a sound 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 invoke the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_STALLED; when enough PCM data should be available again, the CallbackForPlayersEvents delegate is automatically invoked again with the nEvent parameter set to EV_SOUND_PLAYING.

The amount of still buffered bytes can be obtained through the StreamQueueBufferedDataGet method.

Syntax

[Visual Basic]

Public Function StreamQueuePushData (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamQueuePushData (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes StreamQueuePushData (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
pBuffer | Buffer containing 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 method call was successful.


StreamQueuePushDataMs method

StreamQueuePushDataMs method

Remarks

Pushes uncompressed PCM data taken from a memory stream into a sound 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 invoke the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_STALLED; when enough PCM data should be available again, the CallbackForPlayersEvents delegate is automatically invoked again with the nEvent parameter set to EV_SOUND_PLAYING.

When version 3.0 or higher of the .NET framework is available, this method and the StreamQueueCreate method can be used in conjunction with the System.Speech.Synthesis.SpeechSynthesizer class in order to provide a mean for redirecting the output or applying special effect and visual feedbacks to the output of the System.Speech.Synthesis.SpeechSynthesizer.SetOutputToAudioStream method. See the How to integrate Microsoft's Speech API tutorial for details.

Syntax

[Visual Basic]

Public Function StreamQueuePushDataMs (

nPlayerIndex as Int16,

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes StreamQueuePushDataMs (

Int16 nPlayerIndex,

MemoryStream ms

);

[C++]

public: enumErrorCodes StreamQueuePushDataMs (

Int16 nPlayerIndex,

MemoryStream ms

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
ms | Memory stream containing uncompressed PCM data to push into the queue

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.


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]

Public StreamVolumeDirectSoundBufferGet (

nPlayerIndex as Int16,

nScaleType as enumVolumeScales

) as float

[C#]

public float StreamVolumeDirectSoundBufferGet (

Int16 nPlayerIndex,

enumVolumeScales nScaleType

);

[C++]

public: float StreamVolumeDirectSoundBufferGet (

Int16 nPlayerIndex,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player whose volume will change

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


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]

Public Function StreamVolumeDirectSoundBufferSet (

nPlayerIndex as Int16,

nVolume as float,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes StreamVolumeDirectSoundBufferSet (

Int16 nPlayerIndex,

float nVolume,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes StreamVolumeDirectSoundBufferSet (

Int16 nPlayerIndex,

float nVolume,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nVolume

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 value

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.NOERROR (0) | The method call was successful.


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]

Public StreamVolumeLevelGet (

nPlayerIndex as Int16,

fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes StreamVolumeLevelGet (

Int16 nPlayerIndex,

ref float fValue,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes StreamVolumeLevelGet (

Int16 nPlayerIndex,

float __gc *fValue,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player whose volume will change

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.NOERROR (0) | The method call was successful.


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 5.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 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.

Syntax

[Visual Basic]

Public Function StreamVolumeLevelSet (

nPlayerIndex as Int16,

fValue as float,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes StreamVolumeLevelSet (

Int16 nPlayerIndex,

float fValue,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes StreamVolumeLevelSet (

Int16 nPlayerIndex,

float fValue,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

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 value

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.NOERROR (0) | The method call was successful.


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]

Public Function StreamVolumeIsSliding (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool StreamVolumeIsSliding (

Int16 nPlayerIndex

);

[C++]

public: bool StreamVolumeIsSliding (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player

Return value

Mnemonic constant | Meaning
false | Volume sliding is not being performed
true | 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 container application is notified through the CallbackForPlayersEvents delegate which is invoked every 15 milliseconds with the nEvent parameter set to EV_FADING_VOLUME_CHANGED and with the nData1 parameter containing the new volume

When the volume sliding reaches the target volume, the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_VOLUME_SLIDE_COMPLETED.

Syntax

[Visual Basic]

Public Function StreamVolumeSlide (

nPlayerIndex as Int16,

nSlideDuration as Int32,

fVolumeTarget as Single,

nScaleType as enumVolumeScales,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamVolumeSlide (

Int16 nPlayerIndex,

Int32 nSlideDuration,

float fVolumeTarget,

enumVolumeScales nScaleType,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes StreamVolumeSlide (

Int16 nPlayerIndex,

Int32 nSlideDuration,

float fVolumeTarget,

enumVolumeScales nScaleType,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

Parameter

Description

nPlayerIndex

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.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 container application is notified through the CallbackForPlayersEvents delegate which is invoked every 15 milliseconds with the nEvent parameter set to EV_FADING_VOLUME_CHANGED and with the nData1 parameter containing the new volume

When the volume sliding reaches the target volume, the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_VOLUME_SLIDE_COMPLETED.

Syntax

[Visual Basic]

Public Function StreamVolumeSlideEx (

nPlayerIndex as Int16,

nSlideDuration as Int32,

fVolumeTarget as Single,

nScaleType as enumVolumeScales,

nCurveType as enumVolumeCurves,

nLeftX as Int16,

nLeftY as Int16,

nRightX as Int16,

nRightY as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamVolumeSlideEx (

Int16 nPlayerIndex,

Int32 nSlideDuration,

float fVolumeTarget,

enumVolumeScales nScaleType,

enumVolumeCurves nCurveType,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 nRightY

);

[C++]

public: enumErrorCodes StreamVolumeSlideEx (

Int16 nPlayerIndex,

Int32 nSlideDuration,

float fVolumeTarget,

enumVolumeScales nScaleType,

enumVolumeCurves nCurveType,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 nRightY

);

Parameter

Description

nPlayerIndex

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.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 or a fade-out after a StopSound call.

During the fading session the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to the following values:

· EV_FADEIN_STARTED, EV_FADING_VOLUME_CHANGED and EV_FADEIN_COMPLETED after a call to the PlaySound method
· EV_FADEOUT_STARTED, EV_FADING_VOLUME_CHANGED and EV_FADEOUT_COMPLETED after a call to the StopSound method

Syntax

[Visual Basic]

Public Function StreamVolumeSmoothingSet (

nPlayerIndex as Int16,

bfadeIn as Boolean,

nSlideDuration as Int32,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamVolumeSmoothingSet (

Int16 nPlayerIndex,

bool bfadeIn,

Int32 nSlideDuration,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes StreamVolumeSmoothingSet (

Int16 nPlayerIndex,

bool bfadeIn,

Int32 nSlideDuration,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

Parameter

Description

nPlayerIndex

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.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 or a fade-out after a StopSound call.

During the fading session the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to the following values:

· EV_FADEIN_STARTED, EV_FADING_VOLUME_CHANGED and EV_FADEIN_COMPLETED after a call to the PlaySound method
· EV_FADEOUT_STARTED, EV_FADING_VOLUME_CHANGED and EV_FADEOUT_COMPLETED after a call to the StopSound method

Syntax

[Visual Basic]

Public Function StreamVolumeSmoothingSetEx (

nPlayerIndex as Int16,

bfadeIn as Boolean,

nSlideDuration as Int32,

nCurveType as enumVolumeCurves,

nLeftX as Int16,

nLeftY as Int16,

nRightX as Int16,

nRightY as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamVolumeSmoothingSetEx (

Int16 nPlayerIndex,

bool bfadeIn,

Int32 nSlideDuration,

enumVolumeCurves nCurveType,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 nRightY

);

[C++]

public: enumErrorCodes StreamVolumeSmoothingSetEx (

Int16 nPlayerIndex,

bool bfadeIn,

Int32 nSlideDuration,

enumVolumeCurves nCurveType,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 nRightY

);

Parameter

Description

nPlayerIndex

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.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]

Public Function PlayListAddItem (

nPlayerIndex as Int16,

strPathname as string,

nIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListAddItem (

Int16 nPlayerIndex,

string strPathname,

Int16 nIndex

);

[C++]

public: enumErrorCodes PlayListAddItem (

Int16 nPlayerIndex,

string strPathname,

Int16 nIndex

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that owns the playlist

strPathname

String containing the 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 method call was successful.


PlayListAddItemEx method

PlayListAddItemEx 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]

Public Function PlayListAddItemEx (

nPlayerIndex as Int16,

strPathname as string,

nIndex as Int16,

nItemType as enumPlayListItemType

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListAddItemEx (

Int16 nPlayerIndex,

string strPathname,

Int16 nIndex,

enumPlayListItemType nItemType

);

[C++]

public: enumErrorCodes PlayListAddItemEx (

Int16 nPlayerIndex,

string strPathname,

Int16 nIndex,

enumPlayListItemType nItemType

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that owns the playlist

strPathname

String containing the 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_PLAYLIST_LOAD_STARTED, EV_PLAYLIST_LOAD_PERC and EV_PLAYLIST_LOAD_DONE.

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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_PLAYLIST_LOAD_STARTED, EV_PLAYLIST_LOAD_PERC and EV_PLAYLIST_LOAD_DONE.

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.


PlayListAddItemWithTag method

PlayListAddItemWithTag method

Remarks

Adds a song with an associated custom tag string to the loaded playlist. When the container application is notified through the CallbackForPlayersEvents delegate having the nEvent parameter set to EV_PLAYLIST_SOUND_LOADED, the custom tag string is passed inside the pBufferUnicode 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]

Public Function PlayListAddItemWithTag (

nPlayerIndex as Int16,

strPathname as string,

nIndex as Int16,

strTag as String

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListAddItemWithTag (

Int16 nPlayerIndex,

string strPathname,

Int16 nIndex,

string strTag

);

[C++]

public: enumErrorCodes PlayListAddItemWithTag (

Int16 nPlayerIndex,

string strPathname,

Int16 nIndex,

string strTag

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that owns the playlist

strPathname

String containing the 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 method call was successful.


PlayListCreate method

PlayListCreate method

Remarks

Creates a new playlist associated to the given player player.

By default the playlist will use the PLAYLIST_FULL_MODE loading mode; if you want to create a playlist using the PLAYLIST_SPEED_MODE or PLAYLIST_AUTOMATION_MODE loading mode you will have to call the PlayListCreateEx method.

Syntax

[Visual Basic]

Public Function PlayListCreate (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListCreate (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlayListCreate (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 method call was successful.


PlayListCreateEx method

PlayListCreateEx method

Remarks

Creates a new playlist associated to the given player using the given loading mode.

Syntax

[Visual Basic]

Public Function PlayListCreate (

nPlayerIndex as Int16

nMode as enumPlayListModes

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListCreate (

Int16 nPlayerIndex

enumPlayListModes nMode

);

[C++]

public: enumErrorCodes PlayListCreate (

Int16 nPlayerIndex

enumPlayListModes nMode

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will own the new playlist

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.NOERROR (0) | The method 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]

Public Function PlayListCurrIndexGet (

nPlayerIndex as Int16,

ByRef nIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListCurrIndexGet (

Int16 nPlayerIndex,

ref Int16 nIndex

);

[C++]

public: enumErrorCodes PlayListCurrIndexGet (

Int16 nPlayerIndex,

Int16 __gc *nIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function PlayListExecAt (

nPlayerIndex as Int16,

nIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListExecAt (

Int16 nPlayerIndex,

Int16 nIndex

);

[C++]

public: enumErrorCodes PlayListExecAt (

Int16 nPlayerIndex,

Int16 nIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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]

Public Function PlayListExecNext (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListExecNext (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlayListExecNext (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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]

Public Function PlayListSetExecPrev (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListSetExecPrev (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlayListSetExecPrev (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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]

Public Function PlayListExecute (

nPlayerIndex as Int16,

bFromBegin as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListExecute (

Int16 nPlayerIndex,

bool bFromBegin

);

[C++]

public: enumErrorCodes PlayListExecute (

Int16 nPlayerIndex,

bool bFromBegin

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Doesn't execute the playlist from the beginning
true | Executes the playlist from the beginning

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.


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 (

nPlayerIndex as Int16,

tableValues() as Int16,

nTableLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListExecOrderTableGet (

Int16 nPlayerIndex,

Int16 [] tableValues,

Int32 nTableLength

);

[C++]

public: enumErrorCodes PlayListExecOrderTableGet (

Int16 nPlayerIndex,

unsigned Int16 __gc[] tableValues,

Int32 nTableLength

);

Parameter | Description
nPlayerIndex | 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]

Public Function PlayListGetCount (

nPlayerIndex as Int16

) as Int16

[C#]

public Int16 PlayListGetCount (

Int16 nPlayerIndex

);

[C++]

public: Int16 PlayListGetCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function PlayListGetItemString (

nPlayerIndex as Int16,

nItemIndex as Int16,

nString as enumPlayListStrings

) as String

[C#]

public string PlayListGetItemString (

Int16 nPlayerIndex,

Int16 nItemIndex,

enumPlayListStrings nString

);

[C++]

public: string PlayListGetItemString (

Int16 nPlayerIndex,

Int16 nItemIndex,

enumPlayListStrings nString

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that owns the playlist

nItemIndex

Number representing the zero-based index of the song (item) whose information must be obtained

nString

The identifier of the string to obtain.

Supported values are the following:

Mnemonic value

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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_CUE_POINT_REACHED allowing to discriminate the specific cue point through contents of the pBufferUnicode parameter.

This method will return an error if the playlist has not been created with the PlayListCreateEx method or loaded with the PlayListLoad or PlayListLoadSync methods, all 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]

Public Function PlayListItemCuePointAdd (

nPlayerIndex as Int16,

nItemIndex as Int16,

strCuePointName as string,

nPositionUnit as enumVolumeAutomationPositionUnits,

fPosition as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemCuePointAdd (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strCuePointName,

enumVolumeAutomationPositionUnits nPositionUnit,

float fPosition

);

[C++]

public: enumErrorCodes PlayListItemCuePointAdd (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strCuePointName,

enumVolumeAutomationPositionUnits nPositionUnit,

float fPosition

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItemIndex

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.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]

Public Function PlayListItemCuePointCountGet (

nPlayerIndex as Int16,

nItemIndex as Int16,

ByRef nCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemCuePointCountGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

ref Int16 nCount

);

[C++]

public: enumErrorCodes PlayListItemCuePointCountGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

Int16 __gc *nCount

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nItemIndex | 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]

Public Function PlayListItemCuePointGet (

nPlayerIndex as Int16,

nItemIndex as Int16,

nCuePointIndex as Int16,

nPositionUnit as enumVolumeAutomationPositionUnits,

ByRef fPosition as Single

) as String

[C#]

public string PlayListItemCuePointGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

Int16 nCuePointIndex,

enumVolumeAutomationPositionUnits nPositionUnit,

ref float fPosition

);

[C++]

public: string PlayListItemCuePointGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

Int16 nCuePointIndex,

enumVolumeAutomationPositionUnits nPositionUnit,

float __gc *fPosition

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItemIndex

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]

Public Function PlayListItemCuePointRemove (

nPlayerIndex as Int16,

nItemIndex as Int16,

strCuePointName as string

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemCuePointRemove (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strCuePointName

);

[C++]

public: enumErrorCodes PlayListItemCuePointRemove (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strCuePointName

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nItemIndex | 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.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 PlayListCreateEx method or loaded with the PlayListLoad or PlayListLoadSync methods, all 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]

Public Function PlayListItemVolAutomPointAdd (

nPlayerIndex as Int16,

nItemIndex as Int16,

strVolumePointName as String,

nPositionUnit as enumVolumeAutomationPosUnits,

fPosition as Single,

nVolumeScaleType as enumVolumeScales,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemVolAutomPointAdd (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName,

enumVolumeAutomationPosUnits nPositionUnit,

float fPosition,

enumVolumeScales nVolumeScaleType,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes PlayListItemVolAutomPointAdd (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName,

enumVolumeAutomationPosUnits nPositionUnit,

float fPosition,

enumVolumeScales nVolumeScaleType,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItemIndex

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]

Public Function PlayListItemVolAutomPointCountGet (

nPlayerIndex as Int16,

nItemIndex as Int16,

ByRef nCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemVolAutomPointCountGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

ref Int16 nCount

);

[C++]

public: enumErrorCodes PlayListItemVolAutomPointCountGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

Int16 __gc *nCount

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nItemIndex | 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]

Public Function PlayListItemVolAutomPointModify (

nPlayerIndex as Int16,

nItemIndex as Int16,

strVolumePointName as String,

nPositionUnit as enumVolumeAutomationPosUnits,

fPosition as Single,

nVolumeScaleType as enumVolumeScales,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemVolAutomPointModify (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName,

enumVolumeAutomationPosUnits nPositionUnit,

float fPosition,

enumVolumeScales nVolumeScaleType,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes PlayListItemVolAutomPointModify (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName,

enumVolumeAutomationPosUnits nPositionUnit,

float fPosition,

enumVolumeScales nVolumeScaleType,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItemIndex

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]

Public Function PlayListItemVolAutomPointNameGet (

nPlayerIndex as Int16,

nItemIndex as Int16,

nPointIndex as Int16

) as String

[C#]

public string PlayListItemVolAutomPointNameGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

Int16 nPointIndex

);

[C++]

public: string PlayListItemVolAutomPointNameGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

Int16 nPointIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that owns the playlist
nItemIndex | 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

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 automation 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]

Public Function PlayListItemVolAutomPointParamsGet (

nPlayerIndex as Int16,

nItemIndex as Int16,

strVolumePointName as String,

nPositionUnit as enumVolumeAutomationPosUnits,

ByRef fPosition as Single,

nVolumeScaleType as enumVolumeScales,

ByRef fVolumeLevel as Single,

ByRef nCurveType as enumVolumeCurves,

ByRef nLeftX as Int16,

ByRef nLeftY as Int16,

ByRef nRightX as Int16,

ByRef nRightY as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemVolAutomPointParamsGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName,

enumVolumeAutomationPosUnits nPositionUnit,

float fPosition,

enumVolumeScales nVolumeScaleType,

float fVolumeLevel,

enumVolumeCurves nCurveType,

ref Int16 nLeftX,

ref Int16 nLeftY,

ref Int16 nRightX,

ref Int16 nRightY

);

[C++]

public: enumErrorCodes PlayListItemVolAutomPointParamsGet (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName,

enumVolumeAutomationPosUnits nPositionUnit,

float fPosition,

enumVolumeScales nVolumeScaleType,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int16 __gc *nLeftX,

Int16 __gc *nLeftY,

Int16 __gc *nRightX,

Int16 __gc *nRightY

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItemIndex

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.

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.

This method will return an error if the playlist has not been created with the PlayListCreateEx method or loaded with the PlayListLoad or PlayListLoadSync methods, all 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]

Public Function PlayListItemVolAutomPointRemove (

nPlayerIndex as Int16,

nItemIndex as Int16,

strVolumePointName as String

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemVolAutomPointRemove (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName

);

[C++]

public: enumErrorCodes PlayListItemVolAutomPointRemove (

Int16 nPlayerIndex,

Int16 nItemIndex,

string strVolumePointName

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
nItemIndex | 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]

Public Function PlayListItemVolAutomGetMixPos (

nPlayerIndex as Int16,

nItemIndex as Int16,

nPositionUnit as enumVolumeAutomationPositionUnits,

ByRef fStartPos as Single,

ByRef fMixPos as Single,

ByRef fEndPos as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemVolAutomGetMixPos (

Int16 nPlayerIndex,

Int16 nItemIndex,

enumVolumeAutomationPositionUnits nPositionUnit,

ref float fStartPos,

ref float fMixPos,

ref float fEndPos

);

[C++]

public: enumErrorCodes PlayListItemVolAutomGetMixPos (

Int16 nPlayerIndex,

Int16 nItemIndex,

enumVolumeAutomationPositionUnits nPositionUnit,

float __gc *fStartPos,

float __gc *fMixPos,

float __gc *fEndPos

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItemIndex

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.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 PlayListCreateEx method or loaded with the PlayListLoad or PlayListLoadSync methods, all 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]

Public Function PlayListItemVolAutomSetMixPos (

nPlayerIndex as Int16,

nItemIndex as Int16,

nPositionUnit as enumVolumeAutomationPositionUnits,

fStartPos as Single,

fMixPos as Single,

fEndPos as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListItemVolAutomSetMixPos (

Int16 nPlayerIndex,

Int16 nItemIndex,

enumVolumeAutomationPositionUnits nPositionUnit,

float fStartPos,

float fMixPos,

float fEndPos

);

[C++]

public: enumErrorCodes PlayListItemVolAutomSetMixPos (

Int16 nPlayerIndex,

Int16 nItemIndex,

enumVolumeAutomationPositionUnits nPositionUnit,

float fStartPos,

float fMixPos,

float fEndPos

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nItemIndex

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

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.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]

Public Function PlayListLoad (

nPlayerIndex as Int16,

strPathname as string,

nMode as enumPlayListModes

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListLoad (

Int16 nPlayerIndex,

string strPathname,

enumPlayListModes nMode

);

[C++]

public: enumErrorCodes PlayListLoad (

Int16 nPlayerIndex,

string strPathname,

enumPlayListModes nMode

);

Parameter

Description

nPlayerIndex

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: trying to load a playlist in a format different from PDJ will cause the method to return an error.

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.


PlayListLoadFromCd method

PlayListLoadFromCd method

Remarks

Creates a playlist with all of the tracks contained inside a CD.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

Public Function PlayListLoadFromCd (

nPlayerIndex as Int16,

nDriveIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListLoadFromCd (

Int16 nPlayerIndex,

Int16 nDriveIndex

);

[C++]

public: enumErrorCodes PlayListLoadFromCd (

Int16 nPlayerIndex,

Int16 nDriveIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nDriveIndex | 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.NOERROR (0) | The method 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to EV_PLAYLIST_LOAD_STARTED, EV_PLAYLIST_LOAD_PERC and EV_PLAYLIST_LOAD_DONE..

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

Public Function PlayListLoadSync (

nPlayerIndex as Int16,

strPathname as string,

nMode as enumPlayListModes

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListLoadSync (

Int16 nPlayerIndex,

string strPathname,

enumPlayListModes nMode

);

[C++]

public: enumErrorCodes PlayListLoadSync (

Int16 nPlayerIndex,

string strPathname,

enumPlayListModes nMode

);

Parameter

Description

nPlayerIndex

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: trying to load a playlist in a format different from PDJ will cause the method to return an error.

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.


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]

Public Function PlayListMoveItem (

nPlayerIndex as Int16,

nOldIndex as Int16,

nNewIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListMoveItem (

Int16 nPlayerIndex,

Int16 nOldIndex,

Int16 nNewIndex

);

[C++]

public: enumErrorCodes PlayListMoveItem (

Int16 nPlayerIndex,

Int16 nOldIndex,

Int16 nNewIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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]

Public Function PlayListNextIndexGet (

nPlayerIndex as Int16,

ByRef nIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListNextIndexGet (

Int16 nPlayerIndex,

ref Int16 nIndex

);

[C++]

public: enumErrorCodes PlayListNextIndexGet (

Int16 nPlayerIndex,

Int16 __gc *nIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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]

Public Function PlayListNextIndexSet (

nPlayerIndex as Int16,

nIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListNextIndexSet (

Int16 nPlayerIndex,

Int16 nIndex

);

[C++]

public: enumErrorCodes PlayListNextIndexSet (

Int16 nPlayerIndex,

Int16 nIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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]

Public Function PlayListRemoveItem (

nPlayerIndex as Int16,

nIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListRemoveItem (

Int16 nPlayerIndex,

Int16 nIndex

);

[C++]

public: enumErrorCodes PlayListRemoveItem (

Int16 nPlayerIndex,

Int16 nIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method call was successful.


PlayListSave method

PlayListSave method

Remarks

Saves the current playlist into the given file.

Syntax

[Visual Basic]

Public Function PlayListSave (

nPlayerIndex as Int16,

strPathname as string,

nFormat as enumPlayListFormats

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListSave (

Int16 nPlayerIndex,

string strPathname,

enumPlayListFormats nFormat

);

[C++]

public: enumErrorCodes PlayListSave (

Int16 nPlayerIndex,

string strPathname,

enumPlayListFormats nFormat

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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, or created through the PlayListCreatEx method, 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]

Public Function PlayListSaveAutomation (

nPlayerIndex as Int16,

strPathname as string,

nPosUnit as enumVolumeAutomationPositionUnits

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListSaveAutomation (

Int16 nPlayerIndex,

string strPathname,

enumVolumeAutomationPositionUnits nPosUnit,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes PlayListSaveAutomation (

Int16 nPlayerIndex,

string strPathname,

enumVolumeAutomationPositionUnits nPosUnit,

enumVolumeScales 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.NOERROR (0) | The method 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]

Public Function PlayListSetLoop (

nPlayerIndex as Int16,

bLoop as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListSetLoop (

Int16 nPlayerIndex,

bool bLoop

);

[C++]

public: enumErrorCodes PlayListSetLoop (

Int16 nPlayerIndex,

bool bLoop

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Playlist is executed only once
true | Playlist is executed in Loop mode

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.


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 "true".

If the playlist has the Loop mode set to "true" (through the PlayListSetLoop method), each time the playlist is completed the execution order is randomly changed.

For further details about playlists management see the How to create and manage a playlist tutorial.

Syntax

[Visual Basic]

Public Function PlayListSetShuffle (

nPlayerIndex as Int16,

bShuffle as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListSetShuffle (

Int16 nPlayerIndex,

bool bShuffle

);

[C++]

public: enumErrorCodes PlayListSetShuffle (

Int16 nPlayerIndex,

bool bShuffle

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Playlist is executed in ordered mode
true | Playlist is executed in Shuffle mode

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.


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]

Public Function PlayListStop (

nPlayerIndex as Int16,

bStopCurrSound as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListStop (

Int16 nPlayerIndex,

bool bStopCurrSound

);

[C++]

public: enumErrorCodes PlayListStop (

Int16 nPlayerIndex,

bool bStopCurrSound

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Stops the playlist after completing the currently playing sound
true | 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.NOERROR (0) | The method 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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_TRIGGER_REACHED and you will be able to discriminate the specific trigger through its nData1 parameter: this parameter will match exactly the unique identification number assigned to the 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]

Public Function TriggersAdd (

nPlayerIndex as Int16,

nTriggerID as Int16,

nTriggerPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes TriggersAdd (

Int16 nPlayerIndex,

Int16 nTriggerID,

Int32 nTriggerPos

);

[C++]

public: enumErrorCodes TriggersAdd (

Int16 nPlayerIndex,

Int16 nTriggerID,

Int32 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.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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_TRIGGER_REACHED and you will be able to discriminate the specific trigger through its nData1 parameter: this parameter will match exactly the unique identification number assigned to the trigger.

See the How to add Triggers and Cue Points to a player section for further details about triggers.

Syntax

[Visual Basic]

Public Function TriggersAddPerc (

nPlayerIndex as Int16,

nTriggerID as Int16,

nTriggerPosPerc as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes TriggersAddPerc (

Int16 nPlayerIndex,

Int16 nTriggerID,

Int32 nTriggerPosPerc

);

[C++]

public: enumErrorCodes TriggersAddPerc (

Int16 nPlayerIndex,

Int16 nTriggerID,

Int32 nTriggerPosPerc

);

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.
nTriggerPosPerc | 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.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]

Public Function TriggersEnable (

nPlayerIndex as Int16,

nTriggerID as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes TriggersEnable (

Int16 nPlayerIndex,

Int16 nTriggerID,

bool bEnable

);

[C++]

public: enumErrorCodes TriggersEnable (

Int16 nPlayerIndex,

Int16 nTriggerID,

bool 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 | Meaning
false | Disable trigger
true (default) | Enable trigger

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.


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]

Public Function TriggersGetCount (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 TriggersGetCount (

Int16 nPlayerIndex

);

[C++]

public: Int32 TriggersGetCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function TriggersGetPos (

nPlayerIndex as Int16,

nTriggerID as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes TriggersGetPos (

Int16 nPlayerIndex,

Int16 nTriggerID

);

[C++]

public: enumErrorCodes TriggersGetPos (

Int16 nPlayerIndex,

Int16 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]

Public Function TriggersGetPosPerc (

nPlayerIndex as Int16,

nTriggerID as Int16

) as Single

[C#]

public float TriggersGetPosPerc (

Int16 nPlayerIndex,

Int16 nTriggerID

);

[C++]

public: float TriggersGetPosPerc (

Int16 nPlayerIndex,

Int16 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]

Public Function TriggersIsEnabled (

nPlayerIndex as Int16,

nTriggerID as Int16

) as Boolean

[C#]

public bool TriggersIsEnabled (

Int16 nPlayerIndex,

Int16 nTriggerID

);

[C++]

public: bool TriggersIsEnabled (

Int16 nPlayerIndex,

Int16 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 | Meaning
false | Trigger is disabled
true | 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]

Public Function TriggersRemove (

nPlayerIndex as Int16,

nTriggerID as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes TriggersRemove (

Int16 nPlayerIndex,

Int16 nTriggerID

);

[C++]

public: enumErrorCodes TriggersRemove (

Int16 nPlayerIndex,

Int16 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.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]

Public Function TriggersSetPos (

nPlayerIndex as Int16,

nTriggerID as Int16,

nTriggerPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes TriggersSetPos (

Int16 nPlayerIndex,

Int16 nTriggerID,

Int32 nTriggerPos

);

[C++]

public: enumErrorCodes TriggersSetPos (

Int16 nPlayerIndex,

Int16 nTriggerID,

Int32 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.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]

Public Function TriggersSetPosPerc (

nPlayerIndex as Int16,

nTriggerID as Int16,

nTriggerPosPerc as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes TriggersSetPosPerc (

Int16 nPlayerIndex,

Int16 nTriggerID,

Int32 nTriggerPosPerc

);

[C++]

public: enumErrorCodes TriggersSetPosPerc (

Int16 nPlayerIndex,

Int16 nTriggerID,

Int32 nTriggerPosPerc

);

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.NOERROR (0) | The method call was successful.


CallbackCurveDesignerPointsChange delegate

CallbackCurveDesignerPointsChange delegate

Remarks

Callback delegate invoked when the curve inside a volume curve designer control is modified by dragging one of the control points through the mouse interaction: this callback can be set through a call to the CallbackCurveDesignerPointsChangeSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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]

Public Delegate Sub CallbackCurveDesignerPointsChange (

ByVal nDesignerUniqueId as Int32,

ByVal nLeftX as Int16,

ByVal nLeftY as Int16,

ByVal nRightX as Int16,

ByVal nRightY as Int16

)

[C#]

public delegate void CallbackCurveDesignerPointsChange (

Int32 nDesignerUniqueId,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 nRightY

)

[C++]

public delegate void CallbackCurveDesignerPointsChange (

Int32 nDesignerUniqueId,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 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


CallbackDeviceChange delegate

CallbackDeviceChange delegate

Remarks

Callback delegate invoked 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 callback can be set through a call to the CallbackDeviceChangeSet method.

This event is only intended for usage with Windows XP and earlier versions. When dealing with Windows Vista and higher versions it's recommended using the CallbackForCoreAudioEvents callback.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackDeviceChange (

)

[C#]

public delegate void CallbackDeviceChange (

)

[C++]

public delegate void CallbackDeviceChange (

)


CallbackDisplayConfigChanged delegate

CallbackDisplayConfigChanged delegate

Remarks

Callback delegate invoked whenever the configuration of the system display is changed: this callback can be set through a call to the CallbackDisplayConfigChangedSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackDisplayConfigChanged (

)

[C#]

public delegate void CallbackDisplayConfigChanged (

)

[C++]

public delegate void CallbackDisplayConfigChanged (

)


CallbackForCastingEvents delegate

CallbackForCastingEvents delegate

Remarks

Callback delegate invoked during a casting session previously created by one between the CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer methods: this callback can be set through a call to the CallbackForCastingEventsSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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 loopback devices see the WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Delegate Sub CallbackForCastingEvents (

ByVal nEvent as enumCastingEvents,

ByVal nCastingUniqueId as Int32,

ByVal nData1 as Int32,

ByVal nData2 as Int32,

ByVal pBufferUnicode as IntPtr,

ByVal nBufferLength as Int32

)

[C#]

public delegate void CallbackForCastingEvents (

enumCastingEvents nEvent,

Int32 nCastingUniqueId,

Int32 nData1,

Int32 nData2,

IntPtr pBufferUnicode,

Int32 nBufferLength

)

[C++]

public delegate void CallbackForCastingEvents (

enumCastingEvents nEvent,

Int32 nCastingUniqueId,

Int32 nData1,

Int32 nData2,

IntPtr pBufferUnicode,

Int32 nBufferLength

)

Parameter

Description

nEvent

The type of event.

Supported values, with related parameters, are the following:

Mnemonic constant

Value

Meaning

EV_CASTING_PLAYER_START

1

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.

Involved data parameters: none

EV_CASTING_PLAYER_PERC

2

Occurs during a player-based casting session to inform about the advancement percentage.

Involved data parameters:

nData1: Advancement of the casting session expressed in percentage

EV_CASTING_PLAYER_DONE

3

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 .

Involved data parameters:

nData1: The result of the operation. See the LastError property for details about the returned result code.

EV_CASTING_STREAM_MIXER_START

4

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.

EV_CASTING_STREAM_MIXER_STOP

5

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 nData1 parameter.

Involved data parameters:

nData1: 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.

EV_CASTING_WMA_CLIENT_CONNECT

6

Occurs when a client is connected/disconnected on a WMA network session created through a call to CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.

Involved data parameters:

nData1: Boolean value that specifies if the client was connected or disconnected.

Supported values are the following:

Value | Meaning
0 | The client was disconnected
1 | The client was connected

pBufferUnicode: String representing the IP address of the connected client.

EV_CASTING_LOOPBACK_START

7

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.

EV_CASTING_LOOPBACK_STOP

8

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.

Involved data parameters:

nData1: 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.

This event is only intended for usage with Windows Vista and later versions.

nCastingUniqueId

Unique identifier of the casting session returned by a previous call to CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer methods.

nData1

Number representing the first parameter related to the event (see the events table above for details)

nData2

Number representing the second parameter related to the event (see the events table above for details)

pBufferUnicode

Pointer to a buffer containing a string of Unicode characters with text information about the event. Below a couple of snippets that show how to convert the buffer contents into a .NET string through marshaling:

Visual Basic .NET

Imports System.Runtime.InteropServices

Dim strInfo As String = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength)

strInfo = strInfo.Trim()

Visual C#

using System.Runtime.InteropServices;

string strInfo = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength);

strInfo = strInfo.Trim();

nBufferLength

The length in characters of the buffer above


CallbackForCdDrivesEvents delegate

CallbackForCdDrivesEvents delegate

Remarks

Callback delegate invoked when an event related to a CD drive occurs: this callback can be set through a call to the CallbackForCdDrivesEventsSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackForCdDrivesEvents (

ByVal nEvent as enumCdDrivesEvents,

ByVal nCdDrive as Int32,

ByVal nData1 as Int32,

ByVal nData2 as Int32,

ByVal nData3 as Int32

)

[C#]

public delegate void CallbackForCdDrivesEvents (

enumCdDrivesEvents nEvent,

Int32 nCdDrive,

Int32 nData1,

Int32 nData2,

Int32 nData3

)

[C++]

public delegate void CallbackForCdDrivesEvents (

enumCdDrivesEvents nEvent,

Int32 nCdDrive,

Int32 nData1,

Int32 nData2,

Int32 nData3

)

Parameter

Description

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

Occurs at the beginning of a new CD track's loading session started through the LoadTrackFromCd method.

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

Occurs during a CD track loading session, started through the LoadTrackFromCd method, in order to notify the loading advancement percentage.

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

Occurs at the end of a CD track's loading session started through the LoadTrackFromCd method.

Involved data parameters:

nData1: Number representing the one-based index of the CD audio track that is being loaded.

EV_CD_STATUS_CHANGED

3

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.

Involved data parameters:

nData1: Number representing the CD drive status.Supported values are the following:

Mnemonic Value | 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

EV_CDDB_SERVERS_AVAIL

4

Occurs when the list of CDDB servers, requested through a previous call to the CddbRequestServersList method, is available.

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

Occurs when the CDDB server returns the CD album information requested through a previous call to the CddbRequestAlbumInfo method.

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.

Involved data parameters:

nData1: Boolean value that specifies if the CDDB information was retrieved successfully. Supported values are the following:

Mnemonic Value | Meaning
false | The request failed, check the LastError property value in order to see the possible cause of the error
true | The request succeeded and CDDB information is available

EV_CD_COVER_URLS_AVAIL

6

Occurs when the Internet URLs of the CD cover's pictures have been obtained from the Amazon Web Service.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | The request failed, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_CD_COVER_SMALL_FILE_AVAIL

7

Occurs when the small version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | The request failed, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_CD_COVER_MEDIUM_FILE_AVAIL

8

Occurs when the medium version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | The request failed, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_CD_COVER_LARGE_FILE_AVAIL

9

Occurs when the large version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | The request failed, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

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.


CallbackForCoreAudioEvents delegate

CallbackForCoreAudioEvents delegate

Remarks

Callback delegate invoked each time an event generated by CoreAudio devices occurs: this callback can be set through a call to the CallbackForCoreAudioEventsSet method.

This delegate 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 callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackForCoreAudioEvents (

ByVal nEvent as enumCoreAudioEvents,

ByVal nData1 as Int32,

ByVal nData2 as Int32,

ByVal nData3 as Int32

)

[C#]

public delegate void CallbackForCoreAudioEvents (

enumCoreAudioEvents nEvent,

Int32 nData1,

Int32 nData2,

Int32 nData3

)

[C++]

public delegate void CallbackForCoreAudioEvents (

enumCoreAudioEvents nEvent,

Int32 nData1,

Int32 nData2,

Int32 nData3

)

Parameter

Description

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

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..

Involved data parameters:

nData1: 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.

nData2: 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.

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

EV_COREAUDIO_DEVICE_ADDED

1

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.

Involved data parameters: none.

EV_COREAUDIO_DEVICE_REMOVED

2

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.

Involved data parameters: none.

EV_COREAUDIO_DEVICE_DEFAULT_CHANGE

3

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.

Involved data parameters:

nData1: 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.

nData2: 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.

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

EV_COREAUDIO_DEVICE_VOLUME_CHANGE

4

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.

Involved data parameters:

nData1: 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.

nData2: 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.

EV_COREAUDIO_DEVICE_VUMETER_CHANGE

5

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.

Involved data parameters:

nData1: 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.

nData2: 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.

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.


CallbackForDownloaderEvents delegate

CallbackForDownloaderEvents delegate

Remarks

Callback delegate invoked during a downloading session performed through the DownloaderDj class: this callback can be set through a call to the CallbackForDownloaderEventsSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackForDownloaderEvents (

ByVal nEvent as enumDownloaderEvents,

ByVal nDllSessionUniqueId as Int32,

ByVal nParam1 as Int32,

ByVal nParam2 as Int32,

ByVal nParam3 as Int32

)

[C#]

public delegate void CallbackForDownloaderEvents (

enumDownloaderEvents nEvent,

Int32 nDllSessionUniqueId,

Int32 nParam1,

Int32 nParam2,

Int32 nParam3

)

[C++]

public delegate void CallbackForDownloaderEvents (

enumDownloaderEvents nEvent,

Int32 nDllSessionUniqueId,

Int32 nParam1,

Int32 nParam2,

Int32 nParam3

)

Parameter

Description

nEvent

The type of event.

Supported values, with related parameters, are the following:

Mnemonic constant

Value

Meaning

EV_DOWNLOADER_SESSION_COMPLETED

1

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.

Involved data parameters: none

EV_DOWNLOADER_SESSION_FAILED

2

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.

Involved data parameters:

nParam1: Error code generated by the component: see the LastError property for supported values

nParam2: Eventual error code defined inside the Windows SDK.

nParam3: 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.

EV_DOWNLOADER_SESSION_PROGRESS

3

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.

Involved data parameters:

nParam1: Advancement of the download session expressed in percentage

EV_DOWNLOADER_INVALID_FILE

4

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.

Involved data parameters: none

EV_DOWNLOADER_SESSION_STARTED

5

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.

Involved data parameters: none

EV_DOWNLOADER_SESSION_STOPPED

6

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.

Involved data parameters: none

nDllSessionUniqueId

Unique identifier of the downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.

nParam1

Number representing the first parameter related to the event (see the events table above for details)

nParam2

Number representing the second parameter related to the event (see the events table above for details)

nParam3

Number representing the third parameter related to the event (see the events table above for details)


CallbackForMidiKeyboardEvents delegate

CallbackForMidiKeyboardEvents delegate

Remarks

Callback delegate invoked when one of the keys on the virtual piano keyboard, previously created through the MIDI.KeyboardCreate method, is pressed or released: this callback can be set through a call to the CallbackForMidiKeyboardEventsSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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]

Public Delegate Sub CallbackForMidiKeyboardEvents (

ByVal hWndKeyboard as IntPtr,

ByVal nNote as Int16,

ByVal bPressed as Boolean,

ByVal bSimulated as Boolean

)

[C#]

public delegate void CallbackForMidiKeyboardEvents (

IntPtr hWndKeyboard,

Int16 nNote,

bool bPressed,

bool bSimulated

)

[C++]

public delegate void CallbackForMidiKeyboardEvents (

IntPtr hWndKeyboard,

Int16 nNote,

bool bPressed,

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

Value | Meaning
false | The key was released
true | 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:

Value | Meaning
false | The note was played on the MIDI stream in playback
true | The note was not played on the MIDI stream in playback but the corresponding key was rendered as pressed on the piano keyboard.


CallbackForMidiMarkerEvents delegate

Remarks

Callback delegate invoked when a specific type of MIDI marker, previously enabled for notification, has been found inside the MIDI stream during playback: this callback can be set through a call to the CallbackForMidiMarkerEventsSet method.

Notifications of a specific MIDI marker can be enabled/disabled through the MIDI.MarkersEnableNotifications method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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]

Public Delegate Sub CallbackForMidiMarkerEvents (

ByVal nMarkerType as enumMidiMarkerNotifications,

ByVal nPlayerIndex as Int16,

ByVal nTrack as Int32,

ByVal fPositionInMs as Double,

ByVal fPositionInTicks as Double,

ByVal fPositionInPercentage as Double,

ByVal pBufferUnicode as IntPtr,

ByVal nBufferLength as Int32

)

[C#]

public delegate void CallbackForMidiMarkerEvents (

enumMidiMarkerNotifications nMarkerType,

Int16 nPlayerIndex,

Int32 nTrack,

double fPositionInMs,

double fPositionInTicks,

double fPositionInPercentage,

IntPtr pBufferUnicode,

Int32 nBufferLength

)

[C++]

public delegate void CallbackForMidiMarkerEvents (

enumMidiMarkerNotifications nMarkerType,

Int16 nPlayerIndex,

Int32 nTrack,

double fPositionInMs,

double fPositionInTicks,

double fPositionInPercentage,

IntPtr pBufferUnicode,

Int32 nBufferLength

)

Parameter

Description

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

nPlayerIndex

Zero-based index of the player reporting the event

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

pBufferUnicode

Pointer to a buffer containing a string of Unicode characters with the text of the marker. Below a couple of snippets that show how to convert the buffer contents into a .NET string through marshaling:

Visual Basic .NET

Imports System.Runtime.InteropServices

Dim strInfo As String = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength)

strInfo = strInfo.Trim()

Visual C#

using System.Runtime.InteropServices;

string strInfo = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength);

strInfo = strInfo.Trim();

nBufferLength

The length in characters of the buffer above


CallbackForMidiStreamEvents delegate

CallbackForMidiStreamEvents delegate

Remarks

Callback delegate invoked when a specific type of MIDI event, previously enabled for notification, has been found inside the MIDI stream during playback: this callback can be set through a call to the CallbackForMidiStreamEventsSet method.

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 callback delegates see the How to synchronize the container application with the API tutorial.

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]

Public Delegate Sub CallbackForMidiStreamEvents (

ByVal nMidiEvent as enumMidiStreamEvents,

ByVal nPlayerIndex as Int16,

ByVal nMidiParam1 as Int32,

ByVal nMidiParam2 as Int32,

ByVal nMidiChannel as Int16,

ByVal fPositionInMs as Double,

ByVal fPositionInTicks as Double,

ByVal fPositionInPercentage as Double

)

[C#]

public delegate void CallbackForMidiStreamEvents (

enumMidiStreamEvents nMidiEvent,

Int16 nPlayerIndex,

Int32 nMidiParam1,

Int32 nMidiParam2,

Int16 nMidiChannel,

double fPositionInMs,

double fPositionInTicks,

double fPositionInPercentage

)

[C++]

public delegate void CallbackForMidiStreamEvents (

enumMidiStreamEvents nMidiEvent,

Int16 nPlayerIndex,

Int32 nMidiParam1,

Int32 nMidiParam2,

Int16 nMidiChannel,

double fPositionInMs,

double fPositionInTicks,

double fPositionInPercentage

)

Parameter

Description

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 CallbackForMidiStreamEvents delegate.
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

nPlayerIndex

Zero-based index of the player reporting the event

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


CallbackForPlayersEvents delegate

CallbackForPlayersEvents delegate

Remarks

Callback delegate invoked when an event related to a player occurs: this callback can be set through a call to the CallbackForPlayersEventsSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackForPlayersEvents (

ByVal nEvent as enumPlayerEvents,

ByVal nPlayerIndex as Int16,

ByVal nData1 as Int32,

ByVal nData2 as Int32,

ByVal fData3 as Single,

ByVal pBufferUnicode as IntPtr,

ByVal nBufferLength as Int32

)

[C#]

public delegate void CallbackForPlayersEvents (

enumPlayerEvents nEvent,

Int16 nPlayerIndex,

Int32 nData1,

Int32 nData2,

float fData3,

IntPtr pBufferUnicode,

Int32 nBufferLength

)

[C++]

public delegate void CallbackForPlayersEvents (

enumPlayerEvents nEvent,

Int16 nPlayerIndex,

Int32 nData1,

Int32 nData2,

float fData3,

IntPtr pBufferUnicode,

Int32 nBufferLength

)

Parameter

Description

nEvent

Event reported by the player.

Supported values are the following:

Mnemonic constant

Value

Meaning with data parameters

EV_SOUND_DONE

0

Occurs when a song has been performed completely.

Involved data parameters: none.

EV_SOUND_PLAYING

1

Occurs when a song starts playing.

Involved data parameters: none.

EV_SOUND_PAUSED

2

Occurs when a song is paused.

Involved data parameters: none.

EV_SOUND_STOPPED

3

Occurs when a song is stopped.

Involved data parameters: none.

EV_SOUND_LOADED

4

Occurs when a song is loaded in memory from a file.

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

Occurs when a song or video clip has been loaded in memory from a file after a call to the LoadSoundSync, LoadSoundFromMemorySync, LoadEncryptedSoundSync, LoadEncryptedSoundFromMemorySync or VideoPlayer.LoadSync methods.

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

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.

Involved data parameters: none.

EV_DOWNLOAD_COMPLETE

7

Occurs when an Internet stream (usually a file) has been downloaded completely.

Involved data parameters: none.

EV_DOWNLOAD_BUFFERING

8

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.

Involved data parameters:

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

EV_DOWNLOAD_PERC

9

Occurs during the download of an Internet stream to inform about buffering percentage.

Involved data parameters:

nData1: Number representing the download percentage.

EV_STREAM_CONNECTING

10

Occurs when the player starts the connection to an Internet stream.

Involved data parameters: none.

EV_STREAM_LOADED

11

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 EV_STREAM_LOADED_FROM_INET_PLS event (see below).

Involved data parameters:

nData1: The stream loading result.

EV_STREAM_LOADED_FROM_INET_PLS

12

Occurs after the player has tried to load an Internet stream taken from a playlist stored inside a web server.

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

Occurs when a playlist has been performed completely.

Involved data parameters: none.

EV_PLAYLIST_SOUND_LOADED

14

Occurs when a song included inside a playlist is loaded in memory from a file.

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

Occurs when the loading of a playlist's song fails.

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

Occurs when a playlist Internet stream item has been loaded.

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

Occurs when a song is closed and discarded from memory.

Involved data parameters: none.

EV_SERVER_CLOSED

18

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

Involved data parameters: none.

EV_DURATION_CHANGED

19

Occurs after a successful call to the Effects.PlaybackTempoSet and Effects.PlaybackRateSet methods to notify that the original sound duration has been altered.

Involved data parameters:

fData3: The updated sound duration expressed in seconds.

EV_VUMETER

20

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.

This event is fired only if you have created the VUMeter object though a call to the VUMeter.Create method.

For regular mono or stereo streams, peak levels are reported inside the nData1 and nData2 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.

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

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.

Involved data parameters: none.

EV_BPM_AVAILABLE

22

Occurs when a song BPM has been detected.

Involved data parameters:

fData3: The detected song BPM.

EV_FADING_VOLUME_CHANGED

23

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.

Involved data parameters:

fData3: The player's current volume.

EV_FADING_POINT_REACHED

24

Occurs when the playback of the song that will fade-out reaches the Fader.FadeStartFromEnd position

Involved data parameters: none.

EV_FADEIN_STARTED

25

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.

Involved data parameters: none.

EV_FADEIN_COMPLETED

26

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.

Involved data parameters: none.

EV_FADEOUT_STARTED

27

Occurs when the song fading-out starts lowering its volume.

This event is also generated at the start of a fade-in session performed after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

Involved data parameters: none.

EV_FADEOUT_COMPLETED

28

Occurs when the fade-out is completed.

This event is also generated at the end of a fade-in session performed after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

Involved data parameters: none.

EV_TRIGGER_REACHED

29

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.

Involved data parameters:

nData1: Number representing the trigger identifier.

EV_SILENCE_AVAIL

30

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.

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

Occurs when the analysis of a sound's waveform begins. The analysis is started through a previous call to the Waveform.AnalyzeFullSound method.

Involved data parameters: none.

EV_WAVE_ANALYSIS_PERC

32

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.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current sound analysis.

EV_WAVE_ANALYSIS_DONE

33

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.

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

Occurs when a loop of a sound range playback, started through a call to the PlaySoundRangeLoop or the VideoPlayer.PlayRangeWithLoop methods, has been completed.

Involved data parameters:

nData1: Number representing the amount of loops that must be still performed.

EV_WAV_EXPORT_START

35

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.

Involved data parameters: none.

EV_WAV_EXPORT_PERC

36

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.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current exporting session.

EV_WAV_EXPORT_COMPLETE

37

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.

Involved data parameters:

nData1: Number representing the total size, expressed in bytes, of the exported WAV file..

EV_EQUALIZER_LOADED

38

Occurs when settings of an equalizer file are applied to a sound.

Involved data parameters: none.

EV_CUE_POINTS_LOADED

39

Occurs when a file containing cue points have been loaded into the player.

Involved data parameters: none.

EV_BEATS_AVAILABLE

40

Occurs when the offline beats detection is completed. Offline beats detection can be started through a previous call to the BeatsDetectRequest method.

Involved data parameters:

nData1: Number of beats detected.

EV_BEAT_DETECTED

41

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.

Involved data parameters:

nData1: Beat's position expressed in milliseconds.

EV_PLAYLIST_LOAD_STARTED

42

Occurs when the synchronized loading of a playlist starts. A synchronized loading is started through a call to the PlayListLoadSync method.

Involved data parameters: none.

EV_PLAYLIST_LOAD_PERC

43

Occurs during the synchronized loading of a playlist. A synchronized loading is started through a call to the PlayListLoadSync method.

Involved data parameters:

nData1: Number representing the percentage of advancement for the loading session.

EV_PLAYLIST_LOAD_DONE

44

Occurs when the synchronized loading of a playlist is completed. A synchronized loading is started through a call to the PlayListLoadSync method.

Involved data parameters:

nData1: Boolean value specifying if the playlist's loading was successful.

Supported values are the following:

Mnemonic constant | Meaning
false | Playlist's loading failed. See the LastError property for knowing which error occurred.
true | Playlist's loading was successful

EV_CUE_POINT_REACHED

45

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.

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

Occurs when a volume automation point is reached during playback.

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

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

Involved data parameters: none.

EV_LYRICS_AVAIL

48

Occurs when a previous request to the SoundLyricsRequest method is completed.

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

Occurs when a queued stream, created through the StreamQueueCreate method and fed through the StreamQueuePushData method, doesn't have PCM data to play.

Involved data parameters: none.

EV_AUDIO_EXTRACT_START

50

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.

Involved data parameters: none.

EV_AUDIO_EXTRACT_PERC

51

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

Involved data parameters:

nData1: Number representing the current percentage of the audio extraction.

EV_AUDIO_EXTRACT_DONE

52

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.

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

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.

Involved data parameters: none.

EV_PLAYER_DISCONNECTED

54

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.

Involved data parameters: none.

EV_OUTPUT_DEVICE_CHANGED

55

Occurs when the output device (sound card) has been changed through a successful call to the StreamOutputDeviceSet method.

Involved data parameters:

nData1: Number representing the zero-based index of the new output device for the given player.

EV_SILENCE_DETECTION

56

Occurs during playback of a sound stream having realtime silence detection enabled through the SilenceDetectionRealTimeEnable method.

Involved data parameters:

nData1: Boolean value specifying detection of silent data or of audible data.

Supported values are the following:

Mnemonic constant | Meaning
false | Audible sound data has been detected
true | Silent sound data has been detected

nData2: Number representing the position inside the sound stream, expressed in milliseconds, where the silence threshold was crossed.

EV_VST_PARAM_CHANGED

57

Occurs when a parameter of the VST has been changed through its editor.

Involved data parameters:

nData1: Number representing the unique identifier of the VST.

nData2: Number representing the zero-based index of the changed parameter.

fData3: Number representing the updated parameter value.

EV_VST_EDITOR_RESIZED

58

Occurs when the editor of the VST effect is resized.

Involved data parameters:

nData1: Number representing the unique identifier of the VST.

nData2: Number containing the updated size of the VST. The updated width is stored inside the lower 16 bits of the parameter while the updated height is stored inside the higher 16 bits of the parameter.

EV_LRC_FILE_AVAILABLE

59

Occurs when a lyrics LRC file is found and loaded.

Involved data parameters:

nData1: Boolean value specifying if the LRC file is in enhanced format.

EV_LRC_ADVANCETIME_FULL_LINE

60

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.

Involved data parameters:

nData1: Number representing the zero based-index of the Line Time Tag.

nData2: Position, expressed in milliseconds, within the song of the Line Time Tag.

pBufferUnicode: String containing the full line of text of the Line Time Tag

EV_LRC_REALTIME_FULL_LINE

61

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.

Involved data parameters:

nData1: Number representing the zero based-index of the Line Time Tag.

nData2: Position, expressed in milliseconds, within the song of the Line Time Tag.

pBufferUnicode: String containing the full line of text of the Line Time Tag

EV_LRC_REALTIME_PORTION_LINE

62

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.

Involved data parameters:

nData1: Number representing the zero based-index of the Line Enhanced Time Tag

nData2: Position, expressed in milliseconds, within the song of the Enhanced Time Tag

fData3: Duration, expressed in milliseconds, of the Enhanced Time Tag

pBufferUnicode: String containing the full line of text of the Enhanced Time Tag

EV_WAVEFORM_CHANGE

63

Occurs during playback whenever there is a change on the waveform peak values displayed on an object of the Waveform class.

EV_SOUNDCOMPOSER_SOUNDSTART

64

Occurs whenever playback of a sound added to a sound composer session is started.

Involved data parameters:

nData1: Number representing the unique identifier of the item added to the sound composer.

EV_SOUNDCOMPOSER_SOUNDDONE

65

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.

Involved data parameters:

nData1: Number representing the unique identifier of the item added to the sound composer. When this event is received, the unique identifier becomes automatically invalid and cannot be used for further actions.

nPlayerIndex

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 a buffer containing a string of Unicode characters related to the event; its value and meaning depends upon the specific event received: see the table above for possible values. Below a couple of snippets that show how to convert the buffer contents, passed when the callback is invoked with the nEvent parameter set to EV_CUE_POINT_REACHED, into a .NET string through marshaling:

Visual Basic .NET

Imports System.Runtime.InteropServices

Dim strCuePointName As String = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength)

strCuePointName = strCuePointName.Trim()

Visual C#

using System.Runtime.InteropServices;

string strCuePointName = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength);

strCuePointName = strCuePointName.Trim();

nBufferLength

The length in characters of the buffer above


CallbackWaveformScrollerManualScroll delegate

CallbackWaveformScrollerManualScroll delegate

Remarks

Callback delegate invoked every time a manual move is performed through the mouse on the waveform scroller.this callback can be set through a call to the CallbackWaveformScrollerManualScrollSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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]

Public Delegate Sub CallbackWaveformScrollerManualScroll (

hWndWaveformScroller as IntPtr,

nNewPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformScrollerManualScroll (

IntPtr hWndWaveformScroller,

Int32 nNewPosInMs

)

[C++]

public delegate void CallbackWaveformScrollerManualScroll (

IntPtr hWndWaveformScroller,

Int32 nNewPosInMs

)

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
nNewPosInMs | New sound position expressed in milliseconds after a manual scrolling operation


CallbackWaveformScrollerMouseNotif delegate

CallbackWaveformScrollerMouseNotif delegate

Remarks

Callback delegate invoked every time a mouse event happens on the waveform scroller: this callback can be set through a call to the CallbackWaveformScrollerMouseNotifSet method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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]

Public Delegate Sub CallbackWaveformScrollerMouseNotif (

hWndWaveformScroller as IntPtr,

nAction as enumMouseActions,

nFlags as Int32,

xPos as Int32,

yPos as Int32,

nPressPosInPix as Int32,

nPressPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformScrollerMouseNotif (

IntPtr hWndWaveformScroller,

enumMouseActions nAction,

Int32 nFlags,

Int32 xPos,

Int32 yPos,

Int32 nPressPosInPix,

Int32 nPressPosInMs

)

[C++]

public delegate void CallbackWaveformScrollerMouseNotif (

IntPtr hWndWaveformScroller,

enumMouseActions nAction,

Int32 nFlags,

Int32 xPos,

Int32 yPos,

Int32 nPressPosInPix,

Int32 nPressPosInMs

)

Parameter

Description

hWndWaveformScroller

Handle of the 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
MOUSE_ACTION_MIDDLE_DOWN | 9 | Middle mouse button down
MOUSE_ACTION_MIDDLE_UP | 10 | Middle mouse button up
MOUSE_ACTION_MIDDLE_CLICK | 11 | Middle mouse button click
MOUSE_ACTION_MIDDLE_DBLCLICK | 12 | Middle mouse button double click

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.


CallbackZipOperationPerc delegate

CallbackZipOperationPerc delegate

Remarks

Callback delegate for notifying the percentage of advancement of a ZIP operation.

For further details about methods for ZIP management refer to the ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Delegate Sub CallbackZipOperationPerc (

nPercentage as Int16

)

[C#]

public delegate void CallbackZipOperationPerc (

Int16 nPercentage

)

[C++]

public delegate void CallbackZipOperationPerc (

Int16 nPercentage

)

Parameter | Description
nPercentage | Number representing the percentage of advancement of the ZIP operation.


Events for Visual Basic 6 COM interoperability

Events for Visual Basic 6 COM interoperability

Visual Basic 6 results unreliable when dealing with delegates and callbacks in general so, when using the API in conjunctions with this development environment, a set of COM compatible events is provided.

In order to enable the usage of the provided events you simply need to invoke the COMEventsEnable method immediately after initializing the API through the InitSoundSystem method, then you need to manually enter the event management routine.

Inside the snippet below you can see an example of management of events generated by the player through the OnPlayersEvents event handler; the text of a label is modified when monitored events are reported:

Visual Basic 6

' declare the API

Dim WithEvents m_audioDJ As AudioDjStudioApi.AudioDjStudioApiObj

Private Sub m_audioDJ_OnPlayersEvents(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)

   Select Case nEvent

       Case enumPlayerEvents.enumPlayerEvents_EV_SOUND_PLAYING

           labelCurrentStatus.Caption = "Sound playing..."

       Case enumPlayerEvents.enumPlayerEvents_EV_SOUND_PAUSED

           labelCurrentStatus.Caption = "Sound paused"

       Case enumPlayerEvents.enumPlayerEvents_EV_SOUND_STOPPED

           labelCurrentStatus.Caption = "Sound stopped"

       Case enumPlayerEvents.enumPlayerEvents_EV_SOUND_DONE

           labelCurrentStatus.Caption = "Sound playback completed"

   End Select

End Sub

Private Sub Form_Load()

  ' instance the API

   Set m_audioDJ = New AudioDjStudioApi.AudioDjStudioApiObj

  ' init the control

   m_audioDJ.InitSoundSystem 1, 0, 0, 0, 0

  ' enable events for COM clients like VB6

   m_audioDJ.COMEventsEnable

  ' load a sound file and start playback

   m_audioDJ.LoadSound 0, "c:\mysound.mp3"

   m_audioDJ.PlaySound 0

End Sub

as seen for regular ActiveX controls, the name of the event management routine is made of a number of parts: the name of the component (in this case "m_audioDJ" which was originally declared with the "WithEvents" attribute) followed by the underscore "_" character and by the name of the event (in this case "OnPlayersEvents") and related parameters.


OnCurveDesignerPointsChange event

OnCurveDesignerPointsChange event

Remarks

Occurs when the curve inside a volume curve designer control is modified by dragging one of the control points through the mouse interaction.

This event replaces the usage of the CallbackCurveDesignerPointsChange delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable 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 6]

Private Sub DjStudioApi_OnCurveDesignerPointsChange ( _

ByVal nDesignerUniqueId As Long, _

ByVal nLeftX As Integer, _

ByVal nLeftY As Integer, _

ByVal nRightX As Integer, _

ByVal nRightY As Integer _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameters | 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


OnCastingEvents event

OnCastingEvents event

Remarks

Occurs during a casting session previously created by one between the CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer methods.

This event replaces the usage of the CallbackForCastingEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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 loopback devices see the WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic 6]

Private Sub DjStudioApi_OnCastingEvents ( _

ByVal nEvent as enumCastingEvents, _

ByVal nCastingUniqueId as Int32, _

ByVal nData1 as Int32, _

ByVal nData2 as Int32, _

ByVal pBufferUnicode as IntPtr, _

ByVal nBufferLength as Int32 _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter

Description

nEvent

The type of event.

Supported values, with related parameters, are the following:

Mnemonic constant

Value

Meaning

EV_CASTING_PLAYER_START

1

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.

Involved data parameters: none

EV_CASTING_PLAYER_PERC

2

Occurs during a player-based casting session to inform about the advancement percentage.

Involved data parameters:

nData1: Advancement of the casting session expressed in percentage

EV_CASTING_PLAYER_DONE

3

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 .

Involved data parameters:

nData1: The result of the operation. See the LastError property for details about the returned result code.

EV_CASTING_STREAM_MIXER_START

4

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.

EV_CASTING_STREAM_MIXER_STOP

5

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 nData1 parameter.

Involved data parameters:

nData1: 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.

EV_CASTING_WMA_CLIENT_CONNECT

6

Occurs when a client is connected/disconnected on a WMA network session created through a call to CastingWmaNetworkOpenForStreamMixer or CastingWmaNetworkOpenForPlayer methods.

Involved data parameters:

nData1: Boolean value that specifies if the client was connected or disconnected.

Supported values are the following:

Value | Meaning
0 | The client was disconnected
1 | The client was connected

pBufferUnicode: String representing the IP address of the connected client.

EV_CASTING_LOOPBACK_START

7

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.

EV_CASTING_LOOPBACK_STOP

8

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.

Involved data parameters:

nData1: 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.

This event is only intended for usage with Windows Vista and later versions.

nCastingUniqueId

Unique identifier of the casting session returned by a previous call to CastingCreateFromPlayer, CastingWmaPubPointOpenForPlayer or CastingWmaNetworkOpenForPlayer methods.

nData1

Number representing the first parameter related to the event (see the events table above for details)

nData2

Number representing the second parameter related to the event (see the events table above for details)

pBufferUnicode

Pointer to a buffer containing a string of Unicode characters with text information about the event. Below a couple of snippets that show how to convert the buffer contents into a .NET string through marshaling:

Visual Basic .NET

Imports System.Runtime.InteropServices

Dim strInfo As String = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength)

strInfo = strInfo.Trim()

Visual C#

using System.Runtime.InteropServices;

string strInfo = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength);

strInfo = strInfo.Trim();

Visual C++ with MFC (Unmanaged)

CString strInfo;

strInfo.Format (L"Connection from IP %s", pBufferUnicode);

Visual Basic 6

Dim strInfo As String

strInfo = StrFromPtr (pBufferUnicode, nBufferLength)

nBufferLength

The length in characters of the buffer above


OnCdDrivesEvents event

OnCdDrivesEvents event

Remarks

Occurs when an event related to a CD drive occurs.

This event replaces the usage of the CallbackForCdDrivesEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic 6]

Private Sub DjStudioApi_OnCdDrivesEvents ( _

ByVal nEvent as enumCdDrivesEvents, _

ByVal nCdDrive as Int32, _

ByVal nData1 as Int32, _

ByVal nData2 as Int32, _

ByVal nData3 as Int32 _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter

Description

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

Occurs at the beginning of a new CD track's loading session started through the LoadTrackFromCd method.

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

Occurs during a CD track loading session, started through the LoadTrackFromCd method, in order to notify the loading advancement percentage.

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

Occurs at the end of a CD track's loading session started through the LoadTrackFromCd method.

Involved data parameters:

nData1: Number representing the one-based index of the CD audio track that is being loaded.

EV_CD_STATUS_CHANGED

3

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.

Involved data parameters:

nData1: Number representing the CD drive status.Supported values are the following:

Mnemonic Value | 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

EV_CDDB_SERVERS_AVAIL

4

Occurs when the list of CDDB servers, requested through a previous call to the CddbRequestServersList method, is available.

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

Occurs when the CDDB server returns the CD album information requested through a previous call to the CddbRequestAlbumInfo method.

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.

Involved data parameters:

nData1: Boolean value that specifies if the CDDB information was retrieved successfully. Supported values are the following:

Mnemonic Value | Meaning
false | The request failed, check the LastError property value in order to see the possible cause of the error
true | The request succeeded and CDDB information is available

EV_CD_COVER_URLS_AVAIL

6

Occurs when the Internet URLs of the CD cover's pictures have been obtained from the Amazon Web Service.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | The request failed, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_CD_COVER_SMALL_FILE_AVAIL

7

Occurs when the small version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | The request failed, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_CD_COVER_MEDIUM_FILE_AVAIL

8

Occurs when the medium version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | The request failed, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_CD_COVER_LARGE_FILE_AVAIL

9

Occurs when the large version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: The result of the CD cover retrieval attempt. The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | The request failed, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

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.


OnCoreAudioEvents event

OnCoreAudioEvents event

Remarks

Occurs each time an event generated by CoreAudio devices occurs.

This event replaces the usage of the CallbackForCoreAudioEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

This event 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 callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic 6]

Private Sub DjStudioApi_OnCoreAudioEvents ( _

ByVal nEvent as enumCoreAudioEvents, _

ByVal nData1 as Long, _

ByVal nData2 as Long, _

ByVal nData3 as Long _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter

Description

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

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..

Involved data parameters:

nData1: 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.

nData2: 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.

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

EV_COREAUDIO_DEVICE_ADDED

1

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.

Involved data parameters: none.

EV_COREAUDIO_DEVICE_REMOVED

2

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.

Involved data parameters: none.

EV_COREAUDIO_DEVICE_DEFAULT_CHANGE

3

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.

Involved data parameters:

nData1: 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.

nData2: 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.

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

EV_COREAUDIO_DEVICE_VOLUME_CHANGE

4

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.

Involved data parameters:

nData1: 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.

nData2: 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.

EV_COREAUDIO_DEVICE_VUMETER_CHANGE

5

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.

Involved data parameters:

nData1: 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.

nData2: 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.

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.


OnDeviceChange event

OnDeviceChange 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 replaces the usage of the CallbackDeviceChange delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

This event is only intended for usage with Windows XP and earlier versions. When dealing with Windows Vista and higher versions it's recommended using the OnCoreAudioEvents event.

Syntax

[Visual Basic 6]

Private Sub DjStudioApi_OnDeviceChange ( _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj


OnDisplayConfigChanged event

OnDisplayConfigChanged event

Remarks

Occurs whenever whenever the configuration of the system display is changed.

This event replaces the usage of the CallbackDisplayConfigChanged delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

Syntax

[Visual Basic 6]

Private Sub DjStudioApi_OnDisplayConfigChanged ( _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj


OnDownloaderEvents event

OnDownloaderEvents event

Remarks

Occurs during a downloading session performed through the DownloaderDj class.

This event replaces the usage of the CallbackForDownloaderEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic 6]

Private Sub DjStudioApi_OnDownloaderEvents ( _

ByVal nEvent as enumDownloaderEvents, _

ByVal nDllSessionUniqueId as Int32, _

ByVal nParam1 as Int32, _

ByVal nParam2 as Int32, _

ByVal nParam3 as Int32 _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter

Description

nEvent

The type of event.

Supported values, with related parameters, are the following:

Mnemonic constant

Value

Meaning

EV_DOWNLOADER_SESSION_COMPLETED

1

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.

Involved data parameters: none

EV_DOWNLOADER_SESSION_FAILED

2

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.

Involved data parameters:

nParam1: Error code generated by the component: see the LastError property for supported values

nParam2: Eventual error code defined inside the Windows SDK.

nParam3: 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.

EV_DOWNLOADER_SESSION_PROGRESS

3

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.

Involved data parameters:

nParam1: Advancement of the download session expressed in percentage

EV_DOWNLOADER_INVALID_FILE

4

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.

Involved data parameters: none

EV_DOWNLOADER_SESSION_STARTED

5

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.

Involved data parameters: none

EV_DOWNLOADER_SESSION_STOPPED

6

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.

Involved data parameters: none

nDllSessionUniqueId

Unique identifier of the downloading session generated by a previous call to one between the Downloader.SessionStartToFile, Downloader.SessionStartToMemory and Downloader.SessionStartToPlayer.methods.

nParam1

Number representing the first parameter related to the event (see the events table above for details)

nParam2

Number representing the second parameter related to the event (see the events table above for details)

nParam3

Number representing the third parameter related to the event (see the events table above for details)


OnMidiKeyboardEvents event

OnMidiKeyboardEvents event

Remarks

Occurs when one of the keys on the virtual piano keyboard, previously created through the MIDI.KeyboardCreate method, is pressed or released.

This event replaces the usage of the CallbackForMidiKeyboardEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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 6]

Private Sub DjStudioApi_OnMidiKeyboardEvents ( _

ByVal hWndKeyboard as IntPtr, _

ByVal nNote as Int16, _

ByVal bPressed as Boolean, _

ByVal bSimulated as Boolean _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

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:

Value | Meaning
false | The key was released
true | 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:

Value | Meaning
false | The note was played on the MIDI stream in playback
true | The note was not played on the MIDI stream in playback but the corresponding key was rendered as pressed on the piano keyboard.


OnMidiMarkerEvents event

OnMidiMarkerEvents 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.

This event replaces the usage of the CallbackForMidiMarkerEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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 6]

Private Sub DjStudioApi_OnMidiMarkerEvents ( _

ByVal nMarkerType as enumMidiMarkerNotifications, _

ByVal nPlayerIndex as Int16, _

ByVal nTrack as Int32, _

ByVal fPositionInMs as Double, _

ByVal fPositionInTicks as Double, _

ByVal fPositionInPercentage as Double, _

ByVal pBufferUnicode as IntPtr, _

ByVal nBufferLength as Int32 _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter

Description

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

nPlayerIndex

Zero-based index of the player reporting the event

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

pBufferUnicode

Pointer to a buffer containing a string of Unicode characters with the text of the marker. Below a couple of snippets that show how to convert the buffer contents into a .NET string through marshaling:

Visual Basic .NET

Imports System.Runtime.InteropServices

Dim strInfo As String = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength)

strInfo = strInfo.Trim()

Visual C#

using System.Runtime.InteropServices;

string strInfo = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength);

strInfo = strInfo.Trim();

nBufferLength

The length in characters of the buffer above


OnMidiStreamEvents event

OnMidiStreamEvents 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 replaces the usage of the CallbackForMidiStreamEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

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 6]

Private Sub DjStudioApi_OnMidiStreamEvents ( _

ByVal nMidiEvent as enumMidiStreamEvents, _

ByVal nPlayerIndex as Int16, _

ByVal nMidiParam1 as Int32, _

ByVal nMidiParam2 as Int32, _

ByVal nMidiChannel as Int16, _

ByVal fPositionInMs as Double, _

ByVal fPositionInTicks as Double, _

ByVal fPositionInPercentage as Double _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter

Description

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 OnMidiStreamEvents 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

nPlayerIndex

Zero-based index of the player reporting the event

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


OnPlayersEvents event

OnPlayersEvents event

Remarks

Occurs when an event related to a player occurs.

This event replaces the usage of the CallbackForPlayersEvents delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

For further details about callback delegates see the How to synchronize the container application with the API tutorial.

Syntax

[Visual Basic 6]

Private Sub DjStudioApi_OnPlayersEvents ( _

ByVal nEvent as enumPlayerEvents, _

ByVal nPlayerIndex as Int16, _

ByVal nData1 as Int32, _

ByVal nData2 as Int32, _

ByVal fData3 as Single, _

ByVal pBufferUnicode as IntPtr, _

ByVal nBufferLength as Int32 _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter

Description

nEvent

Event reported by the player.

Supported values are the following:

Mnemonic constant

Value

Meaning with data parameters

EV_SOUND_DONE

0

Occurs when a song has been performed completely.

Involved data parameters: none.

EV_SOUND_PLAYING

1

Occurs when a song starts playing.

Involved data parameters: none.

EV_SOUND_PAUSED

2

Occurs when a song is paused.

Involved data parameters: none.

EV_SOUND_STOPPED

3

Occurs when a song is stopped.

Involved data parameters: none.

EV_SOUND_LOADED

4

Occurs when a song is loaded in memory from a file.

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

Occurs when a song or video clip has been loaded in memory from a file after a call to the LoadSoundSync, LoadSoundFromMemorySync, LoadEncryptedSoundSync, LoadEncryptedSoundFromMemorySync or VideoPlayer.LoadSync methods.

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

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.

Involved data parameters: none.

EV_DOWNLOAD_COMPLETE

7

Occurs when an Internet stream (usually a file) has been downloaded completely.

Involved data parameters: none.

EV_DOWNLOAD_BUFFERING

8

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.

Involved data parameters:

nData1: The buffering status.

EV_DOWNLOAD_PERC

9

Occurs during the download of an Internet stream to inform about buffering percentage.

Involved data parameters:

nData1: Number representing the download percentage.

EV_STREAM_CONNECTING

10

Occurs when the player starts the connection to an Internet stream.

Involved data parameters: none.

EV_STREAM_LOADED

11

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 EV_STREAM_LOADED_FROM_INET_PLS event (see below).

Involved data parameters:

nData1: The stream loading result.

EV_STREAM_LOADED_FROM_INET_PLS

12

Occurs after the player has tried to load an Internet stream taken from a playlist stored inside a web server.

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

Occurs when a playlist has been performed completely.

Involved data parameters: none.

EV_PLAYLIST_SOUND_LOADED

14

Occurs when a song included inside a playlist is loaded in memory from a file.

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

Occurs when the loading of a playlist's song fails.

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

Occurs when a playlist Internet stream item has been loaded.

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

Occurs when a song is closed and discarded from memory.

Involved data parameters: none.

EV_SERVER_CLOSED

18

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

Involved data parameters: none.

EV_DURATION_CHANGED

19

Occurs after a successful call to the Effects.PlaybackTempoSet and Effects.PlaybackRateSet methods to notify that the original sound duration has been altered.

Involved data parameters:

fData3: The updated sound duration expressed in seconds.

EV_VUMETER

20

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.

This event is fired only if you have created the VUMeter object though a call to the VUMeter.Create method.

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

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.

Involved data parameters: none.

EV_BPM_AVAILABLE

22

Occurs when a song BPM has been detected.

Involved data parameters:

fData3: The detected song BPM.

EV_FADING_VOLUME_CHANGED

23

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.

Involved data parameters:

fData3: The player's current volume.

EV_FADING_POINT_REACHED

24

Occurs when the playback of the song that will fade-out reaches the Fader.FadeStartFromEnd position

Involved data parameters: none.

EV_FADEIN_STARTED

25

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.

Involved data parameters: none.

EV_FADEIN_COMPLETED

26

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.

Involved data parameters: none.

EV_FADEOUT_STARTED

27

Occurs when the song fading-out starts lowering its volume.

This event is also generated at the start of a fade-in session performed after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

Involved data parameters: none.

EV_FADEOUT_COMPLETED

28

Occurs when the fade-out is completed.

This event is also generated at the end of a fade-in session performed after a call to the StopSound method when the StreamVolumeSmoothingSet or StreamVolumeSmoothingSetEx methods have been applied.

Involved data parameters: none.

EV_TRIGGER_REACHED

29

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.

Involved data parameters:

nData1: Number representing the trigger identifier.

EV_SILENCE_AVAIL

30

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.

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

Occurs when the analysis of a sound's waveform begins. The analysis is started through a previous call to the Waveform.AnalyzeFullSound method.

Involved data parameters: none.

EV_WAVE_ANALYSIS_PERC

32

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.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current sound analysis.

EV_WAVE_ANALYSIS_DONE

33

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.

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

Occurs when a loop of a sound range playback, started through a call to the PlaySoundRangeLoop or the VideoPlayer.PlayRangeWithLoop methods, has been completed.

Involved data parameters:

nData1: Number representing the amount of loops that must be still performed.

EV_WAV_EXPORT_START

35

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.

Involved data parameters: none.

EV_WAV_EXPORT_PERC

36

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.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current exporting session.

EV_WAV_EXPORT_COMPLETE

37

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.

Involved data parameters:

nData1: Number representing the total size, expressed in bytes, of the exported WAV file..

EV_EQUALIZER_LOADED

38

Occurs when settings of an equalizer file are applied to a sound.

Involved data parameters: none.

EV_CUE_POINTS_LOADED

39

Occurs when a file containing cue points have been loaded into the player.

Involved data parameters: none.

EV_BEATS_AVAILABLE

40

Occurs when the offline beats detection is completed. Offline beats detection can be started through a previous call to the BeatsDetectRequest method.

Involved data parameters:

nData1: Number of beats detected.

EV_BEAT_DETECTED

41

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.

Involved data parameters:

nData1: Beat's position expressed in milliseconds.

EV_PLAYLIST_LOAD_STARTED

42

Occurs when the synchronized loading of a playlist starts. A synchronized loading is started through a call to the PlayListLoadSync method.

Involved data parameters: none.

EV_PLAYLIST_LOAD_PERC

43

Occurs during the synchronized loading of a playlist. A synchronized loading is started through a call to the PlayListLoadSync method.

Involved data parameters:

nData1: Number representing the percentage of advancement for the loading session.

EV_PLAYLIST_LOAD_DONE

44

Occurs when the synchronized loading of a playlist is completed. A synchronized loading is started through a call to the PlayListLoadSync method.

Involved data parameters: none.

EV_CUE_POINT_REACHED

45

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.

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

Occurs when a volume automation point is reached during playback.

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

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

Involved data parameters: none.

EV_LYRICS_AVAIL

48

Occurs when a previous request to the SoundLyricsRequest method is completed.

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

Occurs when a queued stream, created through the StreamQueueCreate method and fed through the StreamQueuePushData method, doesn't have PCM data to play.

Involved data parameters: none.

EV_AUDIO_EXTRACT_START

50

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.

Involved data parameters: none.

EV_AUDIO_EXTRACT_PERC

51

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

Involved data parameters:

nData1: Number representing the current percentage of the audio extraction.

EV_AUDIO_EXTRACT_DONE

52

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.

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

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.

Involved data parameters: none.

EV_PLAYER_DISCONNECTED

54

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.

Involved data parameters: none.

EV_OUTPUT_DEVICE_CHANGED

55

Occurs when the output device (sound card) has been changed through a successful call to the StreamOutputDeviceSet method.

Involved data parameters:

nData1: Number representing the zero-based index of the new output device for the given player.

EV_SILENCE_DETECTION

56

Occurs during playback of a sound stream having realtime silence detection enabled through the SilenceDetectionRealTimeEnable method.

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.

EV_VST_PARAM_CHANGED

57

Occurs when a parameter of the VST has been changed through its editor.

Involved data parameters:

nData1: Number representing the unique identifier of the VST.

nData2: Number representing the zero-based index of the changed parameter.

fData3: Number representing the updated parameter value.

EV_VST_EDITOR_RESIZED

58

Occurs when the editor of the VST effect is resized.

Involved data parameters:

nData1: Number representing the unique identifier of the VST.

nData2: Number containing the updated size of the VST. The updated width is stored inside the lower 16 bits of the parameter while the updated height is stored inside the higher 16 bits of the parameter.

EV_LRC_FILE_AVAILABLE

59

Occurs when a lyrics LRC file is found and loaded.

Involved data parameters:

nData1: Boolean value specifying if the LRC file is in enhanced format.

EV_LRC_ADVANCETIME_FULL_LINE

60

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.

Involved data parameters:

nData1: Number representing the zero based-index of the Line Time Tag.

nData2: Position, expressed in milliseconds, within the song of the Line Time Tag.

pBufferUnicode: String containing the full line of text of the Line Time Tag

EV_LRC_REALTIME_FULL_LINE

61

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.

Involved data parameters:

nData1: Number representing the zero based-index of the Line Time Tag.

nData2: Position, expressed in milliseconds, within the song of the Line Time Tag.

pBufferUnicode: String containing the full line of text of the Line Time Tag

EV_LRC_REALTIME_PORTION_LINE

62

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.

Involved data parameters:

nData1: Number representing the zero based-index of the Line Enhanced Time Tag

nData2: Position, expressed in milliseconds, within the song of the Enhanced Time Tag

fData3: Duration, expressed in milliseconds, of the Enhanced Time Tag

pBufferUnicode: String containing the full line of text of the Enhanced Time Tag

EV_WAVEFORM_CHANGE

63

Occurs during playback whenever there is a change on the waveform peak values displayed on an object of the Waveform class.

nPlayerIndex

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 a buffer containing a string of Unicode characters related to the event; its value and meaning depends upon the specific event received: see the table above for possible values. Below a couple of snippets that show how to convert the buffer contents, passed when the callback is invoked with the nEvent parameter set to EV_CUE_POINT_REACHED, into a .NET string through marshaling:

Visual Basic .NET

Imports System.Runtime.InteropServices

Dim strCuePointName As String = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength)

strCuePointName = strCuePointName.Trim()

Visual C#

using System.Runtime.InteropServices;

string strCuePointName = Marshal.PtrToStringUni(pBufferUnicode, nBufferLength);

strCuePointName = strCuePointName.Trim();

Visual C++ with MFC (Unmanaged)

CString strCuePointName;

strCuePointName.Format (L"Reached Cue Point with name %s on player %d", pBufferUnicode, nPlayerIndex);

Visual Basic 6

Dim strCuePointName As String

strCuePointName = StrFromPtr(pBufferUnicode, nBufferLength)

nBufferLength

The length in characters of the buffer above


OnWaveformScrollerManualScroll event

OnWaveformScrollerManualScroll event

Remarks

Occurs when a manual move is performed through the mouse on the waveform scroller.

This event replaces the usage of the CallbackWaveformScrollerManualScroll delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable 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 6]

Private Sub DjStudioApi_OnWaveformScrollerManualScroll ( _

ByVal hWndWaveformScroller as Long, _

ByVal nNewPosInMs as Long _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameters | Description
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


OnWaveformScrollerMouseNotif event

OnWaveformScrollerMouseNotif event

Remarks

Occurs when a mouse action happens over the waveform scroller.

This event replaces the usage of the CallbackWaveformScrollerMouseNotif delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable 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 6]

Private Sub DjStudioApi_OnWaveformAnalyzerMouseNotif ( _

ByVal hWndWaveformScroller as Long, _

ByVal nAction as enumMouseActions, _

ByVal nFlags as Long, _

ByVal xPos as Long, _

ByVal yPos as Long _

ByVal nPressPosInPix as Long, _

ByVal nPressPosInMs as Long _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter

Description

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
MOUSE_ACTION_MIDDLE_DOWN | 9 | Middle mouse button down
MOUSE_ACTION_MIDDLE_UP | 10 | Middle mouse button up
MOUSE_ACTION_MIDDLE_CLICK | 11 | Middle mouse button click
MOUSE_ACTION_MIDDLE_DBLCLICK | 12 | Middle mouse button double click

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.


OnZipOperationPerc event

OnZipOperationPerc 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.

This event replaces the usage of the CallbackZipOperationPerc delegate and is only intended for usage with applications developed using Visual Basic 6 (which results unreliable when dealing with delegates and callbacks) and, in order to be enabled, requires a call to the COMEventsEnable method.

For further details about methods for ZIP management refer to the ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic 6]

Private Sub OnZipOperationPerc ( _

ByVal nPercentage as Integer, _

)

where "DjStudioApi" is declared in Visual Basic 6 code as:

Dim WithEvents DjStudioApi As AudioDjStudioApi.AudioDjStudioApiObj

Event Data

Parameter | Description
nPercentage | Number representing the percentage of advancement of the ZIP operation.


ASIOMan class

ASIOMan class

The ASIOMan class, accessible through the component's ASIO property contains methods needed to manage ASIO compatible devices and drivers.

The ASIOMan class is implemented through the following methods:

AttachInputChannelToPlayer

ControlPanelDisplay

DeviceChannelVolumeGet

DeviceChannelVolumeSet

DeviceGetChannelDesc

DeviceGetChannelsCount

DeviceGetCount

DeviceGetDesc

DeviceGetDriverPathname

DeviceGetIndexFromOutput

DeviceGetOutputIndex

DeviceIsStarted

DeviceLatencyGet

DeviceListenInputStart

DeviceListenInputPause

DeviceListenInputResume

DeviceListenInputPlayerGet

DeviceMasterVolumeGet

DeviceMasterVolumeSet

DeviceMonoToStereoSet

DeviceSampleRateCurrentGet

DeviceSampleRateSupportedCountGet

DeviceSampleRateSupportedGet

DeviceStart

DeviceStop

PlayerOutputChannelGet

PlayerOutputChannelSet

Further information about the use 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#.NET and Visual Basic.NET can be found inside the following samples installed with the product's setup package:

- AsioList

- AsioSpeakersManager

- AsioVideoPlayer

- AsioStreamMixer (requires the installation of Audio Sound Recorder API for .NET)


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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function AttachInputChannelToPlayer (

nPlayerIndex as Int16,

nDeviceIndex as Int16,

nFirstChannel as Int16,

nTotalChannels as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes AttachInputChannelToPlayer (

Int16 nPlayerIndex,

Int16 nDeviceIndex,

Int16 nFirstChannel,

Int16 nTotalChannels

);

[C++]

public: enumErrorCodes AttachInputChannelToPlayer (

Int16 nPlayerIndex,

Int16 nDeviceIndex,

Int16 nFirstChannel,

Int16 nTotalChannels

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function ControlPanelDisplay (

nDeviceIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ControlPanelDisplay (

Int16 nDeviceIndex

);

[C++]

public: enumErrorCodes ControlPanelDisplay (

Int16 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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceChannelVolumeGet (

nDeviceIndex as Int16,

nChannelIndex as Int16,

bInputChannel as Boolean,

nScaleType as enumVolumeScales

) as Single

[C#]

public float DeviceChannelVolumeGet (

Int16 nDeviceIndex,

Int16 nChannelIndex,

bool bInputChannel,

enumVolumeScales nScaleType

);

[C++]

public: float DeviceChannelVolumeGet (

Int16 nDeviceIndex,

Int16 nChannelIndex,

bool bInputChannel,

enumVolumeScales 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 | Meaning
false | Output channel
true | 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceChannelVolumeSet (

nDeviceIndex as Int16,

nChannelIndex as Int16,

bInputChannel as Boolean,

fVolume as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceChannelVolumeSet (

Int16 nDeviceIndex,

Int16 nChannelIndex,

bool bInputChannel,

float fVolume,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes DeviceChannelVolumeSet (

Int16 nDeviceIndex,

Int16 nChannelIndex,

bool bInputChannel,

float fVolume,

enumVolumeScales 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 | Meaning
false | Output channel
true | 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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceGetChannelDesc (

nDeviceIndex as Int16,

nChannelIndex as Int16,

bInputChannel as Boolean

) as String

[C#]

public string DeviceGetChannelDesc (

Int16 nDeviceIndex,

Int16 nChannelIndex,

bool bInputChannel

);

[C++]

public: string DeviceGetChannelDesc (

Int16 nDeviceIndex,

Int16 nChannelIndex,

bool 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 | Meaning
false | Output channel
true | 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceGetChannelsCount (

nDeviceIndex as Int16,

bInputChannel as Boolean

) as Int16

[C#]

public Int16 DeviceGetChannelsCount (

Int16 nDeviceIndex,

bool bInputChannel

);

[C++]

public: Int16 DeviceGetChannelsCount (

Int16 nDeviceIndex,

bool 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 | Meaning
false | Output channels
true | 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceGetCount (

) as Int16

[C#]

public Int16 DeviceGetCount (

);

[C++]

public: Int16 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceGetDesc (

nDeviceIndex as Int16

) as String

[C#]

public string DeviceGetDesc (

Int16 nDeviceIndex

);

[C++]

public: string DeviceGetDesc (

Int16 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceGetDriverPathname (

nDeviceIndex as Int16

) as String

[C#]

public string DeviceGetDriverPathname (

Int16 nDeviceIndex

);

[C++]

public: string DeviceGetDriverPathname (

Int16 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 GetOutputDeviceDescmethods. 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceGetIndexFromOutput (

nOutputIndex as Int16

) as Int16

[C#]

public Int16 DeviceGetIndexFromOutput (

Int16 nOutputIndex

);

[C++]

public: Int16 DeviceGetIndexFromOutput (

Int16 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 GetOutputDeviceDescmethods. 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceGetOutputIndex (

nDeviceIndex as Int16

) as Int16

[C#]

public Int16 DeviceGetOutputIndex (

Int16 nDeviceIndex

);

[C++]

public: Int16 DeviceGetOutputIndex (

Int16 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceIsStarted (

nDeviceIndex as Int16

) as Boolean

[C#]

public bool DeviceIsStarted (

Int16 nDeviceIndex

);

[C++]

public: bool DeviceIsStarted (

Int16 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceLatencyGet (

nDeviceIndex as Int16,

bInputChannel as Boolean

) as Int16

[C#]

public Int16 DeviceLatencyGet (

Int16 nDeviceIndex,

bool bInputChannel,

);

[C++]

public: Int16 DeviceLatencyGet (

Int16 nDeviceIndex,

bool 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 | Meaning
false | Output channels
true | 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceListenInputStart (

nDeviceIndex as Int16,

nInputChannelFirst as Int16,

nOutputChannelFirst as Int16,

nTotalChannels as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceListenInputStart (

Int16 nDeviceIndex,

Int16 nInputChannelFirst,

Int16 nOutputChannelFirst,

Int16 nTotalChannels

);

[C++]

public: enumErrorCodes DeviceListenInputStart (

Int16 nDeviceIndex,

Int16 nInputChannelFirst,

Int16 nOutputChannelFirst,

Int16 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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceListenInputPause (

nDeviceIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceListenInputPause (

Int16 nDeviceIndex

);

[C++]

public: enumErrorCodes DeviceListenInputPause (

Int16 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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceListenInputPlayerGet (

nDeviceIndex as Int16,

ByRef nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceListenInputPlayerGet (

Int16 nDeviceIndex,

ref Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes DeviceListenInputPlayerGet (

Int16 nDeviceIndex,

Int16 __gc *nPlayerIndex

);

Parameter | Description
nDeviceIndex | Number representing the zero-based index of the ASIO device previously started through a call to the ASIO.DeviceListenInputStart method.
nPlayerIndex | 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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceListenInputResume (

nDeviceIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceListenInputResume (

Int16 nDeviceIndex

);

[C++]

public: enumErrorCodes DeviceListenInputResume (

Int16 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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceMasterVolumeGet (

nDeviceIndex as Int16,

bInputChannel as Boolean,

nScaleType as enumVolumeScales

) as Single

[C#]

public float DeviceMasterVolumeGet (

Int16 nDeviceIndex,

bool bInputChannel,

enumVolumeScales nScaleType

);

[C++]

public: float DeviceMasterVolumeGet (

Int16 nDeviceIndex,

bool bInputChannel,

enumVolumeScales 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 | Meaning
false | Output channels
true | 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 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceMasterVolumeSet (

nDeviceIndex as Int16,

bInputChannel as Boolean,

fVolume as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceMasterVolumeSet (

Int16 nDeviceIndex,

bool bInputChannel,

float fVolume,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes DeviceMasterVolumeSet (

Int16 nDeviceIndex,

bool bInputChannel,

float fVolume,

enumVolumeScales 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 | Meaning
false | Output channels
true | Input channels

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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceMonoToStereoSet (

nDeviceIndex as Int16,

bMonoToStereo as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceMonoToStereoSet (

Int16 nDeviceIndex,

bool bMonoToStereo

);

[C++]

public: enumErrorCodes DeviceMonoToStereoSet (

Int16 nDeviceIndex,

bool 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 mono streams must be rendered as stereo.

Supported values are the following:

Mnemonic constant | Meaning
false (default) | Mono streams are reproduced in mono on a single ASIO channel.
true | 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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceSampleRateCurrentGet (

nDeviceIndex as Int16,

ByRef nRate as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceSampleRateCurrentGet (

Int16 nDeviceIndex,

ref Int32 nRate

);

[C++]

public: enumErrorCodes DeviceSampleRateCurrentGet (

Int16 nDeviceIndex,

Int32 __gc *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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceSampleRateSupportedCountGet (

nDeviceIndex as Int16,

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceSampleRateSupportedCountGet (

Int16 nDeviceIndex,

ref Int32 nCount

);

[C++]

public: enumErrorCodes DeviceSampleRateSupportedCountGet (

Int16 nDeviceIndex,

Int32 __gc *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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceSampleRateSupportedGet (

nDeviceIndex as Int16,

nSampleRateIndex as Int32,

ByRef nRate as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceSampleRateSupportedGet (

Int16 nDeviceIndex,

Int32 nSampleRateIndex,

ref Int32 nRate

);

[C++]

public: enumErrorCodes DeviceSampleRateSupportedGet (

Int16 nDeviceIndex,

Int32 nSampleRateIndex,

Int32 __gc *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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceStart (

nDeviceIndex as Int16,

nSampleRate as Int32,

nChannelMode as enumAsioChannelModes,

nOutputChannelFirst as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceStart (

Int16 nDeviceIndex,

Int32 nSampleRate,

enumAsioChannelModes nChannelMode,

Int16 nOutputChannelFirst

);

[C++]

public: enumErrorCodes DeviceStart (

Int16 nDeviceIndex,

Int32 nSampleRate,

enumAsioChannelModes nChannelMode,

Int16 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 Audio Sound Recorder API for .NET component.

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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function DeviceStop (

nDeviceIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceStop (

Int16 nDeviceIndex

);

[C++]

public: enumErrorCodes DeviceStop (

Int16 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.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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function PlayerOutputChannelGet (

nPlayerIndex as Int16

) as Int16

[C#]

public Int16 PlayerOutputChannelGet (

Int16 nPlayerIndex

);

[C++]

public: Int16 PlayerOutputChannelGet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 ASIOMan class and the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function PlayerOutputChannelSet (

nPlayerIndex as Int16,

nChannelIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerOutputChannelSet (

Int16 nPlayerIndex,

Int16 nChannelIndex

);

[C++]

public: enumErrorCodes PlayerOutputChannelSet (

Int16 nPlayerIndex,

Int16 nChannelIndex

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method call was successful.


CoreAudioDevicesMan class

CoreAudioDevicesMan class

The CoreAudioDevicesMan class, accessible through the control's CoreAudioDevices property contains methods needed to manage audio devices under Windows Vista and later versions.

The CoreAudioDevicesMan class 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# and Visual Basic.NET 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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function DisplaySoundApplet (

strOptionalParams as String

) as enumErrorCodes

[C#]

public enumErrorCodes DisplaySoundApplet (

string strOptionalParams

);

[C++]

public: enumErrorCodes DisplaySoundApplet (

string 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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function Enum (

nStateMask as enumCoreAudioDeviceStates

) as enumErrorCodes

[C#]

public enumErrorCodes Enum (

enumCoreAudioDeviceStates nStateMask

);

[C++]

public: enumErrorCodes Enum (

enumCoreAudioDeviceStates 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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function Free (

) as enumErrorCodes

[C#]

public enumErrorCodes Free (

);

[C++]

public: enumErrorCodes Free (

);

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.


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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function CapturePartChannelCountGet (

nDeviceIndex as Int16,

nPartId as enumCoreAudioCaptureParts,

ByRef nChannelsCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes CapturePartChannelCountGet (

Int16 nDeviceIndex,

enumCoreAudioCaptureParts nPartId,

ref Int16 nChannelsCount

);

[C++]

public: enumErrorCodes CapturePartChannelCountGet (

Int16 nDeviceIndex,

enumCoreAudioCaptureParts nPartId,

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function CapturePartChannelVolumeGet (

nDeviceIndex as Int16,

nPartId as enumCoreAudioCaptureParts,

nChannel as Int16,

ByRef fLevelIndB as Single,

ByRef fRangeMinIndB as Single,

ByRef fRangeMaxIndB as Single,

ByRef fSteppingIndB as Single

) as enumErrorCodes

[C#]

public enumErrorCodes CapturePartChannelVolumeGet (

Int16 nDeviceIndex,

enumCoreAudioCaptureParts nPartId,

Int16 nChannel,

ref float fLevelIndB,

ref float fRangeMinIndB,

ref float fRangeMaxIndB,

ref float fSteppingIndB

);

[C++]

public: enumErrorCodes CapturePartChannelVolumeGet (

Int16 nDeviceIndex,

enumCoreAudioCaptureParts nPartId,

Int16 nChannel,

float __gc *fLevelIndB,

float __gc *fRangeMinIndB,

float __gc *fRangeMaxIndB,

float __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function CapturePartChannelVolumeSet (

nDeviceIndex as Int16,

nPartId as enumCoreAudioCaptureParts,

nChannel as Int16,

fLevelIndB as Single

) as enumErrorCodes

[C#]

public enumErrorCodes CapturePartChannelVolumeSet (

Int16 nDeviceIndex,

enumCoreAudioCaptureParts nPartId,

Int16 nChannel,

float fLevelIndB

);

[C++]

public: enumErrorCodes CapturePartChannelVolumeSet (

Int16 nDeviceIndex,

enumCoreAudioCaptureParts nPartId,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function ChannelCountGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

ByRef nChannelsCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ChannelCountGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

ref Int16 nChannelsCount

);

[C++]

public: enumErrorCodes ChannelCountGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_VOLUME_CHANGE.

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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function ChannelVolumeGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

nChannelIndex as Integer,

nScaleType as enumVolumeScales,

ByRef fVolumeLevel as Single

) as enumErrorCodes

[C#]

public enumErrorCodes ChannelVolumeGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 nChannelIndex,

enumVolumeScales nScaleType,

ref float fVolumeLevel

);

[C++]

public: enumErrorCodes ChannelVolumeGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 nChannelIndex,

enumVolumeScales nScaleType,

float __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function ChannelVolumeSet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

nChannelIndex as Integer,

nScaleType as enumVolumeScales,

fVolumeLevel as Single

) as enumErrorCodes

[C#]

public enumErrorCodes ChannelVolumeSet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 nChannelIndex,

enumVolumeScales nScaleType,

float fVolumeLevel

);

[C++]

public: enumErrorCodes ChannelVolumeSet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 nChannelIndex,

enumVolumeScales 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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function CountGet (

nDataFlow as enumCoreAudioDataFlows,

ByRef nDevicesCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes CountGet (

enumCoreAudioDataFlows nDataFlow,

ref Int16 nDevicesCount

);

[C++]

public: enumErrorCodes CountGet (

enumCoreAudioDataFlows nDataFlow,

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_DEFAULT_CHANGE.

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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function DefaultGet (

nDataFlow as enumCoreAudioDataFlows,

nRole as enumCoreAudioRoles,

ByRef nDeviceIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DefaultGet (

enumCoreAudioDataFlows nDataFlow,

enumCoreAudioRoles nRole,

ref Int16 nDeviceIndex

);

[C++]

public: enumErrorCodes DefaultGet (

enumCoreAudioDataFlows nDataFlow,

enumCoreAudioRoles nRole,

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function DefaultSet (

nDataFlow as enumCoreAudioDataFlows,

nRole as enumCoreAudioRoles,

nDeviceIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DefaultSet (

enumCoreAudioDataFlows nDataFlow,

enumCoreAudioRoles nRole,

Int16 nDeviceIndex

);

[C++]

public: enumErrorCodes DefaultSet (

enumCoreAudioDataFlows nDataFlow,

enumCoreAudioRoles nRole,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function DescGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

nTypeOfName as enumCoreAudioDeviceNames

) as String

[C#]

public string DescGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumCoreAudioDeviceNames nTypeOfName

);

[C++]

public: string DescGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumCoreAudioDeviceNames 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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function JackCountGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

ByRef nJacksCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes JackCountGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

ref Int16 nJacksCount

);

[C++]

public: enumErrorCodes JackCountGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function JackDescriptorGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

nJackIndex as Integer,

ByRef desc as KSJACK_DESCRIPTION

) as enumErrorCodes

[C#]

public enumErrorCodes JackDescriptorGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 nJackIndex,

ref KSJACK_DESCRIPTION desc

);

[C++]

public: enumErrorCodes JackDescriptorGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 nJackIndex,

KSJACK_DESCRIPTION __gc *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

Reference to a structure of type KSJACK_DESCRIPTION that, on return from the method call, will contain 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 (see the LastError property for further error details)
enumErrorCodes.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 CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_VOLUME_CHANGE.

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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MasterVolumeGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

nScaleType as enumVolumeScales,

ByRef fVolumeLevel as Single,

ByRef fLevelMinIndB as Single,

ByRef fLevelMaxIndB as Single,

ByRef fVolumeIncrementIndB as Single

) as enumErrorCodes

[C#]

public enumErrorCodes MasterVolumeGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumVolumeScales nScaleType,

ref float fVolumeLevel,

ref float fLevelMinIndB,

ref float fLevelMaxIndB,

ref float fVolumeIncrementIndB

);

[C++]

public: enumErrorCodes MasterVolumeGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumVolumeScales nScaleType,

float __gc *fVolumeLevel,

float __gc *fLevelMinIndB,

float __gc *fLevelMaxIndB,

float __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MasterVolumeSet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

nScaleType as enumVolumeScales,

fVolumeLevel as Single

) as enumErrorCodes

[C#]

public enumErrorCodes MasterVolumeSet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumVolumeScales nScaleType,

float fVolumeLevel

);

[C++]

public: enumErrorCodes MasterVolumeSet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumVolumeScales 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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MuteGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

ByRef bMute as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MuteGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

ref bool bMute

);

[C++]

public: enumErrorCodes MuteGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

bool __gc *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 | Meaning
false | The audio stream is not muted
true | The audio stream is muted

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.


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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MuteSet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

bMute as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MuteSet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

bool bMute

);

[C++]

public: enumErrorCodes MuteSet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

bool 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 | Meaning
false | The audio stream is not muted
true | The audio stream is muted

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.


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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function RenderPartChannelCountGet (

nDeviceIndex as Int16,

nPartId as enumCoreAudioRenderParts,

ByRef nChannelsCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes RenderPartChannelCountGet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

ref Int16 nChannelsCount

);

[C++]

public: enumErrorCodes RenderPartChannelCountGet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function RenderPartChannelVolumeGet (

nDeviceIndex as Int16,

nPartId as enumCoreAudioRenderParts,

nChannel as Int16,

ByRef fLevelIndB as Single,

ByRef fRangeMinIndB as Single,

ByRef fRangeMaxIndB as Single,

ByRef fSteppingIndB as Single

) as enumErrorCodes

[C#]

public enumErrorCodes RenderPartChannelVolumeGet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

Int16 nChannel,

ref float fLevelIndB,

ref float fRangeMinIndB,

ref float fRangeMaxIndB,

ref float fSteppingIndB

);

[C++]

public: enumErrorCodes RenderPartChannelVolumeGet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

Int16 nChannel,

float __gc *fLevelIndB,

float __gc *fRangeMinIndB,

float __gc *fRangeMaxIndB,

float __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function RenderPartChannelVolumeSet (

nDeviceIndex as Int16,

nPartId as enumCoreAudioRenderParts,

nChannel as Int16,

fLevelIndB as Single

) as enumErrorCodes

[C#]

public enumErrorCodes RenderPartChannelVolumeSet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

Int16 nChannel,

float fLevelIndB

);

[C++]

public: enumErrorCodes RenderPartChannelVolumeSet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function RenderPartMuteGet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioRenderParts,

ByRef bMute as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes RenderPartMuteGet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

ref bool bMute

);

[C++]

public: enumErrorCodes RenderPartMuteGet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

bool __gc *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 | Meaning
false | The audio stream is not muted
true | The audio stream is muted

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.


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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function RenderPartMuteSet (

nDeviceIndex as Integer,

nPartId as enumCoreAudioRenderParts,

bMute as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes RenderPartMuteSet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

bool bMute

);

[C++]

public: enumErrorCodes RenderPartMuteSet (

Int16 nDeviceIndex,

enumCoreAudioRenderParts nPartId,

bool 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 | Meaning
false | The audio stream is not muted
true | The audio stream is muted

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.


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 through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_STATE_CHANGED and the nData3 parameter reporting the current status.

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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function StatusGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

ByRef nStatus as enumCoreAudioDeviceStates

) as enumErrorCodes

[C#]

public enumErrorCodes StatusGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

ref enumCoreAudioDeviceStates nStatus

);

[C++]

public: enumErrorCodes StatusGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumCoreAudioDeviceStates __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function TypeGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

ByRef nDeviceType as enumCoreAudioDeviceTypes

) as enumErrorCodes

[C#]

public enumErrorCodes TypeGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

ref enumCoreAudioDeviceTypes nDeviceType

);

[C++]

public: enumErrorCodes TypeGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumCoreAudioDeviceTypes __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_VUMETER_CHANGE.

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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function VuMeterChannelPeakValueGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

nChannelIndex as Integer,

fPeakValue as Single

) as enumErrorCodes

[C#]

public enumErrorCodes VuMeterChannelPeakValueGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 nChannelIndex,

ref float fPeakValue

);

[C++]

public: enumErrorCodes VuMeterChannelPeakValueGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

Int16 nChannelIndex,

float __gc *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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CoreAudioDevices.VuMeterEnableNotifications method

CoreAudioDevices.VuMeterEnableNotifications method

Remarks

Enables/disables VU-Meter notifications, sent through the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_VUMETER_CHANGE, 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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function VuMeterEnableNotifications (

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes VuMeterEnableNotifications (

bool bEnable

);

[C++]

public: enumErrorCodes VuMeterEnableNotifications (

bool bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if the CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_VUMETER_CHANGE must be enabled.

Supported values are the following:

Mnemonic constant | Meaning
false (default) | The event is disabled
true | The event 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.


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 through CallbackForCoreAudioEvents delegate having the nEvent parameter set to EV_COREAUDIO_DEVICE_VUMETER_CHANGE.

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 CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function VuMeterMasterPeakValueGet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

fPeakValue as Single

) as enumErrorCodes

[C#]

public enumErrorCodes VuMeterMasterPeakValueGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

ref float fPeakValue

);

[C++]

public: enumErrorCodes VuMeterMasterPeakValueGet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

float __gc *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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


CustomDSPs class

CustomDSPs class

The CustomDSPs class, accessible through the control's CustomDSP property, contains methods needed to apply custom DSP effects during a playback session.

The CustomDSPs class 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function Enable (

nPlayerIndex as Int16,

nIdDsp as Int32,

bEnable as Boolean,

nUserData as Int32,

nPriority as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Enable (

Int16 nPlayerIndex,

Int32 nIdDsp,

bool bEnable,

Int32 nUserData,

Int32 nPriority

);

[C++]

public: enumErrorCodes Enable (

Int16 nPlayerIndex,

Int32 nIdDsp,

bool bEnable,

Int32 nUserData,

Int32 nPriority

);

Parameter

Description

nPlayerIndex

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
false | Disable the custom DSP effect
true | Enable 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function ExternalEditorGetInfo (

nPlayerIndex as Int16,

nIdDsp as Int32,

pInfo as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalEditorGetInfo (

Int16 nPlayerIndex,

Int32 nIdDsp,

IntPtr pInfo

);

[C++]

public: enumErrorCodes ExternalEditorGetInfo (

Int16 nPlayerIndex,

Int32 nIdDsp,

IntPtr pInfo

);

Parameter | Description
nPlayerIndex | 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function ExternalEditorShow (

nPlayerIndex as Int16,

nIdDsp as Int32,

bShow as Boolean,

hWndParent as IntPtr,

leftPos as Int32,

topPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalEditorShow (

Int16 nPlayerIndex,

Int32 nIdDsp,

bool bShow,

IntPtr hWndParent,

Int32 leftPos,

Int32 topPos

);

[C++]

public: enumErrorCodes ExternalEditorShow (

Int16 nPlayerIndex,

Int32 nIdDsp,

bool bShow,

IntPtr hWndParent,

Int32 leftPos,

Int32 topPos

);

Parameter

Description

nPlayerIndex

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
false | Hides the editor window
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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function ExternalGetParameters (

nPlayerIndex as Int16,

nIdDsp as Int32,

pParameters as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalGetParameters (

Int16 nPlayerIndex,

Int32 nIdDsp,

IntPtr pParameters

);

[C++]

public: enumErrorCodes ExternalGetParameters (

Int16 nPlayerIndex,

Int32 nIdDsp,

IntPtr pParameters

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nIdDsp | Unique identifier of the custom DSP
pParameters | Pointer 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function ExternalLoad (

nPlayerIndex as Int16,

strPathname as String

) as Int32

[C#]

public Int32 ExternalLoad (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: Int32 ExternalLoad (

Int16 nPlayerIndex,

string strPathname

);

Parameter

Description

nPlayerIndex

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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function ExternalSendCommand (

nPlayerIndex as Int16,

nIdDsp as Int32,

hWndParent as IntPtr,

strCommand as string

) as Int32

[C#]

public Int32 ExternalSendCommand (

Int16 nPlayerIndex,

Int32 nIdDsp,

IntPtr hWndParent,

string strCommand

);

[C++]

public: Int32 ExternalSendCommand (

Int16 nPlayerIndex,

Int32 nIdDsp,

IntPtr hWndParent,

string strCommand

);

Parameter

Description

nPlayerIndex

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 Audio Dj Studio API for .NET 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 string 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function ExternalSetFunction (

nPlayerIndex as Int16,

nIdDsp as Int32,

nFunctionType as enumDspExternalFunctions,

strFunctionName as string

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalSetFunction (

Int16 nPlayerIndex,

Int32 nIdDsp,

enumDspExternalFunctions nFunctionType,

string strFunctionName

);

[C++]

public: enumErrorCodes ExternalSetFunction (

Int16 nPlayerIndex,

Int32 nIdDsp,

enumDspExternalFunctions nFunctionType,

string strFunctionName

);

Parameter

Description

nPlayerIndex

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.UseFloatSamples 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function ExternalSetParameters (

nPlayerIndex as Int16,

nIdDsp as Int32,

pParameters as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalSetParameters (

Int16 nPlayerIndex,

Int32 nIdDsp,

IntPtr pParameters

);

[C++]

public: enumErrorCodes ExternalSetParameters (

Int16 nPlayerIndex,

Int32 nIdDsp,

IntPtr pParameters

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
nIdDsp | Unique identifier of the custom DSP
pParameters | Pointer 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function Free (

nPlayerIndex as Int16,

nIdDsp as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Free (

Int16 nPlayerIndex,

Int32 nIdDsp

);

[C++]

public: enumErrorCodes Free (

Int16 nPlayerIndex,

Int32 nIdDsp

);

Parameter | Description
nPlayerIndex | 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function InternalLoad (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 InternalLoad (

Int16 nPlayerIndex

);

[C++]

public: Int32 InternalLoad (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function InternalSetFunction (

nPlayerIndex as Int16,

nIdDsp as Int32,

function as DSPCallbackFunction

) as enumErrorCodes

[C#]

public enumErrorCodes InternalSetFunction (

Int16 nPlayerIndex,

Int32 nIdDsp,

DSPCallbackFunction function

);

[C++]

public: enumErrorCodes InternalSetFunction (

Int16 nPlayerIndex,

Int32 nIdDsp,

DSPCallbackFunction function

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nIdDsp

Unique identifier of the custom DSP

function

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 ]

Private Sub MyCustomCallback (

ByVal bufferSamples As IntPtr,

ByVal bufferSamplesLength As Int32,

ByVal nUserData As Int32

)

[C#]

private void MyCustomCallback (

IntPtr bufferSamples,

Int32 bufferSamplesLength,

Int32 nUserData

);

[C++]

void MyCustomCallback (

IntPtr bufferSamples,

Int32 bufferSamplesLength,

Int32 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.UseFloatSamples 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 CustomDSPs class.

Further information about the use of Custom DSP effects can be found inside the How to manage custom DSP effects tutorial.

Syntax

[Visual Basic]

Public Function UseFloatSamples (

bUseFloatSamples as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes UseFloatSamples (

bool bUseFloatSamples

);

[C++]

public: enumErrorCodes UseFloatSamples (

bool bUseFloatSamples

);

Parameter

Description

bUseFloatSamples

Boolean value that specifies if the callback function needs to receive floating samples.

Supported values are the following:

Value | Meaning
false (default) | The callback function will receive original 8 or 16 bits samples
true | 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 Effects.FilterApply method) or the normalization filter (activated through the Effects.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.


DelayedPlaybackMan class

DelayedPlaybackMan class

The DelayedPlaybackMan class, accessible through the control's DelayedPlayback property, 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 DelayedPlaybackMan class is implemented through the following properties and methods:

Properties

AllowOverlapping

Methods

ListAddItem

ListAddItemByDate

ListGetCount

ListRemoveItem

ListRemoveAll

ItemGetDuration

ItemPlayNow

ItemResetDelay

ItemGetRange

ItemSetRange

ItemGetLoopCount

ItemSetLoopCount

ItemGetFadeTime

ItemSetFadeTime


DelayedPlayback.AllowOverlapping property

DelayedPlayback.AllowOverlapping property

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.

Syntax

[Visual Basic]

Public Function get_AllowOverlapping (

) as Boolean

Public Sub set_AllowOverlapping (

bAllowOverlapping as Boolean

)

[C#]

public bool get_AllowOverlapping (

);

public void set_AllowOverlapping (

bool bAllowOverlapping

);

[C++]

public: bool get_AllowOverlapping (

);

public: void set_AllowOverlapping (

bool bAllowOverlapping

);

Parameter

Description

bAllowOverlapping

Mnemonic value | Meaning
false | Overlapping is not allowed
true (default) | Overlapping is allowed

See also

DelayedPlaybackMan class.

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]

Public Function ItemGetDuration (

nFileUniqueID as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemGetDuration (

Int32 nFileUniqueID

);

[C++]

public: enumErrorCodes ItemGetDuration(

Int32 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]

Public Function ItemGetFadeTime (

nFileUniqueID as Int32,

ByRef nFadeInLength as Int32,

ByRef nFadeOutLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemGetFadeTime (

Int32 nFileUniqueID,

ref Int32 nFadeInLength,

ref Int32 nFadeOutLength

);

[C++]

public: enumErrorCodes ItemGetFadeTime (

Int32 nFileUniqueID,

Int32 __gc *nFadeInLength,

Int32 __gc *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]

Public Function ItemGetLoopCount (

nFileUniqueID as Int32,

ByRef nLoopCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemGetLoopCount (

Int32 nFileUniqueID,

ref Int32 nLoopCount

);

[C++]

public: enumErrorCodes ItemGetLoopCount (

Int32 nFileUniqueID,

Int32 __gc *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]

Public Function ItemGetRange (

nFileUniqueID as Int32,

ByRef nStartPos as Int32,

ByRef nEndPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemGetRange (

Int32 nFileUniqueID,

ref Int32 nStartPos,

ref Int32 nEndPos

);

[C++]

public: enumErrorCodes ItemGetRange (

Int32 nFileUniqueID,

Int32 __gc *nStartPos,

Int32 __gc *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]

Public Function ItemPlayNow (

nFileUniqueID as Int32,

bRemoveFromList as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes ItemPlayNow (

Int32 nFileUniqueID,

bool bRemoveFromList

);

[C++]

public: enumErrorCodes ItemPlayNow (

Int32 nFileUniqueID,

bool 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 value | Meaning
false | Item is not removed from the list after starting playback session
true (default) | 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]

Public Function ItemResetDelay (

nFileUniqueID as Int32,

nDelay as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemResetDelay (

Int32 nFileUniqueID,

Int32 nDelay

);

[C++]

public: enumErrorCodes ItemResetDelay (

Int32 nFileUniqueID,

Int32 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]

Public Function ItemSetFadeTime (

nFileUniqueID as Int32,

nFadeInLength as Int32,

nFadeOutLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSetFadeTime (

Int32 nFileUniqueID,

Int32 nFadeInLength,

Int32 nFadeOutLength

);

[C++]

public: enumErrorCodes ItemSetFadeTime (

Int32 nFileUniqueID,

Int32 nFadeInLength,

Int32 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]

Public Function ItemSetLoopCount (

nFileUniqueID as Int32,

nLoopCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSetLoopCount (

Int32 nFileUniqueID,

Int32 nLoopCount

);

[C++]

public: enumErrorCodes ItemSetLoopCount (

Int32 nFileUniqueID,

Int32 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]

Public Function ItemSetRange (

nFileUniqueID as Int32,

nStartPos as Int32,

nEndPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSetRange (

Int32 nFileUniqueID,

Int32 nStartPos,

Int32 nEndPos

);

[C++]

public: enumErrorCodes ItemSetRange (

Int32 nFileUniqueID,

Int32 nStartPos,

Int32 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.

Overload list

Adds a song (item) to the list.

[Visual Basic] Overloads Public Function ListAddItem (Int16, Int32) As Int32

[C#] public Int32 ListAddItem (Int16, Int32);

[C++] public: Int32 ListAddItem (Int16, Int32);

Adds a song (item) to the list.

[Visual Basic] Overloads Public Function ListAddItem (Int16, string, Int32) As Int32

[C#] public Int32 PlayListAddItem (Int16, string, Int32);

[C++] public: Int32 PlayListAddItem (Int16, string, Int32);

Adds a song (item) to the list and predisposes its initial settings.

[Visual Basic] Overloads Public Function PlayListAddItem (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32) As Int32

[C#] public Int32 PlayListAddItem (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32);

[C++] public: Int32 PlayListAddItem (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32);


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.

Overload list

Adds a song (item) to the list.

[Visual Basic] Overloads Public Function ListAddItemByDate (Int16, Int32, Int32, Int32, Int32, Int32, Int32) As Int32

[C#] public Int32 ListAddItemByDate (Int16, Int32, Int32, Int32, Int32, Int32, Int32);

[C++] public: Int32 ListAddItemByDate (Int16, Int32, Int32, Int32, Int32, Int32, Int32);

Adds a song (item) to the list.

[Visual Basic] Overloads Public Function ListAddItemByDate (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32) As Int32

[C#] public Int32 PlayListAddItemByDate (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32);

[C++] public: Int32 PlayListAddItemByDate (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32);

Adds a song (item) to the list and predisposes its initial settings.

[Visual Basic] Overloads Public Function PlayListAddItemByDate (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32, _

Int32, Int32, Int32, Int32, Int32) As Int32

[C#] public Int32 PlayListAddItemByDate (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32,

Int32, Int32, Int32);

[C++] public: Int32 PlayListAddItemByDate (Int16, string, Int32, Int32, Int32, Int32, Int32, Int32, Int32, Int32,


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]

Public Function ListGetCount (

) as enumErrorCodes

[C#]

public enumErrorCodes ListGetCount (

);

[C++]

public: enumErrorCodes 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]

Public Function ListRemoveAll (

) as enumErrorCodes

[C#]

public enumErrorCodes ListRemoveAll (

);

[C++]

public: enumErrorCodes 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]

Public Function ListRemovetem (

nFileUniqueID as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ListRemovetem (

Int32 nFileUniqueID

);

[C++]

public: enumErrorCodes ListRemovetem (

Int32 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)
enumErrorCodes.ERR_NOERROR (0) | The call was successful.


DownloaderDj class

DownloaderDj class

The DownloaderDj class, accessible through the control's Downloader property, allows implementing and managing delayed playback of sound files.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

The DownloaderDj class 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]

Public Sub Create (

nTimeoutConnectionInMs as Int32,

nTimeoutDataInMs as Int32

)

[C#]

public void Create (

Int32 nTimeoutConnectionInMs,

Int32 nTimeoutDataInMs

);

[C++]

public: void Create(

Int32 nTimeoutConnectionInMs,

Int32 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]

Public Sub Destroy (

)

[C#]

public void Destroy (

);

[C++]

public: void 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]

Public Function LastFileExceptionGet (

) as Int16

[C#]

public Int16 LastFileExceptionGet (

);

[C++]

public: Int16 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]

Public Function SessionDataSizeGet (

strURL as String,

strUsername as String,

strPassword as String,

ByRef nDataSize as Int32,

ByRef nSdkError as Int32,

ByRef strExtendedErrorMsg as String

) as enumErrorCodes

[C#]

public enumErrorCodes SessionDataSizeGet (

string strURL,

string strUsername,

string strPassword,

ref Int32 nDataSize,

ref Int32 nSdkError,

ref string strExtendedErrorMsg

);

[C++]

public: enumErrorCodes SessionDataSizeGet(

string strURL,

string strUsername,

string strPassword,

Int32 __gc *nDataSize,

Int32 __gc *nSdkError,

string __gc *strExtendedErrorMsg

);

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 strExtendedErrorMsg parameter.

strExtendedErrorMsg

Reference that, on return from the method call with an error condition and with the value returned inside the nSdkError parameter set to ERROR_INTERNET_EXTENDED_ERROR (12003), will contain the string reporting the extended error message.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details). In case of error the nSdkError and strExtendedErrorMsg parameters may contain further information about the nature of the error.
enumErrorCodes.NOERROR (0) | The method call was successful.


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 allows the container application the be notified about the advancement through the CallbackForDownloaderEvents delegate which is invoked with the nEvent parameter set to one of the following values:

- the EV_DOWNLOADER_SESSION_STARTED event reports that the downloading session is started

- the EV_DOWNLOADER_SESSION_PROGRESS event informs about the download advancement expressed in percentage

- the EV_DOWNLOADER_SESSION_COMPLETED event reports that the downloading session is completed successfully

In case the connection to the remote server or the access to the remote file should fail, the CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_SESSION_FAILED.

In case the connection should be stopped by the user through a call to the Downloader.SessionStop method, the CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_SESSION_STOPPED.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

Public Function SessionStartToFile (

strURL as String,

strUsername as String,

strPassword as String,

strDestinationPath as String,

bDisableCache as Boolean

) as Int32

[C#]

public Int32 SessionStartToFile (

string strURL,

string strUsername,

string strPassword,

string strDestinationPath,

bool bDisableCache

);

[C++]

public: Int32 SessionStartToFile(

string strURL,

string strUsername,

string strPassword,

string strDestinationPath,

bool 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 | Meaning
false | If the file to download is already inside the Internet cache, allows taking the cached file.
true | 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 allows the container application the be notified about the advancement through the CallbackForDownloaderEvents delegate which is invoked with the nEvent parameter set to one of the following values:

- the EV_DOWNLOADER_SESSION_STARTED event reports that the downloading session is started

- the EV_DOWNLOADER_SESSION_PROGRESS event informs about the download advancement expressed in percentage

- the EV_DOWNLOADER_SESSION_COMPLETED event reports that the downloading session is completed successfully

In case the connection to the remote server or the access to the remote file should fail, the CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_SESSION_FAILED.

In case the connection should be stopped by the user through a call to the Downloader.SessionStop method, the CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_SESSION_STOPPED.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

Public Function SessionStartToMemory (

strURL as String,

strUsername as String,

strPassword as String,

pBuffer() as Byte,

nBufferLength as Int32,

bDisableCache as Boolean

) as Int32

[C#]

public Int32 SessionStartToMemory (

string strURL,

string strUsername,

string strPassword,

byte[] pBuffer,

Int32 nBufferLength,

bool bDisableCache

);

[C++]

public: Int32 SessionStartToMemory(

string strURL,

string strUsername,

string strPassword,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

bool 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

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.

nBufferLength

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 | Meaning
false | If the file to download is already inside the Internet cache, allows taking the cached file.
true | 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 allows the container application the be notified about the advancement through the CallbackForDownloaderEvents delegate which is invoked with the nEvent parameter set to one of the following values:

- the EV_DOWNLOADER_SESSION_STARTED event reports that the downloading session is started

- the EV_DOWNLOADER_SESSION_PROGRESS event informs about the download advancement expressed in percentage

- the EV_DOWNLOADER_SESSION_COMPLETED event reports that the downloading session is completed successfully

In case the connection to the remote server or the access to the remote file should fail, the CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_SESSION_FAILED.

In case the remote file should be of an unsupported format and the automatic loading should fail, the CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_INVALID_FILE.

In case the connection should be stopped by the user through a call to the Downloader.SessionStop method, the CallbackForDownloaderEvents delegate is invoked with the nEvent parameter set to EV_DOWNLOADER_SESSION_STOPPED.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

Public Function SessionStartToPlayer (

strURL as String,

strUsername as String,

strPassword as String,

nMediaType as enumMediaTypes,

strDecryptionKey as String,

bDisableCache as Boolean

) as Int32

[C#]

public Int32 SessionStartToPlayer (

string strURL,

string strUsername,

string strPassword,

enumMediaTypes nMediaType,

string strDecryptionKey,

bool bDisableCache

);

[C++]

public: Int32 SessionStartToPlayer(

string strURL,

string strUsername,

string strPassword,

enumMediaTypes nMediaType,

string strDecryptionKey,

bool 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.

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 | Meaning
false | If the file to download is already inside the Internet cache, allows taking the cached file.
true | 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 causes the CallbackForDownloaderEvents delegate to be invoked with the nEvent parameter set to EV_DOWNLOADER_SESSION_STOPPED.

For details about management of download sessions from HTTP and FTP servers, refer to the How to manage download sessions tutorial.

Syntax

[Visual Basic]

Public Function SessionStop (

nDllSessionUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SessionStop (

Int32 nDllSessionUniqueId

);

[C++]

public: enumErrorCodes SessionStop (

Int32 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
Negative value | An error occurred (see the LastError property for further error details).
enumErrorCodes.NOERROR (0) | The method call was successful.


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]

Public Sub SetTimeouts (

nTimeoutConnectionInMs as Int32,

nTimeoutDataInMs as Int32

)

[C#]

public void SetTimeouts (

Int32 nTimeoutConnectionInMs,

Int32 nTimeoutDataInMs

);

[C++]

public: void SetTimeouts(

Int32 nTimeoutConnectionInMs,

Int32 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 Class

Effects Class

The Effects class, accessible through the control's Effects property, 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

DirectXEffectParamsGet

DirectXEffectParamsSet

DirectXEffectParamsGetChorus

DirectXEffectParamsSetChorus

DirectXEffectParamsGetCompressor

DirectXEffectParamsSetCompressor

DirectXEffectParamsGetDistortion

DirectXEffectParamsSetDistortion

DirectXEffectParamsGetEcho

DirectXEffectParamsSetEcho

DirectXEffectParamsGetFlanger

DirectXEffectParamsSetFlanger

DirectXEffectParamsGetGargle

DirectXEffectParamsSetGargle

DirectXEffectParamsGetL2Reverb

DirectXEffectParamsSetL2Reverb

DirectXEffectParamsGetWavesReverb

DirectXEffectParamsSetWavesReverb

DirectXEffectReset

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]

Public Function AutoWahApply (

nPlayerIndex as Int16,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fRate as Single,

fRange as Single,

fFrequency as Single,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes AutoWahApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fRate,

float fRange,

float fFrequency,

Int16 nPriority

);

[C++]

public: enumErrorCodes AutoWahApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fRate,

float fRange,

float fFrequency,

Int16 nPriority

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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]

Public AutoWahIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes AutoWahIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes AutoWahIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The effect has not been applied
true | The effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function AutoWahReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes AutoWahReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes AutoWahReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function BassBoostApply (

nPlayerIndex as Int16,

nFrequencyInHz as Int32,

fBoostLevelIndB as Single,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes BassBoostApply (

Int16 nPlayerIndex,

Int32 nFrequencyInHz,

float fBoostLevelIndB,

Int16 nPriority

);

[C++]

public: enumErrorCodes BassBoostApply (

Int16 nPlayerIndex,

Int32 nFrequencyInHz,

float fBoostLevelIndB,

Int16 nPriority

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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]

Public BassBoostIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes BassBoostIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes BassBoostIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The DSP has not been applied
true | The DSP has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function BassBoostReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes BassBoostReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes BassBoostReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function ChannelsRemapApply (

nPlayerIndex as Int16,

mapChans as Int32,

nChannelsToMap as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ChannelsRemapApply (

Int16 nPlayerIndex,

enumRemapChannels[] mapChans,

Int16 nChannelsToMap

);

[C++]

public: enumErrorCodes ChannelsRemapApply (

Int16 nPlayerIndex,

enumRemapChannels __gc[] mapChans,

Int16 nChannelsToMap

);

Parameter

Description

nPlayerIndex

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

' define the map of channels

Dim mapChannels As enumRemapChannels() = New enumRemapChannels(2){}

mapChannels(0) = enumRemapChannels.REMAP_CHANNEL_1

mapChannels(1) = enumRemapChannels.REMAP_CHANNEL_0

' apply the new map

audioDjStudio1.Effects.ChannelsRemapApply (Player_1, mapChannels, 2)

C#

// define the map of channels

enumRemapChannels[] mapChannels = new enumRemapChannels[2];

mapChannels[0] = enumRemapChannels.REMAP_CHANNEL_1;

mapChannels[1] = enumRemapChannels.REMAP_CHANNEL_0;

// apply the new map

audioDjStudio1.Effects.ChannelsRemapApply (Player_1, mapChannels, 2);

Mixing of left and right stereo channels:

Visual Basic

' define the map of channels

Dim mapChannels As enumRemapChannels() = New enumRemapChannels(2){}

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

audioDjStudio1.Effects.ChannelsRemapApply (Player_1, mapChannels, 2)

C#

// define the map of channels

enumRemapChannels[] mapChannels = new enumRemapChannels[2];

mapChannels[0] = enumRemapChannels.REMAP_CHANNEL_0 | enumRemapChannels.REMAP_CHANNEL_1;

mapChannels[1] = enumRemapChannels.REMAP_CHANNEL_0 | enumRemapChannels.REMAP_CHANNEL_1;

// apply the new map

audioDjStudio1.Effects.ChannelsRemapApply (Player_1, mapChannels, 2);

Muting of left channel:

Visual Basic

' define the map of channels

Dim mapChannels As enumRemapChannels() = New enumRemapChannels(2){}

mapChannels(0) = enumRemapChannels.REMAP_CHANNEL_SILENT

mapChannels(1) = enumRemapChannels.REMAP_CHANNEL_1

' apply the new map

audioDjStudio1.Effects.ChannelsRemapApply (Player_1, mapChannels, 2)

C#

// define the map of channels

enumRemapChannels[] mapChannels = new enumRemapChannels[2];

mapChannels[0] = enumRemapChannels.REMAP_CHANNEL_SILENT;

mapChannels[1] = enumRemapChannels.REMAP_CHANNEL_1;

// apply the new map

audioDjStudio1.Effects.ChannelsRemapApply (Player_1, mapChannels, 2);

Swapping of front and rear channels on a 4 channels song:

Visual Basic

' define the map of channels

Dim mapChannels As enumRemapChannels() = New enumRemapChannels(4){}

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

audioDjStudio1.Effects.ChannelsRemapApply (Player_1, mapChannels, 4)

C#

// define the map of channels

enumRemapChannels[] mapChannels = new enumRemapChannels[4];

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

audioDjStudio1.Effects.ChannelsRemapApply (Player_1, mapChannels, 4);

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.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]

Public ChannelsRemapIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes ChannelsRemapIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes ChannelsRemapIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The effect has not been applied
true | The effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function ChannelsRemapReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ChannelsRemapReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes ChannelsRemapReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function ChorusApply (

nPlayerIndex as Int16,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fMinSweep as Single,

fMaxSweep as Single,

fRate as Single,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ChorusApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fMinSweep,

float fMaxSweep,

float fRate,

Int16 nPriority

);

[C++]

public: enumErrorCodes ChorusApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fMinSweep,

float fMaxSweep,

float fRate,

Int16 nPriority

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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]

Public ChorusIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes ChorusIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes ChorusIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The effect has not been applied
true | The effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function ChorusReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ChorusReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes ChorusReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function CompressorApply (

nPlayerIndex as Int16,

nAffectedChannel as enumChannelMasks,

fGain as Single,

fThreshold as Single,

fRatio as Single,

fAttack as Single,

fRelease as Single,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes CompressorApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fGain,

float fThreshold,

float fRatio,

float fAttack,

float fRelease,

Int16 nPriority

);

[C++]

public: enumErrorCodes CompressorApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fGain,

float fThreshold,

float fRatio,

float fAttack,

float fRelease,

Int16 nPriority

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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]

Public CompressorIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes CompressorIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes CompressorIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The effect has not been applied
true | The effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function CompressorReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes CompressorReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes CompressorReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function DcOffsetRemovalEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DcOffsetRemovalEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes DcOffsetRemovalEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Disables DC Offset removal
true | Enables DC Offset removal

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.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]

Public Function DcOffsetRemovalIsEnabled (

nPlayerIndex as Int16,

ByRef bEnabled as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DcOffsetRemovalIsEnabled (

Int16 nPlayerInde,

ref bool bEnabled

);

[C++]

public: enumErrorCodes DcOffsetRemovalIsEnabled (

Int16 nPlayerInde,

bool __gc *bEnabled

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Real-time DC offset removal is not enabled
true | 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.NOERROR (0) | The method 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public DirectXEffectApply (

nPlayerIndex as Int16,

nEffect as enumDirectXEffects,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectApply (

Int16 nPlayerIndex,

enumDirectXEffects nEffect,

Int16 nPriority

);

[C++]

public: enumErrorCodes DirectXEffectApply (

Int16 nPlayerIndex,

enumDirectXEffects nEffect,

Int16 nPriority

);

Parameter

Description

nPlayerIndex

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 value | 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 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.

This parameter is ignored when the bSet parameter is set to "false".

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.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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public DirectXEffectIsApplied (

nPlayerIndex as integer,

nEffect as enumDirectXEffects,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectIsApplied (

short nPlayerIndex,

enumDirectXEffects nEffect,

ref bool bApplied

);

[C++]

public: enumErrorCodes DirectXEffectIsApplied (

short nPlayerIndex,

enumDirectXEffects nEffect,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The given effect has not been applied
true | The given effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Overload list

Retrieves parameters for the Chorus effect

[Visual Basic] Overloads Public Function DirectXEffectParamsGet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsChorus) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsGet (Int16, ref Microsoft.DirectX.DirectSound.EffectsChorus);

[C++] public: enumErrorCodes DirectXEffectParamsGet (Int16, Microsoft::DirectX::DirectSound::EffectsChorus __gc *);

Retrieves parameters for the Compressor effect

[Visual Basic] Overloads Public Function DirectXEffectParamsGet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsCompressor) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsGet (Int16, ref Microsoft.DirectX.DirectSound.EffectsCompressor);

[C++] public: enumErrorCodes DirectXEffectParamsGet (Int16, Microsoft::DirectX::DirectSound::EffectsCompressor __gc *);

Retrieves parameters for the Distortion effect

[Visual Basic] Overloads Public Function DirectXEffectParamsGet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsDistortion) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsGet (Int16, ref Microsoft.DirectX.DirectSound.EffectsDistortion);

[C++] public: enumErrorCodes DirectXEffectParamsGet (Int16, Microsoft::DirectX::DirectSound::EffectsDistortion __gc *);

Retrieves parameters for the Echo effect

[Visual Basic] Overloads Public Function DirectXEffectParamsGet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsEcho) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsGet (Int16, ref Microsoft.DirectX.DirectSound.EffectsEcho);

[C++] public: enumErrorCodes DirectXEffectParamsGet (Int16, Microsoft::DirectX::DirectSound::EffectsEcho __gc *);

Retrieves parameters for the Flanger effect

[Visual Basic] Overloads Public Function DirectXEffectParamsGet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsFlanger) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsGet (Int16, ref Microsoft.DirectX.DirectSound.EffectsFlanger);

[C++] public: enumErrorCodes DirectXEffectParamsGet (Int16, Microsoft::DirectX::DirectSound::EffectsFlanger __gc *);

Retrieves parameters for the Gargle effect

[Visual Basic] Overloads Public Function DirectXEffectParamsGet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsGargle) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsGet (Int16, ref Microsoft.DirectX.DirectSound.EffectsGargle);

[C++] public: enumErrorCodes DirectXEffectParamsGet (Int16, Microsoft::DirectX::DirectSound::EffectsGargle __gc *);

Retrieves parameters for the Interactive 3D Level 2 Reverb effect

[Visual Basic] Overloads Public Function DirectXEffectParamsGet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsGet (Int16, ref Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb);

[C++] public: enumErrorCodes DirectXEffectParamsGet (Int16, Microsoft::DirectX::DirectSound::EffectsInteractive3DLevel2Reverb __gc *);

Retrieves parameters for the Waves Reverb effect

[Visual Basic] Overloads Public Function DirectXEffectParamsGet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsWavesReverb) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsGet (Int16, ref Microsoft.DirectX.DirectSound.EffectsWavesReverb);

[C++] public: enumErrorCodes DirectXEffectParamsGet (Int16, Microsoft::DirectX::DirectSound::EffectsWavesReverb __gc *);


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.

Overload list

Sets parameters for the Chorus effect

[Visual Basic] Overloads Public Function DirectXEffectParamsSet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsChorus) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsSet (Int16, ref Microsoft.DirectX.DirectSound.EffectsChorus);

[C++] public: enumErrorCodes DirectXEffectParamsSet (Int16, Microsoft::DirectX::DirectSound::EffectsChorus __gc *);

Sets parameters for the Compressor effect

[Visual Basic] Overloads Public Function DirectXEffectParamsSet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsCompressor) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsSet (Int16, ref Microsoft.DirectX.DirectSound.EffectsCompressor);

[C++] public: enumErrorCodes DirectXEffectParamsSet (Int16, Microsoft::DirectX::DirectSound::EffectsCompressor __gc *);

Sets parameters for the Distortion effect

[Visual Basic] Overloads Public Function DirectXEffectParamsSet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsDistortion) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsSet (Int16, ref Microsoft.DirectX.DirectSound.EffectsDistortion);

[C++] public: enumErrorCodes DirectXEffectParamsSet (Int16, Microsoft::DirectX::DirectSound::EffectsDistortion __gc *);

Sets parameters for the Echo effect

[Visual Basic] Overloads Public Function DirectXEffectParamsSet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsEcho) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsSet (Int16, ref Microsoft.DirectX.DirectSound.EffectsEcho);

[C++] public: enumErrorCodes DirectXEffectParamsSet (Int16, Microsoft::DirectX::DirectSound::EffectsEcho __gc *);

Sets parameters for the Flanger effect

[Visual Basic] Overloads Public Function DirectXEffectParamsSet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsFlanger) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsSet (Int16, ref Microsoft.DirectX.DirectSound.EffectsFlanger);

[C++] public: enumErrorCodes DirectXEffectParamsSet (Int16, Microsoft::DirectX::DirectSound::EffectsFlanger __gc *);

Sets parameters for the Gargle effect

[Visual Basic] Overloads Public Function DirectXEffectParamsSet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsGargle) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsSet (Int16, ref Microsoft.DirectX.DirectSound.EffectsGargle);

[C++] public: enumErrorCodes DirectXEffectParamsSet (Int16, Microsoft::DirectX::DirectSound::EffectsGargle __gc *);

Sets parameters for the Interactive 3D Level 2 Reverb effect

[Visual Basic] Overloads Public Function DirectXEffectParamsSet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsSet (Int16, ref Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb);

[C++] public: enumErrorCodes DirectXEffectParamsSet (Int16, Microsoft::DirectX::DirectSound::EffectsInteractive3DLevel2Reverb __gc *);

Sets parameters for the Waves Reverb effect

[Visual Basic] Overloads Public Function DirectXEffectParamsSet (Int16, ByRef Microsoft.DirectX.DirectSound.EffectsWavesReverb) As enumErrorCodes

[C#] public enumErrorCodes DirectXEffectParamsSet (Int16, ref Microsoft.DirectX.DirectSound.EffectsWavesReverb);

[C++] public: enumErrorCodes DirectXEffectParamsSet (Int16, Microsoft::DirectX::DirectSound::EffectsWavesReverb __gc *);


Effects.DirectXEffectParamsGetChorus method

Effects.DirectXEffectParamsGetChorus method

Remarks

Retrieves parameters related to the Chorus effect. These parameters can be changed using the Effects.DirectXEffectParamsSetChorus method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGetChorus (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsChorus

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGetChorus (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsChorus fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGetChorus (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsChorus __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSetChorus 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.


Effects.DirectXEffectParamsSetChorus method

Effects.DirectXEffectParamsSetChorus method

Remarks

Sets parameters related to the Chorus effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGetChorus method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSetChorus (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsChorus

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSetChorus (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsChorus fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSetChorus (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsChorus __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
Delay | Retrieves and sets the number of milliseconds the input is delayed before it is played back. Can range from ChorusEffect.DelayMin to ChorusEffect.DelayMax. The default value is 16 ms.
Depth | Retrieves and sets the percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Can range from ChorusEffect.DepthMin to ChorusEffect.DepthMax. The default value is 10.
Feedback | Retrieves and sets the percentage of output signal to feed back into the effect's input. Can range from ChorusEffect.FeedbackMin to ChorusEffect.FeedbackMax. The default value is 25.
Frequency | Retrieves and sets the frequency of the LFO Can range from ChorusEffect.FrequencyMin to ChorusEffect.FrequencyMax. The default value is 1.1.
Phase | Retrieves and sets the phase differential between left and right LFOs Can range from ChorusEffect.PhaseMin to ChorusEffect.PhaseMax. Can be set by the one values below: - ChorusEffect.PhaseZero - ChorusEffect.Phase90 - ChorusEffect.PhaseNegative90 - ChorusEffect.Phase180 - ChorusEffect.PhaseNegative180 The default value is ChorusEffect.Phase90.
Waveform | Retrieves and sets the waveform shape of the LFO Can be set by the one values below: - ChorusEffect.WaveSin - ChorusEffect.WaveTrianlge The default value is ChorusEffect.WaveSin.
WetDryMix | Retrieves and sets the ratio of wet (processed) signal to dry (unprocessed) signal Can range from ChorusEffect.WetDryMixMin to ChorusEffect.WetDryMixMax. The default value is 50.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.DirectXEffectParamsGetCompressor method

Effects.DirectXEffectParamsGetCompressor method

Remarks

Retrieves parameters related to the Compressor effect. These parameters can be changed using the Effects.DirectXEffectParamsSetCompressor method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGetCompressor (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsCompressor

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGetCompressor (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsCompressor fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGetCompressor (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsCompressor __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSetCompressor 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.


Effects.DirectXEffectParamsSetCompressor method

Effects.DirectXEffectParamsSetCompressor method

Remarks

Sets parameters related to the Compressor effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGetCompressor method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSetCompressor (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsCompressor

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSetCompressor (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsCompressor fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSetCompressor (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsCompressor __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Effect structure containing parameters to apply.

Property | Meaning
Attack | Retrieves and sets the time before compression reaches its full value. Can range from CompressorEffect.AttackMin to CompressorEffect.AttackMax. The default value is 10 ms.
Gain | Retrieves and sets the output gain of signal after compression. Can range from CompressorEffect.GainMin to CompressorEffect.GainMax. The default value is 0 dB.
Predelay | Retrieves and sets the time after Threshold is reached before attack phase is started, in milliseconds. Can range from CompressorEffect.PredelayMin to CompressorEffect.PredelayMax. The default value is 4 ms.
Ratio | Retrieves and sets the compression ratio. Can range from CompressorEffect.RatioMin to CompressorEffect.RatioMax. The default value is 3, which means 3:1 compression.
Release | Retrieves and sets the speed at which compression is stopped after input drops below Threshold. Can range from CompressorEffect.ReleaseMin to CompressorEffect.ReleaseMax. The default value is 200 ms.
Threshold | Retrieves and sets the point at which compression begins. Can range from CompressorEffect.ThresholdMin to CompressorEffect.ThresholdMax. The default value is -20 dB.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.DirectXEffectParamsGetDistortion method

Effects.DirectXEffectParamsGetDistortion method

Remarks

Retrieves parameters related to the Distortion effect. These parameters can be changed using the Effects.DirectXEffectParamsSetDistortionù method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGetDistortion (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsDistortion

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGetDistortion (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsDistortion fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGetDistortion (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsDistortion __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSetDistortionù 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.


Effects.DirectXEffectParamsSetDistortion method

Effects.DirectXEffectParamsSetDistortion method

Remarks

Sets parameters related to the Distortion effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGetDistortion method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSetDistortion (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsDistortion

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSetDistortion (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsDistortion fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSetDistortion (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsDistortion __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
Edge | Retrieves and sets the percentage of distortion intensity, in the EffectsDistortion structure. Can range from DistortionEffect.EdgeMin to DistortionEffect.EdgeMax. The default value is 15.
Gain | Retrieves and sets the amount of signal change after distortion, in the EffectsDistortion structure. Can range from DistortionEffect.GainMin to DistortionEffect.GainMax. The default value is -18 dB.
PostEqBandwidth | Retrieves and sets the width of frequency band that determines range of harmonic content addition, in the EffectsDistortion structure. Can range from DistortionEffect.PostEqBandwidthMin to DistortionEffect.PostEqBandwidthMax. The default value is 2400Hz.
PostEqCenterFrequency | Retrieves and sets the center frequency of harmonic content addition, in the EffectsDistortion structure. Can range from DistortionEffect.PostEqCenterFrequencyMin to DistortionEffect.PostEqCenterFrequency. The default value is 2400 Hz.
PreLowpassCutoff | Retrieves and sets the filter cutoff for high-frequency harmonics attenuation, in the EffectsDistortion structure. Can range from DistortionEffect.PreLowpassCutoffMin to DistortionEffect.PreLowpassCutoffMax. The default value is 15.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.DirectXEffectParamsGetEcho method

Effects.DirectXEffectParamsGetEcho method

Remarks

Retrieves parameters related to the Echo effect. These parameters can be changed using the Effects.DirectXEffectParamsSetEcho method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGetEcho (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsEcho

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGetEcho (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsEcho fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGetEcho (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsEcho __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSetEcho 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.


Effects.DirectXEffectParamsSetEcho method

Effects.DirectXEffectParamsSetEcho method

Remarks

Sets parameters related to the Echo effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGetEcho method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSetEcho (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsEcho

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSetEcho (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsEcho fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSetEcho (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsEcho __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
Feedback | Retrieves and sets the percentage of output fed back into input. Can range from EchoEffect.FeedbackMin to EchoEffect.FeedbackMax. The default value is 50.
LeftDelay | Retrieves and sets the delay for left channel, in milliseconds. Can range from EchoEffect.LefttDelayMin to EchoEffect.LeftDelayMax. The default value is 500 ms.
PanDelay | Retrieves and sets the value that specifies whether to swap left and right delays with each successive echo. Can range from EchoEffect.PanDelayMin to EchoEffect.PanDelayMax. The default value is zero, meaning no swap.
RightDelay | Retrieves and sets the delay for right channel, in milliseconds. Can range from EchoEffect.RightDelayMin to EchoEffect.RightDelayMax. The default value is 500 ms.
WetDryMix | Retrieves and sets the ratio of wet (processed) signal to dry (unprocessed) signal. Can range from EchoEffect.WetDryMixMin to EchoEffect.WetDryMixMax.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.DirectXEffectParamsGetFlanger method

Effects.DirectXEffectParamsGetFlanger method

Remarks

Retrieves parameters related to the Flanger effect. These parameters can be changed using the Effects.DirectXEffectParamsSetFlanger method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGetFlanger (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsFlanger

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGetFlanger (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsFlanger fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGetFlanger (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsFlanger __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSetFlanger 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.


Effects.DirectXEffectParamsSetFlanger method

Effects.DirectXEffectParamsSetFlanger method

Remarks

Sets parameters related to the Flanger effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGetFlanger method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSetFlanger (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsFlanger

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSetFlanger (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsFlanger fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSetFlanger (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsFlanger __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
Delay | Retrieves and sets the number of milliseconds the input is delayed before it is played back. Can range from FlangerEffect.DelayMin to FlangerEffect.DelayMax. The default value is 2ms.
Depth | Retrieves and sets the percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Can range from FlangerEffect.DepthMin to FlangerEffect.DepthMax. The default value is 100.
Feedback | Retrieves and sets the percentage of output signal to feed back into the effect's input. Can range from FlangerEffect.FeedbackMin to FlangerEffect.FeedbackMax. The default value is -50.
Frequency | Retrieves and sets the frequency of the LFO. Can range from FlangerEffect.FrequencyMin to FlangerEffect.FrequencyMax. The default value is 0.
Phase | Retrieves and sets the phase differential between left and right LFOs. Can be set to on of the following: - FlangerEffect.PhaseNeg180 - FlangerEffect.PhaseNeg90 - FlangerEffect.PhaseZero - FlangerEffect.Phase90 - FlangerEffect.Phase180
Waveform | Retrieves and sets the waveform shape of the LFO. Can be set to on of the following: - FlangerEffect.WaveSine (default) - FlangerEffect.WaveTriangle
WetDryMix | Retrieves and sets the ratio of wet (processed) signal to dry (unprocessed) signal. Can range from FlangerEffect.WetDryMixMin to FlangerEffect.WetDryMixMax. The default value is 50.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.DirectXEffectParamsGetGargle method

Effects.DirectXEffectParamsGetGargle method

Remarks

Retrieves parameters related to the Gargle effect. These parameters can be changed using the Effects.DirectXEffectParamsSetGargle method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGetGargle (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsGargle

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGetGargle (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsGargle fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGetGargle (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsGargle __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSetGargle 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.


Effects.DirectXEffectParamsSetGargle method

Effects.DirectXEffectParamsSetGargle method

Remarks

Sets parameters related to the Gargle effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGetGargle method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSetGargle (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsGargle

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSetGargle (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsGargle fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSetGargle (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsGargle __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
RateHz | Retrieves and sets the rate of modulation expressed in Hertz. Can range from GargleEffect.RateHzMin to GargleEffect.RateHzMax. The default value is 20.
WaveShape | Retrieves and sets the shape of the modulation waveform. Can be set to one of the following: - GargleEffect.WaveTriangle (default) - GargleEffect.WaveSquare

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.DirectXEffectParamsGetL2Reverb method

Effects.DirectXEffectParamsGetL2Reverb method

Remarks

Retrieves parameters related to the Interactive 3D Level 2 Reverb effect. These parameters can be changed using the Effects.DirectXEffectParamsSetL2Reverb method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGetL2Reverb (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGetL2Reverb (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGetL2Reverb (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsInteractive3DLevel2Reverb __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSetL2Reverb 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.


Effects.DirectXEffectParamsSetL2Reverb method

Effects.DirectXEffectParamsSetL2Reverb method

Remarks

Sets parameters related to the Interactive 3D Level 2 Reverb effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGetL2Reverb method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSetL2Reverb (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSetL2Reverb (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSetL2Reverb (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsInteractive3DLevel2Reverb __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property

Meaning

DecayHfRatio

Retrieves and sets the ratio of the decay time at high frequencies to the decay time at low frequencies.

Can range from Interactive3DLevel2ReverbEffect.DecayHfRatioMin to Interactive3DLevel2ReverbEffect.DecayHfRatioMax.

The default value is Interactive3DLevel2ReverbEffect.DecayHfRatioDefault or 0.83.

DecayTime

Retrieves and sets the decay time expressed in seconds.

Can range from Interactive3DLevel2ReverbEffect.DecayTimeMin to Interactive3DLevel2ReverbEffect.DecayTimeMax.

The default value is Interactive3DLevel2ReverbEffect.DecayTimeDefault or 1.49 seconds.

Density

Retrieves and sets the modal density in the late reverberation decay expressed in percent.

Can range from Interactive3DLevel2ReverbEffect.DensityMin to Interactive3DLevel2ReverbEffect.DensityMax.

The default value is Interactive3DLevel2ReverbEffect.DensityDefault or 100 percent.

Diffusion

Retrieves and sets the echo density in the late reverberation decay expressed in percent.

Can range from Interactive3DLevel2ReverbEffect.DiffusionyMin to Interactive3DLevel2ReverbEffect.DiffusionMax.

The default value is Interactive3DLevel2ReverbEffect.DiffusionDefault or 100 percent.

HfReference

Retrieves and sets the reference high frequency expressed in hertz.

Can range from Interactive3DLevel2ReverbEffect.HfReferenceyMin to Interactive3DLevel2ReverbEffect.HfReferenceMax.

The default value is Interactive3DLevel2ReverbEffect.HfReferenceDefault or 5000.0 Hz.

Reflections

Retrieves and sets the attenuation of early reflections relative to Room expressed in millibels (mB).

Can range from Interactive3DLevel2ReverbEffect.ReflectionsMin to Interactive3DLevel2ReverbEffect.ReflectionsMax.

The default value is Interactive3DLevel2ReverbEffect.ReflectionsDefault or -2602 mB.

ReflectionsDelay

Retrieves and sets the delay time of the first reflection relative to the direct path expressed in seconds.

Can range from Interactive3DLevel2ReverbEffect.ReflectionsDelayMin to Interactive3DLevel2ReverbEffect.ReflectionsDelayMax.

The default value is Interactive3DLevel2ReverbEffect.ReflectionsDelayDefault or 0.007 seconds.

Reverb

Retrieves and sets the attenuation of late reverberation relative to Room expressed in millibels (mB).

Can range from Interactive3DLevel2ReverbEffect.ReverbMin to Interactive3DLevel2ReverbEffect.ReverbMax.

The default value is Interactive3DLevel2ReverbEffect.ReverbDefault or -200 mB.

ReverbDelay

Retrieves and sets the time limit between the early reflections and the late reverberation relative to the time of the first reflection expressed in seconds.

Can range from Interactive3DLevel2ReverbEffect.ReverbDelayMin to Interactive3DLevel2ReverbEffect.ReverbDelayMax.

The default value is Interactive3DLevel2ReverbEffect.ReverbDelayDefault or 0.011 seconds.

Room

Retrieves and sets the attenuation of the room effect expressed in millibels (mB).

Can range from Interactive3DLevel2ReverbEffect.RoomMin to Interactive3DLevel2ReverbEffect.RoomMax.

The default value is Interactive3DLevel2ReverbEffect.RoomDefault or -1000 mB.

RoomHf

Retrieves and sets the attenuation of the room high-frequency effect expressed in millibels (mB).

Can range from Interactive3DLevel2ReverbEffect.RoomHfMin to Interactive3DLevel2ReverbEffect.RoomHfMax.

The default value is Interactive3DLevel2ReverbEffect.RoomHfDefault or -100 mB.

RoomRolloffFactor

Retrieves and sets the rolloff factor for the reflected signals.

Can range from Interactive3DLevel2ReverbEffect.RoomRolloffFactorMin to Interactive3DLevel2ReverbEffect.RoomRolloffFactorMax.

The default value is Interactive3DLevel2ReverbEffect.RoomRolloffFactorDefault or 0.0.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


Effects.DirectXEffectParamsGetWavesReverb method

Effects.DirectXEffectParamsGetWavesReverb method

Remarks

Retrieves parameters related to the Waves Reverb effect. These parameters can be changed using the Effects.DirectXEffectParamsSetWavesReverb method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGetWavesReverb (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsWavesReverb

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGetWavesReverb (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsWavesReverb fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGetWavesReverb (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsWavesReverb __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSetWavesReverb 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.


Effects.DirectXEffectParamsSetWavesReverb method

Effects.DirectXEffectParamsSetWavesReverb method

Remarks

Sets parameters related to the Waves Reverb effect. The current parameters for the chosen effect can be retrieved using the Effects.DirectXEffectParamsGetWavesReverb method.

DirectX effects requires the availability of DirectX version 8 or higher on the target system and can be applied only if the IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSetWavesReverb (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsWavesReverb

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSetWavesReverb (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsWavesReverb fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSetWavesReverb (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsWavesReverb __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
HighFrequencyRtRatio | Retrieves and sets the high-frequency reverb time ratio. Can range from WavesReverbEffect.HighFrequencyRtRationMin to WavesReverbEffect.HighFrequencyRtRationMax. The default value is 0.001 or WavesReverbEffect.HighFrequencyRtRationDefault.
InGain | Retrieves and sets the input gain of signal expressed in decibels (dB). Can range from WavesReverbEffect.InGainMin to WavesReverbEffect.InGainMax. The default value is 0 db or WavesReverbEffect.InGainDefault.
ReverbMix | Retrieves and sets the reverb mix expressed in decibels (dB). Can range from WavesReverbEffect.ReverbMixMin to WavesReverbEffect.ReverbMixMax. The default value is 0 db or WavesReverbEffect.ReverbMixDefault.
ReverbTime | Retrieves and sets the reverb time expressed in milliseconds. Can range from WavesReverbEffect.ReverbTimeMin to WavesReverbEffect.ReverbTimeMax. The default value is 1000 ms or WavesReverbEffect.ReverbTimeDefault.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


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]

Public DirectXEffectReset (

nPlayerIndex as Int16,

nEffect as enumDirectXEffects

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectReset (

Int16 nPlayerIndex,

enumDirectXEffects nEffect

);

[C++]

public: enumErrorCodes DirectXEffectReset (

Int16 nPlayerIndex,

enumDirectXEffects nEffect

);

Parameter

Description

nPlayerIndex

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 value | 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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


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]

Public Function DistortionApply (

nPlayerIndex as Int16,

nAffectedChannel as enumChannelMasks,

fDrive as Single,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fVolume as Single,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DistortionApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDrive,

float fDryMix,

float fWetMix,

float fFeedback,

float fVolume,

Int16 nPriority

);

[C++]

public: enumErrorCodes DistortionApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDrive,

float fDryMix,

float fWetMix,

float fFeedback,

float fVolume,

Int16 nPriority

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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]

Public DistortionIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DistortionIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes DistortionIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The effect has not been applied
true | The effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function DistortionReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes DistortionReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes DistortionReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function EchoApply (

nPlayerIndex as Int16,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fDelay as Single,

bStereo as Boolean,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes EchoApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fDelay,

bool bStereo,

Int16 nPriority

);

[C++]

public: enumErrorCodes EchoApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fDelay,

bool bStereo,

Int16 nPriority

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | Affect single channels only
true | 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.NOERROR (0) | The method 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]

Public EchoIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EchoIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes EchoIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The effect has not been applied
true | The effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function EchoReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes EchoReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes EchoReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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.

Syntax

[Visual Basic]

Public Function EqualizerBandAdd (

nPlayerIndex as Int16,

fFrequency As Single,

fBandWidth As Single,

fGain As Single

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerBandAdd (

Int16 nPlayerIndex,

float fFrequency,

float fBandWidth,

float fGain

);

[C++]

public: enumErrorCodes EqualizerBandAdd (

Int16 nPlayerIndex,

float fFrequency,

float fBandWidth,

float fGain

);

Parameter

Description

nPlayerIndex

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]

Public Function EqualizerBandCountGet (

nPlayerIndex as Int16,

ByRef nCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerBandCountGet (

Int16 nPlayerIndex,

ref Int16 nCount

);

[C++]

public: enumErrorCodes EqualizerBandCountGet (

Int16 nPlayerIndex,

Int16 __gc *nCount

);

Parameter | Description
nPlayerIndex | 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.

Syntax

[Visual Basic]

Public Function EqualizerBandFrequencyGet (

nPlayerIndex as Int16,

nIndex as Int32,

ByRef fFrequency As Single

) As enumErrorCodes

[C#]

public enumErrorCodes EqualizerBandFrequencyGet (

Int16 nPlayerIndex,

Int32 nIndex,

ref float fFrequency

);

[C++]

public: enumErrorCodes EqualizerBandFrequencyGet (

Int16 nPlayerIndex,

Int32 nIndex,

float __gc *fFrequency

);

Parameter | Description
nPlayerIndex | 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.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.

Syntax

[Visual Basic]

Public Function EqualizerBandParamsGet (

nPlayerIndex as Int16,

fFrequency As Single,

ByRef fBandWidth As Single,

ByRef fGain As Single

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerBandParamsGet (

Int16 nPlayerIndex,

float fFrequency,

ref float fBandWidth,

ref float fGain

);

[C++]

public: enumErrorCodes EqualizerBandParamsGet (

Int16 nPlayerIndex,

float fFrequency,

float __gc *fBandWidth,

float __gc *fGain

);

Parameter | Description
nPlayerIndex | 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.

Syntax

[Visual Basic]

Public Function EqualizerBandParamsSet (

nPlayerIndex as Int16,

fFrequency As Single,

fBandWidth As Single,

fGain As Single

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerBandParamsSet (

Int16 nPlayerIndex,

float fFrequency,

float fBandWidth,

float fGain

);

[C++]

public: enumErrorCodes EqualizerBandParamsSet (

Int16 nPlayerIndex,

float fFrequency,

float fBandWidth,

float fGain

);

Parameter | Description
nPlayerIndex | 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.

Syntax

[Visual Basic]

Public Function EqualizerBandRemove (

nPlayerIndex as Int16,

fFrequency As Single

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerBandRemove (

Int16 nPlayerIndex,

float fFrequency

);

[C++]

public: enumErrorCodes EqualizerBandRemove (

Int16 nPlayerIndex,

float fFrequency

);

Parameter | Description
nPlayerIndex | 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.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.

Syntax

[Visual Basic]

Public Function EqualizerBandGainSet (

nPlayerIndex as Int16,

fFrequency As Single,

fGain as float

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerBandGainSet (

Int16 nPlayerIndex,

float fFrequency,

float fGain

);

[C++]

public: enumErrorCodes EqualizerBandGainSet (

Int16 nPlayerIndex,

float fFrequency,

float fGain

);

Parameter | Description
nPlayerIndex | 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.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.

Syntax

[Visual Basic]

Public Function EqualizerEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes EqualizerEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Disable the equalizer
true | 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]

Public Function EqualizerIsEnabled (

nPlayerIndex as Int16,

ByRef bEnabled as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerIsEnabled (

Int16 nPlayerInde,

ref bool bEnabled

);

[C++]

public: enumErrorCodes EqualizerIsEnabled (

Int16 nPlayerInde,

bool __gc *bEnabled

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Equalizer is not enabled
true | Equalizer 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.


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 EqualizerSaveToFile method.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

Syntax

[Visual Basic]

Public Function EqualizerLoadFromFile (

nPlayerIndex as Int16,

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerLoadFromFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes EqualizerLoadFromFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
strPathname | 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.EqualizerLoadFromMemoryStream method

Effects.EqualizerLoadFromMemoryStream method

Remarks

Loads new equalizer's settings from a memory stream containing the needed XML code into the given player. Existing equalizer's settings can be saved inside a memory stream through the EqualizerSaveToMemoryStream method.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

Syntax

[Visual Basic]

Public Function EqualizerLoadFromMemoryStream (

nPlayerIndex as Int16,

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerLoadFromMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

[C++]

public: enumErrorCodes EqualizerLoadFromMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
ms | Memory stream containing equalizer's settings in XML format

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.

Syntax

[Visual Basic]

Public Function EqualizerLoadPresets (

nPlayerIndex as Int16,

nPreset as enumEqualizerPresets

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerLoadPresets (

Int16 nPlayerIndex,

enumEqualizerPresets nPreset

);

[C++]

public: enumErrorCodes EqualizerLoadPresets (

Int16 nPlayerIndex,

enumEqualizerPresets nPreset

);

Parameter

Description

nPlayerIndex

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 EqualizerEnable method with bEnable parameter set to "false".

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

Syntax

[Visual Basic]

Public Function EqualizerReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes EqualizerReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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 EqualizerLoadFromFile method.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

Syntax

[Visual Basic]

Public Function EqualizerSaveToFile (

nPlayerIndex as Int16,

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerSaveToFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes EqualizerSaveToFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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.EqualizerSaveToMemoryStream method

Effects.EqualizerSaveToMemoryStream method

Remarks

Saves existing equalizer's settings into a memory stream in XML format. These equalizer's settings can be loaded at a later time through the EqualizerLoadFromMemoryStream method.

For further details about defining the equalizer settings refer to the How to create and use an Equalizer section.

Syntax

[Visual Basic]

Public Function EqualizerSaveToMemoryStream (

nPlayerIndex as Int16,

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes EqualizerSaveToMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

[C++]

public: enumErrorCodes EqualizerSaveToMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
ms | Memory stream for storing equalizer's settings in XML format

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 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]

Public Function FilterApply (

nPlayerIndex as Int16,

nFilterName as enumFilterNames,

nFilterType as enumFilterTypes,

fFrequency1 as Single,

fFrequency2 as Single,

fGain as Single,

fTransitionTime as Single

) as enumErrorCodes

[C#]

public enumErrorCodes FilterApply (

Int16 nPlayerIndex,

enumFilterNames nFilterName,

enumFilterTypes nFilterType,

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

[C++]

public: enumErrorCodes FilterApply (

Int16 nPlayerIndex,

enumFilterNames nFilterName,

enumFilterTypes nFilterType,

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

Parameter

Description

nPlayerIndex

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 nFrequency field of the SoundInfo2 class (requires calling the SoundInfoGet 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 nFrequency field of the SoundInfo2 class (requires calling the SoundInfoGet 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.NOERROR (0) | The method 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]

Public FilterIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes FilterIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes FilterIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The filter has not been applied
true | The filter has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


Effects.FilterReset method

Effects.FilterReset method

Remarks

Resets a filter previously set through a previous call to the FilterApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function FilterReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FilterReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes FilterReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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 FilterVocalRemoverReset 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]

Public Function FilterVocalRemoverApply (

nPlayerIndex as Int16,

nVoiceAttenuation as Int32,

nSoundGain as Int32,

nCutoffFrequency as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FilterVocalRemoverApply (

Int16 nPlayerIndex,

int nVoiceAttenuation,

int nSoundGain,

int nCutoffFrequency

);

[C++]

public: enumErrorCodes FilterVocalRemoverApply (

Int16 nPlayerIndex,

int nVoiceAttenuation,

int nSoundGain,

int nCutoffFrequency

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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]

Public FilterVocalRemoverIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes FilterVocalRemoverIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes FilterVocalRemoverIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The filter has not been applied
true | The filter has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


Effects.FilterVocalRemoverReset method

Effects.FilterVocalRemoverReset method

Remarks

Resets the vocal remover filter previously set through a call to the FilterVocalRemoverApply method on the given player.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function FilterVocalRemoverReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FilterVocalRemoverReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes FilterVocalRemoverReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


Effects.FreeverbApply method

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]

Public Function FreeverbApply (

nPlayerIndex as Int16,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fRoomSize as Single,

fDamp as Single,

fWidth as Single,

nReserved as Int32,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FreeverbApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fRoomSize,

float fDamp,

float fWidth,

Int32 nReserved,

Int16 nPriority

);

[C++]

public: enumErrorCodes FreeverbApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fRoomSize,

float fDamp,

float fWidth,

Int32 nReserved,

Int16 nPriority

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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]

Public FreeverbIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes FreeverbIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes FreeverbIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The effect has not been applied
true | The effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function FreeverbReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FreeverbReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes FreeverbReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function MPXEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MPXEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes MPXEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | MPX DSP is disabled
true | MPX DSP 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.


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]

Public Function MPXInvertChannels (

nPlayerIndex as Int16,

bInvertChannels as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MPXInvertChannels (

Int16 nPlayerIndex,

bool bInvertChannels

);

[C++]

public: enumErrorCodes MPXInvertChannels (

Int16 nPlayerIndex,

bool bInvertChannels

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | MPX channels are not inverted
true | 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.NOERROR (0) | The method 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]

Public Function MPXIsEnabled (

nPlayerIndex as Int16,

ByRef bEnabled as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MPXIsEnabled (

Int16 nPlayerInde,

ref bool bEnabled

);

[C++]

public: enumErrorCodes MPXIsEnabled (

Int16 nPlayerInde,

bool __gc *bEnabled

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The MPX DSP effect is not enabled
true | The MPX DSP effect 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.


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]

Public Function MPXSetVocalAttenuation (

nPlayerIndex as Int16,

nAttenuation as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes MPXSetVocalAttenuation (

Int16 nPlayerIndex,

Int16 nAttenuation

);

[C++]

public: enumErrorCodes MPXSetVocalAttenuation (

Int16 nPlayerIndex,

Int16 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.NOERROR (0) | The method 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]

Public Function NormalizationEnable (

nPlayerIndex as Int16,

bEnable as Boolean,

fTargetLevelPerc as Single,

fBelowLevelPerc as Single,

fAboveLevelPerc as Single

) as enumErrorCodes

[C#]

public enumErrorCodes NormalizationEnable (

Int16 nPlayerIndex,

bool bEnable,

float fTargetLevelPerc,

float fBelowLevelPerc,

float fAboveLevelPerc

);

[C++]

public: enumErrorCodes NormalizationEnable (

Int16 nPlayerIndex,

bool bEnable,

float fTargetLevelPerc,

float fBelowLevelPerc,

float fAboveLevelPerc

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Disables normalization
true | 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.NOERROR (0) | The method 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]

Public Function NormalizationIsEnabled (

nPlayerIndex as Int16,

ByRef bEnabled as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes NormalizationIsEnabled (

Int16 nPlayerInde,

ref bool bEnabled

);

[C++]

public: enumErrorCodes NormalizationIsEnabled (

Int16 nPlayerInde,

bool __gc *bEnabled

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Real-time normalization is not enabled
true | Real-time normalization 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.


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]

Public Function PhaserApply (

nPlayerIndex as Int16,

nAffectedChannel as enumChannelMasks,

fDryMix as Single,

fWetMix as Single,

fFeedback as Single,

fRate as Single,

fRange as Single,

fFrequency as Single,

nPriority as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PhaserApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fRate,

float fRange,

float fFrequency,

Int16 nPriority

);

[C++]

public: enumErrorCodes PhaserApply (

Int16 nPlayerIndex,

enumChannelMasks nAffectedChannel,

float fDryMix,

float fWetMix,

float fFeedback,

float fRate,

float fRange,

float fFrequency,

Int16 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.NOERROR (0) | The method 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]

Public PhaserIsApplied (

nPlayerIndex as integer,

ByRef bApplied as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes PhaserIsApplied (

short nPlayerIndex,

ref bool bApplied

);

[C++]

public: enumErrorCodes PhaserIsApplied (

short nPlayerIndex,

bool __gc *bApplied

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The effect has not been applied
true | The effect has been applied

Return value

Value | Meaning
false | The given effect has not been applied
true | The given effect has been applied


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]

Public Function PhaserReset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PhaserReset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PhaserReset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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.PreAmplifierGetValue method and changed through the Effects.PreAmplifierSetValue 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.PreAmplifierGetSpeakerValue method and changed through the PreAmplifierSetSpeakerValue method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function PreAmplifierEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes PreAmplifierEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes PreAmplifierEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Disables pre-amplification
true | Enables pre-amplification

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.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]

Public Function PreAmplifierIsEnabled (

nPlayerIndex as Int16,

ByRef bEnabled as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes PreAmplifierIsEnabled (

Int16 nPlayerInde,

ref bool bEnabled

);

[C++]

public: enumErrorCodes PreAmplifierIsEnabled (

Int16 nPlayerInde,

bool __gc *bEnabled

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Preamplifier is not enabled
true | Preamplifier 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.


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.PreAmplifierSetSpeakerValue 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]

Public Function PreAmplifierSpeakerValueGet (

nPlayerIndex as Int16,

nSpeaker as enumSpeakers

ByRef fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes PreAmplifierSpeakerValueGet (

Int16 nPlayerIndex,

enumSpeakers nSpeaker,

ref float fValue,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes PreAmplifierSpeakerValueGet (

Int16 nPlayerIndex,

enumSpeakers nSpeaker,

float __gc *fValue,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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.PreAmplifierGetSpeakerValue 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]

Public Function PreAmplifierSpeakerValueSet (

nPlayerIndex as Int16,

nSpeaker as enumSpeakers

fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes PreAmplifierSpeakerValueSet (

Int16 nPlayerIndex,

enumSpeakers nSpeaker,

float fValue,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes PreAmplifierSpeakerValueSet (

Int16 nPlayerIndex,

enumSpeakers nSpeaker,

float fValue,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

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

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.NOERROR (0) | The method call was successful.


Effects.PreAmplifierValueGet method

Effects.PreAmplifierValueGet method

Remarks

Obtains the current pre-amplifier's amplification value. The current value can be modified through the Effects.PreAmplifierSetValue 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]

Public Function PreAmplifierValueGet (

nPlayerIndex as Int16,

ByRef fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes PreAmplifierValueGet (

Int16 nPlayerIndex,

ref float fValue,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes PreAmplifierValueGet (

Int16 nPlayerIndex,

float __gc *fValue,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method call was successful.


Effects.PreAmplifierValueSet method

Effects.PreAmplifierValueSet method

Remarks

Modifies the current pre-amplifier's amplification value. The current value can be obtained through the Effects.PreAmplifierGetValue 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]

Public Function PreAmplifierValueSet (

nPlayerIndex as Int16,

fValue as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes PreAmplifierValueSet (

Int16 nPlayerIndex,

float fValue,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes PreAmplifierValueSet (

Int16 nPlayerIndex,

float fValue,

enumVolumeScales nScaleType

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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]

Public Function PlaybackPitchGet (

nPlayerIndex as Int16,

ByRef fPitch as Single

) as Single

[C#]

public float PlaybackPitchGet (

Int16 nPlayerIndex,

ref float fPitch

);

[C++]

public: float PlaybackPitchGet (

Int16 nPlayerIndex,

float __gc *fPitch

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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 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]

Public Function PlaybackPitchSet (

nPlayerIndex as Int16,

fPitch as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackPitchSet (

Int16 nPlayerIndex,

float fPitch

);

[C++]

public: enumErrorCodes PlaybackPitchSet (

Int16 nPlayerIndex,

float fPitch

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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 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]

Public Function PlaybackRateGet (

nPlayerIndex as Int16,

ByRef fRatePerc as Single

) as Single

[C#]

public float PlaybackRateGet (

Int16 nPlayerIndex,

ref float fRatePerc

);

[C++]

public: enumErrorCodes PlaybackRateGet (

Int16 nPlayerIndex,

float __gc *fRatePerc

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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.PlaybackTempSet 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.PlaybackTempSet 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 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 CallbackForPlayersEvents delegate with the nEvent parameter set to EV_DURATION_CHANGED. The new duration can also be obtained through the SoundDurationGet and SoundDurationStringGet methods by setting the bKeepCountOfRateChange parameter to "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]

Public Function PlaybackRateSet (

nPlayerIndex as Int16,

fRatePerc As Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackRateSet (

Int16 nPlayerIndex,

float fRatePerc

);

[C++]

public: enumErrorCodes PlaybackRateSet (

Int16 nPlayerIndex,

float fRatePerc

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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.PlaybackTempSet 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]

Public Function PlaybackRateRatioGet (

nPlayerIndex as Int16,

ByRef fRatio as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackRateRatioGet (

Int16 nPlayerIndex,

ref float fRatio

);

[C++]

public: enumErrorCodes PlaybackRateRatioGet (

Int16 nPlayerIndex,

float __gc *fRatio

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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 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]

Public Function PlaybackTempoGet (

nPlayerIndex as Int16,

ByRef fTempoPerc as Single

) as Single

[C#]

public float PlaybackTempoGet (

Int16 nPlayerIndex,

ref float fTempoPerc

);

[C++]

public: float PlaybackTempoGet (

Int16 nPlayerIndex,

float __gc *fTempoPerc

);

Parameter | Description
nPlayerIndex | 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.


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.PlaybackTempGet 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 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 CallbackForPlayersEvents delegate with the nEvent parameter set to EV_DURATION_CHANGED. The new duration can also be obtained through the SoundDurationGet and SoundDurationStringGet methods by setting the bKeepCountOfRateChange parameter to "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]

Public Function PlaybackTempoSet (

nPlayerIndex as Int16,

fTempoPerc As Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackTempoSet (

Int16 nPlayerIndex,

float fTempoPerc

);

[C++]

public: enumErrorCodes PlaybackTempoSet (

Int16 nPlayerIndex,

float fTempoPerc

);

Parameter | Description
nPlayerIndex | 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.NOERROR (0) | The method 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 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]

Public Function SoundDirectionEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SoundDirectionEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes SoundDirectionEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Disable reversed sound creation
true | Enable reversed sound creation

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.SoundDirectionGet method

Effects.SoundDirectionGet method

Remarks

Obtains the current sound's playback direction. The playback direction can be modified through the SoundDirectionSet method.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function SoundDirectionGet (

nPlayerIndex as Int16,

ByRef nDirection as enumSoundDirections

) as enumSoundDirections

[C#]

public enumSoundDirections SoundDirectionGet (

Int16 nPlayerIndex,

ref enumSoundDirections nDirection

);

[C++]

public: enumSoundDirections SoundDirectionGet (

Int16 nPlayerIndex,

enumSoundDirections __gc *nDirection

);

Parameter

Description

nPlayerIndex

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.NOERROR (0) | The method 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]

Public Function SoundDirectionIsEnabled (

nPlayerIndex as Int16,

ByRef bEnabled as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SoundDirectionIsEnabled (

Int16 nPlayerIndex,

ref bool bEnabled

);

[C++]

public: enumErrorCodes SoundDirectionIsEnabled (

Int16 nPlayerIndex,

bool __gc *bEnabled

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Reverse playback is not enabled
true | Reverse playback 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.


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 SoundDirectionEnable method.

The current playback direction can be obtained through the 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]

Public Function SoundDirectionSet (

nPlayerIndex as Int16,

nDirection as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SoundDirectionSet (

Int16 nPlayerIndex,

Int16 nDirection

);

[C++]

public: enumErrorCodes SoundDirectionSet (

Int16 nPlayerIndex,

Int16 nDirection

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

nDirection

he 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.NOERROR (0) | The method call was successful.


FaderDisplay class

FaderDisplay class

The FaderDisplay class, accessible through the control's Fader.Display property 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 FaderDisplay class 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 audioDjStudio1 on a form and that you want to change a couple of settings for the Automatic Fader Display (the color of the lines representing the fading songs).

Visual Basic.NET

Here follows the code needed to perform the requested operations

' initialise the Fader

AudioDjStudio1.Fader.Init(AudioDjStudio.enumFadeTypes.FADE_SINGLE, 0, 1)

' create the Display and show it over an existing label control (labelFaderDisplay)

AudioDjStudio1.Fader.Display.Create(labelFaderDisplay.Handle)

AudioDjStudio1.Fader.Display.Show(True)

' set the Blue color for the line representing the song fading-out

AudioDjStudio1.Fader.Display.ColorSongFadingOut = Color.Blue

' set the Yellow color for the line representing the song fading-in

AudioDjStudio1.Fader.Display.ColorSongFadingIn = Color.Yellow

Visual C#.NET

Here follows the code needed to perform the requested operations

// initialise the Fader

audioDjStudio1.Fader.Init (enumFadeTypes.FADE_SINGLE, 0, 1);

// create the Display and show it over an existing label control (labelFaderDisplay)

audioDjStudio1.Fader.Display.Create (labelFaderDisplay.Handle);

audioDjStudio1.Fader.Display.Show (true);

// set the Blue color for the line representing the song fading-out

audioDjStudio1.Fader.Display.ColorSongFadingOut = Color.Blue;

// set the Yellow color for the line representing the song fading-in

audioDjStudio1.Fader.Display.ColorSongFadingIn = Color.Yellow;


Fader.Display.ColorBackground property

Fader.Display.ColorBackground property

Type

[Visual Basic]

Public Property ColorLineSongEnd As Color

[C#]

public Color ColorLineSongEnd {get; set;}

[C++]

public: __property Color get_ColorLineSongEnd();

public: __property void set_ColorLineSongEnd(Color);

Remarks

Determines the color used to render the Display background.

See also

FaderDisplay class

Fader.Display property

How to use the Automatic Fader section.


Fader.Display.ColorLineMixPoint property

Fader.Display.ColorLineMixPoint property

Type

[Visual Basic]

Public Property ColorLineMixPoint As Color

[C#]

public Color ColorLineMixPoint {get; set;}

[C++]

public: __property Color get_ColorLineMixPoint();

public: __property void set_ColorLineMixPoint(Color);

Remarks

Determines the color used to render the line representing the Mix point.

See also

FaderDisplay class

Fader.Display property

How to use the Automatic Fader section.


Fader.Display.ColorLineSongEnd property

Fader.Display.ColorLineSongEnd property

Type

[Visual Basic]

Public Property ColorLineSongEnd As Color

[C#]

public Color ColorLineSongEnd {get; set;}

[C++]

public: __property Color get_ColorLineSongEnd();

public: __property void set_ColorLineSongEnd(Color);

Remarks

Determines the color used to render the line representing the end of the song fading-out.

See also

FaderDisplay class

Fader.Display property

How to use the Automatic Fader section.


Fader.Display.ColorSongFadingIn property

Fader.Display.ColorSongFadingIn property

Type

[Visual Basic]

Public Property ColorSongFadingIn As Color

[C#]

public Color ColorSongFadingIn {get; set;}

[C++]

public: __property Color get_ColorSongFadingIn();

public: __property void set_ColorSongFadingIn(Color);

Remarks

Determines the color of the line representing the song fading-in.

See also

FaderDisplay class

Fader.Display property

How to use the Automatic Fader section.


Fader.Display.ColorSongFadingOut property

Fader.Display.ColorSongFadingOut property

Type

[Visual Basic]

Public Property ColorSongFadingOut As Color

[C#]

public Color ColorSongFadingOut {get; set;}

[C++]

public: __property Color get_ColorSongFadingOut();

public: __property void set_ColorSongFadingOut(Color);

Remarks

Determines the color of the line representing the song fading-out.

See also

FaderDisplay class

Fader.Display property

How to use the Automatic Fader section.


Fader.Display.WidthReferenceLines property

Fader.Display.WidthReferenceLines property

Type

[Visual Basic]

Public Property WidthReferenceLines As Int16

[C#]

public Int16 WidthReferenceLines {get; set;}

[C++]

public: __property Int16 get_WidthReferenceLines();

public: __property void set_WidthReferenceLines(Int16);

Remarks

Determines the width in pixels of the reference lines.

See also

FaderDisplay class

Fader.Display property

How to use the Automatic Fader section.


Fader.Display.WidthSongLines property

Fader.Display.WidthSongLines property

Type

[Visual Basic]

Public Property WidthSongLines As Int16

[C#]

public Int16 WidthSongLines {get; set;}

[C++]

public: __property Int16 get_WidthSongLines();

public: __property void set_WidthSongLines(Int16);

Remarks

Determines the width in pixels of the song lines.

See also

FaderDisplay class

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 class refer to the How to use the Automatic Fader section.

Syntax

[Visual Basic]

Public Function Create (

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Create (

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes Create (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SetBackPictureFromFile (

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

string strPathname

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

string 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SetBackPictureFromHandle (

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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 FaderDisplay class section.

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

Syntax

[Visual Basic]

Public Function SetHwnd (

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetHwnd (

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes SetHwnd (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function Show (

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

bool bShow

);

[C++]

public: enumErrorCodes Show (

bool bShow

);

Parameter

Description

bShow

Boolean value that specifies to the Fader object if it must show/hide the Display graphics

Supported values are the following:

Value | Meaning
false | Hides the Fader Display graphics
true | Shows the Fader Display graphics

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.


FaderObject class

FaderObject class

The FaderObject class, accessible through the control's Fader property, 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 FaderObject class 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 FaderObject class is implemented as an "expandable object" so the sub-properties of the Fader property can be set at Design-time using the "Properties" toolbar of Visual Studio.NET like in the screenshot below:

The following code snippets show how to initialise and change settings for this object in your code at Runtime. These examples assume that you have placed a control named audioDjStudio1 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).

Visual Basic.NET

Here follows the code needed to perform the requested operations

' initialise the Fader on player 0 and player 1

audioDjStudio1 .Fader.Init (AudioDjStudio.enumFadeTypes.FADE_SINGLE, 0, 1)

' set the fade-in and fade-out duration

audioDjStudio1 .Fader.FadeInLength = 3000

audioDjStudio1 .Fader.FadeOutLength = 4000

Visual C#.NET

Here follows the code needed to perform the requested operations

// initialise the Fader on player 0 and player 1

audioDjStudio1 .Fader.Init (AudioDjStudio.enumFadeTypes.FADE_SINGLE, 0, 1);

// set the fade-in and fade-out duration

audioDjStudio1 .Fader.FadeInLength = 3000;

audioDjStudio1 .Fader.FadeOutLength = 4000;


Fader.CheckItemsDurationOnStart property

Fader.CheckItemsDurationOnStart property

Type

[Visual Basic]

Public Property CheckItemsDurationOnStart As Boolean

[C#]

public bool CheckItemsDurationOnStart {get; set;}

[C++]

public: __property bool get_CheckItemsDurationOnStart();

public: __property void set_FadeInEnabled(bool);

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

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.Display property (RO)

Fader.Display property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property Display As FaderDisplay

[C#]

public FaderDisplay Display {get;}

[C++]

public: __property FaderDisplay* get_Display ();

This property is Read-only

Remarks

The Display object for the embedded Automatic Fader object.

This property encapsulates the functionality of the FaderDisplay class

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


Fader.FadeInDelayFromMixStart property

Fader.FadeInDelayFromMixStart property

Type

[Visual Basic]

Public Property FadeInDelayFromMixStart As Int32

[C#]

public Int32 FadeInDelayFromMixStart {get; set;}

[C++]

public: __property Int32 get_FadeInDelayFromMixStart();

public: __property void set_FadeInDelayFromMixStart(Int32);

Remarks

Expressed in milliseconds, determines the delay applied for the fade-in.

See also

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.FadeInEnabled property

Fader.FadeInEnabled property

Type

[Visual Basic]

Public Property FadeInEnabled As Boolean

[C#]

public bool FadeInEnabled {get; set;}

[C++]

public: __property bool get_FadeInEnabled();

public: __property void set_FadeInEnabled(bool);

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

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.FadeInLength property

Fader.FadeInLength property

Type

[Visual Basic]

Public Property FadeInLength As Int32

[C#]

public Int32 FadeInLength {get; set;}

[C++]

public: __property Int32 get_FadeInLength();

public: __property void set_FadeInLength(Int32);

Remarks

Expressed in milliseconds, determines the time required by the song fading-in to slide the volume to its maximum.

See also

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.FadeInSeekPos property

Fader.FadeInSeekPos property

Type

[Visual Basic]

Public Property FadeInSeekPos As Int32

[C#]

public Int32 FadeInSeekPos {get; set;}

[C++]

public: __property Int32 get_FadeInSeekPos();

public: __property void set_FadeInSeekPos(Int32);

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

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.FadeOutDelayFromMixStart property

Fader.FadeOutDelayFromMixStart property

Type

[Visual Basic]

Public Property FadeOutDelayFromMixStart As Int32

[C#]

public Int32 FadeOutDelayFromMixStart {get; set;}

[C++]

public: __property Int32 get_FadeOutDelayFromMixStart();

public: __property void set_FadeOutDelayFromMixStart(Int32);

Remarks

Expressed in milliseconds, determines the delay applied for the fade-out.

See also

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.FadeOutEnabled property

Fader.FadeOutEnabled property

Type

[Visual Basic]

Public Property FadeOutEnabled As Boolean

[C#]

public bool FadeOutEnabled {get; set;}

[C++]

public: __property bool get_FadeOutEnabled();

public: __property void set_FadeOutEnabled(bool);

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

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.FadeOutLength property

Fader.FadeOutLength property

Type

[Visual Basic]

Public Property FadeOutLength As Int32

[C#]

public Int32 FadeOutLength {get; set;}

[C++]

public: __property Int32 get_FadeOutLength();

public: __property void set_FadeOutLength(Int32);

Remarks

Expressed in milliseconds, determines the time required by the song fading-out to slide the volume to its minimum.

See also

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.FadeOutMode property

Fader.FadeOutMode property

Type

[Visual Basic]

Public Property FadeOutMode As enumFadeOutModes

[C#]

public enumFadeOutModes FadeOutMode {get; set;}

[C++]

public: __property enumFadeOutModes get_FadeOutMode();

public: __property void set_FadeOutMode(enumFadeOutModes);

Remarks

Determines how to perform the fade-out process.

Supported values are the following:

Mnemonic value | 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

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.FadeStartFromEnd property

Fader.FadeStartFromEnd property

Type

[Visual Basic]

Public Property FadeStartFromEnd As Int32

[C#]

public Int32 FadeStartFromEnd {get; set;}

[C++]

public: __property Int32 get_FadeStartFromEnd();

public: __property void set_FadeStartFromEnd(Int32);

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

FaderObject class

Fader property

How to use the Automatic Fader section.


Fader.TotalMixingTime property (RO)

Fader.TotalMixingTime property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property TotalMixingTime As Int32

[C#]

public Int32 TotalMixingTime{get;}

[C++]

public: __property Int32 get_TotalMixingTime();

This property is read-only

Remarks

Expressed in milliseconds, retrieves the total time required to perform a complete cross-fading.

See also

FaderObject class

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]

Public Sub Exit (

)

[C#]

public void Exit (

);

[C++]

public: void 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]

Public Function FadeInTargetVolumeGet (

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes FadeInTargetVolumeGet (

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes FadeInTargetVolumeGet (

enumVolumeScales 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]

Public Function FadeInTargetVolumeSet (

fTargetVolume as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes FadeInTargetVolumeSet (

float fTargetVolume,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes FadeInTargetVolumeSet (

float fTargetVolume,

enumVolumeScales 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function FadeInVolumeCurveSet (

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FadeInVolumeCurveSet (

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes FadeInVolumeCurveSet (

enumVolumeCurves nCurveType,

Int32 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.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]

Public Function FadeInVolumeCurveSetEx (

nCurveType as enumVolumeCurves,

nLeftX as Int16,

nLeftY as Int16,

nRightX as Int16,

nRightY as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FadeInVolumeCurveSetEx (

enumVolumeCurves nCurveType,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 nRightY

);

[C++]

public: enumErrorCodes FadeInVolumeCurveSetEx (

enumVolumeCurves nCurveType,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 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.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]

Public Function FadeOutVolumeCurveSet (

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FadeOutVolumeCurveSet (

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes FadeOutVolumeCurveSet (

enumVolumeCurves nCurveType,

Int32 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.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]

Public Function FadeOutVolumeCurveSetEx (

nCurveType as enumVolumeCurves,

nLeftX as Int16,

nLeftY as Int16,

nRightX as Int16,

nRightY as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FadeOutVolumeCurveSetEx (

enumVolumeCurves nCurveType,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 nRightY

);

[C++]

public: enumErrorCodes FadeOutVolumeCurveSetEx (

enumVolumeCurves nCurveType,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 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.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]

Public Function Init (

nFadeType as enumFadeTypes,

nIndexPlayerA as Int16,

nIndexPlayerB as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Init (

enumFadeTypes nFadeType,

Int16 nIndexPlayerA,

Int16 nIndexPlayerB

);

[C++]

public: enumErrorCodes Init (

enumFadeTypes nFadeType,

Int16 nIndexPlayerA,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function PlayListUseSingle (

nIndexPlayer as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayListUseSingle (

Int16 nIndexPlayer

);

[C++]

public: enumErrorCodes PlayListUseSingle (

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StartManualFading (

) as enumErrorCodes

[C#]

public enumErrorCodes StartManualFading (

);

[C++]

public: enumErrorCodes StartManualFading (

);

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.


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]

Public Sub Stop (

)

[C#]

public void Stop (

);

[C++]

public: void Stop (

);

Return value

None

Stop


GraphicBarsMan class

GraphicBarsMan class

The GraphicBarsMan class, accessible through the control's GraphicBarsManager property, contains methods 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 GraphicBarsMan class is implemented through the following methods:

Methods

Create

Destroy

GetGraphicalSettings

GetRange

GetValue

Move

Refresh

SetFlatBorder

SetGraphicalSettings

SetRange

SetValue

Show

Internal classes

GRAPHIC_BAR_SETTINGS

Samples of use of the GraphicBarsMan class in Visual C#.NET and Visual Basic.NET 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 GraphicBarsMan class on the given parent window.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class.

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]

Public Function Create (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32,

colorParentBackColor as Color

) as IntPtr

[C#]

public IntPtr Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Color colorParentBackColor

);

[C++]

public: IntPtr Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Color colorParentBackColor

);

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
colorParentBackColor | Background color of the parent window

Return value

Value | Meaning
IntPtr.Zero | 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 GraphicBarsMan class.

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]

Public Function Destroy (

hWndGraphicBar as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Destroy (

IntPtr hWndGraphicBar

);

[C++]

public: enumErrorCodes Destroy (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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 GraphicBarsMan class.

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]

Public Function GetGraphicalSettings (

hWndGraphicBar as IntPtr,

ByRef settings as GRAPHIC_BAR_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes GetGraphicalSettings (

IntPtr hWndGraphicBar,

ref GRAPHIC_BAR_SETTINGS settings

);

[C++]

public: enumErrorCodes GetGraphicalSettings (

IntPtr hWndGraphicBar,

GRAPHIC_BAR_SETTINGS __gc *settings

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
settings | Reference to the object of class GRAPHIC_BAR_SETTINGS that receives in output the graphical settings of the graphic bar.

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.


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 GraphicBarsMan class.

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]

Public Function GetRange (

hWndGraphicBar as IntPtr,

ByRef nMinValue as Int32,

ByRef nMaxValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetRange (

IntPtr hWndGraphicBar,

ref Int32 nMinValue,

ref Int32 nMaxValue

);

[C++]

public: enumErrorCodes GetRange (

IntPtr hWndGraphicBar,

Int32 __gc *nMinValue,

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 GraphicBarsMan class.

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]

Public Function GetValue (

hWndGraphicBar as IntPtr,

ByRef nValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetValue (

IntPtr hWndGraphicBar,

ref Int32 nValue

);

[C++]

public: enumErrorCodes GetValue (

IntPtr hWndGraphicBar,

Int32 __gc *nValue

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
nValue | Reference to current value

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.


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 GraphicBarsMan class.

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]

Public Function Move (

hWndGraphicBar as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Move (

IntPtr hWndGraphicBar,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Move (

IntPtr hWndGraphicBar,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 GraphicBarsMan class.

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]

Public Function Refresh (

hWndGraphicBar as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Refresh (

IntPtr hWndGraphicBar

);

[C++]

public: enumErrorCodes Refresh (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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 GraphicBarsMan class.

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]

Public Function SetFlatBorder (

hWndGraphicBar as IntPtr,

nWidth as Int32,

color as Color

) as enumErrorCodes

[C#]

public enumErrorCodes SetFlatBorder (

IntPtr hWndGraphicBar,

Int32 nWidth,

Color color

);

[C++]

public: enumErrorCodes SetFlatBorder (

IntPtr hWndGraphicBar,

Int32 nWidth,

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 (see the LastError property for further error details)
enumErrorCodes.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 GraphicBarsMan class.

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]

Public Function GetGraphicalSettings (

hWndGraphicBar as IntPtr,

settings as GRAPHIC_BAR_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes GetGraphicalSettings (

IntPtr hWndGraphicBar,

GRAPHIC_BAR_SETTINGS settings

);

[C++]

public: enumErrorCodes GetGraphicalSettings (

IntPtr hWndGraphicBar,

GRAPHIC_BAR_SETTINGS settings

);

Parameter | Description
hWndGraphicBar | Handle of the control returned by a previous call to the GraphicBarsManager.Create method
settings | Object of class GRAPHIC_BAR_SETTINGS containing the graphical settings of the graphic bar.

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.


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 GraphicBarsMan class.

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]

Public Function SetRange (

hWndGraphicBar as IntPtr,

nMinValue as Int32,

nMaxValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetRange (

IntPtr hWndGraphicBar,

Int32 nMinValue,

Int32 nMaxValue

);

[C++]

public: enumErrorCodes SetRange (

IntPtr hWndGraphicBar,

Int32 nMinValue,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 GraphicBarsMan class.

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]

Public Function SetValue (

hWndGraphicBar as IntPtr,

nValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetValue (

IntPtr hWndGraphicBar,

Int32 nValue

);

[C++]

public: enumErrorCodes SetValue (

IntPtr hWndGraphicBar,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 GraphicBarsMan class.

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]

Public Function Show (

hWndGraphicBar as IntPtr,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

IntPtr hWndGraphicBar,

bool bShow

);

[C++]

public: enumErrorCodes Show (

IntPtr hWndGraphicBar,

bool 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
false | Hides the graphic bar window
true | Shows the graphic bar window

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.


GRAPHIC_BAR_SETTINGS structure

GRAPHIC_BAR_SETTINGS structure

The GRAPHIC_BAR_SETTINGS structure (defined as GRAPHIC_BAR_SETTINGS_DLL when used for COM interoperability) 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 GraphicBarsMan class.

For a tutorial about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

C# definition

public struct GRAPHIC_BAR_SETTINGS

{

 public enumGraphicBarOrientations   nOrientation;

 public bool                         bAppearance3d;

 public bool                         bSmoothing;

 public bool                         bAutomaticDrop;

 public Color                       colorStart;

 public Color                       colorEnd;

 public Color                       colorBackground;

 public enumGraphicBarShapes         nShape;

}

Definition for COM interoperability

public struct GRAPHIC_BAR_SETTINGS_DLL

{

 public Int32 nOrientation;

 public Int16 bAppearance3d;

 public Int16 bSmoothing;

 public Int16 bAutomaticDrop;

 public Int32 colorStart;

 public Int32 colorEnd;

 public Int32 colorBackground;

 public Int32 nShape;

}

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 be smoothed as seen on the image below:
true | The graphic bar will not 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:


MediaFileDecoderMan class

MediaFileDecoderMan class

The MediaFileDecoderMan class, accessible through the control's MediaFileDecoder property, 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 the decoded media file.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

Public Function FileChunkLengthGet (

nStartPosition as Int64,

nEndPosition as Int64,

ByRef nLength as Int64

) as Int32

[C#]

public Int32 FileChunkLengthGet (

Int64 nStartPosition,

Int64 nEndPosition,

ref Int64 nLength

);

[C++]

public: Int32 FileChunkLengthGet (

Int64 nStartPosition,

Int64 nEndPosition,

Int64 __gc *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]

Public Function FileClose (

) as Int32

[C#]

public Int32 FileClose (

);

[C++]

public: Int32 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]

Public Function FileDataGet (

pBuffer() as Byte,

nBufferLen as Int32,

nDataType as enumDataTypes,

ByRef nBytesRead as Int32

) as Int32

[C#]

public Int32 FileDataGet (

byte[] pBuffer,

Int32 nBufferLen,

enumDataTypes nDataType,

ref Int32 nBytesRead

);

[C++]

public: Int32 FileDataGet (

unsigned char __gc[] pBuffer,

Int32 nBufferLen,

enumDataTypes nDataType,

Int32 __gc *nBytesRead

);

Parameter

Description

pBuffer

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 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]

Public Function FileDurationGet (

ByRef nDuration as Int64

) as Int32

[C#]

public Int32 FileDurationGet (

ref Int64 nDuration

);

[C++]

public: Int32 FileDurationGet (

Int64 __gc *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]

Public Function FileInfoGet (

ByRef nFrequency as Int32,

ByRef nChannels as Int32,

ByRef nEncodeMode as enumRAWEncodeModes

) as Int32

[C#]

public Int32 FileInfoGet (

ref Int64 nFrequency,

ref Int64 nChannels,

ref enumRAWEncodeModes nEncodeMode

);

[C++]

public: Int32 FileInfoGet (

Int64 __gc *nFrequency,

Int64 __gc *nChannels,

enumRAWEncodeModes __gc *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]

Public Function FileLengthGet (

ByRef nLength as Int64

) as Int32

[C#]

public Int32 FileLengthGet (

ref Int64 nLength

);

[C++]

public: Int32 FileLengthGet (

Int64 __gc *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]

Public Function FileOpen (

strPathname as String

) as Int32

[C#]

public Int32 FileOpen (

string strPathname

);

[C++]

public: Int32 FileOpen (

string 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]

Public Function FileOpenRaw (

strPathname as String,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as bool,

nFrequency as Int32,

nChannels as Int32

) as Int32

[C#]

public Int32 FileOpenRaw (

string strPathname,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

[C++]

public: Int32 FileOpenRaw (

string strPathname,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 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
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: 1 for Mono or 2 for Stereo

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.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]

Public Function FileOpenCancel (

) as Int32

[C#]

public Int32 FileOpenCancel (

);

[C++]

public: Int32 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]

Public Function FilePositionGet (

ByRef nPosition as Int64,

nPositionUnit as enumDecodePositionUnit

) as Int32

[C#]

public Int32 FilePositionGet (

ref Int64 nPosition,

enumDecodePositionUnit nPositionUnit

);

[C++]

public: Int32 FilePositionGet (

Int64 __gc *nPosition,

enumDecodePositionUnit 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]

Public Function FilePositionSet (

nPosition as Int64,

nPositionUnit as enumDecodePositionUnit

) as Int32

[C#]

public Int32 FilePositionSet (

Int64 nPosition,

enumDecodePositionUnit nPositionUnit

);

[C++]

public: Int32 FilePositionSet (

Int64 nPosition,

enumDecodePositionUnit 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 MediaFileDecoderMan class.

For details about management of media files decoding, refer to the How to decode media files tutorial.

Syntax

[Visual Basic]

Public Sub Initialize (

)

[C#]

public Int32 Initialize (

);

[C++]

public: Int32 Initialize (

);

Return value

None


MIDIMan class

MIDIMan class

The MIDIMan class, accessible through the control's MIDI property, contains methods needed to manage MIDI protocol, MIDI files and MIDI input devices.

The MIDIMan class is implemented through the following methods:

Methods

BpmGet

BpmSet

ChannelsGet

ChannelsSet

DecayModeSet

EventApply

EventValueGet

EventsEnableNotifications

EventsEnum

EventsEnumFromRange

EventsEnumItemGet

EventsListApply

EventsListItemAdd

EventsListItemCountGet

EventsListItemGet

EventsListItemModify

EventsListItemRemove

EventsListItemUniqueIdGet

EventsRawApply

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

StreamPreloadSamples

StreamStart

StreamStop

TempoPercGet

TempoPercSet

TrackCountGet

TrackTagsEnum

TrackTagsItemGet

TrackVolumeGet

TrackVolumeSet

TriggerAdd

TriggerSetPos

VoicesDefaultGet

VoicesDefaultSet

VoicesGet

VoicesSet

Internal classes

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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function BPMGet (

nPlayerIndex as Int16,

ByRef fBPM as Single

) as enumErrorCodes

[C#]

public enumErrorCodes BPMGet (

Int16 nPlayerIndex,

ref float fBPM

);

[C++]

public: enumErrorCodes BPMGet (

Int16 nPlayerIndex,

float __gc *fBPM

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function BPMSet (

nPlayerIndex as Int16,

fBPM as Single

) as enumErrorCodes

[C#]

public enumErrorCodes BPMSet (

Int16 nPlayerIndex,

float fBPM

);

[C++]

public: enumErrorCodes BPMSet (

Int16 nPlayerIndex,

float fBPM

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function ChannelsGet (

nPlayerIndex as Int16,

ByRef nChannels as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ChannelsGet (

Int16 nPlayerIndex,

ref Int16 nChannels

);

[C++]

public: enumErrorCodes ChannelsGet (

Int16 nPlayerIndex,

Int16 __gc *nChannels

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function ChannelsSet (

nPlayerIndex as Int16,

nChannels as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ChannelsSet (

Int16 nPlayerIndex,

Int16 nChannels

);

[C++]

public: enumErrorCodes ChannelsSet (

Int16 nPlayerIndex,

Int16 nChannels

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function DecayModeSet (

nPlayerIndex as Int16,

bLetDecayOnEnd as Boolean,

bLetDecayOnSeek as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DecayModeSet (

Int16 nPlayerIndex,

bool bLetDecayOnEnd,

bool bLetDecayOnSeek

);

[C++]

public: enumErrorCodes DecayModeSet (

Int16 nPlayerIndex,

bool bLetDecayOnEnd,

bool bLetDecayOnSeek

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | The sound will be stopped abruptly when the sound playback is completed.
true | 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:

Value | Meaning
false | The sound will be stopped abruptly when the playback position is modified.
true | The sound will decay naturally when the playback position is modified.

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.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function InputDevicesCountGet (

ByRef nCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes InputDevicesCountGet (

ref Int16 nCount

);

[C++]

public: enumErrorCodes InputDevicesCountGet (

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function InputDevicesEnum (

ByRef nCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes InputDevicesEnum (

ref Int16 nCount

);

[C++]

public: enumErrorCodes InputDevicesEnum (

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function InputDevicesInfoGet (

nDeviceIndex as Int16,

ByRef nManufacturerId as Int32,

ByRef nProductId as Int32,

ByRef bIsEnabled as Boolean,

ByRef bIsStarted as Boolean

) as String

[C#]

public string InputDevicesInfoGet (

Int16 nDeviceIndex,

ref Int32 nManufacturerId,

ref Int32 nProductId,

ref Int32 bIsEnabled,

ref Int32 bIsStarted

);

[C++]

public: string InputDevicesInfoGet (

Int16 nDeviceIndex,

Int32 __gc *nManufacturerId,

Int32 __gc *nProductId,

Int32 __gc *bIsEnabled,

Int32 __gc *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:

Value | Meaning
false | 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.
true | 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:

Value | Meaning
false | The MIDI input device has not been started.
true | 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function InputDevicesStart (

nDeviceIndex as Int32,

pCallback as MidiCallbackFunction,

nUserData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes InputDevicesStart (

Int32 nDeviceIndex,

MidiCallbackFunction pCallback,

Int32 nUserData

);

[C++]

public: enumErrorCodes InputDevicesStart (

Int32 nDeviceIndex,

MidiCallbackFunction pCallback,

Int32 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 IntPtr,

ByVal bufferLength As Int32,

ByVal nUserData As Int32

)

[Visual C#]

void MyMidiCallback (

IntPtr bufferRawEvents,

Int32 bufferLength,

Int32 nUserData

);

Visual C++]

void MyMidiCallback (

IntPtr bufferRawEvents,

Int32 bufferLength,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function InputDevicesStartOnPlayer (

nDeviceIndex as Int32,

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes InputDevicesStartOnPlayer (

Int32 nDeviceIndex,

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes InputDevicesStartOnPlayer (

Int32 nDeviceIndex,

Int16 nPlayerIndex

);

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.
nPlayerIndex | 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.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function InputDevicesStop (

nDeviceIndex as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes InputDevicesStop (

Int32 nDeviceIndex

);

[C++]

public: enumErrorCodes InputDevicesStop (

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 CallbackForMidiKeyboardEvents delegate.

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]

Public Function KeyboardCreate (

nPlayerIndex as Int16,

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32,

nLowNote as Int16,

nHighNote as Int16,

bSendEventNotif as Boolean,

nOrientation as enumMidiKeyboardOrientations

) as IntPtr

[C#]

public IntPtr KeyboardCreate (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Int16 nLowNote,

Int16 nHighNote,

bool bSendEventNotif,

enumMidiKeyboardOrientations nOrientation

);

[C++]

public: IntPtr KeyboardCreate (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Int16 nLowNote,

Int16 nHighNote,

bool bSendEventNotif,

enumMidiKeyboardOrientations nOrientation

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.

Supported values are the following:

Value | Meaning
false | The CallbackForMidiStreamEvents delegate is not invoked for notes played on the piano keyboard.
true | The CallbackForMidiStreamEvents delegate is invoked 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
IntPtr.Zero | An error occurred, check the LastError property value in order to get the error code
Other values | Handle (HWND) of the new graphic bar


MIDI.KeyboardDestroy method

MIDI.KeyboardDestroy method

Remarks

Destroys an existing virtual piano keyboard.

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]

Public Function KeyboardDestroy (

hWndKeyboard as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes KeyboardDestroy (

IntPtr hWndKeyboard

);

[C++]

public: enumErrorCodes KeyboardDestroy (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function KeyboardGraphicalSettingsGet (

hWndKeyboard as IntPtr,

ByRef settings as MIDI_KEYBOARD_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes KeyboardGraphicalSettingsGet (

IntPtr hWndKeyboard,

ref MIDI_KEYBOARD_SETTINGS settings

);

[C++]

public: enumErrorCodes KeyboardGraphicalSettingsGet (

IntPtr hWndKeyboard,

MIDI_KEYBOARD_SETTINGS __gc *settings

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method
settings | Reference to the object of class MIDI_KEYBOARD_SETTINGS that receives in output graphical settings of the keyboard.

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.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function KeyboardGraphicalSettingsSet (

hWndKeyboard as IntPtr,

settings as MIDI_KEYBOARD_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes KeyboardGraphicalSettingsSet (

IntPtr hWndKeyboard,

MIDI_KEYBOARD_SETTINGS settings

);

[C++]

public: enumErrorCodes KeyboardGraphicalSettingsSet (

IntPtr hWndKeyboard,

MIDI_KEYBOARD_SETTINGS settings

);

Parameter | Description
hWndKeyboard | Handle of the virtual keyboard as returned by the call to the MIDI.KeyboardCreate method
settings | Object of class MIDI_KEYBOARD_SETTINGS that receives in output graphical settings of the keyboard.

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.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function KeyboardMove (

hWndKeyboard as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes KeyboardMove (

IntPtr hWndKeyboard,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes KeyboardMove (

IntPtr hWndKeyboard,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function KeyboardNote (

hWndKeyboard as IntPtr,

nNote as Int32,

nVelocity as Int32,

bSimulated as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes KeyboardNote (

IntPtr hWndKeyboard,

Int32 nNote,

Int32 nVelocity,

bool bSimulated

);

[C++]

public: enumErrorCodes KeyboardNote (

IntPtr hWndKeyboard,

Int32 nNote,

Int32 nVelocity,

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

Value | Meaning
false | The call to this method will play the requested note on the MIDI stream in playback
true | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function KeyboardRangeSet (

hWndKeyboard as IntPtr,

nLowNote as Int16,

nHighNote as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes KeyboardRangeSet (

IntPtr hWndKeyboard,

Int16 nLowNote,

Int16 nHighNote

);

[C++]

public: enumErrorCodes KeyboardRangeSet (

IntPtr hWndKeyboard,

Int16 nLowNote,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function KeyboardRefresh (

hWndKeyboard as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes KeyboardRefresh (

IntPtr hWndKeyboard

);

[C++]

public: enumErrorCodes KeyboardRefresh (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function KeyboardShow (

hWndKeyboard as IntPtr,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes KeyboardShow (

IntPtr hWndKeyboard,

bool bShow

);

[C++]

public: enumErrorCodes KeyboardShow (

IntPtr hWndKeyboard,

bool 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
false | Hides the keyboard
true | Shows the keyboard

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.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 invokes the CallbackForMidiMarkerEvents delegate 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function MarkersEnableNotifications (

nPlayerIndex as Int16,

nMarkerType as enumMidiMarkerNotifications,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MarkersEnableNotifications (

Int16 nPlayerIndex,

enumMidiMarkerNotifications nMarkerType,

bool bEnable

);

[C++]

public: enumErrorCodes MarkersEnableNotifications (

Int16 nPlayerIndex,

enumMidiMarkerNotifications nMarkerType,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiMarkerEvents delegate.

Supported values are the following:

Value | Meaning
false | Notification for the given marker is not enabled.
true | Notification for the given marker 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.


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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function MarkersEnum (

nPlayerIndex as Int16,

nMarkerType as enumMidiMarkerNotifications,

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes MarkersEnum (

Int16 nPlayerIndex,

enumMidiMarkerNotifications nMarkerType,

ref Int32 nCount

);

[C++]

public: enumErrorCodes MarkersEnum (

Int16 nPlayerIndex,

enumMidiMarkerNotifications nMarkerType,

Int32 __gc *nCount

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function MarkersEnumItemGet (

nPlayerIndex as Int16,

nMarkerType as enumMidiMarkerNotifications,

nMarkerIndex as Int32,

ByRef fPosition as Double,

nPositionUnit as enumMidiPositionUnits,

ByRef nTrack as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes MarkersEnumItemGet (

Int16 nPlayerIndex,

enumMidiMarkerNotifications nMarkerType,

Int32 nMarkerIndex,

ref double fPosition,

enumMidiPositionUnits nPositionUnit,

ref Int16 nTrack

);

[C++]

public: enumErrorCodes MarkersEnumItemGet (

Int16 nPlayerIndex,

enumMidiMarkerNotifications nMarkerType,

Int32 nMarkerIndex,

double __gc *fPosition,

enumMidiPositionUnits nPositionUnit,

Int16 __gc *nTrack

);

Parameter

Description

nPlayerIndex

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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function PulsesPerQuarterNoteGet (

nPlayerIndex as Int16,

ByRef fPPQN as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PulsesPerQuarterNoteGet (

Int16 nPlayerIndex,

ref float fPPQN

);

[C++]

public: enumErrorCodes PulsesPerQuarterNoteGet (

Int16 nPlayerIndex,

float __gc *fPPQN

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


MIDI.SeekToPosition method

MIDI.SeekToPosition 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SeekToPosition (

nPlayerIndex as Int16,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits,

bPerformDecay as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SeekToPosition (

Int16 nPlayerIndex,

double fPosition,

enumMidiPositionUnits nPositionUnit,

bool bPerformDecay

);

[C++]

public: enumErrorCodes SeekToPosition (

Int16 nPlayerIndex,

double fPosition,

enumMidiPositionUnits nPositionUnit,

bool bPerformDecay

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | The sound will be stopped abruptly when the playback position is modified.
true | The sound will decay naturally when the playback position is modified.

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.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 "false".

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]

Public Function SoundDurationGet (

nPlayerIndex as Int16,

ByRef fDuration as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C#]

public enumErrorCodes SoundDurationGet (

Int16 nPlayerIndex,

ref double fDuration,

enumMidiPositionUnits nPositionUnit

);

[C++]

public: enumErrorCodes SoundDurationGet (

Int16 nPlayerIndex,

double __gc *fDuration,

enumMidiPositionUnits nPositionUnit

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontApply (

nPlayerIndex as Int16,

nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontApply (

Int16 nPlayerIndex,

Int32 nUniqueId

);

[C++]

public: enumErrorCodes SoundFontApply (

Int16 nPlayerIndex,

Int32 nUniqueId

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontDefaultConfigGet (

nUniqueId As Int32,

nPreset as Int32,

nBank as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontDefaultConfigGet (

ref Int32 nUniqueId,

ref Int32 nPreset,

ref Int32 nBank

);

[C++]

public: enumErrorCodes SoundFontDefaultConfigGet (

Int32 __gc *nUniqueId,

Int32 __gc *nPreset,

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontDefaultGet (

) as String

[C#]

public string SoundFontDefaultGet (

);

[C++]

public: string 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontDefaultSet (

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontDefaultSet (

string strPathname

);

[C++]

public: enumErrorCodes SoundFontDefaultSet (

string 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontFree (

nUniqueId As Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontFree (

Int32 nUniqueId

);

[C++]

public: enumErrorCodes SoundFontFree (

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontInfoNumGet (

nUniqueId As Int32,

nInfo as enumMidiSoundFontNumInfo,

ByRef nValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontInfoNumGet (

Int32 nUniqueId,

enumMidiSoundFontNumInfo nInfo,

ref Int32 nValue

);

[C++]

public: enumErrorCodes SoundFontInfoNumGet (

Int32 nUniqueId,

enumMidiSoundFontNumInfo nInfo,

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontInfoStringGet (

nUniqueId As Int32,

nInfo as enumMidiSoundFontStringInfo

) as String

[C#]

public string SoundFontInfoStringGet (

Int32 nUniqueId,

enumMidiSoundFontStringInfo nInfo

);

[C++]

public: string SoundFontInfoStringGet (

Int32 nUniqueId,

enumMidiSoundFontStringInfo 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontInit (

strPathname as String

) as Int32

[C#]

public Int32 SoundFontInit (

string strPathname

);

[C++]

public: Int32 SoundFontInit (

string 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 (see the LastError property for further error details)
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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontInitFromMemory (

pBuffer() as Byte,

nBufferLength as Int32

) as Int32

[C#]

public Int32 SoundFontInitFromMemory (

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: Int32 SoundFontInitFromMemory (

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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 (see the LastError property for further error details)
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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontInitFromZip (

strZipPathname as String,

strPassword as String,

strEntryName as String,

bReserved as Boolean

) as Int32

[C#]

public Int32 SoundFontInitFromZip (

string strZipPathname,

string strPassword,

string strEntryName,

bool bReserved

);

[C++]

public: Int32 SoundFontInitFromZip (

string strZipPathname,

string strPassword,

string strEntryName,

bool 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 (see the LastError property for further error details)
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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontListApply (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontListApply (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes SoundFontListApply (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.SoundFontListApplyAsDefault method

MIDI.SoundFontListApplyAsDefault method

Remarks

Applies in one single shot a list of MIDI SoundFonts as syetm 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontListApplyAsDefault (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontListApplyAsDefault (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes SoundFontListApplyAsDefault (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontListItemAdd (

nPlayerIndex as Int16,

nUniqueId As Int32,

nPreset as Int32,

nBank as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontListItemAdd (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nPreset,

Int32 nBank

);

[C++]

public: enumErrorCodes SoundFontListItemAdd (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nPreset,

Int32 nBank

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontListItemCountGet (

nPlayerIndex as Int16,

ByRef nCount As Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontListItemCountGet (

Int16 nPlayerIndex,

ref Int32 nCount

);

[C++]

public: enumErrorCodes SoundFontListItemCountGet (

Int16 nPlayerIndex,

Int32 __gc *nCount

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontListItemRemove (

nPlayerIndex as Int16,

nUniqueId As Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontListItemRemove (

Int16 nPlayerIndex,

Int32 nUniqueId

);

[C++]

public: enumErrorCodes SoundFontListItemRemove (

Int16 nPlayerIndex,

Int32 nUniqueId

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontListItemUniqueIdGet (

nPlayerIndex as Int16,

nIndex as Int32,

ByRef nUniqueId As Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontListItemUniqueIdGet (

Int16 nPlayerIndex,

Int32 nIndex,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes SoundFontListItemUniqueIdGet (

Int16 nPlayerIndex,

Int32 nIndex,

Int32 __gc *nUniqueId

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SoundFontLoad (

nUniqueId As Int32,

nPreset as Int32,

nBank as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontLoad (

Int32 nUniqueId,

Int32 nPreset,

Int32 nBank

);

[C++]

public: enumErrorCodes SoundFontLoad (

Int32 nUniqueId,

Int32 nPreset,

Int32 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontPresetDescGet (

nUniqueId As Int32,

nPreset as Int32,

nBank as Int32

) as String

[C#]

public string SoundFontPresetDescGet (

Int32 nUniqueId,

Int32 nPreset,

Int32 nBank

);

[C++]

public: string SoundFontPresetDescGet (

Int32 nUniqueId,

Int32 nPreset,

Int32 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]

Public Function SoundFontUnload (

nUniqueId As Int32,

nPreset as Int32,

nBank as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontUnload (

Int32 nUniqueId,

Int32 nPreset,

Int32 nBank

);

[C++]

public: enumErrorCodes SoundFontUnload (

Int32 nUniqueId,

Int32 nPreset,

Int32 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontVolumeGet (

nPlayerIndex as Int16,

ByRef fVolume as Single

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontVolumeGet (

Int16 nPlayerIndex,

ref float fVolume

);

[C++]

public: enumErrorCodes SoundFontVolumeGet (

Int16 nPlayerIndex,

float __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontVolumeSet (

nPlayerIndex as Int16,

fVolume as Single

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontVolumeSet (

Int16 nPlayerIndex,

float fVolume

);

[C++]

public: enumErrorCodes SoundFontVolumeSet (

Int16 nPlayerIndex,

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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontsInStreamEnum (

nPlayerIndex as Int16,

ByRef nCount As Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontsInStreamEnum (

Int16 nPlayerIndex,

ref Int32 nCount

);

[C++]

public: enumErrorCodes SoundFontsInStreamEnum (

Int16 nPlayerIndex,

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function SoundFontsInStreamItemGet (

nPlayerIndex as Int16,

nFontIndex as Int32,

ByRef nUniqueId As Int32,

ByRef nPreset as Int32,

ByRef nBank as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundFontsInStreamItemGet (

Int16 nPlayerIndex,

Int32 nFontIndex,

ref Int32 nUniqueId,

ref Int32 nPreset,

ref Int32 nBank

);

[C++]

public: enumErrorCodes SoundFontsInStreamItemGet (

Int16 nPlayerIndex,

Int32 nFontIndex,

Int32 __gc *nUniqueId,

Int32 __gc  *nPreset,

Int32 __gc *nBank

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 "true".

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]

Public Function SoundPositionGet (

nPlayerIndex as Int16,

ByRef fPosition as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C#]

public enumErrorCodes SoundPositionGet (

Int16 nPlayerIndex,

ref double fPosition,

enumMidiPositionUnits nPositionUnit

);

[C++]

public: enumErrorCodes SoundPositionGet (

Int16 nPlayerIndex,

double __gc *fPosition,

enumMidiPositionUnits nPositionUnit

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventApply (

nPlayerIndex as Int16,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Int16,

nMidiParam2 as Int16,

nMidiChannel as Int16,

bSendEventNotif as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes StreamEventApply (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

Int16 nMidiParam1,

Int16 nMidiParam2,

Int16 nMidiChannel,

bool bSendEventNotif

);

[C++]

public: enumErrorCodes StreamEventApply (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

Int16 nMidiParam1,

Int16 nMidiParam2,

Int16 nMidiChannel,

bool bSendEventNotif

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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 CallbackForMidiStreamEvents delegate.

Supported values are the following:

Value | Meaning
false | The CallbackForMidiStreamEvents delegate is not invoked after applying the MIDI event.
true | The CallbackForMidiStreamEvents delegate is invoked after applying the MIDI event.

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.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventValueGet (

nPlayerIndex as Int16,

nMidiEvent as enumMidiStreamEvents,

nOptionalKeyNoteValue as Int16

nMidiChannel as Int16,

ByRef nCurrValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamEventValueGet (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

Int16 nOptionalKeyNoteValue,

Int16 nMidiChannel,

ref Int32 nCurrValue

);

[C++]

public: enumErrorCodes StreamEventValueGet (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

Int16 nOptionalKeyNoteValue,

Int16 nMidiChannel,

Int32 __gc *nCurrValue

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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 (see the LastError property for further error details)
enumErrorCodes.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 invokes the CallbackForMidiStreamEvents delegate 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsEnableNotifications (

nPlayerIndex as Int16,

nMidiEvent as enumMidiStreamEvents,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes StreamEventsEnableNotifications (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

bool bEnable

);

[C++]

public: enumErrorCodes StreamEventsEnableNotifications (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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 CallbackForMidiStreamEvents delegate.

Supported values are the following:

Value | Meaning
false | Notification for the given event is not enabled.
true | Notification for the given event 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.


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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsEnum (

nPlayerIndex as Int16,

nTrack as Int16,

nMidiEvent as enumMidiStreamEvents,

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamEventsEnum (

Int16 nPlayerIndex,

Int16 nTrack,

enumMidiStreamEvents nMidiEvent,

ref Int32 nCount

);

[C++]

public: enumErrorCodes StreamEventsEnum (

Int16 nPlayerIndex,

Int16 nTrack,

enumMidiStreamEvents nMidiEvent,

Int32 __gc *nCount

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsEnumFromRange (

nPlayerIndex as Int16,

nTrack as Int16,

nMidiEvent as enumMidiStreamEvents,

fStartPosition as Double,

fEndPosition as Double,

nPositionUnit as enumMidiPositionUnits,

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamEventsEnumFromRange (

Int16 nPlayerIndex,

Int16 nTrack,

enumMidiStreamEvents nMidiStreamEvent,

double fStartPosition,

double fEndPosition,

enumMidiPositionUnits nPositionUnit,

ref Int32 nCount

);

[C++]

public: enumErrorCodes StreamEventsEnumFromRange (

Int16 nPlayerIndex,

Int16 nTrack,

enumMidiStreamEvents nMidiEvent,

double fStartPosition,

double fEndPosition,

enumMidiPositionUnits nPositionUnit,

Int32 __gc *nCount

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


MIDI.StreamEventsEnumItemGet method

MIDI.StreamEventsEnumItemGet 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsEnumItemGet (

nPlayerIndex as Int16,

nEventIndex as Int32,

nMidiChannel as Int32,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Int16,

nMidiParam2 as Int16,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C#]

public enumErrorCodes StreamEventsEnumItemGet (

Int16 nPlayerIndex,

Int32 nEventIndex,

ref Int32 nMidiChannel,

ref enumMidiStreamEvents nMidiEvent,

ref Int16 nMidiParam1,

ref Int16 nMidiParam2,

ref double fPosition,

enumMidiPositionUnits nPositionUnit

);

[C++]

public: enumErrorCodes StreamEventsEnumItemGet (

Int16 nPlayerIndex,

Int32 nEventIndex,

Int32 __gc *nMidiChannel,

enumMidiStreamEvents __gc *nMidiEvent,

Int16 __gc *nMidiParam1,

Int16 __gc *nMidiParam2,

double __gc *fPosition,

enumMidiPositionUnits nPositionUnit

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsListApply (

nPlayerIndex as Int16,

bSendEventNotif as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes StreamEventsListApply (

Int16 nPlayerIndex,

bool bSendEventNotif

);

[C++]

public: enumErrorCodes StreamEventsListApply (

Int16 nPlayerIndex,

bool bSendEventNotif

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.

Supported values are the following:

Value | Meaning
false | The CallbackForMidiStreamEvents delegate is not invoked for MIDI events of the list.
true | The CallbackForMidiStreamEvents delegate is invoked for MIDI events of the list.

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.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsListItemAdd (

nPlayerIndex as Int16,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Int16,

nMidiParam2 as Int16,

nMidiChannel as Int16

) as Int32

[C#]

public Int32 StreamEventsListItemAdd (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

Int16 nMidiParam1,

Int16 nMidiParam2,

Int16 nMidiChannel

);

[C++]

public: Int32 StreamEventsListItemAdd (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

Int16 nMidiParam1,

Int16 nMidiParam2,

Int16 nMidiChannel

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsListItemCountGet (

nPlayerIndex as Int16,

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamEventsListItemCountGet (

Int16 nPlayerIndex,

ref Int32 nCount

);

[C++]

public: enumErrorCodes StreamEventsListItemCountGet (

Int16 nPlayerIndex,

Int32 __gc *nCount

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsListItemGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nMidiEvent as enumMidiStreamEvents,

ByRef nMidiParam1 as Int16,

ByRef nMidiParam2 as Int16,

ByRef nMidiChannel as Int16

) as Int32

[C#]

public Int32 StreamEventsListItemGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref enumMidiStreamEvents nMidiEvent,

ref Int16 nMidiParam1,

ref Int16 nMidiParam2,

ref Int16 nMidiChannel

);

[C++]

public: Int32 StreamEventsListItemGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumMidiStreamEvents __gc *nMidiEvent,

Int16 __gc *nMidiParam1,

Int16 __gc *nMidiParam2,

Int16 __gc *nMidiChannel

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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
Value > 0 | The method call was successful and the returned value is the unique identifier of the event.


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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsListItemModify (

nPlayerIndex as Int16,

nUniqueId as Int32,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Int16,

nMidiParam2 as Int16,

nMidiChannel as Int16

) as Int32

[C#]

public Int32 StreamEventsListItemModify (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumMidiStreamEvents nMidiEvent,

Int16 nMidiParam1,

Int16 nMidiParam2,

Int16 nMidiChannel

);

[C++]

public: Int32 StreamEventsListItemModify (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumMidiStreamEvents nMidiEvent,

Int16 nMidiParam1,

Int16 nMidiParam2,

Int16 nMidiChannel

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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
Value > 0 | The method call was successful and the returned value is the unique identifier of the event.


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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsListItemRemove (

nPlayerIndex as Int16,

nUniqueId as Int32

) as Int32

[C#]

public Int32 StreamEventsListItemRemove (

Int16 nPlayerIndex,

Int32 nUniqueId

);

[C++]

public: Int32 StreamEventsListItemRemove (

Int16 nPlayerIndex,

Int32 nUniqueId

);

Parameter | Description
nPlayerIndex | 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
Value > 0 | The method call was successful and the returned value is the unique identifier of the event.


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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsListItemUniqueIdGet (

nPlayerIndex as Int16,

nIndex as Int32,

ByRef nUniqueId as Int32

) as Int32

[C#]

public Int32 StreamEventsListItemUniqueIdGet (

Int16 nPlayerIndex,

Int32 nIndex,

ref Int32 nUniqueId

);

[C++]

public: Int32 StreamEventsListItemUniqueIdGet (

Int16 nPlayerIndex,

Int32 nIndex,

Int32 __gc *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
Value > 0 | The method call was successful and the returned value is the unique identifier of the event.


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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamEventsRawApply (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

bSendEventNotif as Boolean

) as Int32

[C#]

public Int32 StreamEventsRawApply (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

bool bSendEventNotif

);

[C++]

public: Int32 StreamEventsRawApply (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

bool bSendEventNotif

);

Parameter

Description

nPlayer

Number representing the zero-based index of the involved player

pBuffer

Memory buffer containing raw MIDI events.

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 CallbackForMidiStreamEvents delegate.

Supported values are the following:

Value | Meaning
false | The CallbackForMidiStreamEvents delegate is not invoked for MIDI events of the list.
true | The CallbackForMidiStreamEvents delegate is invoked 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
Value > 0 | The method call was successful and the returned value is the unique identifier of the event.


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]

Public Function StreamPreloadSamples (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamPreloadSamples (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes StreamPreloadSamples (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamStart (

nPlayerIndex as Int16,

nFrequency as Int32,

nMidiChannels as Int16,

bMono as Boolean

nBitsPerSample as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamStart (

Int16 nPlayerIndex,

Int32 nFrequency,

Int16 nMidiChannels,

Int16 bMono,

Int16 nBitsPerSample

);

[C++]

public: enumErrorCodes StreamStart (

Int16 nPlayerIndex,

Int32 nFrequency,

Int16 nMidiChannels,

Int16 bMono,

Int16 nBitsPerSample

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | The sound stream will be in Stereo.
true | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function StreamStop (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamStop (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes StreamStop (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function TempoPercGet (

nPlayerIndex as Int16,

ByRef fPercentage as Single

) as enumErrorCodes

[C#]

public enumErrorCodes TempoPercGet (

Int16 nPlayerIndex,

ref float fPercentage

);

[C++]

public: enumErrorCodes TempoPercGet (

Int16 nPlayerIndex,

float __gc *fPercentage

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function TempoPercSet (

nPlayerIndex as Int16,

fPercentage as Single

) as enumErrorCodes

[C#]

public enumErrorCodes TempoPercSet (

Int16 nPlayerIndex,

float fPercentage

);

[C++]

public: enumErrorCodes TempoPercSet (

Int16 nPlayerIndex,

float fPercentage

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function TrackCountGet (

nPlayerIndex as Int16,

ByRef nTracks as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes TrackCountGet (

Int16 nPlayerIndex,

ref Int16 nTracks

);

[C++]

public: enumErrorCodes TrackCountGet (

Int16 nPlayerIndex,

Int16 __gc *nTracks

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function TrackTagsEnum (

nPlayerIndex as Int16,

nTrack as Int16,

ByRef nTracks as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes TrackTagsEnum (

Int16 nPlayerIndex,

Int16 nTrack,

ref Int16 nCount

);

[C++]

public: enumErrorCodes TrackTagsEnum (

Int16 nPlayerIndex,

Int16 nTrack,

Int16 __gc *nCount

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function TrackTagsItemGet (

nPlayerIndex as Int16,

nItemIndex as Int16

) as String

[C#]

public string TrackTagsItemGet (

Int16 nPlayerIndex,

Int16 nItemIndex

);

[C++]

public: string TrackTagsItemGet (

Int16 nPlayerIndex,

Int16 nItemIndex

);

Parameter | Description
nPlayerIndex | 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function TrackVolumeGet (

nPlayerIndex as Int16,

nTrack as Int16,

ByRef fTrackVolume as Single

) as enumErrorCodes

[C#]

public enumErrorCodes TrackVolumeGet (

Int16 nPlayerIndex,

Int16 nTrack,

ref float fTrackVolume

);

[C++]

public: enumErrorCodes TrackVolumeGet (

Int16 nPlayerIndex,

Int16 nTrack,

float __gc *fTrackVolume

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function TrackVolumeSet (

nPlayerIndex as Int16,

nTrack as Int16,

fTrackVolume as Single

) as enumErrorCodes

[C#]

public enumErrorCodes TrackVolumeSet (

Int16 nPlayerIndex,

Int16 nTrack,

float fTrackVolume

);

[C++]

public: enumErrorCodes TrackVolumeSet (

Int16 nPlayerIndex,

Int16 nTrack,

float fTrackVolume

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_TRIGGER_REACHED and you will be able to discriminate the specific trigger through its nData1 parameter: this parameter will match exactly the unique identification number assigned to the 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 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function TriggerAdd (

nPlayerIndex as Int16,

nTriggerID as Int16,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C#]

public enumErrorCodes TriggerAdd (

Int16 nPlayerIndex,

Int16 nTriggerID,

double fPosition,

enumMidiPositionUnits nPositionUnit

);

[C++]

public: enumErrorCodes TriggerAdd (

Int16 nPlayerIndex,

Int16 nTriggerID,

double fPosition,

enumMidiPositionUnits nPositionUnit

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


MIDI.TriggerSetPos method

MIDI.TriggerSetPos 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.

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 MIDIMan class 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]

Public Function TriggerSetPos (

nPlayerIndex as Int16,

nTriggerID as Int16,

fPosition as Double,

nPositionUnit as enumMidiPositionUnits

) as enumErrorCodes

[C#]

public enumErrorCodes TriggerSetPos (

Int16 nPlayerIndex,

Int16 nTriggerID,

double fPosition,

enumMidiPositionUnits nPositionUnit

);

[C++]

public: enumErrorCodes TriggerSetPos (

Int16 nPlayerIndex,

Int16 nTriggerID,

double fPosition,

enumMidiPositionUnits nPositionUnit

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function VoicesDefaultGet (

ByRef nVoices as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes VoicesDefaultGet (

ref Int16 nVoices

);

[C++]

public: enumErrorCodes VoicesDefaultGet (

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function VoicesDefaultSet (

nVoices as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes VoicesDefaultSet (

Int16 nVoices

);

[C++]

public: enumErrorCodes VoicesDefaultSet (

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function VoicesGet (

nPlayerIndex as Int16,

ByRef nVoices as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes VoicesGet (

Int16 nPlayerIndex,

ref Int16 nVoices

);

[C++]

public: enumErrorCodes VoicesGet (

Int16 nPlayerIndex,

Int16 __gc *nVoices

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function VoicesSet (

nPlayerIndex as Int16,

nVoices as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes VoicesSet (

Int16 nPlayerIndex,

Int16 nVoices

);

[C++]

public: enumErrorCodes VoicesSet (

Int16 nPlayerIndex,

Int16 nVoices

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


MIDI_KEYBOARD_SETTINGS structure

MIDI_KEYBOARD_SETTINGS structure

The MIDI_KEYBOARD_SETTINGS structure (defined as MIDI_KEYBOARD_SETTINGS_DLL when used for COM interoperability) 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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

C# definition

public struct MIDI_KEYBOARD_SETTINGS

{

public Color     colorBackground;

public Color     colorWhiteKeys;

public Color     colorBlackKeys;

public Color     colorWhiteKeysBorders;

public Color     colorBlackKeysBorders;

public Color     colorWhiteKeysPressed;

public Color     colorBlackKeysPressed;

public Color     colorWhiteKeysPressedBorders;

public Color     colorBlackKeysPressedBorders;

}

Definition for COM interoperability

public struct MIDI_KEYBOARD_SETTINGS_DLL

{

public Int32     colorBackground;

public Int32     colorWhiteKeys;

public Int32     colorBlackKeys;

public Int32     colorWhiteKeysBorders;

public Int32     colorBlackKeysBorders;

public Int32     colorWhiteKeysPressed;

public Int32     colorBlackKeysPressed;

public Int32     colorWhiteKeysPressedBorders;

public Int32     colorBlackKeysPressedBorders;

}

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 class

Oscilloscope class

The Oscilloscope class, accessible through the control's DisplayOscilloscope property, 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 class is implemented through the following methods and properties:

Methods

Create

CreateNew

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 audioDjStudio1 on a form or dialog and that you want to change a couple of graphic settings (Line and Background colors).

Visual Basic.NET

Here follows the code needed to perform the requested operations

' create the Oscilloscope on player 0 over an existing control

AudioDjStudio1.DisplayOscilloscope.Create(0, PictureBox1.Handle)

' set the blue color for Oscilloscope line of player 0

AudioDjStudio1.DisplayOscilloscope.set_ColorLine(0, Color.Blue)

' set the white color for Oscilloscope background of player 0

AudioDjStudio1.DisplayOscilloscope.set_ColorBackground(0, Color.White)

Visual C#.NET

Here follows the code needed to perform the requested operations

// create the Oscilloscope on player 0 over an

existing control

audioDjStudio1.DisplayOscilloscope.Create(0, pictureBox1.Handle);

// set the blue color for Oscilloscope line of player 0

audioDjStudio1.DisplayOscilloscope.set_ColorLine (0, Color.Blue);

// set the white color for Oscilloscope background of player 0

audioDjStudio1.DisplayOscilloscope.set_ColorBackground(0, Color.White);


Oscilloscope.ColorBackground property

Oscilloscope.ColorBackground property

Remarks

Determines the color of the Oscilloscope background.

Syntax

[Visual Basic]

Public Function get_ColorBackground (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorBackground (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorBackground (

Int16 nPlayerIndex

);

public void set_ColorBackground (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorBackground (

Int16 nPlayerIndex

);

public: void set_ColorBackground (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Oscilloscope
color | The new color to apply

See also

Oscilloscope class.

DisplayOscilloscope property

How to use the embedded Visual Feedbacks section.


Oscilloscope.ColorLine property

Oscilloscope.ColorLine property

Remarks

Determines the color of the Oscilloscope line.

Syntax

[Visual Basic]

Public Function get_ColorLine (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorLine (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorLine (

Int16 nPlayerIndex

);

public void set_ColorLine (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorLine (

Int16 nPlayerIndex

);

public: void set_ColorLine (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Oscilloscope
color | The new color to apply

See also

Oscilloscope class.

DisplayOscilloscope property

How to use the embedded Visual Feedbacks section.


Oscilloscope.LineWidth property

Oscilloscope.LineWidth property

Remarks

Determines the width in pixels of the Oscilloscope line.

Syntax

[Visual Basic]

Public Function get_LineWidth (

nPlayerIndex as Int16

) as Int16

Public Sub set_LineWidth (

nPlayerIndex as Int16,

nLineWidth as Int16

)

[C#]

public Int16 get_LineWidth (

Int16 nPlayerIndex

);

public void set_LineWidth (

Int16 nPlayerIndex,

Int16 nLineWidth

);

[C++]

public: Int16 get_LineWidth (

Int16 nPlayerIndex

);

public: void set_LineWidth (

Int16 nPlayerIndex,

Int16 nLineWidth

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Spectrum
nLineWidth | The new width to apply

See also

Oscilloscope class.

DisplayOscilloscope property

How to use the embedded Visual Feedbacks section.


Oscilloscope.Type property

Oscilloscope.Type property

Remarks

Determines the type of drawing used to render the Oscilloscope line.

Syntax

[Visual Basic]

Public Function get_Type (

nPlayerIndex as Int16

) as enumOscillType

Public Sub set_Type (

nPlayerIndex as Int16,

nType as enumOscillType

)

[C#]

public enumOscillType get_Type (

Int16 nPlayerIndex

);

public void set_Type (

Int16 nPlayerIndex,

enumOscillType nType

);

[C++]

public: enumOscillType get_Type (

Int16 nPlayerIndex

);

public: void set_Type (

Int16 nPlayerIndex,

enumOscillType nType

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will use the Spectrum

nType

The type of line drawing.

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 class.

DisplayOscilloscope property

How to use the embedded Visual Feedbacks section.


Oscilloscope.ZoomPerc property

Oscilloscope.ZoomPerc property

Remarks

Determines the height zoom percentage of the oscilloscope line. By default set to 100%, can assume values in the range from 5% to 500%

Syntax

[Visual Basic]

Public Function get_ZoomPerc (

nPlayerIndex as Int16

) as Int16

Public Sub set_ZoomPerc (

nPlayerIndex as Int16,

nZoomPerc as Int16

)

[C#]

public Int16 get_ZoomPerc (

Int16 nPlayerIndex

);

public void set_ZoomPerc (

Int16 nPlayerIndex,

Int16 nZoomPerc

);

[C++]

public: Int16 get_ZoomPerc (

Int16 nPlayerIndex

);

public: void set_ZoomPerc (

Int16 nPlayerIndex,

Int16 nZoomPerc

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Oscilloscope
nZoomPerc | The new zoom percentage to apply

See also

Oscilloscope class.

DisplayOscilloscope 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. For development environments like WPF, where controls don't expose a HWND, the usage of the Oscilloscope.CreateNew method should be preferred.

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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Create (

nPlayerIndex as Int16

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Oscilloscope.CreateNew method

Oscilloscope.CreateNew method

Remarks

Creates a new instance of the Oscilloscope class on the given parent window. This method is alternative to the Oscilloscope.Create method and should be used when dealing with development environments like WPF where controls don't expose a HWND.

Once created, by default the VU-Meter 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 VU-Meter refer to the Oscilloscope class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function CreateNew (

nPlayerIndex as Int16,

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the VU-Meter
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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Resize (

nPlayerIndex as Int16,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Resize (

Int16 nPlayerIndex,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Resize (

Int16 nPlayerIndex,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromFile (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromHandle (

nPlayerIndex as Int16,

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetHwnd (

nPlayerIndex as Int16

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Show (

nPlayerIndex as Int16,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

[C++]

public: enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Hides the Oscilloscope graphics
true | Shows the Oscilloscope graphics

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.


SoundComposerMan class

SoundComposerMan class

The SoundComposerMan class, accessible through the control's SoundComposer property, 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function SessionCreate (

nPlayerIndex as Int16,

nSampleRate as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SessionCreate (

Int16 nPlayerIndex,

Int32 nSampleRate,

Int32 nChannels

);

[C++]

public: enumErrorCodes SessionCreate (

Int16 nPlayerIndex,

Int32 nSampleRate,

Int32 nChannels

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function SessionAutomaticStopWhenDoneGet (

nPlayerIndex as Int16,

ByRef bAutomaticStop as bool

) as enumErrorCodes

[C#]

public enumErrorCodes SessionAutomaticStopWhenDoneGet (

Int16 nPlayerIndex,

ref bool bAutomaticStop

);

[C++]

public: enumErrorCodes SessionAutomaticStopWhenDoneGet (

Int16 nPlayerIndex,

bool __gc  *bAutomaticStop

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function SessionAutomaticStopWhenDoneSet (

nPlayerIndex as Int16,

bAutomaticStop as bool

) as enumErrorCodes

[C#]

public enumErrorCodes SessionAutomaticStopWhenDoneSet (

Int16 nPlayerIndex,

bool bAutomaticStop

);

[C++]

public: enumErrorCodes SessionAutomaticStopWhenDoneSet (

Int16 nPlayerIndex,

bool bAutomaticStop

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function SessionItemsCountGet (

nPlayerIndex as Int16,

ByRef nItems as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SessionItemsCountGet (

Int16 nPlayerIndex,

ref Int32 nItems

);

[C++]

public: enumErrorCodes SessionItemsCountGet (

Int16 nPlayerIndex,

Int32 __gc *nItems

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function SessionLoad (

nPlayerIndex as Int16,

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes SessionLoad (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes SessionLoad (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function SessionSave (

nPlayerIndex as Int16,

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes SessionSave (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes SessionSave (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemAmplitudeGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef fAmplitude as Single

) as enumErrorCodes

[C#]

public enumErrorCodes ItemAmplitudeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref float fAmplitude

);

[C++]

public: enumErrorCodes ItemAmplitudeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float __gc *fAmplitude

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemAmplitudeSet (

nPlayerIndex as Int16,

nUniqueId as Int32,

fAmplitude as Single

) as enumErrorCodes

[C#]

public enumErrorCodes ItemAmplitudeSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float fAmplitude

);

[C++]

public: enumErrorCodes ItemAmplitudeSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float fAmplitude

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemAppendNext (

nPlayerIndex as Int16,

nUniqueIdAppendTo as Int32,

nOffsetFromAppendPosInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemAppendNext (

Int16 nPlayerIndex,

Int32 nUniqueIdAppendTo,

Int32 nOffsetFromAppendPosInMs

);

[C++]

public: enumErrorCodes ItemAppendNext (

Int16 nPlayerIndex,

Int32 nUniqueIdAppendTo,

Int32 nOffsetFromAppendPosInMs

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemChannelGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nChannel as Int32,

ByRef bDownMixToMono as bool

) as enumErrorCodes

[C#]

public enumErrorCodes ItemChannelGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nChannel,

ref bool bDownMixToMono

);

[C++]

public: enumErrorCodes ItemChannelGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc *nChannel,

bool __gc  *bDownMixToMono

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemChannelSet (

nPlayerIndex as Int16,

nUniqueId as Int32,

nChannel as Int32,

bDownMixToMono as bool

) as enumErrorCodes

[C#]

public enumErrorCodes ItemChannelSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nChannel,

bool bDownMixToMono

);

[C++]

public: enumErrorCodes ItemChannelSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nChannel,

bool bDownMixToMono

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemContentGet (

nPlayerIndex as Int16,

nUniqueId as Int32

) as String

[C#]

public string ItemContentGet (

Int16 nPlayerIndex,

Int32 nUniqueId

);

[C++]

public: string ItemContentGet (

Int16 nPlayerIndex,

Int32 nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemFriendlyNameGet (

nPlayerIndex as Int16,

nUniqueId as Int32

) as String

[C#]

public string ItemFriendlyNameGet (

Int16 nPlayerIndex,

Int32 nUniqueId

);

[C++]

public: string ItemFriendlyNameGet (

Int16 nPlayerIndex,

Int32 nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemFriendlyNameSet (

nPlayerIndex as Int16,

nUniqueId as Int32,

strFriendlyName as String

) as enumErrorCodes

[C#]

public enumErrorCodes ItemFriendlyNameSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

string strFriendlyName

);

[C++]

public: enumErrorCodes ItemFriendlyNameSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

string strFriendlyName

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemInfoGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nDurationMs as Int32,

ByRef nChannelsSource as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemInfoGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nDurationMs,

ref Int32 nChannelsSource

);

[C++]

public: enumErrorCodes ItemInfoGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc *nDurationMs,

Int32 __gc *nChannelsSource

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemIsPlaying (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef bIsPlaying as bool

) as enumErrorCodes

[C#]

public enumErrorCodes ItemIsPlaying (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref bool bIsPlaying

);

[C++]

public: enumErrorCodes ItemIsPlaying (

Int16 nPlayerIndex,

Int32 nUniqueId,

bool __gc  *bIsPlaying

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemOffsetGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nOffset as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemOffsetGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nOffset

);

[C++]

public: enumErrorCodes ItemOffsetGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc *nOffset

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemOffsetSet (

nPlayerIndex as Int16,

nUniqueId as Int32,

nOffset as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemOffsetSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nOffset

);

[C++]

public: enumErrorCodes ItemOffsetSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nOffset

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemPlaybackPositionGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nPositionInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemPlaybackPositionGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nPositionInMs

);

[C++]

public: enumErrorCodes ItemPlaybackPositionGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc  *nPositionInMs

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemRemove (

nPlayerIndex as Int16,

nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemRemove (

Int16 nPlayerIndex,

Int32 nUniqueId

);

[C++]

public: enumErrorCodes ItemRemove (

Int16 nPlayerIndex,

Int32 nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSoundFileAdd (

nPlayerIndex as Int16,

strFriendlyName as String,

nChannel as Int16,

strPathname as String,

bDownMixToMonoe as bool,

nOffsetMs as Int32,

nStartPositionMs as Int32,

nEndPositionMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSoundFileAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

string strPathname,

bool bDownMixToMono,

Int32 nOffsetMs,

Int32 nStartPositionMs,

Int32 nEndPositionMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes ItemSoundFileAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

string strPathname,

bool bDownMixToMono,

Int32 nOffsetMs,

Int32 nStartPositionMs,

Int32 nEndPositionMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSoundFileMemoryAdd (

nPlayerIndex as Int16,

strFriendlyName as String,

nChannel as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

bDownMixToMono as bool,

nOffsetMs as Int32,

nStartPositionMs as Int32,

nEndPositionMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSoundFileMemoryAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

byte[] pBuffer,

Int32 nBufferLength,

bool bDownMixToMono,

Int32 nOffsetMs,

Int32 nStartPositionMs,

Int32 nEndPositionMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes ItemSoundFileMemoryAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

bool bDownMixToMono,

Int32 nOffsetMs,

Int32 nStartPositionMs,

Int32 nEndPositionMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSoundFileRawAdd (

nPlayerIndex as Int16,

strFriendlyName as String,

nChannel as Int16,

strPathname as String,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as Boolean,

nFrequency as Int32,

nChannels as Int32,

bDownMixToMono as bool,

nOffsetMs as Int32,

nStartPositionMs as Int32,

nEndPositionMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSoundFileRawAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

string strPathname,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels,

bool bDownMixToMono,

Int32 nOffsetMs,

Int32 nStartPositionMs,

Int32 nEndPositionMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes ItemSoundFileRawAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

string strPathname,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels,

bool bDownMixToMono,

Int32 nOffsetMs,

Int32 nStartPositionMs,

Int32 nEndPositionMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSoundFileMemoryRawAdd (

nPlayerIndex as Int16,

strFriendlyName as String,

nChannel as Int16,

pBuffer() as Byte,

nBufferLength as Long,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as Boolean,

nFrequency as Int32,

nChannels as Int32,

bDownMixToMono as bool,

nOffsetMs as Int32,

nStartPositionMs as Int32,

nEndPositionMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSoundFileMemoryRawAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

byte[] pBuffer,

Int32 nBufferLength,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels,

bool bDownMixToMono,

Int32 nOffsetMs,

Int32 nStartPositionMs,

Int32 nEndPositionMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes ItemSoundFileMemoryRawAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels,

bool bDownMixToMono,

Int32 nOffsetMs,

Int32 nStartPositionMs,

Int32 nEndPositionMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSoundFileLoadRangeGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nStartPositionMs as Int32,

ByRef nEndPositionMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSoundFileLoadRangeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nStartPositionMs,

ref Int32 nEndPositionMs

);

[C++]

public: enumErrorCodes ItemSoundFileLoadRangeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc  *nStartPositionMs,

Int32 __gc  *nEndPositionMs

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSoundFileRawInfoGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nEncodeMode as enumRAWEncodeModes,

ByRef bIsBigEndian as Boolean,

ByRef nFrequency as Int32,

ByRef nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSoundFileRawInfoGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref enumRAWEncodeModes nEncodeMode,

ref bool bIsBigEndian,

ref Int32 nFrequency,

ref Int32 nChannels

);

[C++]

public: enumErrorCodes ItemSoundFileRawInfoGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumRAWEncodeModes __gc *nEncodeMode,

bool __gc *bIsBigEndian,

Int32 __gc *nFrequency,

Int32 __gc *nChannels

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSoundFileVolumeSmoothingGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nSlideDurationStartMs as Int32,

ByRef nSlideDurationEndMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSoundFileVolumeSmoothingGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nSlideDurationStartMs,

ref Int32 nSlideDurationEndMs

);

[C++]

public: enumErrorCodes ItemSoundFileVolumeSmoothingGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc *nSlideDurationStartMs,

Int32 __gc *nSlideDurationEndMs

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSoundFileVolumeSmoothingSet (

nPlayerIndex as Int16,

nUniqueId as Int32,

nSlideDurationStartMs as Int32,

nSlideDurationEndMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSoundFileVolumeSmoothingSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nSlideDurationStartMs,

Int32 nSlideDurationEndMs

);

[C++]

public: enumErrorCodes ItemSoundFileVolumeSmoothingSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nSlideDurationStartMs,

Int32 nSlideDurationEndMs

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSpeechFromFileAdd (

nPlayerIndex as Int16,

strFriendlyName as String,

nChannel as Int16,

strPathname as String,

nVoice as Int32,

bRemoveFinalSilence as bool,

nOffsetMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSpeechFromFileAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

string strPathname,

Int32 nVoice,

bool bRemoveFinalSilence,

Int32 nOffsetMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes ItemSpeechFromFileAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

string strPathname,

Int32 nVoice,

bool bRemoveFinalSilence,

Int32 nOffsetMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSpeechFromStringAdd (

nPlayerIndex as Int16,

strFriendlyName as String,

nChannel as Int16,

strTextToSpeech as String,

nVoice as Int32,

bRemoveFinalSilence as bool,

nOffsetMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSpeechFromStringAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

string strTextToSpeech,

Int32 nVoice,

bool bRemoveFinalSilence,

Int32 nOffsetMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes ItemSpeechFromStringAdd (

Int16 nPlayerIndex,

string strFriendlyName,

Int16 nChannel,

string strTextToSpeech,

Int32 nVoice,

bool bRemoveFinalSilence,

Int32 nOffsetMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSpeechFileSet (

nPlayerIndex as Int16,

ByRef nUniqueId as Int32,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSpeechFileSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

string strPathname

);

[C++]

public: enumErrorCodes ItemSpeechFileSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSpeechStringSet (

nPlayerIndex as Int16,

ByRef nUniqueId as Int32,

strTextToSpeech as String

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSpeechStringSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

string strTextToSpeech

);

[C++]

public: enumErrorCodes ItemSpeechStringSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

string strTextToSpeech

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSpeechVoiceGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nVoice as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSpeechVoiceGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nVoice

);

[C++]

public: enumErrorCodes ItemSpeechVoiceGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc *nVoice

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemSpeechVoiceSet (

nPlayerIndex as Int16,

nUniqueId as Int32,

nVoice as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemSpeechVoiceSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nVoice

);

[C++]

public: enumErrorCodes ItemSpeechVoiceSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 nVoice

);

Parameter | Description
nPlayerIndex | 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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemTypeGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nType as enumPlayerSoundComposerTypes

) as enumErrorCodes

[C#]

public enumErrorCodes ItemTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref enumPlayerSoundComposerTypes nType

);

[C++]

public: enumErrorCodes ItemTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumPlayerSoundComposerTypes __gc *nType

);

Parameter

Description

nPlayerIndex

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 SoundComposerMan class and the How to compose a sound tutorial.

Syntax

[Visual Basic]

Public Function ItemUniqueIdGet (

nPlayerIndex as Int16,

nItem as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ItemUniqueIdGet (

Int16 nPlayerIndex,

Int32 nItem,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes ItemUniqueIdGet (

Int16 nPlayerIndex,

Int32 nItem,

Int32 __gc *nUniqueId

);

Parameter

Description

nPlayerIndex

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.


SoundGeneratorMan class

SoundGeneratorMan class

The SoundGeneratorMan class, accessible through the control's SoundGenerator property, contains methods needed to generate several kinds of sounds like wave tones, noises, DTMF tones and text to speech.

The SoundGeneratorMan class 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 through the SoundGeneratorMan object in Visual C# and Visual Basic.NET 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.

For further details about sound generation see the SoundGeneratorMan class and the How to generate wave tones, noises, DTMF tones and text to speech tutorial.

Syntax

[Visual Basic]

Public Function SpeechVoicesNumGet (

ByRef nVoices as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SpeechVoicesNumGet (

ref Int32 nVoices

);

[C++]

public: enumErrorCodes SpeechVoicesNumGet (

Int32 __gc  *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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SpeechVoiceAttributeGet (

nVoice as Int32,

nAttribute as enumSapiVoiceAttributes

) as String

[C#]

public string SpeechVoiceAttributeGet (

Int32 nVoice,

enumSapiVoiceAttributes nAttribute

);

[C++]

public: string SpeechVoiceAttributeGet (

Int32 nVoice,

enumSapiVoiceAttributes 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]

Public Function StreamChannelAddDtmfString (

nPlayerIndex as Int16,

nChannel as Int16,

strDtmf as String,

nToneDurationMs as Int32,

nSilenceDurationMs as Int32,

nOffsetMs as Int32,

nFadeInMs as Int32,

nFadeOutMs as Int32,

fAmplitude as Single,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelAddDtmfString (

Int16 nPlayerIndex,

Int16 nChannel,

string strDtmf,

Int32 nToneDurationMs,

Int32 nSilenceDurationMs,

Int32 nOffsetMs,

Int32 nFadeInMs,

Int32 nFadeOutMs,

float fAmplitude,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes StreamChannelAddDtmfString (

Int16 nPlayerIndex,

Int16 nChannel,

string strDtmf,

Int32 nToneDurationMs,

Int32 nSilenceDurationMs,

Int32 nOffsetMs,

Int32 nFadeInMs,

Int32 nFadeOutMs,

float fAmplitude,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelAddNoise (

nPlayerIndex as Int16,

nChannel as Int16,

nNoiseType as enumSoundGenNoiseTypes,

fReserved as Single,

fAmplitude as Single,

nDurationMs as Int32,

nOffsetMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelAddNoise (

Int16 nPlayerIndex,

Int16 nChannel,

enumSoundGenNoiseTypes nNoiseType,

float fReserved,

float fAmplitude,

Int32 nDurationMs,

Int32 nOffsetMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes StreamChannelAddNoise (

Int16 nPlayerIndex,

Int16 nChannel,

enumSoundGenNoiseTypes nNoiseType,

float fReserved,

float fAmplitude,

Int32 nDurationMs,

Int32 nOffsetMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelAddSlidingTone (

nPlayerIndex as Int16,

nChannel as Int16,

nWaveType as enumSoundGenSlidingWaveTypes,

fFrequencyStart as Single,

fFrequencyEnd as Single,

fAmplitudeStart as Single,

fAmplitudeEnd as Single,

bLogInterpolation as bool,

nDurationMs as Int32,

nOffsetMs as Int32,

nFadeInMs as Int32,

nFadeOutMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelAddSlidingTone (

Int16 nPlayerIndex,

Int16 nChannel,

enumSoundGenSlidingWaveTypes nWaveType,

float fFrequencyStart,

float fFrequencyEnd,

float fAmplitudeStart,

float fAmplitudeEnd,

bool bLogInterpolation,

Int32 nDurationMs,

Int32 nOffsetMs,

Int32 nFadeInMs,

Int32 nFadeOutMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes StreamChannelAddSlidingTone (

Int16 nPlayerIndex,

Int16 nChannel,

enumSoundGenSlidingWaveTypes nWaveType,

float fFrequencyStart,

float fFrequencyEnd,

float fAmplitudeStart,

float fAmplitudeEnd,

bool bLogInterpolation,

Int32 nDurationMs,

Int32 nOffsetMs,

Int32 nFadeInMs,

Int32 nFadeOutMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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
false | Uses linear interpolation
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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelAddSpeechFromFile (

nPlayerIndex as Int16,

nChannel as Int16,

strPathname as String,

nVoice as Int32,

fAmplitude as Single,

nOffsetMs as Int32,

bRemoveFinalSilence as bool,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelAddSpeechFromFile (

Int16 nPlayerIndex,

Int16 nChannel,

string strPathname,

Int32 nVoice,

float fAmplitude,

Int32 nOffsetMs,

bool bRemoveFinalSilence,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes StreamChannelAddSpeechFromFile (

Int16 nPlayerIndex,

Int16 nChannel,

string strPathname,

Int32 nVoice,

float fAmplitude,

Int32 nOffsetMs,

bool bRemoveFinalSilence,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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
false | Don't remove final silence
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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelAddSpeechFromString (

nPlayerIndex as Int16,

nChannel as Int16,

strTextToSpeech as String,

nVoice as Int32,

fAmplitude as Single,

nOffsetMs as Int32,

bRemoveFinalSilence as bool,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelAddSpeechFromString (

Int16 nPlayerIndex,

Int16 nChannel,

string strTextToSpeech,

Int32 nVoice,

float fAmplitude,

Int32 nOffsetMs,

bool bRemoveFinalSilence,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes StreamChannelAddSpeechFromString (

Int16 nPlayerIndex,

Int16 nChannel,

string strTextToSpeech,

Int32 nVoice,

float fAmplitude,

Int32 nOffsetMs,

bool bRemoveFinalSilence,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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
false | Don't remove final silence
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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelAddTone (

nPlayerIndex as Int16,

nChannel as Int16,

nWaveType as enumSoundGenWaveTypes,

fFrequency as Single,

fAmplitude as Single,

nDurationMs as Int32,

nOffsetMs as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelAddTone (

Int16 nPlayerIndex,

Int16 nChannel,

enumSoundGenWaveTypes nWaveType,

float fFrequency,

float fAmplitude,

Int32 nDurationMs,

Int32 nOffsetMs,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes StreamChannelAddTone (

Int16 nPlayerIndex,

Int16 nChannel,

enumSoundGenWaveTypes nWaveType,

float fFrequency,

float fAmplitude,

Int32 nDurationMs,

Int32 nOffsetMs,

Int32 __gc  *nUniqueId

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelElementsCountGet (

nPlayerIndex as Int16,

nChannel as Int16,

ByRef nElements as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelElementsCountGet (

Int16 nPlayerIndex,

Int16 nChannel,

ref Int32 nElements

);

[C++]

public: enumErrorCodes StreamChannelElementsCountGet (

Int16 nPlayerIndex,

Int16 nChannel,

Int32 __gc *nElements,

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelElementUniqueIdGet (

nPlayerIndex as Int16,

nChannel as Int16,

nElement as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelElementUniqueIdGet (

Int16 nPlayerIndex,

Int16 nChannel,

Int32 nElement,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes StreamChannelElementUniqueIdGet (

Int16 nPlayerIndex,

Int16 nChannel,

Int32 nElement,

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelEmpty (

nPlayerIndex as Int16,

nChannel as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamChannelEmpty (

Int16 nPlayerIndex,

Int16 nChannel

);

[C++]

public: enumErrorCodes StreamChannelEmpty (

Int16 nPlayerIndex,

Int16 nChannel

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamChannelIsEmpty (

nPlayerIndex as Int16,

nChannel as Int16

) as bool

[C#]

public bool StreamChannelIsEmpty (

Int16 nPlayerIndex,

Int16 nChannel

);

[C++]

public: bool StreamChannelIsEmpty (

Int16 nPlayerIndex,

Int16 nChannel

);

Parameter | Description
nPlayerIndex | 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]

Public Function StreamCreateDtmfString (

nPlayerIndex as Int16,

nSampleRate as Int32,

bMono as bool,

strDtmf as String,

nToneDurationMs as Int32,

nSilenceDurationMs as Int32,

nFadeInMs as Int32,

nFadeOutMs as Int32,

fAmplitude as Single

) as enumErrorCodes

[C#]

public enumErrorCodes StreamCreateDtmfString (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

string strDtmf,

Int32 nToneDurationMs,

Int32 nSilenceDurationMs,

Int32 nFadeInMs,

Int32 nFadeOutMs,

float fAmplitude

);

[C++]

public: enumErrorCodes StreamCreateDtmfString (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

string strDtmf,

Int32 nToneDurationMs,

Int32 nSilenceDurationMs,

Int32 nFadeInMs,

Int32 nFadeOutMs,

float fAmplitude

);

Parameter

Description

nPlayerIndex

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
false | Creates a stereo audio stream
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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamCreateMultiChannelEmpty (

nPlayerIndex as Int16,

nSampleRate as Int32,

nChannels as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes StreamCreateMultiChannelEmpty (

Int16 nPlayerIndex,

Int32 nSampleRate,

Int16 nChannels

);

[C++]

public: enumErrorCodes StreamCreateMultiChannelEmpty (

Int16 nPlayerIndex,

Int32 nSampleRate,

Int16 nChannels

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamCreateNoise (

nPlayerIndex as Int16,

nSampleRate as Int32,

bMono as bool,

nNoiseType as enumSoundGenNoiseTypes,

fReserved as Single,

fAmplitude as Single,

nDurationMs as Int32,

nFadeInMs as Int32,

nFadeOutMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamCreateNoise (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

enumSoundGenNoiseTypes nNoiseType,

float fReserved,

float fAmplitude,

Int32 nDurationMs,

Int32 nFadeInMs,

Int32 nFadeOutMs

);

[C++]

public: enumErrorCodes StreamCreateNoise (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

enumSoundGenNoiseTypes nNoiseType,

float fReserved,

float fAmplitude,

Int32 nDurationMs,

Int32 nFadeInMs,

Int32 nFadeOutMs

);

Parameter

Description

nPlayerIndex

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
false | Creates a stereo audio stream
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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamCreateSlidingTone (

nPlayerIndex as Int16,

nSampleRate as Int32,

bMono as bool,

nWaveType as enumSoundGenSlidingWaveTypes,

fFrequencyStart as Single,

fFrequencyEnd as Single,

fAmplitudeStart as Single,

fAmplitudeEnd as Single,

bLogInterpolation as bool,

nDurationMs as Int32,

nFadeInMs as Int32,

nFadeOutMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamCreateSlidingTone (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

enumSoundGenSlidingWaveTypes nWaveType,

float fFrequencyStart,

float fFrequencyEnd,

float fAmplitudeStart,

float fAmplitudeEnd,

bool bLogInterpolation,

Int32 nDurationMs,

Int32 nFadeInMs,

Int32 nFadeOutMs

);

[C++]

public: enumErrorCodes StreamCreateSlidingTone (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

enumSoundGenSlidingWaveTypes nWaveType,

float fFrequencyStart,

float fFrequencyEnd,

float fAmplitudeStart,

float fAmplitudeEnd,

bool bLogInterpolation,

Int32 nDurationMs,

Int32 nFadeInMs,

Int32 nFadeOutMs

);

Parameter

Description

nPlayerIndex

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
false | Creates a stereo audio stream
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 attenuates the sound volume

- value 1.0 sets the sound at full volume

- values higher than 1.0 amplifies the sound volume

bLogInterpolation

Boolean value indicating if the sliding should use linear or logarithmic interpolation.

Supported values are the following:

Mnemonic Value | Meaning
false | Uses linear interpolation
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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamCreateSpeechFromFile (

nPlayerIndex as Int16,

nSampleRate as Int32,

bMono as bool,

strPathname as String,

nVoice as Int32,

fAmplitude as Single,

bRemoveFinalSilence as bool

) as enumErrorCodes

[C#]

public enumErrorCodes StreamCreateSpeechFromFile (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

string strPathname,

Int32 nVoice,

float fAmplitude,

bool bRemoveFinalSilence

);

[C++]

public: enumErrorCodes StreamCreateSpeechFromString (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

string strPathname,

Int32 nVoice,

float fAmplitude,

bool bRemoveFinalSilence

);

Parameter

Description

nPlayerIndex

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
false | Creates a stereo audio stream
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
false | Don't remove final silence
true | Remove final silence

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.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]

Public Function StreamCreateSpeechFromString (

nPlayerIndex as Int16,

nSampleRate as Int32,

bMono as bool,

strTextToSpeech as String,

nVoice as Int32,

fAmplitude as Single,

bRemoveFinalSilence as bool

) as enumErrorCodes

[C#]

public enumErrorCodes StreamCreateSpeechFromString (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

string strTextToSpeech,

Int32 nVoice,

float fAmplitude,

bool bRemoveFinalSilence

);

[C++]

public: enumErrorCodes StreamCreateSpeechFromString (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

string strTextToSpeech,

Int32 nVoice,

float fAmplitude,

bool bRemoveFinalSilence

);

Parameter

Description

nPlayerIndex

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
false | Creates a stereo audio stream
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
false | Don't remove final silence
true | Remove final silence

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.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]

Public Function StreamCreateTone (

nPlayerIndex as Int16,

nSampleRate as Int32,

bMono as bool,

nWaveType as enumSoundGenWaveTypes,

fFrequency as Single,

fAmplitude as Single,

nDurationMs as Int32,

nFadeInMs as Int32,

nFadeOutMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamCreateTone (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

enumSoundGenWaveTypes nWaveType,

float fFrequency,

float fAmplitude,

Int32 nDurationMs,

Int32 nFadeInMs,

Int32 nFadeOutMs

);

[C++]

public: enumErrorCodes StreamCreateTone (

Int16 nPlayerIndex,

Int32 nSampleRate,

bool bMono,

enumSoundGenWaveTypes nWaveType,

float fFrequency,

float fAmplitude,

Int32 nDurationMs,

Int32 nFadeInMs,

Int32 nFadeOutMs

);

Parameter

Description

nPlayerIndex

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
false | Creates a stereo audio stream
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

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementAmplitudeGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef fAmplitude as Single

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementAmplitudeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref float fAmplitude

);

[C++]

public: enumErrorCodes StreamElementAmplitudeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float __gc *fAmplitude

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementAmplitudeSet (

nPlayerIndex as Int16,

nUniqueId as Int32,

fAmplitude as Single

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementAmplitudeSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float fAmplitude

);

[C++]

public: enumErrorCodes StreamElementAmplitudeSet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float fAmplitude

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementDtmfStringGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nToneDurationMs as Int32,

ByRef nSilenceDurationMs as Int32,

ByRef nFadeInMs as Int32,

ByRef nFadeOutMs as Int32

) as String

[C#]

public string StreamElementDtmfStringGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nToneDurationMs,

ref Int32 nSilenceDurationMs,

ref Int32 nFadeInMs,

ref Int32 nFadeOutMs

);

[C++]

public: string StreamElementDtmfStringGet (

Int16 nPlayerIndex,,

Int32 nUniqueId,

Int32 __gc  *nToneDurationMs,

Int32 __gc  *nSilenceDurationMs

Int32 __gc  *nFadeInMs,

Int32 __gc  *nFadeOutMs

);

Parameter | Description
nPlayerIndex | 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]

Public Function StreamElementDurationGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nDurationMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementDurationGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nDurationMs

);

[C++]

public: enumErrorCodes StreamElementDurationGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc *nDurationMs

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementNoiseTypeGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nType as enumSoundGenNoiseTypes

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementNoiseTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref enumSoundGenNoiseTypes nType

);

[C++]

public: enumErrorCodes StreamElementNoiseTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumSoundGenNoiseTypes __gc *nType

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementOffsetGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nOffsetMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementOffsetGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nOffsetMs

);

[C++]

public: enumErrorCodes StreamElementOffsetGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc *nOffsetMs

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementRemove (

nPlayerIndex as Int16,

nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementRemove (

Int16 nPlayerIndex,

Int32 nUniqueId

);

[C++]

public: enumErrorCodes StreamElementRemove (

Int16 nPlayerIndex,

Int32 nUniqueId

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementSlidingToneLimitsGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef fFrequencyStart as Single,

ByRef fFrequencyEnd as Single,

ByRef fAmplitudeStart as Single,

ByRef fAmplitudeEnd as Single

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementSlidingToneLimitsGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref float fFrequencyStart,

ref float fFrequencyEnd,

ref float fAmplitudeStart,

ref float fAmplitudeEnd

);

[C++]

public: enumErrorCodes StreamElementSlidingToneLimitsGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float __gc *fFrequencyStart,

float __gc *fFrequencyEnd,

float __gc *fAmplitudeStart,

float __gc *fAmplitudeEnd

);

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementSlidingToneTypeGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nType as enumSoundGenSlidingWaveTypes

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementSlidingToneTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref enumSoundGenSlidingWaveTypes nType

);

[C++]

public: enumErrorCodes StreamElementSlidingToneTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumSoundGenSlidingWaveTypes __gc *nType

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementSpeechTextGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef bIsFile as bool

) as String

[C#]

public string StreamElementSpeechTextGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref bool bIsFile

);

[C++]

public: string StreamElementSpeechTextGet (

Int16 nPlayerIndex,,

Int32 nUniqueId,

bool __gc  *bIsFile

);

Parameter

Description

nPlayerIndex

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
false | The returned string represents the text to speech
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]

Public Function StreamElementSpeechVoiceGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nVoice as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementSpeechVoiceGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref Int32 nVoice

);

[C++]

public: enumErrorCodes StreamElementSpeechVoiceGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

Int32 __gc *nVoice

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementToneFrequencyGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef fFrequency as Single

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementToneFrequencyGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref float fFrequency

);

[C++]

public: enumErrorCodes StreamElementToneFrequencyGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float __gc *fFrequency

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function StreamElementToneFrequencySet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef fFrequency as Single

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementToneFrequencySet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref float fFrequency

);

[C++]

public: enumErrorCodes StreamElementToneFrequencySet (

Int16 nPlayerIndex,

Int32 nUniqueId,

float __gc *fFrequency

);

Parameter | Description
nPlayerIndex | 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 | The wave tone frequency expressed in Hertz

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.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]

Public Function StreamElementToneTypeGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

ByRef nType as enumSoundGenWaveTypes

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementToneTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref enumSoundGenWaveTypes nType

);

[C++]

public: enumErrorCodes StreamElementToneTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumSoundGenWaveTypes __gc *nType

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


SoundGenerator.StreamElementTypeGet method

SoundGenerator.StreamElementTypeGet 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]

Public Function StreamElementTypeGet (

nPlayerIndex as Int16,

nUniqueId as Int32,

nType as enumSoundGeneratorTypes

) as enumErrorCodes

[C#]

public enumErrorCodes StreamElementTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

ref enumSoundGeneratorTypes nType

);

[C++]

public: enumErrorCodes StreamElementTypeGet (

Int16 nPlayerIndex,

Int32 nUniqueId,

enumSoundGeneratorTypes __gc *nType

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Spectrum class

Spectrum class

The Spectrum class, accessible through the control's DisplaySpectrum property, 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 class is implemented through the following methods and properties:

Methods

Create

CreateNew

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 audioDjStudio1 on a form or dialog and that you want to change a couple of graphic settings (Bands and Background colors).

Visual Basic.NET

Here follows the code needed to perform the requested operations

' create the spectrum on player 0 over an existing control

AudioDjStudio1.DisplaySpectrum.Create(0, PictureBox1.Handle)

' set the blue color for spectrum bands of player 0

AudioDjStudio1.DisplaySpectrum.set_ColorBands(0, Color.Blue)

' set the white color for spectrum background of player 0

AudioDjStudio1.DisplaySpectrum.set_ColorBackground(0, Color.White)

Visual C#.NET

Here follows the code needed to perform the requested operations

// create the spectrum on player 0 over an existing control

audioDjStudio1.DisplaySpectrum.Create(0, pictureBox1.Handle);

// set the blue color for spectrum bands of player 0

audioDjStudio1.DisplaySpectrum.set_ColorBands (0, Color.Blue);

// set the white color for spectrum background of player 0

audioDjStudio1.DisplaySpectrum.set_ColorBackground(0, Color.White);


Spectrum.BandsWidth property

Spectrum.BandsWidth property

Remarks

Gets/sets the width in pixel of each single band composing the Spectrum visual feedback.

Syntax

[Visual Basic]

Public Function get_BandsWidth (

nPlayerIndex as Int16

) as Int16

Public Sub set_BandsWidth (

nPlayerIndex as Int16,

nBandsWidth as Int16

)

[C#]

public Int16 get_BandsWidth (

Int16 nPlayerIndex

);

public void set_BandsWidth (

Int16 nPlayerIndex,

Int16 nBandsWidth

);

[C++]

public: Int16 get_BandsWidth (

Int16 nPlayerIndex

);

public: void set_BandsWidth (

Int16 nPlayerIndex,

Int16 nBandsWidth

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Spectrum
nBandsWidth | The new width expressed in pixels

See also

Spectrum class.

DisplaySpectrum property

How to use the embedded Visual Feedbacks section.


Spectrum.ColorBackground property

Spectrum.ColorBackground property

Remarks

Determines the color of the Spectrum background.

Syntax

[Visual Basic]

Public Function get_ColorBackground (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorBackground (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorBackground (

Int16 nPlayerIndex

);

public void set_ColorBackground (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorBackground (

Int16 nPlayerIndex

);

public: void set_ColorBackground (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Spectrum
color | The new color to apply

See also

Spectrum class.

DisplaySpectrum property

How to use the embedded Visual Feedbacks section.


Spectrum.ColorBands property

Spectrum.ColorBands property

Remarks

Determines the spectrum "bands" color.

Syntax

[Visual Basic]

Public Function get_ColorBands (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorBands (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorBands (

Int16 nPlayerIndex

);

public void set_ColorBands (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorBands (

Int16 nPlayerIndex

);

public: void set_ColorBands (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Spectrum
color | The new color to apply

See also

Spectrum class.

DisplaySpectrum property

How to use the embedded Visual Feedbacks section.


Spectrum.ColorPeaks property

Spectrum.ColorPeaks property

Remarks

Determines the Spectrum "peaks" color.

Syntax

[Visual Basic]

Public Function get_ColorPeaks (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorPeaks (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorPeaks (

Int16 nPlayerIndex

);

public void set_ColorPeaks (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorPeaks (

Int16 nPlayerIndex

);

public: void set_ColorPeaks (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Spectrum
color | The new color to apply

See also

Spectrum class.

DisplaySpectrum property

How to use the embedded Visual Feedbacks section.


Spectrum.HasPeaks property

Spectrum.HasPeaks property

Remarks

Determines if the embedded Spectrum visual feedback will display graphic "peaks" over the "bands".

Syntax

[Visual Basic]

Public Function get_HasPeaks (

nPlayerIndex as Int16

) as Boolean

Public Sub set_HasPeaks (

nPlayerIndex as Int16,

bHasPeaks as Boolean

)

[C#]

public bool get_HasPeaks (

Int16 nPlayerIndex

);

public void set_HasPeaks (

Int16 nPlayerIndex,

bool bHasPeaks

);

[C++]

public: bool get_HasPeaks (

Int16 nPlayerIndex

);

public: void set_HasPeaks (

Int16 nPlayerIndex,

bool bHasPeaks

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will use the Spectrum

bHasPeaks

Mnemonic value | Meaning
false | No peaks
true (default) | Visible peaks

See also

Spectrum class.

DisplaySpectrum property

How to use the embedded Visual Feedbacks section.


Spectrum.UseLogarithmic property

Spectrum.HasPeaks property

Remarks

Specifies 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.

Syntax

[Visual Basic]

Public Function get_UseLogarithmic (

nPlayerIndex as Int16

) as Boolean

Public Sub set_UseLogarithmic (

nPlayerIndex as Int16,

bUseLogarithmic as Boolean

)

[C#]

public bool get_UseLogarithmic (

Int16 nPlayerIndex

);

public void set_UseLogarithmic (

Int16 nPlayerIndex,

bool bUseLogarithmic

);

[C++]

public: bool get_UseLogarithmic (

Int16 nPlayerIndex

);

public: void set_UseLogarithmic (

Int16 nPlayerIndex,

bool bUseLogarithmic

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will use the Spectrum

bUseLogarithmic

Specifies 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.

Supported values are the following:

Mnemonic value | Meaning
false | Use normal FFT calculation
true (default) | Use logarithmic calculation

See also

Spectrum class.

DisplaySpectrum property

How to use the embedded Visual Feedbacks section.


Spectrum.ZoomPerc property

Spectrum.ZoomPerc property

Remarks

Determines the height zoom percentage of bands. By default set to 100%, can assume values in the range from 5% to 500%

Syntax

[Visual Basic]

Public Function get_ZoomPerc (

nPlayerIndex as Int16

) as Int16

Public Sub set_ZoomPerc (

nPlayerIndex as Int16,

nZoomPerc as Int16

)

[C#]

public Int16 get_ZoomPerc (

Int16 nPlayerIndex

);

public void set_ZoomPerc (

Int16 nPlayerIndex,

Int16 nZoomPerc

);

[C++]

public: Int16 get_ZoomPerc (

Int16 nPlayerIndex

);

public: void set_ZoomPerc (

Int16 nPlayerIndex,

Int16 nZoomPerc

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Oscilloscope
nZoomPerc | The new zoom percentage to apply

See also

Spectrum class.

DisplaySpectrum 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. For development environments like WPF, where controls don't expose a HWND, the usage of the Spectrum.CreateNew method should be preferred.

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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Create (

nPlayerIndex as Int16,

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 CallbackForPlayersEvents delegate having the nEvent parameter set to EV_SPECTRUM_CHANGE, allowing to render your custom spectrum graphics after calling the Spectrum.GetTable 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.


Spectrum.CreateNew method

Spectrum.CreateNew method

Remarks

Creates a new instance of the Spectrum class on the given parent window. This method is alternative to the Spectrum.Create method and should be used when dealing with development environments like WPF where controls don't expose a HWND.

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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function CreateNew (

nPlayerIndex as Int16,

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Spectrum.
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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.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 the CallbackForPlayersEvents delegate is invoked having the nEvent parameter set to EV_SPECTRUM_CHANGE

For further details about using the embedded Spectrum refer to the Spectrum class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function GetTable (

nPlayerIndex as Int16,

tableValues() as Int16,

nTableLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetTable (

Int16 nPlayerIndex,

Int16 [] tableValues,

Int32 nTableLength

);

[C++]

public: enumErrorCodes GetTable (

Int16 nPlayerIndex,

unsigned Int16 __gc[] tableValues,

Int32 nTableLength

);

Parameter | Description
nPlayerIndex | 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 last error.
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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Resize (

nPlayerIndex as Int16,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Resize (

Int16 nPlayerIndex,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Resize (

Int16 nPlayerIndex,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromFile (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromHandle (

nPlayerIndex as Int16,

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetHwnd (

nPlayerIndex as Int16,

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetNumberOfBands (

nPlayerIndex as Int16,

nBands as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SetNumberOfBands (

Int16 nPlayerIndex,

Int16 nBands

);

[C++]

public: enumErrorCodes SetNumberOfBands (

Int16 nPlayerIndex,

Int16 nBands

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Show (

nPlayerIndex as Int16,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

[C++]

public: enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Hides the Spectrum graphics
true | Shows the Spectrum graphics

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.


SpectrumEnh class

SpectrumEnh class

The SpectrumEnh class, accessible through the control's DisplaySpectrumEnh property, 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 class 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: being a graphical object, the spectrum analyzer 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 SpectrumEnh.SetHwnd method. For development environments like WPF, where controls don't expose a HWND, the usage of the SpectrumEnh.CreateNew method should be preferred.

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 embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class 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 Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Create (

nPlayerIndex as Int16,

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 graphics of the spectrum analyzer. This parameter cannot be set to NULL or 0.

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.CreateNew method

SpectrumEnh.CreateNew method

Remarks

Creates a new instance of the SpectrumEnh class on the given parent window. This method is alternative to the SpectrumEnh.Create method and should be used when dealing with development environments like WPF where controls don't expose a HWND.

Once created, by default the 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 Spectrum for each of the allocated players.

For further details about using the embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class 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 Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function CreateNew (

nPlayerIndex as Int16,

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the spectrum analyzer.
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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.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 embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class 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 Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Move (

nPlayerIndex as Int16,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Move (

Int16 nPlayerIndex,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Move (

Int16 nPlayerIndex,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class 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 Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromFile (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class 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 Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromHandle (

nPlayerIndex as Int16,

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class 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 Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetHwnd (

nPlayerIndex as Int16,

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 or SpectrumEnh.CreateNew method.

For further details about using the embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class 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 Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Show (

nPlayerIndex as Int16,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

[C++]

public: enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Hides the spectrum analyzer graphics
true | Shows the spectrum analyzer graphics

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.


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]

Public Function SettingsGeneralGet (

nPlayerIndex as Int16,

ByRef settings as SPECTR_ENH_GENERAL_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsGeneralGet (

Int16 nPlayerIndex,

ref SPECTR_ENH_GENERAL_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsGeneralGet (

Int16 nPlayerIndex,

SPECTR_ENH_GENERAL_SETTINGS __gc *settings

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the spectrum analyzer
settings | Reference 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]

Public Function SettingsGeneralSet (

nPlayerIndex as Int16,

settings as SPECTR_ENH_GENERAL_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsGeneralSet (

Int16 nPlayerIndex,

SPECTR_ENH_GENERAL_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsGeneralSet (

Int16 nPlayerIndex,

SPECTR_ENH_GENERAL_SETTINGS settings

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the spectrum analyzer
settings | 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]

Public Function SettingsRulersGet (

nPlayerIndex as Int16,

ByRef settings as SPECTR_ENH_RULERS_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsRulersGet (

Int16 nPlayerIndex,

ref SPECTR_ENH_RULERS_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsRulersGet (

Int16 nPlayerIndex,

SPECTR_ENH_RULERS_SETTINGS __gc *settings

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the spectrum analyzer
settings | Reference 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]

Public Function SettingsRulersSet (

nPlayerIndex as Int16,

settings as SPECTR_ENH_RULERS_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsRulersSet (

Int16 nPlayerIndex,

SPECTR_ENH_RULERS_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsRulersSet (

Int16 nPlayerIndex,

SPECTR_ENH_RULERS_SETTINGS settings

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the spectrum analyzer
settings | 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]

Public Function SettingsWaveGet (

nPlayerIndex as Int16,

ByRef settings as SPECTR_ENH_WAVE_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsWaveGet (

Int16 nPlayerIndex,

ref SPECTR_ENH_WAVE_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsWaveGet (

Int16 nPlayerIndex,

SPECTR_ENH_WAVE_SETTINGS __gc *settings

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the spectrum analyzer
settings | Reference 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]

Public Function SettingsWaveSet (

nPlayerIndex as Int16,

settings as SPECTR_ENH_WAVE_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsWaveSet (

Int16 nPlayerIndex,

SPECTR_ENH_WAVE_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsWaveSet (

Int16 nPlayerIndex,

SPECTR_ENH_WAVE_SETTINGS settings

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the spectrum analyzer
settings | 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 structure (defined as SPECTR_ENH_GENERAL_SETTINGS_DLL when used for COM interoperability) 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 embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

C# definition

public struct SPECTR_ENH_GENERAL_SETTINGS

{

 public bool                       bAppearance3d;

 public Int32                     nResolution;

 public enumSpectrumEnhTypes       nGraphType;

 public enumSpectrumEnhWindowTypes nFFTWindowType;

 public bool                       bFreqGridVisible;

 public bool                       bDbGridVisible;

 public bool                       bSubGridVisible;

 public bool                       bBackBitmapVisible;

 public bool                       bBackBitmapStretch;

 public Color                     colorBackground;

 public Color                     colorFreqGrid;

 public Color                     colorDbGrid;

 public Color                     colorSubGrid;

}

Definition for COM interoperability

public struct SPECTR_ENH_GENERAL_SETTINGS_DLL

{

 public Int16                     bAppearance3d;

 public Int32                     nResolution;

 public Int32                     nGraphType;

 public Int32                     nFFTWindowType;

 public Int16                     bFreqGridVisible;

 public Int16                     bDbGridVisible;

 public Int16                     bSubGridVisible;

 public Int16                     bBackBitmapVisible;

 public Int16                     bBackBitmapStretch;

 public Int32                     colorBackground;

 public Int32                     colorFreqGrid;

 public Int32                     colorDbGrid;

 public Int32                     colorSubGrid;

}

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 with some of the configurable elements evidenced:


SPECTR_ENH_RULERS_SETTINGS structure

SPECTR_ENH_RULERS_SETTINGS structure

The SPECTR_ENH_RULERS_SETTINGS structure (defined as SPECTR_ENH_RULERS_SETTINGS_DLL when used for COM interoperability) describes the graphical 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 embedded Enhanced Spectrum Analyzer refer to the SpectrumEnh class section.

For details about using the Enhanced Spectrum Analyzer refer to the How to use the Enhanced Spectrum Analyzer tutorial.

C# definition

public struct SPECTR_ENH_RULERS_SETTINGS

{

 public bool   bLinearScale;

 public bool   bScaleTopVisible;

 public bool   bScaleBottomVisible;

 public bool   bScaleLeftVisible;

 public bool   bScaleRightVisible;

 public Color colorBackground;

 public Color colorTicks;

 public Color colorText;

}

Definition for COM interoperability

public struct SPECTR_ENH_RULERS_SETTINGS_DLL

{

 public Int16 bLinearScale;

 public Int16 bScaleTopVisible;

 public Int16 bScaleBottomVisible;

 public Int16 bScaleLeftVisible;

 public Int16 bScaleRightVisible;

 public Int32 colorBackground;

 public Int32 colorTicks;

 public Int32 colorText;

}

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 (defined as SPECTR_ENH_WAVE_SETTINGS_DLL when used for COM interoperability) 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.

C# definition

public struct SPECTR_ENH_WAVE_SETTINGS

{

 public Int16 nAreaTransparency;

 public bool   bClearSpectralViewOnEnd;

 public Color colorLineTopLeftChan;

 public Color colorLineTopRightChan;

 public Color colorLineCoveredLeftChan;

 public Color colorLineCoveredRightChan;

 public Color colorAreaLeftChan;

 public Color colorAreaRightChan;

 public Color colorAreaCoveredLeftChan;

 public Color colorAreaCoveredRightChan;

 public Color colorVertLineSpectralView;

}

Definition for COM interoperability

public struct SPECTR_ENH_WAVE_SETTINGS_DLL

{

 public Int16 nAreaTransparency;

 public Int16 bClearSpectralViewOnEnd;

 public Int32 colorLineTopLeftChan;

 public Int32 colorLineTopRightChan;

 public Int32 colorLineCoveredLeftChan;

 public Int32 colorLineCoveredRightChan;

 public Int32 colorAreaLeftChan;

 public Int32 colorAreaRightChan;

 public Int32 colorAreaCoveredLeftChan;

 public Int32 colorAreaCoveredRightChan;

 public Int32 colorVertLineSpectralView;

}

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.


TagsReaderMan class

TagsReaderMan class

The TagsReaderMan class, accessible through the control's TagsReader property, contains methods needed to manage meta tags information stored in sound files of various audio formats.

The TagsReaderMan class 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 editing through the TagsReader object in Visual C# and Visual Basic.NET 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function TagsReader.ALL_AnalyzeSoundOnPlayer (

nPlayerIndex as Int16

) as enumTagAvailable

[C#]

public enumTagAvailable TagsReader.ALL_AnalyzeSoundOnPlayer (

Int16 nPlayerIndex

);

[C++]

public: enumTagAvailable TagsReader.ALL_AnalyzeSoundOnPlayer (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ALL_AnalyzeSoundFile (

strPathname as String

) as enumTagAvailable

[C#]

public enumTagAvailable ALL_AnalyzeSoundFile (

string strPathname

);

[C++]

public: enumTagAvailable 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.

For further details about methods related to tags reading refer to the TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ALL_CommonFrameGet (

nField as enumTagFields

) as String

[C#]

public string ALL_CommonFrameGet (

enumTagFields nField

);

[C++]

public: string ALL_CommonFrameGet (

enumTagFields 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function APE_TextFieldGet (

nField as enumTagFields

) as String

[C#]

public string APE_TextFieldGet (

enumTagFields nField

);

[C++]

public: string APE_TextFieldGet (

enumTagFields nField

);

Parameter

Description

nField

Identifier of the tag field to set.

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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function APE_UniqueFramesCountGet (

) as Int16

[C#]

public Int16 APE_UniqueFramesCountGet (

);

[C++]

public: Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function APE_UniqueFramesIdGet (

nFrameIndex as Int16

) as String

[C#]

public string APE_UniqueFramesIdGet (

Int16 nFrameIndex

);

[C++]

public: string APE_UniqueFramesIdGet (

Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function APE_UserFieldGet (

strFrameId as string

) as String

[C#]

public string APE_UserFieldGet (

string strFrameId

);

[C++]

public: string APE_UserFieldGet (

string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_PictureFrameBitmapGet (

nIndex as Int32,

hBitmap as IntPtr,

ByRef nOriginalWidth as Int32,

ByRef nOriginalHeight as Int32,

nResizeWidth as Int32,

nResizeHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FLAC_PictureFrameBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

ref Int32 nOriginalWidth,

ref Int32 nOriginalHeight,

Int32 nResizeWidth,

Int32 nResizeHeight

);

[C++]

public: enumErrorCodes FLAC_PictureFrameBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

Int32 __gc *nOriginalWidth,

Int32 __gc *nOriginalHeight,

Int32 nResizeWidth,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_PictureFrameCountGet (

) as Int16

[C#]

public Int16 FLAC_PictureFrameCountGet (

);

[C++]

public: Int16 FLAC_PictureFrameCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_PictureFrameFileGet (

nIndex as Int32,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public string FLAC_PictureFrameFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: string FLAC_PictureFrameFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_PictureFrameInfoGet (

nIndex as Int32,

nInfo as enumId3v2FrameInfo

) as String

[C#]

public string FLAC_PictureFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo nInfo

);

[C++]

public: string FLAC_PictureFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_PictureFrameMemoryFileGet (

nIndex as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public string FLAC_PictureFrameMemoryFileGet (

Int32 nIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: string FLAC_PictureFrameMemoryFileGet (

Int32 nIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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.NET and Visual C#:

Visual Basic.NET

Private Sub buttonGetPicture_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles buttonGetPicture.Click

{

' get the size of the picture in bytes

Dim nSizeInBytes As Int32

AudioSoundEditor1.TagsReader.FLAC_PictureFrameSizeGet (0, nSizeInBytes)

if nSizeInBytes = 0 then Exit Sub

' allocate the receiving buffer

Dim byteBuffer As Byte() = Nothing

byteBuffer = New Byte(nSizeInBytes)

' read picture data

AudioSoundEditor1.TagsReader.FLAC_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes)

...

use the buffer

...

}

Visual C#

private void buttonGetPicture_Click(object sender, System.EventArgs e)

{

// get the size of the picture in bytes

Int32 nSizeInBytes = 0;

AudioSoundEditor1.TagsReader.FLAC_PictureFrameSizeGet (0, ref nSizeInBytes);

if (nSizeInBytes == 0)

   return;

// allocate the receiving buffer

byte[] byteBuffer = new byte[nSizeInBytes];

// read picture data

AudioSoundEditor1.TagsReader.FLAC_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes);

...

use the buffer

...

}


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_PictureFrameSizeGet (

nIndex as Int32,

ByRef nSize as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FLAC_PictureFrameSizeGet (

Int32 nIndex,

ref Int32 nSize

);

[C++]

public: enumErrorCodes FLAC_PictureFrameSizeGet (

Int32 nIndex,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_PictureFrameTypeGet (

nIndex as Int32,

ByRef nPictureType as enumId3v2FrameInfo

) as enumErrorCodes

[C#]

public enumErrorCodes FLAC_PictureFrameTypeGet (

Int32 nIndex,

ref enumId3v2FrameInfo nPictureType

);

[C++]

public: enumErrorCodes ID3V2_PictureFrameTypeGet (

Int32 nIndex,

enumId3v2FrameInfo __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_TextFrameGet (

strFrameId as String

) as String

[C#]

public string FLAC_TextFrameGet (

string strFrameId

);

[C++]

public: string FLAC_TextFrameGet (

string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_UniqueFramesCountGet (

) as Int16

[C#]

public Int16 FLAC_UniqueFramesCountGet (

);

[C++]

public: Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function FLAC_UniqueFramesIdGet (

nFrameIndex as Int16

) as String

[C#]

public string FLAC_UniqueFramesIdGet (

Int16 nFrameIndex

);

[C++]

public: string FLAC_UniqueFramesIdGet (

Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V1_FieldGet (

nField as enumTagFields

) as String

[C#]

public string ID3V1_FieldGet (

enumTagFields nField

);

[C++]

public: string ID3V1_FieldGet (

enumTagFields 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_CommentFrameGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_CommentFrameGet (

Int32 nIndex

);

[C++]

public: string ID3V2_CommentFrameGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_CommentFrameInfoGet (

nIndex as Int32,

nInfo as enumId3v2FrameInfo

) as String

[C#]

public string ID3V2_CommentFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo nInfo

);

[C++]

public: string ID3V2_CommentFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_CommercialFrameInfoGet (

nIndex as Int32,

nInfo as enumId3v2CommercialInfo

) as String

[C#]

public string ID3V2_CommercialFrameInfoGet (

Int32 nIndex,

enumId3v2CommercialInfo nInfo

);

[C++]

public: string ID3V2_CommercialFrameInfoGet (

Int32 nIndex,

enumId3v2CommercialInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_CommercialFramePictureBitmapGet (

nIndex as Int32,

hBitmap as IntPtr,

ByRef nOriginalWidth as Int32,

ByRef nOriginalHeight as Int32,

nResizeWidth as Int32,

nResizeHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_CommercialFramePictureBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

ref Int32 nOriginalWidth,

ref Int32 nOriginalHeight,

Int32 nResizeWidth,

Int32 nResizeHeight

);

[C++]

public: enumErrorCodes ID3V2_CommercialFramePictureBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

Int32 __gc *nOriginalWidth,

Int32 __gc *nOriginalHeight,

Int32 nResizeWidth,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_CommercialFramePictureFileGet (

nIndex as Int32,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public string ID3V2_CommercialFramePictureFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: string ID3V2_CommercialFramePictureFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_CommercialFramePictureMemoryFileGet (

nIndex as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public string ID3V2_CommercialFramePictureMemoryFileGet (

Int32 nIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: string ID3V2_CommercialFramePictureMemoryFileGet (

Int32 nIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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.NET and Visual C#:

Visual Basic.NET

Private Sub buttonGetPicture_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles buttonGetPicture.Click

{

' get the size of the picture in bytes

Dim nSizeInBytes As Int32

AudioSoundEditor1.TagsReader.ID3V2_CommercialFramePictureSizeGet (0, nSizeInBytes)

if nSizeInBytes = 0 then Exit Sub

' allocate the receiving buffer

Dim byteBuffer As Byte() = Nothing

byteBuffer = New Byte(nSizeInBytes)

' read picture data

AudioSoundEditor1.TagsReader.ID3V2_CommercialFramePictureMemoryFileGet (0, byteBuffer, nSizeInBytes)

...

use the buffer

...

}

Visual C#

private void buttonGetPicture_Click(object sender, System.EventArgs e)

{

// get the size of the picture in bytes

Int32 nSizeInBytes = 0;

AudioSoundEditor1.TagsReader.ID3V2_CommercialFramePictureSizeGet (0, ref nSizeInBytes);

if (nSizeInBytes == 0)

   return;

// allocate the receiving buffer

byte[] byteBuffer = new byte[nSizeInBytes];

// read picture data

AudioSoundEditor1.TagsReader.ID3V2_CommercialFramePictureMemoryFileGet (0, byteBuffer, nSizeInBytes);

...

use the buffer

...

}


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_CommercialFramePictureSizeGet (

nIndex as Int32,

ByRef nSize as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_CommercialFramePictureSizeGet (

Int32 nIndex,

ref Int32 nSize

);

[C++]

public: enumErrorCodes ID3V2_CommercialFramePictureSizeGet (

Int32 nIndex,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_CommercialFrameReceivedAsGet (

nIndex as Int32,

ByRef nReceivedAs as enumId3v2ReceivedAsType

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_CommercialFrameReceivedAsGet (

Int32 nIndex,

ref enumId3v2ReceivedAsType nReceivedAs

);

[C++]

public: enumErrorCodes ID3V2_CommercialFrameReceivedAsGet (

Int32 nIndex,

enumId3v2ReceivedAsType __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_EventTimingsFrameEventCountGet (

ByRef nCount as Int32,

ByRef nTimeStampFormat as enumId3v2TimeStampFormats

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_EventTimingsFrameEventCountGet (

ref Int32 nCount,

ref enumId3v2TimeStampFormats nTimeStampFormat

);

[C++]

public: enumErrorCodes ID3V2_EventTimingsFrameEventCountGet (

Int32 __gc *nCount,

enumId3v2TimeStampFormats __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_EventTimingsFrameEventInfoGet (

nIndex as Int32,

ByRef nEventTimingType as enumId3v2EventTimingTypes,

ByRef nPositionInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_EventTimingsFrameEventInfoGet (

Int32 nIndex,

ref enumId3v2EventTimingTypes nEventTimingType,

ref Int32 nPositionInMs

);

[C++]

public: enumErrorCodes ID3V2_EventTimingsFrameEventInfoGet (

Int32 nIndex,

enumId3v2EventTimingTypes __gc *nEventTimingType,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_FrameCountGet (

strText as String

) as Int16

[C#]

public Int16 ID3V2_FrameCountGet (

LPCTSTR strText

);

[C++]

public: Int16 ID3V2_FrameCountGet (

LPCTSTR strText

);

Parameter | Description
strFrameId | String containing the identifier of the specific frame to enumerate

Return value

Value | Meaning
Negative value | An error occurred (see the 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_GeneralObjectFrameFileGet (

nIndex as Int32,

strPathname as String

) as enumErrorCodes

[C#]

public string ID3V2_GeneralObjectFrameFileGet (

Int32 nIndex,

string strPathname

);

[C++]

public: string ID3V2_GeneralObjectFrameFileGet (

Int32 nIndex,

string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_GeneralObjectFrameInfoGet (

nIndex as Int32,

nInfo as enumId3v2FrameInfo

) as String

[C#]

public string ID3V2_GeneralObjectFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo nInfo

);

[C++]

public: string ID3V2_GeneralObjectFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_GeneralObjectFrameMemoryFileGet (

nIndex as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public string ID3V2_GeneralObjectFrameMemoryFileGet (

Int32 nIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: string ID3V2_GeneralObjectFrameMemoryFileGet (

Int32 nIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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.NET and Visual C#:

Visual Basic.NET

Private Sub buttonGetObject_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles buttonGetObject.Click

{

' get the size of the picture in bytes

Dim nSizeInBytes As Int32

AudioSoundEditor1.TagsReader.ID3V2_GeneralObjectFrameSizeGet (0, nSizeInBytes)

if nSizeInBytes = 0 then Exit Sub

' allocate the receiving buffer

Dim byteBuffer As Byte() = Nothing

byteBuffer = New Byte(nSizeInBytes)

' read picture data

AudioSoundEditor1.TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet (0, byteBuffer, nSizeInBytes)

...

use the buffer

...

}

Visual C#

private void buttonGetObject_Click(object sender, System.EventArgs e)

{

// get the size of the picture in bytes

Int32 nSizeInBytes = 0;

AudioSoundEditor1.TagsReader.ID3V2_GeneralObjectFrameSizeGet (0, ref nSizeInBytes);

if (nSizeInBytes == 0)

   return;

// allocate the receiving buffer

byte[] byteBuffer = new byte[nSizeInBytes];

// read picture data

AudioSoundEditor1.TagsReader.ID3V2_GeneralObjectFrameMemoryFileGet (0, byteBuffer, nSizeInBytes);

...

use the buffer

...

}


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_GeneralObjectFrameSizeGet (

nIndex as Int32,

ByRef nSize as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_GeneralObjectFrameSizeGet (

Int32 nIndex,

ref Int32 nSize

);

[C++]

public: enumErrorCodes ID3V2_GeneralObjectFrameSizeGet (

Int32 nIndex,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_MusicCdIdentifierFrameGet (

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public string ID3V2_MusicCdIdentifierFrameGet (

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: string ID3V2_MusicCdIdentifierFrameGet (

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_MusicCdIdentifierFrameSizeGet (

ByRef nSize as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_MusicCdIdentifierFrameSizeGet (

ref Int32 nSize

);

[C++]

public: enumErrorCodes ID3V2_MusicCdIdentifierFrameSizeGet (

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_OwnershipFrameInfoGet (

nInfo as enumId3v2OwnershipInfo

) as String

[C#]

public string ID3V2_OwnershipFrameInfoGet (

enumId3v2OwnershipInfo nInfo

);

[C++]

public: string ID3V2_OwnershipFrameInfoGet (

enumId3v2OwnershipInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PictureFrameBitmapGet (

nIndex as Int32,

hBitmap as IntPtr,

ByRef nOriginalWidth as Int32,

ByRef nOriginalHeight as Int32,

nResizeWidth as Int32,

nResizeHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_PictureFrameBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

ref Int32 nOriginalWidth,

ref Int32 nOriginalHeight,

Int32 nResizeWidth,

Int32 nResizeHeight

);

[C++]

public: enumErrorCodes ID3V2_PictureFrameBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

Int32 __gc *nOriginalWidth,

Int32 __gc *nOriginalHeight,

Int32 nResizeWidth,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PictureFrameFileGet (

nIndex as Int32,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public string ID3V2_PictureFrameFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: string ID3V2_PictureFrameFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PictureFrameInfoGet (

nIndex as Int32,

nInfo as enumId3v2FrameInfo

) as String

[C#]

public string ID3V2_PictureFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo nInfo

);

[C++]

public: string ID3V2_PictureFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PictureFrameMemoryFileGet (

nIndex as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public string ID3V2_PictureFrameMemoryFileGet (

Int32 nIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: string ID3V2_PictureFrameMemoryFileGet (

Int32 nIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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.NET and Visual C#:

Visual Basic.NET

Private Sub buttonGetPicture_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles buttonGetPicture.Click

{

' get the size of the picture in bytes

Dim nSizeInBytes As Int32

AudioSoundEditor1.TagsReader.ID3V2_PictureFrameSizeGet (0, nSizeInBytes)

if nSizeInBytes = 0 then Exit Sub

' allocate the receiving buffer

Dim byteBuffer As Byte() = Nothing

byteBuffer = New Byte(nSizeInBytes)

' read picture data

AudioSoundEditor1.TagsReader.ID3V2_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes)

...

use the buffer

...

}

Visual C#

private void buttonGetPicture_Click(object sender, System.EventArgs e)

{

// get the size of the picture in bytes

Int32 nSizeInBytes = 0;

AudioSoundEditor1.TagsReader.ID3V2_PictureFrameSizeGet (0, ref nSizeInBytes);

if (nSizeInBytes == 0)

   return;

// allocate the receiving buffer

byte[] byteBuffer = new byte[nSizeInBytes];

// read picture data

AudioSoundEditor1.TagsReader.ID3V2_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes);

...

use the buffer

...

}


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PictureFrameTypeGet (

nIndex as Int32,

ByRef nPictureType as enumId3v2FrameInfo

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_PictureFrameTypeGet (

Int32 nIndex,

ref enumId3v2FrameInfo nPictureType

);

[C++]

public: enumErrorCodes ID3V2_PictureFrameTypeGet (

Int32 nIndex,

enumId3v2FrameInfo __gc *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_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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PictureFrameSizeGet (

nIndex as Int32,

ByRef nSize as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_PictureFrameSizeGet (

Int32 nIndex,

ref Int32 nSize

);

[C++]

public: enumErrorCodes ID3V2_PictureFrameSizeGet (

Int32 nIndex,

Int32 __gc *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_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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PlayCounterFrameCountGet (

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_PlayCounterFrameCountGet (

ref Int32 nCount

);

[C++]

public: enumErrorCodes ID3V2_PlayCounterFrameCountGet (

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PopularimeterFrameCounterGet (

nIndex as Int32,

ByRef nCounter as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_PopularimeterFrameCounterGet (

Int32 nIndex,

ref Int32 nCounter

);

[C++]

public: enumErrorCodes ID3V2_PopularimeterFrameCounterGet (

Int32 nIndex,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PopularimeterFrameEmailGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_PopularimeterFrameEmailGet (

Int32 nIndex

);

[C++]

public: string ID3V2_PopularimeterFrameEmailGet (

Int32 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 content of the requested frame


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_PopularimeterFrameRatingGet (

nIndex as Int32,

ByRef nRating as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_PopularimeterFrameRatingGet (

Int32 nIndex,

ref Int32 nRating

);

[C++]

public: enumErrorCodes ID3V2_PopularimeterFrameRatingGet (

Int32 nIndex,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_SynchLyricsFrameGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_SynchLyricsFrameGet (

Int32 nIndex

);

[C++]

public: string ID3V2_SynchLyricsFrameGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_SynchLyricsFrameInfoGet (

nIndex as Int32,

nInfo as enumId3v2FrameInfo

) as String

[C#]

public string ID3V2_SynchLyricsFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo nInfo

);

[C++]

public: string ID3V2_SynchLyricsFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_SynchLyricsFrameInfoNumGet (

nIndex as Int32,

ByRef nLyricsType as enumId3v2SyncLyricsType,

ByRef nTimeStampFormat as enumId3v2TimeStampFormats

) as enumErrorCodes

[C#]

public enumErrorCodes ID3V2_SynchLyricsFrameInfoNumGet (

Int32 nIndex,

ref enumId3v2SyncLyricsType nLyricsType,

ref enumId3v2TimeStampFormats nTimeStampFormat

);

[C++]

public: enumErrorCodes ID3V2_SynchLyricsFrameInfoNumGet (

Int32 nIndex,

enumId3v2SyncLyricsType __gc *nLyricsType,

enumId3v2TimeStampFormats __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_TermsOfUseFrameGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_TermsOfUseFrameGet (

Int32 nIndex

);

[C++]

public: string ID3V2_TermsOfUseFrameGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_TermsOfUseFrameLanguageGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_TermsOfUseFrameLanguageGet (

Int32 nIndex

);

[C++]

public: string ID3V2_TermsOfUseFrameLanguageGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_TextFrameGet (

strFrameId as string

) as String

[C#]

public string ID3V2_TextFrameGet (

string strFrameId

);

[C++]

public: string ID3V2_TextFrameGet (

string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_UniqueFramesCountGet (

) as Int16

[C#]

public Int16 ID3V2_UniqueFramesCountGet (

);

[C++]

public: Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_UniqueFramesIdGet (

nFrameIndex as Int16

) as String

[C#]

public string ID3V2_UniqueFramesIdGet (

Int16 nFrameIndex

);

[C++]

public: string ID3V2_UniqueFramesIdGet (

Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_UnsynchLyricsFrameGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_UnsynchLyricsFrameGet (

Int32 nIndex

);

[C++]

public: string ID3V2_UnsynchLyricsFrameGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_UnsynchLyricsFrameInfoGet (

nIndex as Int32,

nInfo as enumId3v2FrameInfo

) as String

[C#]

public string ID3V2_UnsynchLyricsFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo nInfo

);

[C++]

public: string ID3V2_UnsynchLyricsFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_URLFrameGet (

strFrameId as string

) as String

[C#]

public string ID3V2_URLFrameGet (

string strFrameId

);

[C++]

public: string ID3V2_URLFrameGet (

string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_UserTextFrameDescriptionGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_UserTextFrameDescriptionGet (

Int32 nIndex

);

[C++]

public: string ID3V2_UserTextFrameDescriptionGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_UserTextFrameGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_UserTextFrameGet (

Int32 nIndex

);

[C++]

public: string ID3V2_UserTextFrameGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_UserURLFrameDescriptionGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_UserURLFrameDescriptionGet (

Int32 nIndex

);

[C++]

public: string ID3V2_UserURLFrameDescriptionGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function ID3V2_UserURLFrameGet (

nIndex as Int32

) as String

[C#]

public string ID3V2_UserURLFrameGet (

Int32 nIndex

);

[C++]

public: string ID3V2_UserURLFrameGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function LYRICS3_ImageLinkGet (

) as String

[C#]

public string LYRICS3_ImageLinkGet (

);

[C++]

public: string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function LYRICS3_LyricsGet (

) as String

[C#]

public string LYRICS3_LyricsGet (

);

[C++]

public: string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function LYRICS3_TextFieldGet (

nField as enumTagFields

) as String

[C#]

public string LYRICS3_TextFieldGet (

enumTagFields nField

);

[C++]

public: string LYRICS3_TextFieldGet (

enumTagFields 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_PictureFrameBitmapGet (

nIndex as Int32,

hBitmap as IntPtr,

ByRef nOriginalWidth as Int32,

ByRef nOriginalHeight as Int32,

nResizeWidth as Int32,

nResizeHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes MP4_PictureFrameBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

ref Int32 nOriginalWidth,

ref Int32 nOriginalHeight,

Int32 nResizeWidth,

Int32 nResizeHeight

);

[C++]

public: enumErrorCodes MP4_PictureFrameBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

Int32 __gc *nOriginalWidth,

Int32 __gc *nOriginalHeight,

Int32 nResizeWidth,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_PictureFrameCountGet (

) as Int16

[C#]

public Int16 MP4_PictureFrameCountGet (

);

[C++]

public: Int16 MP4_PictureFrameCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_PictureFrameFileGet (

nIndex as Int32,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public string MP4_PictureFrameFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: string MP4_PictureFrameFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_PictureFrameMemoryFileGet (

nIndex as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public string MP4_PictureFrameMemoryFileGet (

Int32 nIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: string MP4_PictureFrameMemoryFileGet (

Int32 nIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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.NET and Visual C#:

Visual Basic.NET

Private Sub buttonGetPicture_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles buttonGetPicture.Click

{

' get the size of the picture in bytes

Dim nSizeInBytes As Int32

AudioSoundEditor1.TagsReader.MP4_PictureFrameSizeGet (0, nSizeInBytes)

if nSizeInBytes = 0 then Exit Sub

' allocate the receiving buffer

Dim byteBuffer As Byte() = Nothing

byteBuffer = New Byte(nSizeInBytes)

' read picture data

AudioSoundEditor1.TagsReader.MP4_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes)

...

use the buffer

...

}

Visual C#

private void buttonGetPicture_Click(object sender, System.EventArgs e)

{

// get the size of the picture in bytes

Int32 nSizeInBytes = 0;

AudioSoundEditor1.TagsReader.MP4_PictureFrameSizeGet (0, ref nSizeInBytes);

if (nSizeInBytes == 0)

   return;

// allocate the receiving buffer

byte[] byteBuffer = new byte[nSizeInBytes];

// read picture data

AudioSoundEditor1.TagsReader.MP4_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes);

...

use the buffer

...

}


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_PictureFrameMimeGet (

nIndex as Int32

) as String

[C#]

public string MP4_PictureFrameMimeGet (

Int32 nIndex

);

[C++]

public: string MP4_PictureFrameMimeGet (

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_PictureFrameSizeGet (

nIndex as Int32,

ByRef nSize as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes MP4_PictureFrameSizeGet (

Int32 nIndex,

ref Int32 nSize

);

[C++]

public: enumErrorCodes MP4_PictureFrameSizeGet (

Int32 nIndex,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_TextFrameGet (

nFrameId as enumMp4Frames

) as String

[C#]

public string MP4_TextFrameGet (

enumMp4Frames nFrameId

);

[C++]

public: string MP4_TextFrameGet (

enumMp4Frames 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_UniqueFramesCountGet (

) as Int16

[C#]

public Int16 MP4_UniqueFramesCountGet (

);

[C++]

public: Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function MP4_UniqueFramesIdGet (

nFrameIndex as Int16

) as String

[C#]

public string MP4_UniqueFramesIdGet (

Int16 nFrameIndex

);

[C++]

public: string MP4_UniqueFramesIdGet (

Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function OGG_TextFrameGet (

nFrameId as enumOggFrames

) as String

[C#]

public string OGG_TextFrameGet (

enumOggFrames nFrameId

);

[C++]

public: string OGG_TextFrameGet (

enumOggFrames 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function OGG_UniqueFramesCountGet (

) as Int16

[C#]

public Int16 OGG_UniqueFramesCountGet (

);

[C++]

public: Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function OGG_UniqueFramesIdGet (

nFrameIndex as Int16

) as String

[C#]

public string OGG_UniqueFramesIdGet (

Int16 nFrameIndex

);

[C++]

public: string OGG_UniqueFramesIdGet (

Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function OGG_UserFrameGet (

strFrameId as string

) as String

[C#]

public string OGG_UserFrameGet (

string strFrameId

);

[C++]

public: string OGG_UserFrameGet (

string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WAV_BextChunkBinaryFieldGet (

nFieldId as enumBextChunkBinaryField,

pBuffer() as Byte,

ByRef nBufferLength as Int32

) as enumErrorCodes

[C#]

public string WAV_BextChunkBinaryFieldGet (

enumBextChunkBinaryField nFieldId,

byte[] pBuffer,

ref Int32 nBufferLength

);

[C++]

public: string WAV_BextChunkBinaryFieldGet (

enumBextChunkBinaryField nFieldId,

unsigned char __gc[] pBuffer,

Int32 __gc *nBufferLength

);

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.

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.NET and Visual C#:

Visual Basic.NET

Private Sub buttonGetPicture_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles buttonGetPicture.Click

{

' get the size of the picture in bytes

Dim nSizeInBytes As Int32

AudioSoundEditor1.TagsReader.FLAC_PictureFrameSizeGet (0, nSizeInBytes)

if nSizeInBytes = 0 then Exit Sub

' allocate the receiving buffer

Dim byteBuffer As Byte() = Nothing

byteBuffer = New Byte(nSizeInBytes)

' read picture data

AudioSoundEditor1.TagsReader.FLAC_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes)

...

use the buffer

...

}

Visual C#

private void buttonGetPicture_Click(object sender, System.EventArgs e)

{

// get the size of the picture in bytes

Int32 nSizeInBytes = 0;

AudioSoundEditor1.TagsReader.FLAC_PictureFrameSizeGet (0, ref nSizeInBytes);

if (nSizeInBytes == 0)

   return;

// allocate the receiving buffer

byte[] byteBuffer = new byte[nSizeInBytes];

// read picture data

AudioSoundEditor1.TagsReader.FLAC_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes);

...

use the buffer

...

}


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WAV_BextChunkTextFieldGet (

nFieldId as enumBextChunkField

) as String

[C#]

public string WAV_BextChunkTextFieldGet (

enumBextChunkField nFieldId

);

[C++]

public: string WAV_BextChunkTextFieldGet (

enumBextChunkField 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WAV_CartChunkTextFieldGet (

nFieldId as enumCartChunkField

) as String

[C#]

public string WAV_CartChunkTextFieldGet (

enumCartChunkField nFieldId

);

[C++]

public: string WAV_CartChunkTextFieldGet (

enumCartChunkField 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WAV_CartChunkTimeMarkerFieldGet (

nFieldId as enumCartChunkTimeMarkerField,

nPositionInSamples as Int32

) as String

[C#]

public string WAV_CartChunkTimeMarkerFieldGet (

enumCartChunkTimeMarkerField nFieldId,

ref Int32 nPositionInSamples

);

[C++]

public: string WAV_CartChunkTimeMarkerFieldGet (

enumCartChunkTimeMarkerField nFieldId,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WAV_DisplayChunkTextGet (

) as String

[C#]

public string WAV_DisplayChunkTextGet (

);

[C++]

public: string 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 requested field


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WAV_ListInfoChunkFrameGet (

strFrameId as string

) as String

[C#]

public string WAV_ListInfoChunkFrameGet (

string strFrameId

);

[C++]

public: string WAV_ListInfoChunkFrameGet (

string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WAV_ListInfoChunkUniqueFramesCountGet (

) as Int16

[C#]

public Int16 WAV_ListInfoChunkUniqueFramesCountGet (

);

[C++]

public: Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WAV_ListInfoChunkUniqueFramesIdGet (

nFrameIndex as Int16

) as String

[C#]

public string WAV_ListInfoChunkUniqueFramesIdGet (

Int16 nFrameIndex

);

[C++]

public: string WAV_ListInfoChunkUniqueFramesIdGet (

Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_PictureFrameBitmapGet (

nIndex as Int32,

hBitmap as IntPtr,

ByRef nOriginalWidth as Int32,

ByRef nOriginalHeight as Int32,

nResizeWidth as Int32,

nResizeHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes WMA_PictureFrameBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

ref Int32 nOriginalWidth,

ref Int32 nOriginalHeight,

Int32 nResizeWidth,

Int32 nResizeHeight

);

[C++]

public: enumErrorCodes WMA_PictureFrameBitmapGet (

Int32 nIndex,

IntPtr hBitmap,

Int32 __gc *nOriginalWidth,

Int32 __gc *nOriginalHeight,

Int32 nResizeWidth,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_PictureFrameCountGet (

) as Int16

[C#]

public Int16 WMA_PictureFrameCountGet (

);

[C++]

public: Int16 WMA_PictureFrameCountGet (

);

Return value

Value | Meaning
Negative value | An error occurred (see the 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_PictureFrameFileGet (

nIndex as Int32,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public string WMA_PictureFrameFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: string WMA_PictureFrameFileGet (

Int32 nIndex,

string strPathname,

enumGraphicFormats nFormat,

Int32 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_PictureFrameInfoGet (

nIndex as Int32,

nInfo as enumId3v2FrameInfo

) as String

[C#]

public string WMA_PictureFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo nInfo

);

[C++]

public: string WMA_PictureFrameInfoGet (

Int32 nIndex,

enumId3v2FrameInfo 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_PictureFrameMemoryFileGet (

nIndex as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public string WMA_PictureFrameMemoryFileGet (

Int32 nIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: string WMA_PictureFrameMemoryFileGet (

Int32 nIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

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.NET and Visual C#:

Visual Basic.NET

Private Sub buttonGetPicture_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles buttonGetPicture.Click

{

' get the size of the picture in bytes

Dim nSizeInBytes As Int32

AudioSoundEditor1.TagsReader.WMA_PictureFrameSizeGet (0, nSizeInBytes)

if nSizeInBytes = 0 then Exit Sub

' allocate the receiving buffer

Dim byteBuffer As Byte() = Nothing

byteBuffer = New Byte(nSizeInBytes)

' read picture data

AudioSoundEditor1.TagsReader.WMA_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes)

...

use the buffer

...

}

Visual C#

private void buttonGetPicture_Click(object sender, System.EventArgs e)

{

// get the size of the picture in bytes

Int32 nSizeInBytes = 0;

AudioSoundEditor1.TagsReader.WMA_PictureFrameSizeGet (0, ref nSizeInBytes);

if (nSizeInBytes == 0)

   return;

// allocate the receiving buffer

byte[] byteBuffer = new byte[nSizeInBytes];

// read picture data

AudioSoundEditor1.TagsReader.WMA_PictureFrameMemoryFileGet (0, byteBuffer, nSizeInBytes);

...

use the buffer

...

}


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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_PictureFrameSizeGet (

nIndex as Int32,

ByRef nSize as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes WMA_PictureFrameSizeGet (

Int32 nIndex,

ref Int32 nSize

);

[C++]

public: enumErrorCodes WMA_PictureFrameSizeGet (

Int32 nIndex,

Int32 __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_PictureFrameTypeGet (

nIndex as Int32,

ByRef nPictureType as enumId3v2FrameInfo

) as enumErrorCodes

[C#]

public enumErrorCodes WMA_PictureFrameTypeGet (

Int32 nIndex,

ref enumId3v2FrameInfo nPictureType

);

[C++]

public: enumErrorCodes WMA_PictureFrameTypeGet (

Int32 nIndex,

enumId3v2FrameInfo __gc *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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_TextFrameGet (

strFrameId as string

) as String

[C#]

public string WMA_TextFrameGet (

string strFrameId

);

[C++]

public: string WMA_TextFrameGet (

string 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_UniqueFramesCountGet (

) as Int16

[C#]

public Int16 WMA_UniqueFramesCountGet (

);

[C++]

public: Int16 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 TagsReaderMan class.

For details about the reading of tags see the How to read TAG information in sound files tutorial.

Syntax

[Visual Basic]

Public Function WMA_UniqueFramesIdGet (

nFrameIndex as Int16

) as String

[C#]

public string WMA_UniqueFramesIdGet (

Int16 nFrameIndex

);

[C++]

public: string WMA_UniqueFramesIdGet (

Int16 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 class

VideoMixer class

The VideoMixer class, accessible through the control's DisplayVideoMixer property, 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 class 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 class in Visual C# and Visual Basic.NET 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]

Public Function BackgroundColorSet (

nMixerUniqueId as Int32,

colorBackground as Color

) as enumErrorCodes

[C#]

public enumErrorCodes BackgroundColorSet (

Int32 nMixerUniqueId,

Color colorBackground

);

[C++]

public: enumErrorCodes BackgroundColorSet (

Int32 nMixerUniqueId,

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function Create (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32,

colorBackground as Color

) as Int32

[C#]

public Int32 Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Color colorBackground

);

[C++]

public: Int32 Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

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 | 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
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


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]

Public Function Destroy (

nMixerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Destroy (

Int32 nMixerUniqueId

);

[C++]

public: enumErrorCodes Destroy (

Int32 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)
enumErrorCodes.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]

Public Function GetHWND (

nMixerUniqueId as Int32,

ByRef hWnd as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes GetHWND (

Int32 nMixerUniqueId,

ref IntPtr hWnd

);

[C++]

public: enumErrorCodes GetHWND (

Int32 nMixerUniqueId,

IntPtr __gc *hWnd

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
hWnd | Reference that, on return from the method call, will contain the HWND of the video mixer rendering window.

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.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]

Public Function Move (

nMixerUniqueId as Int32,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Move (

Int32 nMixerUniqueId,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Move (

Int32 nMixerUniqueId,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDBackgroundBitmapSet (

nMixerUniqueId as Int32,

hBitmap as IntPtr,

bKeepAspectRatio as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes OSDBackgroundBitmapSet (

Int32 nMixerUniqueId,

IntPtr hBitmap,

bool bKeepAspectRatio

);

[C++]

public: enumErrorCodes OSDBackgroundBitmapSet (

Int32 nMixerUniqueId,

IntPtr hBitmap,

bool 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 | Meaning
false (default) | Don't keep aspect ratio
true | Keep aspect ratio

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.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]

Public Function OSDBackgroundPictureFileSet (

nMixerUniqueId as Int32,

strPathname as String,

bKeepAspectRatio as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes OSDBackgroundPictureFileSet (

Int32 nMixerUniqueId,

string strPathname,

bool bKeepAspectRatio

);

[C++]

public: enumErrorCodes OSDBackgroundPictureFileSet (

Int32 nMixerUniqueId,

string strPathname,

bool 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 | Meaning
false (default) | Don't keep aspect ratio
true | Keep aspect ratio

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.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]

Public Function OSDEnable (

nMixerUniqueId as Int32,

bEnable as Boolean,

bZoomContentsOnResize as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes OSDEnable (

Int32 nMixerUniqueId,

bool bEnable,

bool bZoomContentsOnResize

);

[C++]

public: enumErrorCodes OSDEnable (

Int32 nMixerUniqueId,

bool bEnable,

bool 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 | Meaning
false | Disable the OSD
true | 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 | Meaning
false | Don't zoom items on resize of the video mixer window
true | Zoom items on resize of the video mixer window

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.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]

Public Function OSDIsEnabled (

nMixerUniqueId as Int32

) as Booelan

[C#]

public bool OSDIsEnabled (

Int32 nMixerUniqueId

);

[C++]

public: bool OSDIsEnabled (

Int32 nMixerUniqueId

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Mnemonic constant | Meaning
false | The OSD is disabled
true | 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]

Public Function OSDItemAlphaGet (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

ByRef nAlpha as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemAlphaGet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

ref Int16 nAlpha

);

[C++]

public: enumErrorCodes OSDItemAlphaGet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemAlphaSet (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

nAlpha as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemAlphaSet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

Int16 nAlpha

);

[C++]

public: enumErrorCodes OSDItemAlphaSet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemBitmapAdd (

nMixerUniqueId as Int32,

hBitmap as IntPtr,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as enumBoolean

) as Int32

[C#]

public Int32 OSDItemBitmapAdd (

Int32 nMixerUniqueId,

IntPtr hBitmap,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

[C++]

public: Int32 OSDItemBitmapAdd (

Int32 nMixerUniqueId,

IntPtr hBitmap,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool 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 | Meaning
false | The item is initially kept hidden
true | 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]

Public Function OSDItemBitmapChange (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemBitmapChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

IntPtr hBitmap

);

[C++]

public: enumErrorCodes OSDItemBitmapChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

IntPtr 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]

Public Function OSDItemBitmapGet (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

hBitmap as IntPtr,

nOriginalWidth as Int32,

nOriginalHeight as Int32,

nResizeWidth as Int32,

nResizeHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemBitmapGet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

ref IntPtr hBitmap,

ref Int32 nOriginalWidth,

ref Int32 nOriginalHeight,

Int32 nResizeWidth,

Int32 nResizeHeight

);

[C++]

public: enumErrorCodes OSDItemBitmapGet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

IntPtr __gc *hBitmap,

Int32 __gc *nOriginalWidth,

Int32 __gc *nOriginalHeight,

Int32 nResizeWidth,

Int32 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]

Public Function OSDItemChangeAlignment (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

nAlignment as enumRectAlignment

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemChangeAlignment (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

enumRectAlignment nAlignment

);

[C++]

public: enumErrorCodes OSDItemChangeAlignment (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

enumRectAlignment 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemIsOnVisibleArea (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

ByRef bIsVisible as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemIsOnVisibleArea (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

ref bool bIsVisible

);

[C++]

public: enumErrorCodes OSDItemIsOnVisibleArea (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

bool __gc *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 | Meaning
false | The item is outside of the visible area
true | The item is inside the visible area

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.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]

Public Function OSDItemMove (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

fLeftPos as Single,

fTopPos as Single

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemMove (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

float fLeftPos,

float fTopPos

);

[C++]

public: enumErrorCodes OSDItemMove (

Int32 nMixerUniqueId,

Int32 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]

Public Function OSDItemMovementSet (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

nDirection as enumOSDAutoMoveDirection,

nSpeedInPixPerSec as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemMovementSet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

enumOSDAutoMoveDirection nDirection,

Int16 nSpeedInPixPerSec

);

[C++]

public: enumErrorCodes OSDItemMovementSet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

enumOSDAutoMoveDirection nDirection,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemNormalizedRectGet (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

ByRef fLeft as Single,

ByRef fTop as Single,

ByRef fRight as Single,

ByRef fBottom as Single

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemNormalizedRectGet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId

ref float fLeft,

ref float fTop,

ref float fRight,

ref float fBottom

);

[C++]

public: enumErrorCodes OSDItemNormalizedRectGet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId

float __gc *fLeft,

float __gc *fTop,

float __gc *fRight,

float __gc *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 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemOutlineTextAdd (

nMixerUniqueId as Int32,

strText as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as Boolean,

LogFont as ADJ_LOGFONT,

strFacename as String,

color as Color,

colorOutline as Color,

nAlignment as enumTextAlignment,

nOutlineWidth as Int16

) as Int32

[C#]

public Int32 OSDItemOutlineTextAdd (

Int32 nMixerUniqueId,

string strText,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

Color colorOutline,

enumTextAlignment nAlignment,

Int16 nOutlineWidth

);

[C++]

public: Int32 OSDItemOutlineTextAdd (

Int32 nMixerUniqueId,

string strText,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

Color colorOutline,

enumTextAlignment nAlignment,

Int16 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
false | 0 | The item is initially kept hidden
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]

Public Function OSDItemOutlineTextChange (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

strText as String,

LogFont as ADJ_LOGFONT,

strFacename as String,

color as Color,

colorOutline as Color,

nAlignment as enumTextAlignment,

nOutlineWidth as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemOutlineTextChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

string strText,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

Color colorOutline,

enumTextAlignment nAlignment,

Int16 nOutlineWidth

);

[C++]

public: enumErrorCodes OSDItemOutlineTextChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

string strText,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

Color colorOutline,

enumTextAlignment nAlignment,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemPictureFileAdd (

nMixerUniqueId as Int32,

strPathname as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as enumBoolean

) as Int32

[C#]

public Int32 OSDItemPictureFileAdd (

Int32 nMixerUniqueId,

string strPathname,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

[C++]

public: Int32 OSDItemPictureFileAdd (

Int32 nMixerUniqueId,

string strPathname,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool 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.OSDItemPictureFileChangemethod.

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 | Meaning
false | The item is initially kept hidden
true | 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]

Public Function OSDItemPictureFileChange (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemPictureFileChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

string strPathname

);

[C++]

public: enumErrorCodes OSDItemPictureFileChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

string 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]

Public Function OSDItemPictureMemoryAdd (

nMixerUniqueId as Int32,

pBuffer() as Byte,

nBufferLength as Int32,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as enumBoolean

) as Int32

[C#]

public Int32 OSDItemPictureMemoryAdd (

Int32 nMixerUniqueId,

byte[] pBuffer,

Int32 nBufferLength,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

[C++]

public: Int32 OSDItemPictureMemoryAdd (

Int32 nMixerUniqueId,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

pBuffer

Buffer containing the picture file data. 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 | Meaning
false | The item is initially kept hidden
true | 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]

Public Function OSDItemPictureMemoryChange (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemPictureMemoryChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes OSDItemPictureMemoryChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

unsigned char __gc[] pBuffer,

Int32 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 | Buffer containing the picture file data. 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]

Public Function OSDItemRectangleAdd (

nMixerUniqueId as Int32,

fLeftPos as Single,

fTopPos as Single,

fWidth as Single,

fHeight as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as Boolean,

color as Color

) as Int32

[C#]

public Int32 OSDItemRectangleAdd (

Int32 nMixerUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

Color color

);

[C++]

public: Int32 OSDItemRectangleAdd (

Int32 nMixerUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

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 | Meaning
false | The item is initially kept hidden
true | 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]

Public Function OSDItemRectangleChange (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

fLeftPos as Single,

fTopPos as Single,

fWidth as Single,

fHeight as Single,

color as Color

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemRectangleChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

Color color

);

[C++]

public: enumErrorCodes OSDItemRectangleChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

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]

Public Function OSDItemRemove (

nMixerUniqueId as Int32,

nItemUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemRemove (

Int32 nMixerUniqueId,

Int32 nItemUniqueId

);

[C++]

public: enumErrorCodes OSDItemRemove (

Int32 nMixerUniqueId,

Int32 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]

Public Function OSDItemScrollByPixels (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

xOffset as Int32,

yOffset as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemScrollByPixels (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

Int32 xOffset,

Int32 yOffset

);

[C++]

public: enumErrorCodes OSDItemScrollByPixels (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

Int32 xOffset,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemShow (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemShow (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

bool bShow

);

[C++]

public: enumErrorCodes OSDItemShow (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

bool 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 | Meaning
false | Hides the item
true | Shows 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.


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]

Public Function OSDItemTextAdd (

nMixerUniqueId as Int32,

strText as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as Boolean,

LogFont as ADJ_LOGFONT,

strFacename as String,

color as Color,

nAlignment as enumTextAlignment

) as Int32

[C#]

public Int32 OSDItemTextAdd (

Int32 nMixerUniqueId,

string strText,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

enumTextAlignment nAlignment

);

[C++]

public: Int32 OSDItemTextAdd (

Int32 nMixerUniqueId,

string strText,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

enumTextAlignment 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 | Meaning
false | The item is initially kept hidden
true | The item is immediately shown

Visibility can be modified at a later time through the VideoMixer.OSDItemShow method.

LogFont

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]

Public Function OSDItemTextChange (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

strText as String,

LogFont as ADJ_LOGFONT,

strFacename as String,

color as Color,

nAlignment as enumTextAlignment

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemTextChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

string strText,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

enumTextAlignment nAlignment

);

[C++]

public: enumErrorCodes OSDItemTextChange (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

string strText,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

enumTextAlignment nAlignment

);

Parameter

Description

nMixerUniqueId

Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

strText

Text string.

LogFont

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemZOrderGet (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

ByRef nZOrder as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemZOrderGet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

ref Int32 nZOrder

);

[C++]

public: enumErrorCodes OSDItemZOrderGet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDItemZOrderSet (

nMixerUniqueId as Int32,

nItemUniqueId as Int32,

nZOrder as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemZOrderSet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

Int32 nZOrder

);

[C++]

public: enumErrorCodes OSDItemZOrderSet (

Int32 nMixerUniqueId,

Int32 nItemUniqueId,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDKeyColorGet (

nMixerUniqueId as Int32

) as Color

[C#]

public Color OSDKeyColorGet (

Int32 nMixerUniqueId

);

[C++]

public: Color OSDKeyColorGet (

Int32 nMixerUniqueId

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method

Return value

Value | Meaning
Color.Empty | An error occurred (see the LastError property for further error details)
Other color value | 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]

Public Function OSDKeyColorSet (

nMixerUniqueId as Int32,

colorKey as Color

) as enumErrorCodes

[C#]

public enumErrorCodes OSDKeyColorSet (

Int32 nMixerUniqueId,

Color colorKey

);

[C++]

public: enumErrorCodes OSDKeyColorSet (

Int32 nMixerUniqueId,

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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDNormalizedRectGet (

nMixerUniqueId as Int32,

ByRef fLeft as Single,

ByRef fTop as Single,

ByRef fRight as Single,

ByRef fBottom as Single

) as enumErrorCodes

[C#]

public enumErrorCodes OSDNormalizedRectGet (

Int32 nMixerUniqueId,

ref float fLeft,

ref float fTop,

ref float fRight,

ref float fBottom

);

[C++]

public: enumErrorCodes OSDNormalizedRectGet (

Int32 nMixerUniqueId,

float __gc *fLeft,

float __gc *fTop,

float __gc *fRight,

float __gc *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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function OSDNormalizedRectSet (

nMixerUniqueId as Int32,

fLeft as Single,

fTop as Single,

fRight as Single,

fBottom as Single

) as enumErrorCodes

[C#]

public enumErrorCodes OSDNormalizedRectSet (

Int32 nMixerUniqueId,

float fLeft,

float fTop,

float fRight,

float fBottom

);

[C++]

public: enumErrorCodes OSDNormalizedRectSet (

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function PlayerAlphaGet (

nMixerUniqueId as Int32,

nPlayerIndex as Int16,

ByRef nAlpha as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerAlphaGet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

ref Int16 nAlpha

);

[C++]

public: enumErrorCodes PlayerAlphaGet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

Int16 __gc *nAlpha

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VideoMixer.PlayerAlphaSet method

VideoMixer.PlayerAlphaSet method

Remarks

Sets 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]

Public Function PlayerAlphaSet (

nMixerUniqueId as Int32,

nPlayerIndex as Int16,

nAlpha as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerAlphaSet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

Int16 nAlpha

);

[C++]

public: enumErrorCodes PlayerAlphaSet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

Int16 nAlpha

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function PlayerNormalizedRectGet (

nMixerUniqueId as Int32,

nPlayerIndex as Int16,

ByRef fLeft as Single,

ByRef fTop as Single,

ByRef fRight as Single,

ByRef fBottom as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerNormalizedRectGet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

ref float fLeft,

ref float fTop,

ref float fRight,

ref float fBottom

);

[C++]

public: enumErrorCodes PlayerNormalizedRectGet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

float __gc *fLeft,

float __gc *fTop,

float __gc *fRight,

float __gc *fBottom

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function PlayerNormalizedRectSet (

nMixerUniqueId as Int32,

nPlayerIndex as Int16,

fLeft as Single,

fTop as Single,

fRight as Single,

fBottom as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerNormalizedRectSet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

float fLeft,

float fTop,

float fRight,

float fBottom

);

[C++]

public: enumErrorCodes PlayerNormalizedRectSet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

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
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function PlayerNormalizedRectSetIdeal (

nMixerUniqueId as Int32,

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerNormalizedRectSetIdeal (

Int32 nMixerUniqueId,

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlayerNormalizedRectSetIdeal (

Int32 nMixerUniqueId,

Int16 nPlayerIndex

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function PlayerZOrderGet (

nMixerUniqueId as Int32,

nPlayerIndex as Int16,

ByRef nZOrder as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerZOrderGet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

ref Int32 nZOrder

);

[C++]

public: enumErrorCodes PlayerZOrderGet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

Int32 __gc *nZOrder

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function PlayerZOrderSet (

nMixerUniqueId as Int32,

nPlayerIndex as Int16,

nZOrder as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerZOrderSet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

Int32 nZOrder

);

[C++]

public: enumErrorCodes PlayerZOrderSet (

Int32 nMixerUniqueId,

Int16 nPlayerIndex,

Int32 nZOrder

);

Parameter | Description
nMixerUniqueId | Unique identifier of the video mixer returned by a previous call to the VideoMixer.Create method
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function Reset (

nMixerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Reset (

Int32 nMixerUniqueId

);

[C++]

public: enumErrorCodes Reset (

Int32 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)
enumErrorCodes.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]

Public Function ScreenshotSaveToFile (

nMixerUniqueId as Int32,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ScreenshotSaveToFile (

Int32 nMixerUniqueId,

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: enumErrorCodes ScreenshotSaveToFile (

Int32 nMixerUniqueId,

string strPathname,

enumGraphicFormats nFormat,

Int32 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]

Public Function Show (

nMixerUniqueId as Int32,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

Int32 nMixerUniqueId,

bool bShow

);

[C++]

public: enumErrorCodes Show (

Int32 nMixerUniqueId,

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

Value | Meaning
false | Hides the video mixer window
true | Shows the video mixer window

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 class

VideoPlayer class

The VideoPlayer class, accessible through the control's DisplayVideoPlayer property, 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 class 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

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

GetDuration

GetNativeSize

GetPosition

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

Resume

Rewind

Seek

SeekToNextFrame

SeekToPreviousFrame

Stop

VideoStreamKeepAspectRatio

VideoStreamSendToActiveMovieWin

VideoTransformIsAvailable

VideoWindowAdd

VideoWindowChangeTarget

VideoWindowGetHWND

VideoWindowMove

VideoWindowShow

Examples of use of the VideoPlayer class in Visual C# and Visual Basic.NET 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 class 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]

Public Function AttachToVideoMixer (

nPlayerIndex as Int16,

nMixerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes AttachToVideoMixer (

Int16 nPlayerIndex,

Int32 nMixerUniqueId

);

[C++]

public: enumErrorCodes AttachToVideoMixer (

Int16 nPlayerIndex,

Int32 nMixerUniqueId

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioMultiStreamCheck (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool AudioMultiStreamCheck (

Int16 nPlayerIndex

);

[C++]

public: bool AudioMultiStreamCheck (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioMultiStreamGetCount (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 AudioMultiStreamGetCount (

Int16 nPlayerIndex

);

[C++]

public: Int32 AudioMultiStreamGetCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioMultiStreamGetName (

nPlayerIndex as Int16,

nStreamIndex as Int16

) as String

[C#]

public string AudioMultiStreamGetName (

Int16 nPlayerIndex,

Int16 nStreamIndex

);

[C++]

public: string AudioMultiStreamGetName (

Int16 nPlayerIndex,

Int16 nStreamIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioMultiStreamSelect (

nPlayerIndex as Int16,

nStreamIndex as Int16

) as String

[C#]

public string AudioMultiStreamSelect (

Int16 nPlayerIndex,

Int16 nStreamIndex

);

[C++]

public: string AudioMultiStreamSelect (

Int16 nPlayerIndex,

Int16 nStreamIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioRendererDelayGet (

nPlayerIndex as Int16,

ByRef nDelay as Int32

) as Int32

[C#]

public Int32 AudioRendererDelayGet (

Int16 nPlayerIndex,

ref Int32 nDelay

);

[C++]

public: Int32 AudioRendererDelayGet (

Int16 nPlayerIndex,

Int32 __gc *nDelay

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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, Audio 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioRendererDelaySet (

nPlayerIndex as Int16,

nDelay as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes AudioRendererDelaySet (

Int16 nPlayerIndex,

Int32 nDelay

);

[C++]

public: enumErrorCodes AudioRendererDelaySet (

Int16 nPlayerIndex,

Int32 nDelay

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioRendererDsDeviceGet (

nPlayerIndex as Int16

) as Int16

[C#]

public Int16 AudioRendererDsDeviceGet (

Int16 nPlayerIndex

);

[C++]

public: Int16 AudioRendererDsDeviceGet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 number of installed DirectSound devices recognized by DirectShow as valid audio renderers.

The friendly name of each output device can be obtained using the VideoPlayer.AudioRendererDsDeviceGetDesc method.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioRendererDsDeviceGetCount (

) as Int16

[C#]

public Int16 AudioRendererDsDeviceGetCount (

);

[C++]

public: Int16 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioRendererDsDeviceGetDesc (

nIndex as Int16

) as String

[C#]

public string AudioRendererDsDeviceGetDesc (

Int16 nIndex

);

[C++]

public: string AudioRendererDsDeviceGetDesc (

Int16 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioRendererDsDeviceSet (

nPlayerIndex as Int16,

nIndex as Integer

) as enumErrorCodes

[C#]

public enumErrorCodes AudioRendererDsDeviceSet (

Int16 nPlayerIndex,

Int16 nIndex

);

[C++]

public: enumErrorCodes AudioRendererDsDeviceSet (

Int16 nPlayerIndex,

Int16 nIndex

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioRendererModeGet (

nPlayerIndex as Int16

) as enumAudioRendererModes

[C#]

public enumAudioRendererModes AudioRendererModeGet (

Int16 nPlayerIndex

);

[C++]

public: enumAudioRendererModes AudioRendererModeGet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioRendererModeSet (

nPlayerIndex as Int16,

nMode as enumAudioRendererModes

) as enumErrorCodes

[C#]

public enumErrorCodes AudioRendererModeSet (

Int16 nPlayerIndex,

enumAudioRendererModes nMode

);

[C++]

public: enumErrorCodes AudioRendererModeSet (

Int16 nPlayerIndex,

enumAudioRendererModes nMode

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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.

During the audio extracting session, the container application will be notified about the exporting advancement through the CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to:

· EV_AUDIO_EXTRACT_START invoked once at the beginning
· EV_AUDIO_EXTRACT_PERC invoked multiple times reporting the current advancement percentage inside the nData1 parameter
· EV_AUDIO_EXTRACT_DONE invoked once at the end

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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioTrackExtract (

nPlayerIndex as Int16,

bStoreInMemory as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes AudioTrackExtract (

Int16 nPlayerIndex,

bool bStoreInMemory

);

[C++]

public: enumErrorCodes AudioTrackExtract (

Int16 nPlayerIndex,

bool bStoreInMemory

);

Parameter

Description

nPlayerIndex

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

Meaning

false

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.

true

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 nData1 parameter of the CallbackForPlayersEvents delegate invoked with the nEvent parameter set to:EV_AUDIO_EXTRACT_DONE.

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.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 cause the CallbackForPlayersEvents delegate to be invoked with the nEvent parameter set to:EV_AUDIO_EXTRACT_DONE.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioTrackExtractAbort (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes AudioTrackExtractAbort (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes AudioTrackExtractAbort (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioTrackFree (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes AudioTrackFree (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes AudioTrackFree (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioTrackGetMemoryPtr (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 AudioTrackGetMemoryPtr (

Int16 nPlayerIndex

);

[C++]

public: Int32 AudioTrackGetMemoryPtr (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Value >= 0 | Address of the memory buffer
Negative value | An error occurred (see the LastError property for further error details)


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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioTrackGetMemorySize (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 AudioTrackGetMemorySize (

Int16 nPlayerIndex

);

[C++]

public: Int32 AudioTrackGetMemorySize (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Value >= 0 | Size of the memory buffer expressed in bytes
Negative value | An error occurred (see the LastError property for further error details)


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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioTrackGetTempFilePathname (

nPlayerIndex as Int16

) as String

[C#]

public string AudioTrackGetTempFilePathname (

Int16 nPlayerIndex

);

[C++]

public: string AudioTrackGetTempFilePathname (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 file
Empty string | An error occurred (see the LastError property for further error details)


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 inside a temporary file, this method will return the size in bytes of the temporary file containing sound data.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function AudioTrackGetTempFileSize (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 AudioTrackGetTempFileSize (

Int16 nPlayerIndex

);

[C++]

public: Int32 AudioTrackGetTempFileSize (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Value > 0 | Size of the temporary file expressed in bytes
Negative value | An error occurred (see the LastError property for further error details)


VideoPlayer.Close method

VideoPlayer.Close method

Remarks

Closes the loaded video and discard it from memory.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_CLOSED.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function Close (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Close (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes Close (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function CodecAudioDescGet (

nPlayerIndex as Int16

) as String

[C#]

public string CodecAudioDescGet (

Int16 nPlayerIndex

);

[C++]

public: string CodecAudioDescGet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)


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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function CodecVideoDescGet (

nPlayerIndex as Int16

) as String

[C#]

public string CodecVideoDescGet (

Int16 nPlayerIndex

);

[C++]

public: string CodecVideoDescGet (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)


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 class 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]

Public Function DetachFromVideoMixer (

nPlayerIndex as Int16,

nMixerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DetachFromVideoMixer (

Int16 nPlayerIndex,

Int32 nMixerUniqueId

);

[C++]

public: enumErrorCodes DetachFromVideoMixer (

Int16 nPlayerIndex,

Int32 nMixerUniqueId

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function EnableDsErrorMessages (

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EnableDsErrorMessages (

bool bEnable

);

[C++]

public: enumErrorCodes EnableDsErrorMessages (

bool bEnable

);

Parameter

Description

bEnable

Boolean value that determines if error message boxes should be displayed.

Supported values are the following:

Mnemonic constant | Meaning
false | Disables message boxes reporting DirectShow internal errors.
true (default) | Enables message boxes reporting DirectShow internal errors.

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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FiltersInGraphGetClsid (

nPlayerIndex as Int16,

nFilterIndex as Int16

) as String

[C#]

public string FiltersInGraphGetClsid (

Int16 nPlayerIndex,

Int16 nFilterIndex

);

[C++]

public: string FiltersInGraphGetClsid (

Int16 nPlayerIndex,

Int16 nFilterIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FiltersInGraphGetCount (

nPlayerIndex as Int16

) as enumAudioRendererModes

[C#]

public enumAudioRendererModes FiltersInGraphGetCount (

Int16 nPlayerIndex

);

[C++]

public: enumAudioRendererModes FiltersInGraphGetCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FiltersInGraphGetName (

nPlayerIndex as Int16,

nFilterIndex as Int16

) as String

[C#]

public string FiltersInGraphGetName (

Int16 nPlayerIndex,

Int16 nFilterIndex

);

[C++]

public: string FiltersInGraphGetName (

Int16 nPlayerIndex,

Int16 nFilterIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FiltersInGraphHasPropertyPage (

nPlayerIndex as Int16,

nFilterIndex as Int16

) as Boolean

[C#]

public bool FiltersInGraphHasPropertyPage (

Int16 nPlayerIndex,

Int16 nFilterIndex

);

[C++]

public: bool FiltersInGraphHasPropertyPage (

Int16 nPlayerIndex,

Int16 nFilterIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FiltersInGraphShowPropertyPage (

nPlayerIndex as Int16,

nFilterIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FiltersInGraphShowPropertyPage (

Int16 nPlayerIndex,

Int16 nFilterIndex

);

[C++]

public: enumErrorCodes FiltersInGraphShowPropertyPage (

Int16 nPlayerIndex,

Int16 nFilterIndex

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function ForceWideScreen (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ForceWideScreen (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes ForceWideScreen (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function Forward (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Forward (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes Forward (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberInit (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FrameGrabberInit (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes FrameGrabberInit (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberExit (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FrameGrabberExit (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes FrameGrabberExit (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberExecToFile (

nPlayerIndex as Int16,

nStopType as enumVideoGrabberStopTypes,

nStartPosition as Int32,

nEndPosition as Int32,

nNumberOfFrames as Int32,

strOutputPath as String,

strOutputFilenamePrefix as String,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FrameGrabberExecToFile (

Int16 nPlayerIndex,

enumVideoGrabberStopTypes nStopType,

Int32 nStartPosition,

Int32 nEndPosition,

Int32 nNumberOfFrames,

string strOutputPath,

string strOutputFilenamePrefix,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: enumErrorCodes FrameGrabberExecToFile (

Int16 nPlayerIndex,

enumVideoGrabberStopTypes nStopType,

Int32 nStartPosition,

Int32 nEndPosition,

Int32 nNumberOfFrames,

string strOutputPath,

string strOutputFilenamePrefix,

enumGraphicFormats nFormat,

Int32 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberExecToMemory (

nPlayerIndex as Int16,

nStopType as enumVideoGrabberStopTypes,

nStartPosition as Int32,

nEndPosition as Int32,

nNumberOfFrames as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FrameGrabberExecToMemory (

Int16 nPlayerIndex,

enumVideoGrabberStopTypes nStopType,

Int32 nStartPosition,

Int32 nEndPosition,

Int32 nNumberOfFrames

);

[C++]

public: enumErrorCodes FrameGrabberExecToMemory (

Int16 nPlayerIndex,

enumVideoGrabberStopTypes nStopType,

Int32 nStartPosition,

Int32 nEndPosition,

Int32 nNumberOfFrames

);

Parameter

Description

nPlayerIndex

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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberOutputResizeSet (

nPlayerIndex as Int16,

nOutputWidth as Int32,

nOutputHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FrameGrabberOutputResizeSet (

Int16 nPlayerIndex,

Int32 nOutputWidth,

Int32 nOutputHeight

);

[C++]

public: enumErrorCodes FrameGrabberOutputResizeSet (

Int16 nPlayerIndex,

Int32 nOutputWidth,

Int32 nOutputHeight

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberResultsGetAvailableType (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes FrameGrabberResultsGetAvailableType (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes FrameGrabberResultsGetAvailableType (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberResultsGetPixelColor (

nPlayerIndex as Int16,

nFrameIndex as Int32,

X as Int32,

Y as Int32

) as Color

[C#]

public Color FrameGrabberResultsGetPixelColor (

Int16 nPlayerIndex,

Int32 nFrameIndex,

Int32 X,

Int32 Y

);

[C++]

public: Color FrameGrabberResultsGetPixelColor (

Int16 nPlayerIndex,

Int32 nFrameIndex,

Int32 X,

Int32 Y

);

Parameter

Description

nPlayerIndex

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

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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberResultsGetBitmap (

nPlayerIndex as Int16,

nFrameIndex as Int32

) as IntPtr

[C#]

public IntPtr FrameGrabberResultsGetBitmap (

Int16 nPlayerIndex,

Int32 nFrameIndex

);

[C++]

public: IntPtr FrameGrabberResultsGetBitmap (

Int16 nPlayerIndex,

Int32 nFrameIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberResultsGetBitmapsCount (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 FrameGrabberResultsGetBitmapsCount (

Int16 nPlayerIndex

);

[C++]

public: Int32 FrameGrabberResultsGetBitmapsCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberResultsGetFilePathname (

nPlayerIndex as Int16,

nFrameIndex as Int32

) as IntPtr

[C#]

public IntPtr FrameGrabberResultsGetFilePathname (

Int16 nPlayerIndex,

Int32 nFrameIndex

);

[C++]

public: IntPtr FrameGrabberResultsGetFilePathname (

Int16 nPlayerIndex,

Int32 nFrameIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FrameGrabberResultsGetFilesCount (

nPlayerIndex as Int16

) as IntPtr

[C#]

public IntPtr FrameGrabberResultsGetFilesCount (

Int16 nPlayerIndex

);

[C++]

public: IntPtr FrameGrabberResultsGetFilesCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FramesAverageRateGet (

nPlayerIndex as Int16,

ByRef fAverageRate as Single

) as enumErrorCodes

[C#]

public enumErrorCodes FramesAverageRateGet (

Int16 nPlayerIndex,

ref float fAverageRate

);

[C++]

public: enumErrorCodes FramesAverageRateGet (

Int16 nPlayerIndex,

float __gc *fAverageRate

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FramesNumberGet (

nPlayerIndex as Int16,

ByRef nFrames as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FramesNumberGet (

Int16 nPlayerIndex,

ref Int32 nFrames

);

[C++]

public: enumErrorCodes FramesNumberGet (

Int16 nPlayerIndex,

Int32 __gc *nFrames

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FullscreenMonitorActivate (

nPlayerIndex as Int16,

nMonitorIndex as Int32,

bActivate as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes FullscreenMonitorActivate (

Int16 nPlayerIndex,

Int32 nMonitorIndex,

bool bActivate

);

[C++]

public: enumErrorCodes FullscreenMonitorActivate (

Int16 nPlayerIndex,

Int32 nMonitorIndex,

bool 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 | Meaning
false | Deactivates full screen
true | Activates full screen

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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FullscreenMonitorCountGet (

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FullscreenMonitorCountGet (

ref Int32 nCount

);

[C++]

public: enumErrorCodes FullscreenMonitorCountGet (

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FullscreenMonitorNameGet (

nMonitorIndex as Int32

) as String

[C#]

public string FullscreenMonitorNameGet (

Int32 nMonitorIndex

);

[C++]

public: string FullscreenMonitorNameGet (

Int32 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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FullscreenMonitorIsActivated (

nPlayerIndex as Int16,

nMonitorIndex as Int32

) as Boolean

[C#]

public bool FullscreenMonitorIsActivated (

Int16 nPlayerIndex,

Int32 nMonitorIndex

);

[C++]

public: bool FullscreenMonitorIsActivated (

Int16 nPlayerIndex,

Int32 nMonitorIndex

);

Parameter | Description
nPlayerIndex | 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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FullscreenMonitorPositionGet (

nMonitorIndex as Int32,

ByRef nLeft as Int32,

ByRef nTop as Int32,

ByRef nWidth as Int32,

ByRef nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FullscreenMonitorPositionGet (

Int32 nMonitorIndex,

ref Int32 nLeft,

ref Int32 nTop,

ref Int32 nWidth,

ref Int32 nHeight

);

[C++]

public: enumErrorCodes FullscreenMonitorPositionGet (

Int32 nMonitorIndex,

Int32 __gc *nLeft,

Int32 __gc *nTop,

Int32 __gc *nWidth,

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FullscreenMonitorPredispose (

nPlayerIndex as Int16,

nMonitorIndex as Int32,

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes FullscreenMonitorPredispose (

Int16 nPlayerIndex,

Int32 nMonitorIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes FullscreenMonitorPredispose (

Int16 nPlayerIndex,

Int32 nMonitorIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function FullscreenMonitorRemove (

nPlayerIndex as Int16,

nMonitorIndex as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes FullscreenMonitorRemove (

Int16 nPlayerIndex,

Int32 nMonitorIndex

);

[C++]

public: enumErrorCodes FullscreenMonitorRemove (

Int16 nPlayerIndex,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function GetAspectRatio (

nPlayerIndex as Int16,

ByRef nAspectX as Int32,

ByRef nAspectY as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetAspectRatio (

Int16 nPlayerIndex,

ref Int32 nAspectX,

ref Int32 nAspectY

);

[C++]

public: enumErrorCodes GetAspectRatio (

Int16 nPlayerIndex,

Int32 __gc *nAspectX,

Int32 __gc *nAspectY

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VideoPlayer.GetDuration method

VideoPlayer.GetDuration method

Remarks

Gets the duration of the video currently loaded.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function GetDuration (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 GetDuration (

Int16 nPlayerIndex

);

[C++]

public: Int32 GetDuration (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Value > 0 | The video duration expressed in milliseconds
Negative value | An error occurred (see the LastError property for further error details)


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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function GetNativeSize (

nPlayerIndex as Int16,

ByRef nWidth as Int32,

ByRef nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetNativeSize (

Int16 nPlayerIndex,

ref Int32 nWidth,

ref Int32 nHeight

);

[C++]

public: enumErrorCodes GetNativeSize (

Int16 nPlayerIndex,

Int32 __gc *nWidth,

Int32 __gc *nHeight

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VideoPlayer.GetPosition method

VideoPlayer.GetPosition 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function GetPosition (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 GetPosition (

Int16 nPlayerIndex

);

[C++]

public: Int32 GetPosition (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the video player.

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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function ImageAdjustEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes ImageAdjustEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes ImageAdjustEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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

Meaning

false (default)

Disable image adjustment

true

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 is 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function ImageAdjustIsEnabled (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool ImageAdjustIsEnabled (

Int16 nPlayerIndex

);

[C++]

public: bool ImageAdjustIsEnabled (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 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]

Public Function ImageAdjustPropertyGet (

nPlayerIndex as Int16,

nProperty as enumVideoImageAdjustProps,

ByRef nValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ImageAdjustPropertyGet (

Int16 nPlayerIndex,

enumVideoImageAdjustProps nProperty,

ref Int32 nValue

);

[C++]

public: enumErrorCodes ImageAdjustPropertyGet (

Int16 nPlayerIndex,

enumVideoImageAdjustProps nProperty,

Int32 __gc *nValue

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 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]

Public Function ImageAdjustPropertySet (

nPlayerIndex as Int16,

nProperty as enumVideoImageAdjustProps,

nValue as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ImageAdjustPropertySet (

Int16 nPlayerIndex,

enumVideoImageAdjustProps nProperty,

Int32 nValue

);

[C++]

public: enumErrorCodes ImageAdjustPropertySet (

Int16 nPlayerIndex,

enumVideoImageAdjustProps nProperty,

Int32 nValue

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 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]

Public Function ImageAdjustPropertyRangeGet (

nPlayerIndex as Int16,

nProperty as enumVideoImageAdjustProps,

ByRef nValueMin as Int32,

ByRef nValueMax as Int32,

ByRef nValueDefault as Int32,

ByRef nValueStepping as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ImageAdjustPropertyRangeGet (

Int16 nPlayerIndex,

enumVideoImageAdjustProps nProperty,

ref Int32 nValueMin,

ref Int32 nValueMax,

ref Int32 nValueDefault,

ref Int32 nValueStepping

);

[C++]

public: enumErrorCodes ImageAdjustPropertyRangeGet (

Int16 nPlayerIndex,

enumVideoImageAdjustProps nProperty,

Int32 __gc *nValueMin,

Int32 __gc *nValueMax,

Int32 __gc *nValueDefault,

Int32 __gc *nValueStepping

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function IsAudioStreamAvailable (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool IsAudioStreamAvailable (

Int16 nPlayerIndex

);

[C++]

public: bool IsAudioStreamAvailable (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 the loaded media file contains a video stream.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function IsDirectShowAvail (

) as Boolean

[C#]

public bool IsDirectShowAvail (

);

[C++]

public: bool 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function IsSeekable (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool IsSeekable (

Int16 nPlayerIndex

);

[C++]

public: bool IsSeekable (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function IsVideoStreamAvailable (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool IsVideoStreamAvailable (

Int16 nPlayerIndex

);

[C++]

public: bool IsVideoStreamAvailable (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.

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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function Load (

nPlayerIndex as Int16,

strFilename as string

) as enumErrorCodes

[C#]

public enumErrorCodes Load (

Int16 nPlayerIndex,

string strFilename

);

[C++]

public: enumErrorCodes Load (

Int16 nPlayerIndex,

string strFilename

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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.

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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadForEAX (

nPlayerIndex as Int16,

strFilename as string

) as enumErrorCodes

[C#]

public enumErrorCodes LoadForEAX (

Int16 nPlayerIndex,

string strFilename

);

[C++]

public: enumErrorCodes LoadForEAX (

Int16 nPlayerIndex,

string strFilename

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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.

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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadForTempoChange (

nPlayerIndex as Int16,

strFilename as string

) as enumErrorCodes

[C#]

public enumErrorCodes LoadForTempoChange (

Int16 nPlayerIndex,

string strFilename

);

[C++]

public: enumErrorCodes LoadForTempoChange (

Int16 nPlayerIndex,

string strFilename

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

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 EV_SOUND_LOADED event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadFromMemory (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C#]

public enumErrorCodes LoadFromMemory (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

[C++]

public: enumErrorCodes LoadFromMemory (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Buffer containing sound data

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 method call was successful.


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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

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 EV_SOUND_LOADED event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadFromMemoryForEAX (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C#]

public enumErrorCodes LoadFromMemoryForEAX (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

[C++]

public: enumErrorCodes LoadFromMemoryForEAX (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Buffer containing sound data

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 method call was successful.


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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_LOADED.

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 EV_SOUND_LOADED event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadFromMemoryForTempoChange (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C#]

public enumErrorCodes LoadFromMemoryForTempoChange (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

[C++]

public: enumErrorCodes LoadFromMemoryForTempoChange (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Buffer containing sound data

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 method call was successful.


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 and it's recommended waiting for the CallbackForPlayersEvents delegate being invoked with the nEvent parameter set to EV_SOUND_SYNC_LOADED 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.

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 EV_SOUND_SYNC_LOADED event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadFromMemorySync (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C#]

public enumErrorCodes LoadFromMemorySync (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

[C++]

public: enumErrorCodes LoadFromMemorySync (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Buffer containing sound data

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 method call was successful.


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 and it's recommended waiting for the CallbackForPlayersEvents delegate being invoked with the nEvent parameter set to EV_SOUND_SYNC_LOADED 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.

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 EV_SOUND_SYNC_LOADED event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadFromMemorySyncForEAX (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C#]

public enumErrorCodes LoadFromMemorySyncForEAX (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

[C++]

public: enumErrorCodes LoadFromMemorySyncForEAX (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Buffer containing sound data

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 method call was successful.


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 and it's recommended waiting for the CallbackForPlayersEvents delegate being invoked with the nEvent parameter set to EV_SOUND_SYNC_LOADED 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.

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 EV_SOUND_SYNC_LOADED event before deallocating the buffer.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadFromMemorySyncForTempoChange (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

nMediaFormat as enumMemoryMediaFormats

) as enumErrorCodes

[C#]

public enumErrorCodes LoadFromMemorySyncForTempoChange (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

[C++]

public: enumErrorCodes LoadFromMemorySyncForTempoChange (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumMemoryMediaFormats nMediaFormat

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will load the memory sound

pBuffer

Buffer containing sound data

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 method call was successful.


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 and it's recommended waiting for the CallbackForPlayersEvents delegate being invoked with the nEvent parameter set to EV_SOUND_SYNC_LOADED 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadSync (

nPlayerIndex as Int16,

strFilename as string

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSync (

Int16 nPlayerIndex,

string strFilename

);

[C++]

public: enumErrorCodes LoadSync (

Int16 nPlayerIndex,

string strFilename

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 and it's recommended waiting for the CallbackForPlayersEvents delegate being invoked with the nEvent parameter set to EV_SOUND_SYNC_LOADED 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadSyncForEAX (

nPlayerIndex as Int16,

strFilename as string

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSyncForEAX (

Int16 nPlayerIndex,

string strFilename

);

[C++]

public: enumErrorCodes LoadSyncForEAX (

Int16 nPlayerIndex,

string strFilename

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 and it's recommended waiting for the CallbackForPlayersEvents delegate being invoked with the nEvent parameter set to EV_SOUND_SYNC_LOADED 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function LoadSyncForTempoChange (

nPlayerIndex as Int16,

strFilename as string

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSyncForTempoChange (

Int16 nPlayerIndex,

string strFilename

);

[C++]

public: enumErrorCodes LoadSyncForTempoChange (

Int16 nPlayerIndex,

string strFilename

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDEnable (

nPlayerIndex as Int16,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes OSDEnable (

Int16 nPlayerIndex,

bool bEnable

);

[C++]

public: enumErrorCodes OSDEnable (

Int16 nPlayerIndex,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | Disable the OSD
true | Enable the OSD

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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDIsEnabled (

nPlayerIndex as Int16

) as Booelan

[C#]

public bool OSDIsEnabled (

Int16 nPlayerIndex

);

[C++]

public: bool OSDIsEnabled (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the video player.

Return value

Mnemonic constant | Meaning
false | The OSD is disabled
true | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemAlphaGet (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

ByRef nAlpha as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemAlphaGet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

ref Int16 nAlpha

);

[C++]

public: enumErrorCodes OSDItemAlphaGet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

Int16 __gc *nAlpha

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemAlphaSet (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

nAlpha as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemAlphaSet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

Int16 nAlpha

);

[C++]

public: enumErrorCodes OSDItemAlphaSet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

Int16 nAlpha

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemBitmapAdd (

nPlayerIndex as Int16,

hBitmap as IntPtr,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as enumBoolean

) as Int32

[C#]

public Int32 OSDItemBitmapAdd (

Int16 nPlayerIndex,

IntPtr hBitmap,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

[C++]

public: Int32 OSDItemBitmapAdd (

Int16 nPlayerIndex,

IntPtr hBitmap,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The item is initially kept hidden
true | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemBitmapChange (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemBitmapChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

IntPtr hBitmap

);

[C++]

public: enumErrorCodes OSDItemBitmapChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

IntPtr hBitmap

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemBitmapGet (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

hBitmap as IntPtr,

nOriginalWidth as Int32,

nOriginalHeight as Int32,

nResizeWidth as Int32,

nResizeHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemBitmapGet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

ref IntPtr hBitmap,

ref Int32 nOriginalWidth,

ref Int32 nOriginalHeight,

Int32 nResizeWidth,

Int32 nResizeHeight

);

[C++]

public: enumErrorCodes OSDItemBitmapGet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

IntPtr __gc *hBitmap,

Int32 __gc *nOriginalWidth,

Int32 __gc *nOriginalHeight,

Int32 nResizeWidth,

Int32 nResizeHeight

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemChangeAlignment (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

nAlignment as enumRectAlignment

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemChangeAlignment (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

enumRectAlignment nAlignment

);

[C++]

public: enumErrorCodes OSDItemChangeAlignment (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

enumRectAlignment nAlignment

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemIsOnVisibleArea (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

ByRef bIsVisible as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemIsOnVisibleArea (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

ref bool bIsVisible

);

[C++]

public: enumErrorCodes OSDItemIsOnVisibleArea (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

bool __gc *bIsVisible

);

Parameter

Description

nPlayerIndex

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:

false | 0 | The item is outside of the visible area
true | 1 | The item is inside the visible area

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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemMove (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

fLeftPos as Single,

fTopPos as Single

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemMove (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

float fLeftPos,

float fTopPos

);

[C++]

public: enumErrorCodes OSDItemMove (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

float fLeftPos,

float fTopPos

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemOutlineTextAdd (

nPlayerIndex as Int16,

strText as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as Boolean,

LogFont as ADJ_LOGFONT,

strFacename as String,

color as Color,

colorOutline as Color,

nAlignment as enumTextAlignment,

nOutlineWidth as Int16

) as Int32

[C#]

public Int32 OSDItemOutlineTextAdd (

Int16 nPlayerIndex,

string strText,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

Color colorOutline,

enumTextAlignment nAlignment,

Int16 nOutlineWidth

);

[C++]

public: Int32 OSDItemOutlineTextAdd (

Int16 nPlayerIndex,

string strText,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

Color colorOutline,

enumTextAlignment nAlignment,

Int16 nOutlineWidth

);

Parameter

Description

nPlayerIndex

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:

false | 0 | The item is initially kept hidden
true | 1 | The item is immediately shown

Visibility can be modified at a later time through the VideoPlayer.OSDItemShow method.

LogFont

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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemOutlineTextChange (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

strText as String,

LogFont as ADJ_LOGFONT,

strFacename as String,

color as Color,

colorOutline as Color,

nAlignment as enumTextAlignment,

nOutlineWidth as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemOutlineTextChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

string strText,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

Color colorOutline,

enumTextAlignment nAlignment,

Int16 nOutlineWidth

);

[C++]

public: enumErrorCodes OSDItemOutlineTextChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

string strText,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

Color colorOutline,

enumTextAlignment nAlignment,

Int16 nOutlineWidth

);

Parameter

Description

nPlayerIndex

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

LogFont

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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemPictureFileAdd (

nPlayerIndex as Int16,

strPathname as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as enumBoolean

) as Int32

[C#]

public Int32 OSDItemPictureFileAdd (

Int16 nPlayerIndex,

string strPathname,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

[C++]

public: Int32 OSDItemPictureFileAdd (

Int16 nPlayerIndex,

string strPathname,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The item is initially kept hidden
true | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemPictureFileChange (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemPictureFileChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

string strPathname

);

[C++]

public: enumErrorCodes OSDItemPictureFileChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemPictureMemoryAdd (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as enumBoolean

) as Int32

[C#]

public Int32 OSDItemPictureMemoryAdd (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

[C++]

public: Int32 OSDItemPictureMemoryAdd (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int16 nZOrder,

bool bShow

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The item is initially kept hidden
true | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemPictureMemoryChange (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemPictureMemoryChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes OSDItemPictureMemoryChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
nPlayerIndex | 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 | Buffer containing 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemRectangleAdd (

nPlayerIndex as Int16,

fLeftPos as Single,

fTopPos as Single,

fWidth as Single,

fHeight as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as Boolean,

color as Color

) as Int32

[C#]

public Int32 OSDItemRectangleAdd (

Int16 nPlayerIndex,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

Color color

);

[C++]

public: Int32 OSDItemRectangleAdd (

Int16 nPlayerIndex,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

Color color

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The item is initially kept hidden
true | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemRectangleChange (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

fLeftPos as Single,

fTopPos as Single,

fWidth as Single,

fHeight as Single,

color as Color

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemRectangleChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

Color color

);

[C++]

public: enumErrorCodes OSDItemRectangleChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

float fLeftPos,

float fTopPos,

float fWidth,

float fHeight,

Color color

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemRectGet (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

ByRef fLeftPos as Single,

ByRef fTopPos as Single,

ByRef fRightPos as Single,

ByRef fBottomPos as Single

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemRectGet (

Int16 nPlayerIndex,

Int32 nItemUniqueId

ref float fLeftPos,

ref float fTopPos,

ref float fRightPos,

ref float fBottomPos

);

[C++]

public: enumErrorCodes OSDItemRectGet (

Int16 nPlayerIndex,

Int32 nItemUniqueId

float __gc *fLeftPos,

float __gc *fTopPos,

float __gc *fRightPos,

float __gc *fBottomPos

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemRemove (

nPlayerIndex as Int16,

nItemUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemRemove (

Int16 nPlayerIndex,

Int32 nItemUniqueId

);

[C++]

public: enumErrorCodes OSDItemRemove (

Int16 nPlayerIndex,

Int32 nItemUniqueId

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemScrollByPixels (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

xOffset as Int32,

yOffset as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemScrollByPixels (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

Int32 xOffset,

Int32 yOffset

);

[C++]

public: enumErrorCodes OSDItemScrollByPixels (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

Int32 xOffset,

Int32 yOffset

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemShow (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemShow (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

bool bShow

);

[C++]

public: enumErrorCodes OSDItemShow (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

bool bShow

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | Hides the item
true | Shows 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.


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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemTextAdd (

nPlayerIndex as Int16,

strText as String,

fLeftPos as Single,

fTopPos as Single,

nAlpha as Int16,

nZOrder as Int32,

bShow as Boolean,

LogFont as ADJ_LOGFONT,

strFacename as String,

color as Color,

nAlignment as enumTextAlignment

) as Int32

[C#]

public Int32 OSDItemTextAdd (

Int16 nPlayerIndex,

string strText,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

enumTextAlignment nAlignment

);

[C++]

public: Int32 OSDItemTextAdd (

Int16 nPlayerIndex,

string strText,

float fLeftPos,

float fTopPos,

Int16 nAlpha,

Int32 nZOrder,

bool bShow,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

enumTextAlignment nAlignment

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | The item is initially kept hidden
true | The item is immediately shown

Visibility can be modified at a later time through the VideoPlayer.OSDItemShow method.

LogFont

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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemTextChange (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

strText as String,

LogFont as ADJ_LOGFONT,

strFacename as String,

color as Color,

nAlignment as enumTextAlignment

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemTextChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

string strText,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

enumTextAlignment nAlignment

);

[C++]

public: enumErrorCodes OSDItemTextChange (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

string strText,

ADJ_LOGFONT LogFont,

string strFacename,

Color color,

enumTextAlignment nAlignment

);

Parameter

Description

nPlayerIndex

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

LogFont

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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemZOrderGet (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

ByRef nZOrder as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemZOrderGet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

ref Int32 nZOrder

);

[C++]

public: enumErrorCodes OSDItemZOrderGet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

Int32 __gc *nZOrder

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDItemZOrderSet (

nPlayerIndex as Int16,

nItemUniqueId as Int32,

nZOrder as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes OSDItemZOrderSet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

Int32 nZOrder

);

[C++]

public: enumErrorCodes OSDItemZOrderSet (

Int16 nPlayerIndex,

Int32 nItemUniqueId,

Int32 nZOrder

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDKeyColorGet (

nPlayerIndex as Int16

) as Color

[C#]

public Color OSDKeyColorGet (

Int16 nPlayerIndex

);

[C++]

public: Color OSDKeyColorGet (

Int16 nPlayerIndex,

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the video player.

Return value

Value | Meaning
Color.Empty | An error occurred (see the LastError property for further error details)
Other color value | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function OSDKeyColorSet (

nPlayerIndex as Int16,

colorKey as Color

) as enumErrorCodes

[C#]

public enumErrorCodes OSDKeyColorSet (

Int16 nPlayerIndex,

Color colorKey

);

[C++]

public: enumErrorCodes OSDKeyColorSet (

Int16 nPlayerIndex,

Color colorKey

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


VideoPlayer.Pause method

VideoPlayer.Pause method

Remarks

Pauses the playing video.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PAUSED.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function Pause (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Pause (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes Pause (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Once the sound has been performed completely, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Function Play (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Play (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes Play (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Once the sound has been performed completely, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Function PlayRange (

nPlayerIndex as Int16,

nFromPosition as Int32,

nToPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlayRange (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition

);

[C++]

public: enumErrorCodes PlayRange (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

Each loop completion invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_RANGE_LOOP_DONE

Once the sound has been performed completely, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE..

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow section.

Syntax

[Visual Basic]

Public Function PlayRangeWithLoop (

nPlayerIndex as Int16,

nFromPosition as Int32,

nToPosition as Int32,

nLoopCount as Int32,

) as enumErrorCodes

[C#]

public enumErrorCodes PlayRangeWithLoop (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition,

Int32 nLoopCount

);

[C++]

public: enumErrorCodes PlayRangeWithLoop (

Int16 nPlayerIndex,

Int32 nFromPosition,

Int32 nToPosition,

Int32 nLoopCount

);

Parameter

Description

nPlayerIndex

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.PlayDisableLoop 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.


VideoPlayer.PlayDisableLoop method

VideoPlayer.PlayDisableLoop method

Remarks

Disables an eventual loop, set by a previous call to the VideoPlayer.Play method, without stopping the current playback.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function PlayDisableLoop (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayDisableLoop (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlayDisableLoop (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.NOERROR (0) | The method call was successful.


VideoPlayer.Resume method

VideoPlayer.Resume method

Remarks

Resumes playback of the paused video.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_PLAYING.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function Resume (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Resume (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes Resume (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function Rewind (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Rewind (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes Rewind (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function ScreenshotSaveToFile (

nPlayerIndex as Int16,

nUniqueID as Int32,

strPathname as String,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ScreenshotSaveToFile (

Int16 nPlayerIndex,

Int32 nUniqueID,

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: enumErrorCodes ScreenshotSaveToFile (

Int16 nPlayerIndex,

Int32 nUniqueID,

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

Parameter

Description

nPlayerIndex

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. In case the player should be "stopped", a call to this method will move the playback position and will automatically put the player in "paused" state.

If the seek operation brings the playback position beyond the end of the file, the CallbackForPlayersEvents delegate is invoked with the nEvent parameter set to EV_SOUND_DONE..

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function Seek (

nPlayerIndex as Int16,

nPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Seek (

Int16 nPlayerIndex,

Int32 nPosition

);

[C++]

public: enumErrorCodes Seek (

Int16 nPlayerIndex,

Int32 nPosition

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function SeekToNextFrame (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SeekToNextFrame (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes SeekToNextFrame (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function SeekToPreviousFrame (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SeekToPreviousFrame (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes SeekToPreviousFrame (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.NOERROR (0) | The method call was successful.


VideoPlayer.Stop method

VideoPlayer.Stop method

Remarks

Stops the playing video.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_SOUND_STOPPED.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function Stop (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Stop (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes Stop (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function VideoStreamKeepAspectRatio (

nPlayerIndex as Int16,

bKeepAspectRatio as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes VideoStreamKeepAspectRatio (

Int16 nPlayerIndex,

bool bKeepAspectRatio

);

[C++]

public: enumErrorCodes VideoStreamKeepAspectRatio (

Int16 nPlayerIndex,

bool bKeepAspectRatio

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | Don't keep the original aspect ratio
true (default) | Keep the original aspect ratio

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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function VideoStreamSendToActiveMovieWin (

nPlayerIndex as Int16,

bSend as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes VideoStreamSendToActiveMovieWin (

Int16 nPlayerIndex,

bool bSend

);

[C++]

public: enumErrorCodes VideoStreamSendToActiveMovieWin (

Int16 nPlayerIndex,

bool bSend

);

Parameter

Description

nPlayerIndex

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 | Meaning
false (default) | Don't send the video stream to the ActiveMovie window.
true | Send the video stream to the ActiveMovie window.

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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function VideoTransformIsAvailable (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool VideoTransformIsAvailable (

Int16 nPlayerIndex

);

[C++]

public: bool VideoTransformIsAvailable (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function VideoWindowAdd (

nPlayerIndex as Int16,

nUniqueID as Int32,

hWndTarget as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes VideoWindowAdd (

Int16 nPlayerIndex,

Int32 nUniqueID,

IntPtr hWndTarget,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes VideoWindowAdd (

Int16 nPlayerIndex,

Int32 nUniqueID,

IntPtr hWndTarget,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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.

For further details about the use of the embedded video player see the VideoPlayer class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function VideoWindowChangeTarget (

nPlayerIndex as Int16,

nUniqueID as Int32,

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes VideoWindowChangeTarget (

Int16 nPlayerIndex,

Int32 nUniqueID,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes VideoWindowChangeTarget (

Int16 nPlayerIndex,

Int32 nUniqueID,

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function VideoWindowGetHWND (

nPlayerIndex as Int16,

nUniqueID as Int32,

ByRef hWnd as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes VideoWindowGetHWND (

Int16 nPlayerIndex,

Int32 nUniqueID,

ref IntPtr hWnd

);

[C++]

public: enumErrorCodes VideoWindowGetHWND (

Int16 nPlayerIndex,

Int32 nUniqueID,

IntPtr __gc *hWnd

);

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
hWnd | Reference that, on return from the method call, will contain the HWND of the video rendering window.

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.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function VideoWindowMove (

nPlayerIndex as Int16,

nUniqueID as Int32,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes VideoWindowMove (

Int16 nPlayerIndex,

Int32 nUniqueID,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes VideoWindowMove (

Int16 nPlayerIndex,

Int32 nUniqueID,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about video clips rendering refer to the How to play video files through DirectShow tutorial.

Syntax

[Visual Basic]

Public Function VideoWindowShow (

nPlayerIndex as Int16,

nUniqueID as Int32,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes VideoWindowShow (

Int16 nPlayerIndex,

Int32 nUniqueID,

bool bShow

);

[C++]

public: enumErrorCodes VideoWindowShow (

Int16 nPlayerIndex,

Int32 nUniqueID,

bool bShow

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | Hide window
true (default) | Show window

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.


VolumeAutomationMan class

VolumeAutomationMan class

The VolumeAutomationMan class, accessible through the control's VolumeAutomation property contains methods needed to manage volume automation on sounds being played.

The VolumeAutomationMan class is implemented through the following methods and properties:

Methods

IsSliding

Load

LoadFromMemoryStream

PointAdd

PointEnable

PointGetCount

PointGetName

PointGetNext

PointGetParams

PointIsEnabled

PointRemove

PointSetParams

Reset

Save

SaveToMemoryStream

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# and Visual Basic.NET 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

[Visual Basic]

Public Property CurveDesigner As CurveDesignerMan

[C#]

public CurveDesignerMan CurveDesigner {get;}

[C++]

public: __property CurveDesignerMan* get_CurveDesigner ();

This property is Read-only

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

[Visual Basic]

Public Property PositionUnit As enumVolumeAutomationPosUnits

[C#]

public enumVolumeAutomationPosUnits PositionUnit {get; set;}

[C++]

public: __property enumVolumeAutomationPosUnits get_PositionUnit();

public: __property void set_PositionUnit(enumVolumeAutomationPosUnits);

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

See also

VolumeAutomation property

VolumeAutomationMan class

How to manage Volume Automation tutorial.


VolumeAutomation.ScaleType property

VolumeAutomation.ScaleType property

Type

[Visual Basic]

Public Property ScaleType As enumVolumeScales

[C#]

public enumVolumeScales ScaleType {get; set;}

[C++]

public: __property enumVolumeScales get_ScaleType();

public: __property void set_ScaleType(enumVolumeScales);

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

See also

VolumeAutomation property

VolumeAutomationMan class

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]

Public Function IsSliding (

nPlayerIndex as Int16

) as Boolean

[C#]

public bool IsSliding (

Int16 nPlayerIndex

);

[C++]

public: bool IsSliding (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_VOLUME_AUTOMATION_LOADED.

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]

Public Function Load (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes Load (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes Load (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
strPathname | 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.LoadFromMemoryStream method

VolumeAutomation.LoadFromMemoryStream method

Remarks

Loads a volume automation procedure from a memory stream containing the needed XML code into the given player. The existing procedure can be saved inside a memory stream through the VolumeAutomation.SaveToMemoryStream method.

A successful call to this method invokes the CallbackForPlayersEvents delegate with the nEvent parameter set to EV_VOLUME_AUTOMATION_LOADED.

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]

Public Function LoadFromMemoryStream (

nPlayerIndex as Int16,

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes LoadFromMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

[C++]

public: enumErrorCodes LoadFromMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
ms | Memory stream containing volume automation procedure in XML format

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.


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]

Public Function PointAdd (

nPlayerIndex as Int16,

strVolumePointName as String,

fPosition as Single,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PointAdd (

Int16 nPlayerIndex,

string strVolumePointName,

float fPosition,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes PointAdd (

Int16 nPlayerIndex,

string strVolumePointName,

float fPosition,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

Parameter

Description

nPlayerIndex

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]

Public Function PointEnable (

nPlayerIndex as Int16,

strVolumePointName as String,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes PointEnable (

Int16 nPlayerIndex,

string strVolumePointName,

bool bEnable

);

[C++]

public: enumErrorCodes PointEnable (

Int16 nPlayerIndex,

string strVolumePointName,

bool bEnable

);

Parameter

Description

nPlayerIndex

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 | Meaning
false | Disables the volume point
true | 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]

Public Function PointGetCount (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 PointGetCount (

Int16 nPlayerIndex

);

[C++]

public: Int32 PointGetCount (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function PointGetName (

nPlayerIndex as Int16,

nIndex as Int16

) as String

[C#]

public string PointGetName (

Int16 nPlayerIndex,

Int16 nIndex

);

[C++]

public: string PointGetName (

Int16 nPlayerIndex,

Int16 nIndex

);

Parameter | Description
nPlayerIndex | 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]

Public Function PointGetNext (

nPlayerIndex as Int16,

ByRef nIndexVolumePoint as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PointGetNext (

Int16 nPlayerIndex,

ref Int32 nIndexVolumePoint

);

[C++]

public: enumErrorCodes PointGetNext (

Int16 nPlayerIndex,

Int32 __gc *nIndexVolumePoint

);

Parameter | Description
nPlayerIndex | 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]

Public Function PointGetParams (

nPlayerIndex as Int16,

strVolumePointName as String,

Byref fPosition as Single,

Byref fVolumeLevel as Single,

Byref nCurveType as enumVolumeCurves

) as enumErrorCodes

[C#]

public enumErrorCodes PointGetParams (

Int16 nPlayerIndex,

string strVolumePointName,

ref float fPosition,

ref float fVolumeLevel,

ref enumVolumeCurves nCurveType

);

[C++]

public: enumErrorCodes PointGetParams (

Int16 nPlayerIndex,

string strVolumePointName,

float __gc *fPosition,

float __gc *fVolumeLevel,

enumVolumeCurves __gc *nCurveType

);

Parameter

Description

nPlayerIndex

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]

Public Function PointIsEnabled (

nPlayerIndex as Int16,

strVolumePointName as String

) as Boolean

[C#]

public bool PointIsEnabled (

Int16 nPlayerIndex,

string strVolumePointName

);

[C++]

public: bool PointIsEnabled (

Int16 nPlayerIndex,

string strVolumePointName

);

Parameter | Description
nPlayerIndex | 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]

Public Function PointRemove (

nPlayerIndex as Int16,

strVolumePointName as String

) as enumErrorCodes

[C#]

public enumErrorCodes PointRemove (

Int16 nPlayerIndex,

string strVolumePointName

);

[C++]

public: enumErrorCodes PointRemove (

Int16 nPlayerIndex,

string strVolumePointName

);

Parameter

Description

nPlayerIndex

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.

bEnable

Boolean value that specifies if the volume point must be enabled or disabled.

Supported values are the following:

Mnemonic constant | Meaning
false | Disables the volume point
true | 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.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]

Public Function PointSetParams (

nPlayerIndex as Int16,

strVolumePointName as String,

fPosition as Single,

fVolumeLevel as Single,

nCurveType as enumVolumeCurves,

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PointSetParams (

Int16 nPlayerIndex,

string strVolumePointName,

float fPosition,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes PointSetParams (

Int16 nPlayerIndex,

string strVolumePointName,

float fPosition,

float fVolumeLevel,

enumVolumeCurves nCurveType,

Int32 nDesignerUniqueId

);

Parameter

Description

nPlayerIndex

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]

Public Function Reset (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes Reset (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes Reset (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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.


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]

Public Function Save (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes Save (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes Save (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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
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.


VolumeAutomation.SaveToMemoryStream method

VolumeAutomation.SaveToMemoryStream method

Remarks

Saves the existing volume automation procedure into a memory stream in XML format. The volume automation procedure can be loaded at a later time through the VolumeAutomation.LoadFromMemoryStream method.

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]

Public Function SaveToMemoryStream (

nPlayerIndex as Int16,

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes SaveToMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

[C++]

public: enumErrorCodes SaveToMemoryStream (

Int16 nPlayerIndex,

MemoryStream ms

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
ms | Memory stream for storing Cue Points in XML format

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.


VolumeAutomation.CurveDesignerMan class

VolumeAutomation.CurveDesignerMan class

The CurveDesignerMan class, accessible through the control's VolumeAutomation.CurveDesigner property, contains methods needed to manage the embedded Curve Designer used for designing custom shaped curves in volume automation.

The CurveDesignerMan class is implemented through the following methods:

Methods

Create

Destroy

DisplayCurveType

GetGraphicalSettings

GetPoints

Move

Refresh

SetBackPictureFromFile

SetBackPictureFromHandle

SetGraphicalSettings

SetPoints

Show

Internal classes

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]

Public Function Create (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32,

colorParentBackColor as Color

) as Int32

[C#]

public Int32 Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Color colorParentBackColor

);

[C++]

public: Int32 Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Color colorParentBackColor

);

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
colorParentBackColor | Background color of the parent window

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]

Public Function Destroy (

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Destroy (

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes Destroy (

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function DisplayCurveType (

nDesignerUniqueId as Int32,

nCurveType as enumVolumeCurves

) as enumErrorCodes

[C#]

public enumErrorCodes DisplayCurveType (

Int32 nDesignerUniqueId,

enumVolumeCurves nCurveType

);

[C++]

public: enumErrorCodes DisplayCurveType (

Int32 nDesignerUniqueId,

enumVolumeCurves 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 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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.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]

Public Function GetGraphicalSettings (

nDesignerUniqueId as Int32,

ByRef settings as CURVE_DESIGNER_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes GetGraphicalSettings (

Int32 nDesignerUniqueId,

ref CURVE_DESIGNER_SETTINGS settings

);

[C++]

public: enumErrorCodes GetGraphicalSettings (

Int32 nDesignerUniqueId,

CURVE_DESIGNER_SETTINGS __gc *settings

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
settings | Reference to the object of class CURVE_DESIGNER_SETTINGS that receives in output graphical settings of the curve designer.

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.


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]

Public Function GetPoints (

nDesignerUniqueId as Int32,

ByRef nLeftX as Int16,

ByRef nLeftY as Int16,

ByRef nRightX as Int16,

ByRef nRightY as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes GetPoints (

Int32 nDesignerUniqueId,

ref Int16 nLeftX,

ref Int16 nLeftY,

ref Int16 nRightX,

ref Int16 nRightY

);

[C++]

public: enumErrorCodes GetPoints (

Int32 nDesignerUniqueId,

Int16 __gc *nLeftX,

Int16 __gc *nLeftY,

Int16 __gc *nRightX,

Int16 __gc *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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


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]

Public Function Move (

nDesignerUniqueId as Int32,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Move (

Int32 nDesignerUniqueId,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Move (

Int32 nDesignerUniqueId,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function Refresh (

nDesignerUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Refresh (

Int32 nDesignerUniqueId

);

[C++]

public: enumErrorCodes Refresh (

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SetBackPictureFromFile (

nDesignerUniqueId as Int32,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

Int32 nDesignerUniqueId,

string strPathname

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

Int32 nDesignerUniqueId,

string strPathname

);

Parameter | Description
nDesignerUniqueId | Number representing the zero-based index of the player that will use the Waveform
strPathname | Absolute pathname of the BMP file 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.


VolumeAutomation.CurveDesigner.SetBackPictureFromHandle method

VolumeAutomation.CurveDesigner.SetBackPictureFromHandle method

 Return to chapter overview

Remarks

Sets a background picture from an existing bitmap handle (HBITMAP).

For further details about using the embedded Waveform refer to the Waveform class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromHandle (

nDesignerUniqueId as Int32,

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

Int32 nDesignerUniqueId,

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

Int32 nDesignerUniqueId,

IntPtr 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.

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.


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]

Public Function SetGraphicalSettings (

nDesignerUniqueId as Int32,

settings as CURVE_DESIGNER_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SetGraphicalSettings (

Int32 nDesignerUniqueId,

CURVE_DESIGNER_SETTINGS settings

);

[C++]

public: enumErrorCodes SetGraphicalSettings (

Int32 nDesignerUniqueId,

CURVE_DESIGNER_SETTINGS settings

);

Parameter | Description
nDesignerUniqueId | Unique identifier of the curve designer returned by a previous call to the VolumeAutomation.CurveDesigner.Create method
settings | Object of class CURVE_DESIGNER_SETTINGS containing graphical settings of the curve designer.

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.


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]

Public Function SetPoints (

nDesignerUniqueId as Int32,

nLeftX as Int16,

nLeftY as Int16,

nRightX as Int16,

nRightY as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SetPoints (

Int32 nDesignerUniqueId,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 nRightY

);

[C++]

public: enumErrorCodes SetPoints (

Int32 nDesignerUniqueId,

Int16 nLeftX,

Int16 nLeftY,

Int16 nRightX,

Int16 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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


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]

Public Function Show (

nDesignerUniqueId as Int32,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

Int32 nDesignerUniqueId,

bool bShow

);

[C++]

public: enumErrorCodes Show (

Int32 nDesignerUniqueId,

bool 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 graphic bar control.

Supported values are the following:

Value | Meaning
false | Hides the curve designer window
true | Shows the curve designer window

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.


CURVE_DESIGNER_SETTINGS structure

CURVE_DESIGNER_SETTINGS structure

The CURVE_DESIGNER_SETTINGS structure (defined as CURVE_DESIGNER_SETTINGS_DLL when used for COM interoperability) 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.

C# definition

public struct CURVE_DESIGNER_SETTINGS

{

 public bool   bAppearance3d;

 public bool   bFadeIn;

 public Color colorCurveLine;

 public Color colorBackground;

 public Color colorHandles;

 public Color colorHandlesBorder;

 public Color colorHandleLines;

 public Color colorBorder;

 public Int16 nCurveLineWidth;

 public bool   bHandleLinesVisible;

}

Definition for COM interoperability

public struct CURVE_DESIGNER_SETTINGS_DLL

{

 public Int16 bAppearance3d;

 public Int16 bFadeIn;

 public Int32 colorCurveLine;

 public Int32 colorBackground;

 public Int32 colorHandles;

 public Int32 colorHandlesBorder;

 public Int32 colorHandleLines;

 public Int32 colorBorder;

 public Int16 nCurveLineWidth;

 public Int16 bHandleLinesVisible;

}

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:


VSTs class

VSTs class

The VSTs class, accessible through the control's VST property, contains methods needed to apply Steinberg's Virtual Studio Technology (VST) effects.

The VSTs class 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 a VST effect refer to the How to manage VST effects tutorial.

A sample of use of the VSTs class in Visual C# and Visual Basic.NET 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 show, hidden or moved using the VST.EditorShow method.

For further details about methods related to the use of VST effects refer to the VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function EditorGetInfo (

nPlayerIndex as Int16,

nIdVST as Int32,

pInfo as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes EditorGetInfo (

Int16 nPlayerIndex,

Int32 nIdVST,

IntPtr pInfo

);

[C++]

public: enumErrorCodes EditorGetInfo (

Int16 nPlayerIndex,

Int32 nIdVST,

IntPtr pInfo

);

Parameter

Description

nPlayerIndex

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 an object of class VstEditorInfo containing information about the VST editor.

The VST_EDITOR_INFO data structure is defined in C++ as follows:

public class VstEditorInfo

{

 bool   bIsEditorAvailable;

 bool   bIsEditorVisible;

 Int16   nEditorLeft;

 Int16   nEditorTop;

 Int16   nEditorWidth;

 Int16   nEditorHeight;

}

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 editor can be obtained through the VST.EditorGetInfo method.

For further details about methods related to the use of VST effects refer to the VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function EditorMove (

nPlayerIndex as Int16,

nIdVST as Int32,

leftPos as Int32,

topPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EditorMove (

Int16 nPlayerIndex,

Int32 nIdVST,

Int32 leftPos,

Int32 topPos

);

[C++]

public: enumErrorCodes EditorMove (

Int16 nPlayerIndex,

Int32 nIdVST,

Int32 leftPos,

Int32 topPos

);

Parameter | Description
nPlayerIndex | 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 editor can be obtained through the VST.EditorGetInfo method.

For further details about methods related to the use of VST effects refer to the VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function EditorShow (

nPlayerIndex as Int16,

nIdVST as Int32,

bShow as Boolean,

hWndParent as IntPtr,

leftPos as Int32,

topPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EditorShow (

Int16 nPlayerIndex,

Int32 nIdVST,

bool bShow,

IntPtr hWndParent,

Int32 leftPos,

Int32 topPos

);

[C++]

public: enumErrorCodes EditorShow (

Int16 nPlayerIndex,

Int32 nIdVST,

bool bShow,

IntPtr hWndParent,

Int32 leftPos,

Int32 topPos

);

Parameter

Description

nPlayerIndex

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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function EffectEnable (

nPlayerIndex as Int16,

nIdVST as Int32,

bEnable as Boolean,

nPriority as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EffectEnable (

Int16 nPlayerIndex,

Int32 nIdVST,

bool bEnable,

Int32 nPriority

);

[C++]

public: enumErrorCodes EffectEnable (

Int16 nPlayerIndex,

Int32 nIdVST,

bool bEnable,

Int32 nPriority

);

Parameter

Description

nPlayerIndex

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
false | Disables the VST effect
true | Enable the VST effect

nPriority

VST effects 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function EffectFlush (

nPlayerIndex as Int16,

nIdVST as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EffectFlush (

Int16 nPlayerIndex,

Int32 nIdVST

);

[C++]

public: enumErrorCodes EffectFlush (

Int16 nPlayerIndex,

Int32 nIdVST

);

Parameter | Description
nPlayerIndex | 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function EffectFree (

nIdVST as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EffectFree (

Int32 nIdVST

);

[C++]

public: enumErrorCodes EffectFree (

Int32 nIdVST

);

Parameter | Description
nIdVST | Unique identifier of the VST effect as returned by the VST.Load 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function EffectLoad (

nPlayerIndex as Int16,

strPathname as String,

bEnable as Boolean

) as Int32

[C#]

public Int32 EffectLoad (

Int16 nPlayerIndex,

string strPathname,

bool bEnable

);

[C++]

public: Int32 EffectLoad (

Int16 nPlayerIndex,

string strPathname,

bool bEnable

);

Parameter

Description

nPlayerIndex

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
false | Doesn't enable the VST effect after loading
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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function GetInfo (

nPlayerIndex as Int16,

nIdVST as Int32,

ByRef Info as VstEffectInfo

) as enumErrorCodes

[C#]

public enumErrorCodes GetInfo (

Int16 nPlayerIndex,

Int32 nIdVST,

ref VstEffectInfo Info

);

[C++]

public: enumErrorCodes GetInfo (

Int16 nPlayerIndex,

Int32 nIdVST,

VstEffectInfo __gc *Info

);

Parameter

Description

nPlayerIndex

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.

Info

Reference to an instance of class VstEffectInfo containing information about the VST effect.

The VstEffectInfo class is defined in C# as follows:

public class VstEffectInfo

{

 public Int32   nRegisteredUniqueID;

 public Int32   nVersion;

 public Int32   nVstVersion;

 public Int32   nVstMaxSupportedVersion;

 public Int32   nInputChannels;

 public Int32   nOutputChannels;

 public Int32   nInitialDelay;

 public Int32   ptrUnderlyingAEffect;

}

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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function GetInfoString (

nPlayerIndex as Int16,

nIdVST as Int32,

nInfo as enumVstInfo

) as string

[C#]

public string GetInfoString (

Int16 nPlayerIndex,

Int32 nIdVST,

enumVstInfo nInfo

);

[C++]

public: string GetInfoString (

Int16 nPlayerIndex,

Int32 nIdVST,

enumVstInfo nInfo

);

Parameter

Description

nPlayerIndex

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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function GetType (

nIdVST as Int32,

ByRef nType as enumVstType

) as string

[C#]

public string GetType (

Int32 nIdVST,

ref enumVstType nType

);

[C++]

public: string GetType (

Int32 nIdVST,

enumVstType __gc *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 MIDIMan class, is not supported.

For further details about methods related to the use of VST effects refer to the VSTs class.

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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function InstrumentEventApply (

nPlayerIndex as Int16,

nMidiEvent as enumMidiStreamEvents,

nMidiParam1 as Int16,

nMidiParam2 as Int16,

nMidiChannel as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes InstrumentEventApply (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

Int16 nMidiParam1,

Int16 nMidiParam2,

Int16 nMidiChannel

);

[C++]

public: enumErrorCodes InstrumentEventApply (

Int16 nPlayerIndex,

enumMidiStreamEvents nMidiEvent,

Int16 nMidiParam1,

Int16 nMidiParam2,

Int16 nMidiChannel

);

Parameter

Description

nPlayerIndex

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 CallbackForMidiStreamEvents delegate.
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 (see the LastError property for further error details)
enumErrorCodes.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 MIDIMan class, is not supported.

For further details about methods related to the use of VST effects refer to the VSTs class.

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 MIDIMan class section and the How to deal with MIDI protocol tutorial.

Syntax

[Visual Basic]

Public Function InstrumentEventRawApply (

nPlayerIndex as Int16,

nByte0 as Byte,

nByte1 as Byte,

nByte2 as Byte

) as enumErrorCodes

[C#]

public enumErrorCodes InstrumentEventRawApply (

Int16 nPlayerIndex,

Byte nByte0,

Byte nByte1,

Byte nByte2

);

[C++]

public: enumErrorCodes InstrumentEventRawApply (

Int16 nPlayerIndex,

Byte nByte0,

Byte nByte1,

Byte nByte2

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function InstrumentFree (

nPlayerIndex as Int16

) as Int32

[C#]

public Int32 InstrumentFree (

Int16 nPlayerIndex

);

[C++]

public: Int32 InstrumentFree (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function InstrumentLoad (

nPlayerIndex as Int16,

strPathname as String,

nFrequency as Int32,

nChannels as Int16

) as Int32

[C#]

public Int32 InstrumentLoad (

Int16 nPlayerIndex,

string strPathname,

Int32 nFrequency,

Int16 nChannels

);

[C++]

public: Int32 InstrumentLoad (

Int16 nPlayerIndex,

string strPathname,

Int32 nFrequency,

Int16 nChannels

);

Parameter

Description

nPlayerIndex

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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramGetCurrent (

nPlayerIndex as Int16,

nIdVST as Int32

) as Int16

[C#]

public Int16 ProgramGetCurrent (

Int16 nPlayerIndex,

Int32 nIdVST

);

[C++]

public: Int16 ProgramGetCurrent (

Int16 nPlayerIndex,

Int32 nIdVST

);

Parameter | Description
nPlayerIndex | 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramSetCurrent (

nPlayerIndex as Int16,

nIdVST as Int32,

nProgramIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ProgramSetCurrent (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex

);

[C++]

public: enumErrorCodes ProgramSetCurrent (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex

);

Parameter | Description
nPlayerIndex | 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramNameGet (

nPlayerIndex as Int16,

nIdVST as Int32,

nProgramIndex as Int16

) as string

[C#]

public string ProgramNameGet (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex

);

[C++]

public: string ProgramNameGet (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex

);

Parameter | Description
nPlayerIndex | 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramNameSet (

nPlayerIndex as Int16,

nIdVST as Int32,

nProgramIndex as Int16,

strName as string

) as enumErrorCodes

[C#]

public enumErrorCodes ProgramNameSet (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

string strName

);

[C++]

public: enumErrorCodes ProgramNameSet (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

string strName

);

Parameter | Description
nPlayerIndex | 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
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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramParamGetDefaultValue (

nPlayerIndex as Int16,

nIdVST as Int32,

nProgramIndex as Int16,

nParamIndex as Int16,

fValue as Single

) as enumErrorCodes

[C#]

public enumErrorCodes ProgramParamGetDefaultValue (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

Int16 nParamIndex,

ref float fValue

);

[C++]

public: enumErrorCodes ProgramParamGetDefaultValue (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

Int16 nParamIndex,

float __gc *fValue

);

Parameter | Description
nPlayerIndex | 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
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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramParamGetInfo (

nPlayerIndex as Int16,

nIdVST as Int32,

nProgramIndex as Int16,

nParamIndex as Int16,

nInfo as enumVstParamInfo

) as string

[C#]

public string ProgramParamGetInfo (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

Int16 nParamIndex,

enumVstParamInfo nInfo

);

[C++]

public: string ProgramParamGetInfo (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

Int16 nParamIndex,

enumVstParamInfo nInfo

);

Parameter

Description

nPlayerIndex

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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramParamGetValue (

nPlayerIndex as Int16,

nIdVST as Int32,

nProgramIndex as Int16,

nParamIndex as Int16,

fValue as Single

) as enumErrorCodes

[C#]

public enumErrorCodes ProgramParamGetValue (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

Int16 nParamIndex,

ref float fValue

);

[C++]

public: enumErrorCodes ProgramParamGetValue (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

Int16 nParamIndex,

float __gc *fValue

);

Parameter

Description

nPlayerIndex

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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramParamSetValue (

nPlayerIndex as Int16,

nIdVST as Int32,

nProgramIndex as Int16,

nParamIndex as Int16,

fValue as Single

) as enumErrorCodes

[C#]

public enumErrorCodes ProgramParamSetValue (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

Int16 nParamIndex,

float fValue

);

[C++]

public: enumErrorCodes ProgramParamSetValue (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex,

Int16 nParamIndex,

float fValue

);

Parameter | Description
nPlayerIndex | 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramParamsGetCount (

nPlayerIndex as Int16,

nIdVST as Int32,

nProgramIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes ProgramParamsGetCount (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex

);

[C++]

public: enumErrorCodes ProgramParamsGetCount (

Int16 nPlayerIndex,

Int32 nIdVST,

Int16 nProgramIndex

);

Parameter | Description
nPlayerIndex | 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 VSTs class.

For further details about managing a VST effect refer to the How to manage VST effects tutorial.

Syntax

[Visual Basic]

Public Function ProgramsGetCount (

nPlayerIndex as Int16,

nIdVST as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ProgramsGetCount (

Int16 nPlayerIndex,

Int32 nIdVST

);

[C++]

public: enumErrorCodes ProgramsGetCount (

Int16 nPlayerIndex,

Int32 nIdVST

);

Parameter | Description
nPlayerIndex | 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 class

VUMeter class

The VUMeter class, accessible through the control's DisplayVUMeter property, 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 class is implemented through the following methods and properties:

Methods

Create

CreateNew

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 audioDjStudio1 on a form and that you want to change a couple of graphic settings (Bands and Background colors).

Visual Basic.NET

Here follows the code needed to perform the requested operations

' create the VU-meter on player 0 over an existing control

AudioDjStudio1.DisplayVUMeter.Create(0, PictureBox1.Handle)

' set the blue color for VU-meter bands of player 0

AudioDjStudio1.DisplayVUMeter.set_ColorBands(0, Color.Blue)

' set the white color for VU-meter background of player 0

AudioDjStudio1.DisplayVUMeter.set_ColorBackground(0, Color.White)

Visual C#.NET

Here follows the code needed to perform the requested operations

// create the VU-meter on player 0 over an existing control

audioDjStudio1.DisplayVUMeter.Create(0, pictureBox1.Handle);

// set the blue color for VU-meter bands of player 0

audioDjStudio1.DisplayVUMeter.set_ColorBands (0, Color.Blue);

// set the white color for VU-meter background of player 0

audioDjStudio1.DisplayVUMeter.set_ColorBackground(0, Color.White);


VUMeter.BandType property

VUMeter.BandType property

Remarks

Determines 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).

Syntax

[Visual Basic]

Public Function get_BandType (

nPlayerIndex as Int16

) as enumVuBandsMode

Public Sub set_BandType (

nPlayerIndex as Int16,

nBandMode as enumVuBandsMode

)

[C#]

public enumVuBandsMode get_BandType (

Int16 nPlayerIndex

);

public void set_BandType (

Int16 nPlayerIndex,

enumVuBandsMode nBandMode

);

[C++]

public: enumVuBandsMode get_BandType (

Int16 nPlayerIndex

);

public: void set_BandType (

Int16 nPlayerIndex,

enumVuBandsMode nBandMode

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will use the VU-Meter

nBandMode

Mnemonic value | 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 class.

DisplayVUMeter property

How to use the embedded Visual Feedbacks section.


VUMeter.ColorBackground property

VUMeter.ColorBackground property

Remarks

Determines the color of the VU-Meter background.

Syntax

[Visual Basic]

Public Function get_ColorBackground (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorBackground (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorBackground (

Int16 nPlayerIndex

);

public void set_ColorBackground (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorBackground (

Int16 nPlayerIndex

);

public: void set_ColorBackground (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the VU-Meter
color | The new color to apply

See also

VUMeter class.

DisplayVUMeter property

How to use the embedded Visual Feedbacks section.


VUMeter.ColorBands property

VUMeter.ColorBands property

Remarks

Determines the VU-Meter "bands" color.

Syntax

[Visual Basic]

Public Function get_ColorBands (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorBands (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorBands (

Int16 nPlayerIndex

);

public void set_ColorBands (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorBands (

Int16 nPlayerIndex

);

public: void set_ColorBands (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the VU-Meter
color | The new color to apply

See also

VUMeter class.

DisplayVUMeter property

How to use the embedded Visual Feedbacks section.


VUMeter.ColorPeaks property

VUMeter.ColorPeaks property

Remarks

Determines the VU-Meter "peaks" color.

Syntax

[Visual Basic]

Public Function get_ColorPeaks (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorPeaks (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorPeaks (

Int16 nPlayerIndex

);

public void set_ColorPeaks (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorPeaks (

Int16 nPlayerIndex

);

public: void set_ColorPeaks (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the VU-Meter
color | The new color to apply

See also

VUMeter class.

DisplayVUMeter property

How to use the embedded Visual Feedbacks section.


VUMeter.HasPeaks property

VUMeter.HasPeaks property

Remarks

Determines if the embedded VU-Meter visual feedback will display graphic "peaks" over the "bands".

Syntax

[Visual Basic]

Public Function get_HasPeaks (

nPlayerIndex as Int16

) as Boolean

Public Sub set_HasPeaks (

nPlayerIndex as Int16,

bHasPeaks as Boolean

)

[C#]

public bool get_HasPeaks (

Int16 nPlayerIndex

);

public void set_HasPeaks (

Int16 nPlayerIndex,

bool bHasPeaks

);

[C++]

public: bool get_HasPeaks (

Int16 nPlayerIndex

);

public: void set_HasPeaks (

Int16 nPlayerIndex,

bool bHasPeaks

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will use the VU-Meter

bHasPeaks

Mnemonic value | Meaning
false | No peaks
true (default) | Visible peaks

See also

VUMeter class.

DisplayVUMeter property

How to use the embedded Visual Feedbacks section.


VUMeter.ZoomPerc property

VUMeter.ZoomPerc property

Remarks

Determines the height zoom percentage of bands drawn. By default set to 100%, can assume values in the range from 5% to 500%

Syntax

[Visual Basic]

Public Function get_ZoomPerc (

nPlayerIndex as Int16

) as Int16

Public Sub set_ZoomPerc (

nPlayerIndex as Int16,

nZoomPerc as Int16

)

[C#]

public Int16 get_ZoomPerc (

Int16 nPlayerIndex

);

public void set_ZoomPerc (

Int16 nPlayerIndex,

Int16 nZoomPerc

);

[C++]

public: Int16 get_ZoomPerc (

Int16 nPlayerIndex

);

public: void set_ZoomPerc (

Int16 nPlayerIndex,

Int16 nZoomPerc

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Oscilloscope
nZoomPerc | The new zoom percentage to apply

See also

VUMeter class.

DisplayVUMeter 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. For development environments like WPF, where controls don't expose a HWND, the usage of the VUMeter.CreateNew method should be preferred.

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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Create (

nPlayerIndex as Int16,

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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: set this parameter to 0 if you want to implement your own VU-Meter graphics driven by values received through the CallbackForPlayersEvents delegate invoked with the nEvent parameter set to EV_VUMETER.

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.


VUMeter.CreateNew method

VUMeter.CreateNew method

Remarks

Creates a new instance of the VUMeter class on the given parent window. This method is alternative to the VUMeter.Create method and should be used when dealing with development environments like WPF where controls don't expose a HWND.

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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function CreateNew (

nPlayerIndex as Int16,

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the VU-Meter
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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function KeepCountOfVolume (

nPlayerIndex as Int16,

bKeepCountOfVolume as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes KeepCountOfVolume (

Int16 nPlayerIndex,

bool bKeepCountOfVolume

);

[C++]

public: enumErrorCodes KeepCountOfVolume (

Int16 nPlayerIndex,

bool bKeepCountOfVolume

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | 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.
true (default) | 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 CallbackForPlayersEvents delegate invoked with the nEvent parameter set to EV_VUMETER

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.


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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Resize (

nPlayerIndex as Int16,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Resize (

Int16 nPlayerIndex,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Resize (

Int16 nPlayerIndex,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromFile (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromHandle (

nPlayerIndex as Int16,

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetHwnd (

nPlayerIndex as Int16

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Show (

nPlayerIndex as Int16,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

[C++]

public: enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Hides the VU-Meter graphics
true | Shows the VU-Meter graphics

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.


WASAPIMan class

WASAPIMan class

The WASAPIMan class, accessible through the component's WASAPI property contains methods needed to manage WASAPI.

The WASAPIMan class 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#.NET and Visual Basic.NET 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.

This method is only intended for usage with Windows Vista and later versions.

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]

Public Function AttachInputDeviceToPlayer (

nPlayerIndex as Int16,

nDeviceIndex as Int16,

nDeviceType as enumWasapiDeviceTypes

) as enumErrorCodes

[C#]

public enumErrorCodes AttachInputDeviceToPlayer (

Int16 nPlayerIndex,

Int16 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

[C++]

public: enumErrorCodes AttachInputDeviceToPlayer (

Int16 nPlayerIndex,

Int16 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceChannelsGet (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

nChannelsCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceChannelsGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

ref Int32 nChannelsCount

);

[C++]

public: enumErrorCodes DeviceChannelsGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

Int32 __gc  *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 (see the LastError property for further error details)
enumErrorCodes.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 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: 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 WASAPIMan class 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]

Public Function DeviceCoreAudioIndexGet (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

ByRef nIndexCoreAudio as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceCoreAudioIndexGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

ref Int32 nIndexCoreAudio

);

[C++]

public: enumErrorCodes DeviceCoreAudioIndexGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

Int32 __gc  *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 (see the LastError property for further error details)
enumErrorCodes.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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial.

Syntax

[Visual Basic]

Public Function DeviceGetCount (

nDeviceType as enumWasapiDeviceTypes,

ByRef nDevicesCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceGetCount (

enumWasapiDeviceTypes nDeviceType,

ref Int32 nDevicesCount

);

[C++]

public: enumErrorCodes DeviceGetCount (

enumWasapiDeviceTypes nDeviceType,

Int32 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceGetDesc (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes

) as String

[C#]

public string DeviceGetDesc (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

[C++]

public: string DeviceGetDesc (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

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.

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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceIsFormatSupported (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

nFrequency as Int32,

nChannels as Int16

) as Booelan

[C#]

public bool DeviceIsFormatSupported (

Int32 nDeviceIndex,

enumWasapiDeviceTypes DeviceMuteSet,

Int32 nFrequency,

Int16 nChannels

);

[C++]

public: bool DeviceIsFormatSupported (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

Int32 nFrequency,

Int16 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceIsStarted (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes

) as Boolean

[C#]

public bool DeviceIsStarted (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

[C++]

public: bool DeviceIsStarted (

Int32 nDeviceIndex,

enumWasapiDeviceTypes 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceLatencyGet (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

ByRef nLatencyMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceLatencyGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

ref Int32 nLatencyMs

);

[C++]

public: enumErrorCodes DeviceLatencyGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

Int32 __gc  *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 (see the LastError property for further error details)
enumErrorCodes.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 WASAPIMan class 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]

Public Function DeviceMuteGet (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

ByRef bMute as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceMuteGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

ref bool bMute

);

[C++]

public: enumErrorCodes DeviceMuteGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

bool __gc  *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 | Meaning
false | The audio stream is not muted
true | The audio stream is muted

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.


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 WASAPIMan class 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]

Public Function DeviceMuteSet (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

ByRef bMute as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceMuteSet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes DeviceMuteSet,

ref bool bMute

);

[C++]

public: enumErrorCodes DeviceMuteGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

bool __gc  *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 | Meaning
false | The audio stream is not muted
true | The audio stream is muted

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.


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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceSharedFormatGet (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

ByRef nFrequency as Int32,

ByRef nChannels as Int16,

ByRef nBitDepth as enumWasapiBitDepths

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceSharedFormatGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes DeviceMuteSet,

ref Int32 nFrequency,

ref Int16 nChannels

);

[C++]

public: enumErrorCodes DeviceSharedFormatGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

Int32 __gc *nFrequency,

Int16 __gc *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 (see the LastError property for further error details)
enumErrorCodes.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 InitSoundSystem method.

This method will affect any other instance of the component inside the application. If the component should be used in conjunction with the Audio Sound Recorder API for .NET and/or Audio Sound Editor API for .NET components, these ones 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceStartExclusive (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

nSampleRate as Int32,

nChannels as Int16,

nBufferLengthMs as Int32,

nBufferUpdateTimeMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceStartExclusive (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

Int32 nSampleRate,

Int16 nChannels,

Int32 nBufferLengthMs,

Int32 nBufferUpdateTimeMs

);

[C++]

public: enumErrorCodes DeviceStartExclusive (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

Int32 nSampleRate,

Int16 nChannels,

Int32 nBufferLengthMs,

Int32 nBufferUpdateTimeMs

);

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.

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 (see the LastError property for further error details)
enumErrorCodes.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 InitSoundSystem method.

This method will affect any other instance of the component inside the application. If the component should be used in conjunction with the Audio Sound Recorder API for .NET and/or Audio Sound Editor API for .NET components, these ones would be affected too.

If you should be using Audio Dj Studio API for .NET in conjunction with Audio Sound Recorder API for .NET, as seen inside the WasapiStreamMixer sample, you should prefer calling this method from Audio Dj Studio API for .NET 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceStartShared (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

nChannelMode as enumWasapiChannelModes,

nBufferLengthMs as Int32,

nBufferUpdateTimeMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceStartShared (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

enumWasapiChannelModes nChannelMode,

Int32 nBufferLengthMs,

Int32 nBufferUpdateTimeMs

);

[C++]

public: enumErrorCodes DeviceStartShared (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

enumWasapiChannelModes nChannelMode,

Int32 nBufferLengthMs,

Int32 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 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 StreamOutputSpeakerSet 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 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 Audio Sound Recorder API for .NET component.

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 (see the LastError property for further error details)
enumErrorCodes.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 component inside the application. If the component should be used in conjunction with the Audio Sound Recorder API for .NET and/or Audio Sound Editor API for .NET components, these ones 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 WASAPIMan class and the How to manage audio flow through WASAPI tutorial

Syntax

[Visual Basic]

Public Function DeviceStop (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

bReset as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceStop (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

bool bReset

);

[C++]

public: enumErrorCodes DeviceStop (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

bool 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 | Meaning
false | The device buffer must not be reset
true | The device buffer must be reset

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.


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 WASAPIMan class 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]

Public Function DeviceVolumeGet (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

nScaleType as enumVolumeScales,

ByRef fVolumeLevel as Single

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceVolumeGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

enumVolumeScales nScaleType,

ref float fVolumeLevel

);

[C++]

public: enumErrorCodes DeviceVolumeGet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

enumVolumeScales nScaleType,

float __gc *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 master's volume level (the meaning of the returned value depends upon the nScaleType 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.


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 WASAPIMan class 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]

Public Function DeviceVolumeSet (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

nScaleType as enumVolumeScales,

fVolumeLevel as Single

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceVolumeSet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

enumVolumeScales nScaleType,

float fVolumeLevel

);

[C++]

public: enumErrorCodes DeviceVolumeSet (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

enumVolumeScales 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Waveform class

Waveform class

The Waveform class, accessible through the control's DisplayWaveform property, 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 class is implemented through the following methods and properties:

Methods

Create

CreateNew

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 audioDjStudio1 on a form or dialog and that you want to change a couple of graphic settings (Line and Background colors).

Visual Basic.NET

Here follows the code needed to perform the requested operations

' create the Waveform on player 0 over an existing control

AudioDjStudio1.DisplayWaveform.Create(0, PictureBox1.Handle)

' set the blue color for Waveform line of player 0

AudioDjStudio1.DisplayWaveform.set_ColorLine(0, Color.Blue)

' set the white color for Waveform background of player 0

AudioDjStudio1.DisplayWaveform.set_ColorBackground(0, Color.White)

Visual C#.NET

Here follows the code needed to perform the requested operations

// create the Waveform on player 0 over an existing control

audioDjStudio1.DisplayWaveform.Create(0, pictureBox1.Handle);

// set the blue color for Waveform line of player 0

audioDjStudio1.DisplayWaveform.set_ColorLine (0, Color.Blue);

// set the white color for Waveform background of player 0

audioDjStudio1.DisplayWaveform.set_ColorBackground(0, Color.White);


Waveform.ColorBackground property

Waveform.ColorBackground property

Remarks

Determines the color of the Waveform background.

Syntax

[Visual Basic]

Public Function get_ColorBackground (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorBackground (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorBackground (

Int16 nPlayerIndex

);

public void set_ColorBackground (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorBackground (

Int16 nPlayerIndex

);

public: void set_ColorBackground (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Waveform
color | The new color to apply

See also

Waveform class.

DisplayWaveform property

How to use the embedded Visual Feedbacks tutorial.

How to obtain the sound's waveform tutorial.


Waveform.ColorLine property

Waveform.ColorLine property

Remarks

Determines the color of the Waveform line.

Syntax

[Visual Basic]

Public Function get_ColorLine (

nPlayerIndex as Int16

) as Color

Public Sub set_ColorLine (

nPlayerIndex as Int16,

color as Color

)

[C#]

public Color get_ColorLine (

Int16 nPlayerIndex

);

public void set_ColorLine (

Int16 nPlayerIndex,

Color color

);

[C++]

public: Color get_ColorLine (

Int16 nPlayerIndex

);

public: void set_ColorLine (

Int16 nPlayerIndex,

Color color

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Waveform
color | The new color to apply

See also

Waveform class.

DisplayWaveform property

How to use the embedded Visual Feedbacks tutorial.

How to obtain the sound's waveform tutorial.


Waveform.UpdateResolution property

Waveform.UpdateResolution property

Remarks

Determines how frequently vertical lines are drawn on the screen (by default every 30 milliseconds).

Syntax

[Visual Basic]

Public Function get_UpdateResolution (

nPlayerIndex as Int16

) as enumWaveformUpdateRes

Public Sub set_UpdateResolution (

nPlayerIndex as Int16,

nResolution as enumWaveformUpdateRes

)

[C#]

public enumWaveformUpdateRes get_UpdateResolution (

Int16 nPlayerIndex

);

public void set_UpdateResolution (

Int16 nPlayerIndex,

enumWaveformUpdateRes nResolution

);

[C++]

public: enumWaveformUpdateRes get_UpdateResolution (

Int16 nPlayerIndex

);

public: void set_UpdateResolution (

Int16 nPlayerIndex,

enumWaveformUpdateRes nResolution

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will use the Waveform

nResolution

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 class.

DisplayWaveform property

How to use the embedded Visual Feedbacks section.


Waveform.UseHalfColorForPeaks property

Waveform.UseHalfColorForPeaks property

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.

Syntax

[Visual Basic]

Public Function get_UseHalfColorForPeaks (

nPlayerIndex as Int16

) as Boolean

Public Sub set_UseHalfColorForPeaks (

nPlayerIndex as Int16,

bUseHalfColor as Boolean

)

[C#]

public bool get_UseHalfColorForPeaks (

Int16 nPlayerIndex

);

public void set_UseHalfColorForPeaks (

Int16 nPlayerIndex,

bool bUseHalfColor

);

[C++]

public: bool get_UseHalfColorForPeaks (

Int16 nPlayerIndex

);

public: void set_UseHalfColorForPeaks (

Int16 nPlayerIndex,

bool bUseHalfColor

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the player that will use the Waveform

bUseHalfColor

Boolean value determining if half color must be used.

Mnemonic value | Meaning
false | Don't use half color for drawing waveform peaks
true (default) | Use half color for drawing waveform peaks

See also

Waveform class.

DisplayWaveform property

How to use the embedded Visual Feedbacks tutorial.

How to obtain the sound's waveform tutorial.


Waveform.ZoomPerc property

Waveform.ZoomPerc property

Remarks

Determines the height zoom percentage of waveform's lines.

Syntax

[Visual Basic]

Public Function get_ZoomPerc (

nPlayerIndex as Int16

) as Int16

Public Sub set_ZoomPerc (

nPlayerIndex as Int16,

nZoomPerc as Int16

)

[C#]

public Int16 get_ZoomPerc (

Int16 nPlayerIndex

);

public void set_ZoomPerc (

Int16 nPlayerIndex,

Int16 nZoomPerc

);

[C++]

public: Int16 get_ZoomPerc (

Int16 nPlayerIndex

);

public: void set_ZoomPerc (

Int16 nPlayerIndex,

Int16 nZoomPerc

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Waveform
nZoomPerc | The new zoom percentage to apply. By default set to 100%, can assume values in the range from 5% to 500%

See also

Waveform class.

DisplayWaveform 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 cause the CallbackForPlayersEvents delegate to be invoked with the nEvent parameter set to EV_WAVE_ANALYSIS_DONE

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]

Public Function AnalyzeAbort (

nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes AnalyzeAbort (

Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes AnalyzeAbort (

Int16 nPlayerIndex

);

Parameter | Description
nPlayerIndex | 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 CallbackForPlayersEvents delegate which is invoked with the nEvent parameter set to:

· EV_WAVE_ANALYSIS_START: invoked when the sound's analysis begins.
· EV_WAVE_ANALYSIS_PERC: invoked several times during the analysis in order to inform the container application about the percentage of advancement.
· EV_WAVE_ANALYSIS_DONE: invoked 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.

NOTE: Remember that a call to a method of a certain .NET component should be never performed from within a management function of an event generated by the same .NET component: 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]

Public Function AnalyzeFullSound (

nPlayerIndex as Int16,

nResolution as enumWaveformResolutions

) as enumErrorCodes

[C#]

public enumErrorCodes AnalyzeFullSound (

Int16 nPlayerIndex,

enumWaveformResolutions nResolution

);

[C++]

public: enumErrorCodes AnalyzeFullSound (

Int16 nPlayerIndex,

enumWaveformResolutions nResolution

);

Parameter

Description

nPlayerIndex

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.Create method

Waveform.Create method

Remarks

Creates the Waveform object for real-time visual feedback during sound's playback: once created, the Waveform feedback will stay active until the termination of the container application: being a graphical object, the Waveform feedback 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. For development environments like WPF, where controls don't expose a HWND, the usage of the Waveform.CreateNew method should be preferred.

Once created, by default the Waveform feedback 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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Create (

nPlayerIndex as Int16,

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes Create (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


Waveform.CreateNew method

Waveform.CreateNew method

Remarks

Creates a new instance of the Waveform class on the given parent window. This method is alternative to the Waveform.Create method and should be used when dealing with development environments like WPF where controls don't expose a HWND.

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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function CreateNew (

nPlayerIndex as Int16,

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the VU-Meter
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
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


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.

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]

Public Function BitmapViewDrawToHdc (

hDC as IntPtr,

nPosLeft as Int32,

nPosTop as Int32,

nWidth as Int32,

nHeight as Int32,

nWaveformStereoMode as enumWaveformStereoModes,

bUseHalfColorsForPeaks as Boolean,

bShowVerticalLines as Boolean,

nStartPos as Int32,

nEndPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes BitmapViewDrawToHdc (

IntPtr hDC,

Int32 nPosLeft,

Int32 nPosTop,

Int32 nWidth,

Int32 nHeight,

enumWaveformStereoModes nWaveformStereoMode,

bool bUseHalfColorsForPeaks,

bool bShowVerticalLines,

Int32 nStartPos,

Int32 nEndPos

);

[C++]

public: enumErrorCodes BitmapViewDrawToHdc (

IntPtr hDC,

Int32 nPosLeft,

Int32 nPosTop,

Int32 nWidth,

Int32 nHeight,

enumWaveformStereoModes nWaveformStereoMode,

bool bUseHalfColorsForPeaks,

bool bShowVerticalLines,

Int32 nStartPos,

Int32 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 | Meaning
false | Doesn't use half color for peaks
true (default) | Uses half color for peaks

bShowVerticalLines

Boolean value that determines if eventual vertical lines, added through previous calls to the Waveform.BitmapViewVerticalLineAdd method, should be rendered as well.

Supported values are the following:

Mnemonic constant | Meaning
false | Doesn't render vertical lines
true (default) | 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.

nEndPos

Number representing the sound's position, expressed in milliseconds, where the waveform visualization 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)
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.

For further details about generating a waveform's view of the loaded sound, before starting its playback, refer to the How to obtain the sound's waveform tutorial.

Syntax

[Visual Basic]

Public Function BitmapViewGetWidth (

nPlayerIndex as Int16,

nStartPos as Int32,

nEndPos as Int32

) as Int32

[C#]

public Int32 BitmapViewGetWidth (

Int16 nPlayerIndex,

Int32 nStartPos,

Int32 nEndPos

);

[C++]

public: Int32 BitmapViewGetWidth (

Int16 nPlayerIndex,

Int32 nStartPos,

Int32 nEndPos

);

Parameter | Description
nPlayerIndex | 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.BitmapViewSaveToFile method

Waveform.BitmapViewSaveToFile method

Remarks

Creates a view of the waveform (in form of a BMP file) 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.

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]

Public Function BitmapViewSaveToFile (

nPlayerIndex as Int16,

nStartPos as Int32,

nEndPos as Int32,

nBitmapWidth as Int32,

nBitmapHeight as Int32,

nWaveformType as enumWaveformTypes,

strPathname as string,

nFormat as enumGraphicFormats,

nFormatParameter as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes BitmapViewSaveToFile (

Int16 nPlayerIndex,

Int32 nStartPos,

Int32 nEndPos,

Int32 nBitmapWidth,

Int32 nBitmapHeight,

enumWaveformTypes nWaveformType,

string strPathname,

enumGraphicFormats nFormat,

long nFormatParameter

);

[C++]

public: enumErrorCodes BitmapViewSaveToFile (

Int16 nPlayerIndex,

Int32 nStartPos,

Int32 nEndPos,

Int32 nBitmapWidth,

Int32 nBitmapHeight,

enumWaveformTypes nWaveformType,

string strPathname,

enumGraphicFormats nFormat,

long nFormatParameter

);

Parameter

Description

nPlayerIndex

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 aboslute 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 and the waveform's bitmap was saved inside the BMP file indicated by the strPathname parameter.


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.

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]

Public Function BitmapViewSaveToMemory (

nPlayerIndex as Int16,

nStartPos as Int32,

nEndPos as Int32,

nBitmapWidth as Int32,

nBitmapHeight as Int32,

nWaveformType as enumWaveformTypes

) as IntPtr

[C#]

public IntPtr BitmapViewSaveToMemory (

Int16 nPlayerIndex,

Int32 nStartPos,

Int32 nEndPos,

Int32 nBitmapWidth,

Int32 nBitmapHeight,

enumWaveformTypes nWaveformType

);

[C++]

public: IntPtr BitmapViewSaveToMemory (

Int16 nPlayerIndex,

Int32 nStartPos,

Int32 nEndPos,

Int32 nBitmapWidth,

Int32 nBitmapHeight,

enumWaveformTypes nWaveformType

);

Parameter

Description

nPlayerIndex

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]

Public Function BitmapViewVerticalLineAdd (

nUniqueId as Int16,

nPosition as Int32,

color as Color,

nMode as enumWaveformLineModes,

nWidth as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes BitmapViewVerticalLineAdd (

Int16 nUniqueId,

Int32 nPosition,

Color color,

enumWaveformLineModes nMode,

Int16 nWidth

);

[C++]

public: enumErrorCodes BitmapViewVerticalLineAdd (

Int16 nUniqueId,

Int32 nPosition,

Color color,

enumWaveformLineModes nMode,

Int16 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function BitmapViewVerticalLineRemove (

nUniqueId as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes BitmapViewVerticalLineRemove (

Int16 nUniqueId

);

[C++]

public: enumErrorCodes BitmapViewVerticalLineRemove (

Int16 nUniqueId

);

Parameter | Description
nUniqueId | Unique identification number of the line to remove.

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.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.

For further details about using the embedded Waveform refer to the Waveform class 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]

Public Function PeaksBufferGet (

nPlayerIndex as Int16,

nChannel as Int16,

nStartPos as Int32,

nEndPos as Int32,

bValueInPerc as Boolean,

pBufferMin() as Int16,

pBufferMax() as Int16,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PeaksBufferGet (

Int16 nPlayerIndex,

Int16 nChannel,

Int32 nStartPos,

Int32 nEndPos,

bool bValueInPerc,

Int16[] pBufferMin,

Int16[] pBufferMax,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes PeaksBufferGet (

Int16 nPlayerIndex,

Int16 nChannel,

Int32 nStartPos,

Int32 nEndPos,

bool bValueInPerc,

Int16 __gc[] pBufferMin,

Int16 __gc[] pBufferMax,

Int32 nBufferLength

);

Parameter

Description

nPlayerIndex

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 (see the LastError property for further error details)
enumErrorCodes.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.NET and Visual C#

Visual Basic.NET

' memory buffers must be declared as global variables

Dim m_bufferMin() As Int16

Dim m_bufferMax() As Int16

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click

 ' get the size in bytes of the buffers

 Dim nBufferLength As Int32 = 0

AudioDjStudio1.DisplayWaveform.PeaksBufferLengthGet (0, nStartPosInMs, nEndPosInMs, nBufferLength)

 ' reallocate the memory buffer space and store the song

 ReDim m_bufferMin(nBufferLength/2)

 ReDim m_bufferMax(nBufferLength/2)

 ' fill the buffers with peaks data

 AudioDjStudio1.DisplayWaveform.PeaksBufferGet (0, 0, nStartPosInMs, nEndPosInMs, true, m_bufferMin, m_bufferMax, nBufferLength)

End Sub

Visual C#.NET

// declare the memory buffer (cannot be a local variable)

Int16[] m_bufferMin = null;

Int16[] m_bufferMax = null;

private void buttonLoad1_Click(object sender, System.EventArgs e)

{

 // get the size in bytes of the buffers

 Int32 nBufferLength = 0;

AudioDjStudio1.DisplayWaveform.PeaksBufferLengthGet (0, nStartPosInMs, nEndPosInMs, ref nBufferLength);

 // reallocate the memory buffer space and store the song

 m_bufferMin = new Int16[nBufferLength/2];

 m_bufferMax = new Int16[nBufferLength/2];

 // fill the buffers with peaks data

AudioDjStudio1.DisplayWaveform.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.

For further details about using the embedded Waveform refer to the Waveform class 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]

Public Function PeaksBufferLengthGet (

nPlayerIndex as Int16,

nStartPos as Int32,

nEndPos as Int32,

ByRef nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PeaksBufferLengthGet (

Int16 nPlayerIndex,

Int32 nStartPos,

Int32 nEndPos,

ref Int32 nBufferLength

);

[C++]

public: enumErrorCodes PeaksBufferLengthGet (

Int16 nPlayerIndex,

Int32 nStartPos,

Int32 nEndPos,

Int32 __gc[] *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 (see the LastError property for further error details)
enumErrorCodes.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 cause the CallbackForPlayersEvents delegate to be invoked with the nEvent parameter set to EV_WAVE_ANALYSIS_START and EV_WAVE_ANALYSIS_DONE as seen when calling the Waveform.AnalyzeFullSound method.

For further details about using the embedded Waveform refer to the Waveform class 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]

Public Function PeaksLoad (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes PeaksLoad (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes PeaksLoad (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 cause the CallbackForPlayersEvents delegate to be invoked with the nEvent parameter set to EV_WAVE_ANALYSIS_START and EV_WAVE_ANALYSIS_DONE as seen when calling the Waveform.AnalyzeFullSound method.

For further details about using the embedded Waveform refer to the Waveform class 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]

Public Function PeaksLoadFromMemory (

nPlayerIndex as Int16,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PeaksLoadFromMemory (

Int16 nPlayerIndex,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes PeaksLoadFromMemory (

Int16 nPlayerIndex,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the player that will use the Waveform
pBuffer | Buffer containing waveform peaks previously loaded in memory.
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.


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 class 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]

Public Function PeaksSave (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes PeaksSave (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes PeaksSave (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Resize (

nPlayerIndex as Int16,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Resize (

Int16 nPlayerIndex,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Resize (

Int16 nPlayerIndex,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromFile (

nPlayerIndex as Int16,

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

Int16 nPlayerIndex,

string strPathname

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromHandle (

nPlayerIndex as Int16,

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

Int16 nPlayerIndex,

IntPtr hBitmap

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetHwnd (

nPlayerIndex as Int16

hWndTarget as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

[C++]

public: enumErrorCodes SetHwnd (

Int16 nPlayerIndex,

IntPtr hWndTarget

);

Parameter | Description
nPlayerIndex | 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 (see the LastError property for further error details)
enumErrorCodes.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 class section.

For details about using Visual Feedbacks refer to the How to use the embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Show (

nPlayerIndex as Int16,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

[C++]

public: enumErrorCodes Show (

Int16 nPlayerIndex,

bool bShow

);

Parameter

Description

nPlayerIndex

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:

Value | Meaning
false | Hides the Waveform graphics
true | Shows the Waveform graphics

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 class

WaveformScroller class

The WaveformScroller class, accessible through the control's DisplayWaveformScroller property, 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

PlayerGet

Refresh

SetBackPictureFromFile

SetBackPictureFromHandle

SetCursor

SettingsGet

SettingsSet

SetViewLength

Show

Internal classes

WSCROLLER_SETTINGS

Samples of use of the WaveformScroller class in Visual C#.NET and Visual Basic.NET 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 class for the given player on the given parent window.

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.

Syntax

[Visual Basic]

Public Function Create (

nPlayerIndex as Int16,

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32,

colorParentBackColor as Color

) as IntPtr

[C#]

public IntPtr Create (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Color colorParentBackColor

);

[C++]

public: IntPtr Create (

Int16 nPlayerIndex,

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight,

Color colorParentBackColor

);

Parameter | Description
nPlayerIndex | 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
colorParentBackColor | Background color of the parent window

Return value

Value | Meaning
IntPtr.Zero | 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 class.

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]

Public Function Destroy (

hWndWaveformScroller as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Destroy (

IntPtr hWndWaveformScroller

);

[C++]

public: enumErrorCodes Destroy (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function GetViewLength (

hWndWaveformScroller as IntPtr,

nLengthInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetViewLength (

IntPtr hWndWaveformScroller,

Int32 nLengthInMs

);

[C++]

public: enumErrorCodes GetViewLength (

IntPtr hWndWaveformScroller,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function Move (

hWndWaveformScroller as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Move (

IntPtr hWndWaveformScroller,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Move (

IntPtr hWndWaveformScroller,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function PlaybackOnScrollEnable (

hWndWaveformScroller as IntPtr,

bEnable as Boolean,

nScrollSensitivity as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackOnScrollEnable (

IntPtr hWndWaveformScroller,

bool bEnable,

Int32 nScrollSensitivity

);

[C++]

public: enumErrorCodes PlaybackOnScrollEnable (

IntPtr hWndWaveformScroller,

bool bEnable,

Int32 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
false (default) | Playback is disabled
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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


WaveformScroller.PlaybackOnScrollInfoGet method

WaveformScroller.PlaybackOnScrollInfoGet method

Remarks

Enables/disables playback of audio data 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]

Public Function PlaybackOnScrollInfoGet (

hWndWaveformScroller as IntPtr,

ByRef bEnable as Boolean,

ByRef nScrollSensitivity as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackOnScrollInfoGet (

IntPtr hWndWaveformScroller,

ref bool bEnable,

ref Int32 nScrollSensitivity

);

[C++]

public: enumErrorCodes PlaybackOnScrollInfoGet (

IntPtr hWndWaveformScroller,

bool __gc *bEnable,

Int32 __gc *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
false (default) | Playback is disabled
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 (see the LastError property for further error details)
enumErrorCodes.NOERROR (0) | The method call was successful.


WaveformScroller.PlayerGet method

WaveformScroller.PlayerGet method

Remarks

Obtains the player that originally created the waveform scroller through the WaveformScroller.Create 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]

Public Function PlayerGet (

hWndWaveformScroller as IntPtr,

ByRef nPlayerIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes PlayerGet (

IntPtr hWndWaveformScroller,

ref Int16 nPlayerIndex

);

[C++]

public: enumErrorCodes PlayerGet (

IntPtr hWndWaveformScroller,

Int16 __gc *nPlayerIndex

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
nPlayerIndex | Reference that, on return from the method call, will contain the zero-based index of the 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.


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]

Public Function Refresh (

hWndWaveformScroller as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes Refresh (

IntPtr hWndWaveformScroller

);

[C++]

public: enumErrorCodes Refresh (

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SetBackPictureFromFile (

hWndWaveformScroller as IntPtr,

strPathname as String,

nMode as enumBitmapModes

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

IntPtr hWndWaveformScroller,

string strPathname,

enumBitmapModes nMode

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

IntPtr hWndWaveformScroller,

string strPathname,

enumBitmapModes 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SetBackPictureFromHandle (

hWndWaveformScroller as IntPtr,

hBitmap as IntPtr,

nMode as enumBitmapModes

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

IntPtr hWndWaveformScroller,

IntPtr hBitmap,

enumBitmapModes nMode

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

IntPtr hWndWaveformScroller,

IntPtr hBitmap,

enumBitmapModes 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SetCursor (

hWndWaveformScroller as IntPtr,

hCursor as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetCursor (

IntPtr hWndWaveformScroller,

IntPtr hCursor

);

[C++]

public: enumErrorCodes SetCursor (

IntPtr hWndWaveformScroller,

IntPtr 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function SettingsGet (

hWndWaveformScroller as IntPtr,

ByRef settings as WSCROLLER_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsGet (

IntPtr hWndWaveformScroller,

ref WSCROLLER_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsGet (

IntPtr hWndWaveformScroller,

WSCROLLER_SETTINGS __gc *settings

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
settings | Reference that, on return from the method call, will contain the 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]

Public Function SettingsSet (

hWndWaveformScroller as IntPtr,

settings as WSCROLLER_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsSet (

IntPtr hWndWaveformScroller,

WSCROLLER_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsSet (

IntPtr hWndWaveformScroller,

WSCROLLER_SETTINGS settings

);

Parameter | Description
hWndWaveformScroller | Handle of the control returned by a previous call to the WaveformScroller.Create method
settings | The 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.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]

Public Function SetViewLength (

hWndWaveformScroller as IntPtr,

nLengthInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetViewLength (

IntPtr hWndWaveformScroller,

Int32 nLengthInMs

);

[C++]

public: enumErrorCodes SetViewLength (

IntPtr hWndWaveformScroller,

Int32 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 (see the LastError property for further error details)
enumErrorCodes.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]

Public Function Show (

hWndWaveformScroller as IntPtr,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes Show (

IntPtr hWndWaveformScroller,

bool bShow

);

[C++]

public: enumErrorCodes Show (

IntPtr hWndWaveformScroller,

bool 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 waveform scroller control.

Supported values are the following:

Value | Meaning
false | Hides the waveform scroller window
true | Shows the waveform scroller window

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.


WSCROLLER_SETTINGS stucture

WSCROLLER_SETTINGS structure

The WSCROLLER_SETTINGS data structure (defined as WSCROLLER_SETTINGS_DLL when used for COM interoperability) 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.

C# definition

public struct WSCROLLER_SETTINGS

{

     public enumWaveformStereoModes   nStereoVisualizationMode;

     public Color                     colorWaveLinePeak;

     public Color                     colorWaveLineCenter;

     public Int16                     nWaveLineIntensityFactor;

     public Color                     colorWaveBackground;

     public bool                       bUseHalfColorsForPeaks;

     public bool                       bAppearance3d;

     public Color                     colorPositionLine;

     public Color                     colorBorder;

     public bool                       bPositionLineShow;

     public enumWaveformLineDashStyles nPositionLineDashStyle;

     public Int16                     nPositionLineWidth;

     public enumLineCaps               nPositionLineHighCap;

     public enumLineCaps               nPositionLineLowCap;

     public enumLineDashCaps           nPositionLineDashCap;

     public Int16                     nPositionLineTranspFactor;

     public enumGraphicItemMaskValues nGraphicItemsMask;

     public enumWaveScrollerAutoUpdate nUpdateSpeed;

     public float                     fVerticalZoomFactor;

}

Definition for COM interoperability

public struct WSCROLLER_SETTINGS_DLL

{

     public Int32                     nStereoVisualizationMode;

     public Int32                     colorWaveLinePeak;

     public Int32                     colorWaveLineCenter;

     public Int16                     nWaveLineIntensityFactor;

     public Int32                     colorWaveBackground;

     public Int16                     bUseHalfColorsForPeaks;

     public Int16                     bAppearance3d;

     public Int32                     colorPositionLine;

     public Int32                     colorBorder;

     public Int16                     bPositionLineShow;

     public Int32                     nPositionLineDashStyle;

     public Int16                     nPositionLineWidth;

     public Int32                     nPositionLineHighCap;

     public Int32                     nPositionLineLowCap;

     public Int32                     nPositionLineDashCap;

     public Int16                     nPositionLineTranspFactor;

     public Int32                     nGraphicItemsMask;

     public Int32                     nUpdateSpeed;

     public float                     fVerticalZoomFactor;

}

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


ZipMan class

ZipMan class

The ZipMan class, 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 ZipMan class 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 ZipMan class in Visual C#.NET and Visual Basic.NET 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 ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function Close (

) as enumErrorCodes

[C#]

public enumErrorCodes Close (

);

[C++]

public: enumErrorCodes Close (

);

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.Create method

ZIP.Create method

Remarks

Creates a brand new ZIP file session.

For further details about methods for ZIP management refer to the ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function Create (

strZipFilePathname as String,

nEncryptionType as enumZipEncryptionTypes,

strPassword as String,

bool bReplaceExisting

) as enumErrorCodes

[C#]

public enumErrorCodes Create (

string strZipFilePathname,

enumZipEncryptionTypes nEncryptionType,

string strPassword,

bool bReplaceExisting

);

[C++]

public: enumErrorCodes Create (

string strZipFilePathname,

enumZipEncryptionTypes nEncryptionType,

string strPassword,

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

Value | Meaning
false | Doesn't replace an eventual existing ZIP file, in which case the method call would have the same effect as the ZIP.Open method
true | 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 see the last error.
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 ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function EntriesCountGet (

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EntriesCountGet (

ref Int32 nCount

);

[C++]

public: enumErrorCodes EntriesCountGet (

Int32 __gc *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 (see the LastError property for further error details)
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.

During the compression phase the container application is notified through the CallbackZipOperationPerc delegate which reports the current percentage of advancement.

For further details about methods for ZIP management refer to the ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function EntryAdd (

strSourcePath as String,

bRecurseDirs as Boolean,

bAddExtraPath as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EntryAdd (

string strSourcePath,

bool bRecurseDirs,

bool bAddExtraPath

);

[C++]

public: enumErrorCodes EntryAdd (

string strSourcePath,

bool bRecurseDirs,

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

Value | Meaning
false | Eventual sub-directories are not traversed
true | 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:

Value | Meaning
false | The relative path of each zipped file is not added to the final entry name.
true | 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 see the last error.
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.

During the compression phase the container application is notified through the CallbackZipOperationPerc delegate which reports the current percentage of advancement.

For further details about methods for ZIP management refer to the ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function EntryAddFromMemory (

strEntryName as String,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EntryAddFromMemory (

string strEntryName,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes EntryAddFromMemory (

string strEntryName,

unsigned char __gc[] pBuffer,

Int32 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 see the last error.
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.

During the extraction phase the container application is notified through the CallbackZipOperationPerc delegate which reports the current percentage of advancement.

For further details about methods for ZIP management refer to the ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function EntryExtractToFile (

strEntryName as String,

strPassword as String,

strDestPath as String,

bAddRelativePathToDest as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EntryExtractToFile (

string strEntryName,

string strPassword,

string strDestPath,

bool bAddRelativePathToDest

);

[C++]

public: enumErrorCodes EntryExtractToFile (

string strEntryName,

string strPassword,

string strDestPath,

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

Value | Meaning
false | 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"
true | 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 see the last error.
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.

During the extraction phase the container application is notified through the CallbackZipOperationPerc delegate which reports the current percentage of advancement.

For further details about methods for ZIP management refer to the ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function EntryExtractToMemory (

strEntryName as String,

strPassword as String,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EntryExtractToMemory (

string strEntryName,

string strPassword,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes EntryExtractToMemory (

string strEntryName,

string strPassword,

unsigned char __gc[] pBuffer,

Int32 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 see the last error.
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 ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function EntryNameGet (

nEntryIndex as Int32,

ByRef bIsDirectory as Boolean

) as string

[C#]

public string EntryNameGet (

Int32 nEntryIndex,

ref bool bIsDirectory

);

[C++]

public: string EntryNameGet (

Int32 nEntryIndex,

bool __gc *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 | Meaning
false | The requested entry is a file
true | 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 ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function EntryRemove (

nEntryIndex as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EntryRemove (

Int32 nEntryIndex

);

[C++]

public: enumErrorCodes EntryRemove (

Int32 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 (see the LastError property for further error details)
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 ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function EntryExtractToMemory (

strEntryName as String,

ByRef nSize as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes EntryUncompressedSizeGet (

string strEntryName,

ref Int32 nSize

);

[C++]

public: enumErrorCodes EntryUncompressedSizeGet (

string strEntryName,

Int32 __gc *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 see the last error.
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 ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function IsProtected (

ByRef bHasPassword as Boolean,

ByRef bHasEncryption as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes IsProtected (

ref bool bHasPassword,

ref bool bHasEncryption

);

[C++]

public: enumErrorCodes IsProtected (

ref bool __gc *bHasPassword,

ref bool __gc *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 see the last error.
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 ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function Open (

strZipFilePathname as String,

strPassword as String

) as enumErrorCodes

[C#]

public enumErrorCodes Open (

string strZipFilePathname,

string strPassword

);

[C++]

public: enumErrorCodes Open (

string strZipFilePathname,

string 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 ZipMan class.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function Save (

) as enumErrorCodes

[C#]

public enumErrorCodes Save (

);

[C++]

public: enumErrorCodes 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" 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.


Adjstudnet_0000d0

Copyright © 2005-2018 MultiMedia Soft

Adjstudnet_0000d0

 Return to chapter overview


SetDirectXEffectParams method (Compressor)

Effects.DirectXEffectParamsSet method (Compressor)

Return to chapter overview

Remarks

Sets parameters related to the Compressor 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsCompressor

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsCompressor fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsCompressor __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Effect structure containing parameters to apply.

Property | Meaning
Attack | Retrieves and sets the time before compression reaches its full value. Can range from CompressorEffect.AttackMin to CompressorEffect.AttackMax. The default value is 10 ms.
Gain | Retrieves and sets the output gain of signal after compression. Can range from CompressorEffect.GainMin to CompressorEffect.GainMax. The default value is 0 dB.
Predelay | Retrieves and sets the time after Threshold is reached before attack phase is started, in milliseconds. Can range from CompressorEffect.PredelayMin to CompressorEffect.PredelayMax. The default value is 4 ms.
Ratio | Retrieves and sets the compression ratio. Can range from CompressorEffect.RatioMin to CompressorEffect.RatioMax. The default value is 3, which means 3:1 compression.
Release | Retrieves and sets the speed at which compression is stopped after input drops below Threshold. Can range from CompressorEffect.ReleaseMin to CompressorEffect.ReleaseMax. The default value is 200 ms.
Threshold | Retrieves and sets the point at which compression begins. Can range from CompressorEffect.ThresholdMin to CompressorEffect.ThresholdMax. The default value is -20 dB.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


SetDirectXEffectParams method (Distortion)

Effects.DirectXEffectParamsSet method (Distortion)

Return to chapter overview

Remarks

Sets parameters related to the Distortion 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsDistortion

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsDistortion fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsDistortion __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
Edge | Retrieves and sets the percentage of distortion intensity, in the EffectsDistortion structure. Can range from DistortionEffect.EdgeMin to DistortionEffect.EdgeMax. The default value is 15.
Gain | Retrieves and sets the amount of signal change after distortion, in the EffectsDistortion structure. Can range from DistortionEffect.GainMin to DistortionEffect.GainMax. The default value is -18 dB.
PostEqBandwidth | Retrieves and sets the width of frequency band that determines range of harmonic content addition, in the EffectsDistortion structure. Can range from DistortionEffect.PostEqBandwidthMin to DistortionEffect.PostEqBandwidthMax. The default value is 2400Hz.
PostEqCenterFrequency | Retrieves and sets the center frequency of harmonic content addition, in the EffectsDistortion structure. Can range from DistortionEffect.PostEqCenterFrequencyMin to DistortionEffect.PostEqCenterFrequency. The default value is 2400 Hz.
PreLowpassCutoff | Retrieves and sets the filter cutoff for high-frequency harmonics attenuation, in the EffectsDistortion structure. Can range from DistortionEffect.PreLowpassCutoffMin to DistortionEffect.PreLowpassCutoffMax. The default value is 15.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


SetDirectXEffectParams method (Echo)

Effects.DirectXEffectParamsSet method (Echo)

Return to chapter overview

Remarks

Sets parameters related to the Echo 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsEcho

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsEcho fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsEcho __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
Feedback | Retrieves and sets the percentage of output fed back into input. Can range from EchoEffect.FeedbackMin to EchoEffect.FeedbackMax. The default value is 50.
LeftDelay | Retrieves and sets the delay for left channel, in milliseconds. Can range from EchoEffect.LefttDelayMin to EchoEffect.LeftDelayMax. The default value is 500 ms.
PanDelay | Retrieves and sets the value that specifies whether to swap left and right delays with each successive echo. Can range from EchoEffect.PanDelayMin to EchoEffect.PanDelayMax. The default value is zero, meaning no swap.
RightDelay | Retrieves and sets the delay for right channel, in milliseconds. Can range from EchoEffect.RightDelayMin to EchoEffect.RightDelayMax. The default value is 500 ms.
WetDryMix | Retrieves and sets the ratio of wet (processed) signal to dry (unprocessed) signal. Can range from EchoEffect.WetDryMixMin to EchoEffect.WetDryMixMax.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


SetDirectXEffectParams method (Flanger)

Effects.DirectXEffectParamsSet method (Flanger)

Return to chapter overview

Remarks

Sets parameters related to the Flanger 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsFlanger

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsFlanger fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsFlanger __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
Delay | Retrieves and sets the number of milliseconds the input is delayed before it is played back. Can range from FlangerEffect.DelayMin to FlangerEffect.DelayMax. The default value is 2ms.
Depth | Retrieves and sets the percentage by which the delay time is modulated by the low-frequency oscillator (LFO), in hundredths of a percentage point. Can range from FlangerEffect.DepthMin to FlangerEffect.DepthMax. The default value is 100.
Feedback | Retrieves and sets the percentage of output signal to feed back into the effect's input. Can range from FlangerEffect.FeedbackMin to FlangerEffect.FeedbackMax. The default value is -50.
Frequency | Retrieves and sets the frequency of the LFO. Can range from FlangerEffect.FrequencyMin to FlangerEffect.FrequencyMax. The default value is 0.
Phase | Retrieves and sets the phase differential between left and right LFOs. Can be set to on of the following: - FlangerEffect.PhaseNeg180 - FlangerEffect.PhaseNeg90 - FlangerEffect.PhaseZero - FlangerEffect.Phase90 - FlangerEffect.Phase180
Waveform | Retrieves and sets the waveform shape of the LFO. Can be set to on of the following: - FlangerEffect.WaveSine (default) - FlangerEffect.WaveTriangle
WetDryMix | Retrieves and sets the ratio of wet (processed) signal to dry (unprocessed) signal. Can range from FlangerEffect.WetDryMixMin to FlangerEffect.WetDryMixMax. The default value is 50.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


SetDirectXEffectParams method (Gargle)

Effects.DirectXEffectParamsSet method (Gargle)

Return to chapter overview

Remarks

Sets parameters related to the Gargle 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsGargle

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsGargle fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsGargle __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
RateHz | Retrieves and sets the rate of modulation expressed in Hertz. Can range from GargleEffect.RateHzMin to GargleEffect.RateHzMax. The default value is 20.
WaveShape | Retrieves and sets the shape of the modulation waveform. Can be set to one of the following: - GargleEffect.WaveTriangle (default) - GargleEffect.WaveSquare

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


SetDirectXEffectParams method (Interactive3DLevel2Reverb)

Effects.DirectXEffectParamsSet method (Interactive3DLevel2Reverb)

Return to chapter overview

Remarks

Sets parameters related to the Interactive 3D Level 2 Reverb 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsInteractive3DLevel2Reverb __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property

Meaning

DecayHfRatio

Retrieves and sets the ratio of the decay time at high frequencies to the decay time at low frequencies.

Can range from Interactive3DLevel2ReverbEffect.DecayHfRatioMin to Interactive3DLevel2ReverbEffect.DecayHfRatioMax.

The default value is Interactive3DLevel2ReverbEffect.DecayHfRatioDefault or 0.83.

DecayTime

Retrieves and sets the decay time expressed in seconds.

Can range from Interactive3DLevel2ReverbEffect.DecayTimeMin to Interactive3DLevel2ReverbEffect.DecayTimeMax.

The default value is Interactive3DLevel2ReverbEffect.DecayTimeDefault or 1.49 seconds.

Density

Retrieves and sets the modal density in the late reverberation decay expressed in percent.

Can range from Interactive3DLevel2ReverbEffect.DensityMin to Interactive3DLevel2ReverbEffect.DensityMax.

The default value is Interactive3DLevel2ReverbEffect.DensityDefault or 100 percent.

Diffusion

Retrieves and sets the echo density in the late reverberation decay expressed in percent.

Can range from Interactive3DLevel2ReverbEffect.DiffusionyMin to Interactive3DLevel2ReverbEffect.DiffusionMax.

The default value is Interactive3DLevel2ReverbEffect.DiffusionDefault or 100 percent.

HfReference

Retrieves and sets the reference high frequency expressed in hertz.

Can range from Interactive3DLevel2ReverbEffect.HfReferenceyMin to Interactive3DLevel2ReverbEffect.HfReferenceMax.

The default value is Interactive3DLevel2ReverbEffect.HfReferenceDefault or 5000.0 Hz.

Reflections

Retrieves and sets the attenuation of early reflections relative to Room expressed in millibels (mB).

Can range from Interactive3DLevel2ReverbEffect.ReflectionsMin to Interactive3DLevel2ReverbEffect.ReflectionsMax.

The default value is Interactive3DLevel2ReverbEffect.ReflectionsDefault or -2602 mB.

ReflectionsDelay

Retrieves and sets the delay time of the first reflection relative to the direct path expressed in seconds.

Can range from Interactive3DLevel2ReverbEffect.ReflectionsDelayMin to Interactive3DLevel2ReverbEffect.ReflectionsDelayMax.

The default value is Interactive3DLevel2ReverbEffect.ReflectionsDelayDefault or 0.007 seconds.

Reverb

Retrieves and sets the attenuation of late reverberation relative to Room expressed in millibels (mB).

Can range from Interactive3DLevel2ReverbEffect.ReverbMin to Interactive3DLevel2ReverbEffect.ReverbMax.

The default value is Interactive3DLevel2ReverbEffect.ReverbDefault or -200 mB.

ReverbDelay

Retrieves and sets the time limit between the early reflections and the late reverberation relative to the time of the first reflection expressed in seconds.

Can range from Interactive3DLevel2ReverbEffect.ReverbDelayMin to Interactive3DLevel2ReverbEffect.ReverbDelayMax.

The default value is Interactive3DLevel2ReverbEffect.ReverbDelayDefault or 0.011 seconds.

Room

Retrieves and sets the attenuation of the room effect expressed in millibels (mB).

Can range from Interactive3DLevel2ReverbEffect.RoomMin to Interactive3DLevel2ReverbEffect.RoomMax.

The default value is Interactive3DLevel2ReverbEffect.RoomDefault or -1000 mB.

RoomHf

Retrieves and sets the attenuation of the room high-frequency effect expressed in millibels (mB).

Can range from Interactive3DLevel2ReverbEffect.RoomHfMin to Interactive3DLevel2ReverbEffect.RoomHfMax.

The default value is Interactive3DLevel2ReverbEffect.RoomHfDefault or -100 mB.

RoomRolloffFactor

Retrieves and sets the rolloff factor for the reflected signals.

Can range from Interactive3DLevel2ReverbEffect.RoomRolloffFactorMin to Interactive3DLevel2ReverbEffect.RoomRolloffFactorMax.

The default value is Interactive3DLevel2ReverbEffect.RoomRolloffFactorDefault or 0.0.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


SetDirectXEffectParams method (WavesReverb)

Effects.DirectXEffectParamsSet method (WavesReverb)

Return to chapter overview

Remarks

Sets parameters related to the Waves Reverb 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsWavesReverb

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsWavesReverb fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsWavesReverb __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
HighFrequencyRtRatio | Retrieves and sets the high-frequency reverb time ratio. Can range from WavesReverbEffect.HighFrequencyRtRationMin to WavesReverbEffect.HighFrequencyRtRationMax. The default value is 0.001 or WavesReverbEffect.HighFrequencyRtRationDefault.
InGain | Retrieves and sets the input gain of signal expressed in decibels (dB). Can range from WavesReverbEffect.InGainMin to WavesReverbEffect.InGainMax. The default value is 0 db or WavesReverbEffect.InGainDefault.
ReverbMix | Retrieves and sets the reverb mix expressed in decibels (dB). Can range from WavesReverbEffect.ReverbMixMin to WavesReverbEffect.ReverbMixMax. The default value is 0 db or WavesReverbEffect.ReverbMixDefault.
ReverbTime | Retrieves and sets the reverb time expressed in milliseconds. Can range from WavesReverbEffect.ReverbTimeMin to WavesReverbEffect.ReverbTimeMax. The default value is 1000 ms or WavesReverbEffect.ReverbTimeDefault.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


GetDirectXEffectParams method (Compressor)

Effects.DirectXEffectParamsGet method (Compressor)

Return to chapter overview

Remarks

Retrieves parameters related to the Compressor 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsCompressor

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsCompressor fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsCompressor __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSet 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.


GetDirectXEffectParams method (Distortion)

Effects.DirectXEffectParamsGet method (Distortion)

Return to chapter overview

Remarks

Retrieves parameters related to the Distortion 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsDistortion

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsDistortion fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsDistortion __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSet 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.


GetDirectXEffectParams method (Interactive3DLevel2Reverb)

Effects.DirectXEffectParamsGet method (Interactive3DLevel2Reverb)

Return to chapter overview

Remarks

Retrieves parameters related to the Interactive 3D Level 2 Reverb 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsInteractive3DLevel2Reverb fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsInteractive3DLevel2Reverb __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSet 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.


GetDirectXEffectParams method (WavesReverb)

Effects.DirectXEffectParamsGet method (WavesReverb)

Return to chapter overview

Remarks

Retrieves parameters related to the Waves Reverb 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsWavesReverb

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsWavesReverb fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsWavesReverb __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSet 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.


Adjstudnet_000013

Copyright © 2005-2018 MultiMedia Soft

Adjstudnet_000013

 Return to chapter overview


Adjstudnet_000035

Copyright © 2005-2018 MultiMedia Soft

Adjstudnet_000035

 Return to chapter overview


SoundInfo2 class

SoundInfo2 class

The SoundInfo2 class is used in conjunction with the SoundInfoGet method in order to obtain information about a loaded song and is implemented through the following properties

Property name

Property type

Meaning

nChannels

UInt32

The number of channels in the loaded song:

Value | Meaning
1 | Mono
2 | Stereo
4 | Quadraphonic
6 | 5.1 Surround
8 | 7.1 Surround

nFileType

enumFileTypes

The format of the loaded song.

Supported values are the following:

Mnemonic constant | Value | Format
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.

nFrequency

UInt32

The playback rate of the loaded sound expressed in Hertz

nMP3StreamTypeLevel (*)

UInt32

The MPEG level:

0- MPEG 2.5

1- MPEG 1

2- MPEG 2

nMP3StreamTypeLayer (*)

UInt32

The MPEG layer

1- MPEG layer 1

2- MPEG layer 2

3- MPEG layer 3

nMP3StreamTypeBitRate (*)

UInt32

The Bitrate (number of bits per second)

nMP3StreamTypeMode (*)

UInt32

The MPEG mode

0- Stereo

1- Joint stereo

2- Dual channel

3- Single.channel

nMP3Frames (*)

UInt32

The number of MP3 frames

nMP3TagVersion (*)

enumTagId3Versions

The version of MP3 tag(s).

Supported value are the following:

Mnemonic constant | Value | Meaning
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

nWAVBytesPerSec (**)

UInt32

Required average data-transfer rate, expressed in bytes per second, for the format tag.

nWAVBlockAlign (**)

UInt32

Block alignment, expressed in bytes. The block alignment is the minimum atomic unit of data for the nWavFormatTag format type.

nWAVBitsPerSample (**)

UInt32

Bits per sample for the nWavFormatTag format type.

nWAVFormatTag (**)

UInt32

Waveform-audio format type of the loaded WAV file. Format tags are registered with Microsoft Corporation for many compression algorithms.

Supported values are the following:

Microsoft defined mnemonic value | Numeric value | Manufacturer
 | -1 | The loaded file is not a valid WAV
WAVE_FORMAT_UNKNOWN | 0x0000 | None
WAVE_FORMAT_PCM | 0x0001 | Microsoft Corporation
WAVE_FORMAT_ADPCM | 0x0002 | Microsoft Corporation
WAVE_FORMAT_IEEE_FLOAT | 0x0003 | Microsoft Corporation
WAVE_FORMAT_IBM_CVSD | 0x0005 | IBM Corporation
WAVE_FORMAT_ALAW | 0x0006 | Microsoft Corporation
WAVE_FORMAT_MULAW | 0x0007 | Microsoft Corporation
WAVE_FORMAT_OKI_ADPCM | 0x0010 | OKI
WAVE_FORMAT_DVI_ADPCM | 0x0011 | Intel Corporation
WAVE_FORMAT_MEDIASPACE_ADPCM | 0x0012 | Videologic
WAVE_FORMAT_SIERRA_ADPCM | 0x0013 | Sierra Semiconductor Corp
WAVE_FORMAT_G723_ADPCM | 0x0014 | Antex Electronics Corporation
WAVE_FORMAT_DIGISTD | 0x0015 | DSP Solutions, Inc.
WAVE_FORMAT_DIGIFIX | 0x0016 | DSP Solutions, Inc.
WAVE_FORMAT_DIALOGIC_OKI_ADPCM | 0x0017 | Dialogic Corporation
WAVE_FORMAT_MEDIAVISION_ADPCM | 0x0018 | Media Vision, Inc.
WAVE_FORMAT_YAMAHA_ADPCM | 0x0020 | Yamaha Corporation of America
WAVE_FORMAT_SONARC | 0x0021 | Speech Compression
WAVE_FORMAT_DSPGROUP_TRUESPEECH | 0x0022 | DSP Group, Inc.
WAVE_FORMAT_ECHOSC1 | 0x0023 | Echo Speech Corporation
WAVE_FORMAT_AUDIOFILE_AF36 | 0x0024 | Not defined
WAVE_FORMAT_APTX | 0x0025 | Audio Processing Technology
WAVE_FORMAT_AUDIOFILE_AF10 | 0x0026 | Not defined
WAVE_FORMAT_DOLBY_AC2 | 0x0030 | Dolby Laboratories
WAVE_FORMAT_GSM610 | 0x0031 | Microsoft Corporation
WAVE_FORMAT_MSNAUDIO | 0x0032 | Microsoft Corporation
WAVE_FORMAT_ANTEX_ADPCME | 0x0033 | Antex Electronics Corporation
WAVE_FORMAT_CONTROL_RES_VQLPC | 0x0034 | Control Resources Limited
WAVE_FORMAT_DIGIREAL | 0x0035 | DSP Solutions, Inc.
WAVE_FORMAT_DIGIADPCM | 0x0036 | DSP Solutions, Inc.
WAVE_FORMAT_CONTROL_RES_CR10 | 0x0037 | Control Resources Limited
WAVE_FORMAT_NMS_VBXADPCM | 0x0038 | Natural MicroSystems
WAVE_FORMAT_CS_IMAADPCM | 0x0039 | Crystal Semiconductor IMA ADPCM
WAVE_FORMAT_ECHOSC3 | 0x003A | Echo Speech Corporation
WAVE_FORMAT_ROCKWELL_ADPCM | 0x003B | Rockwell International
WAVE_FORMAT_ROCKWELL_DIGITALK | 0x003C | Rockwell International
WAVE_FORMAT_XEBEC | 0x003D | Xebec Multimedia Solutions Limited
WAVE_FORMAT_G721_ADPCM | 0x0040 | Antex Electronics Corporation
WAVE_FORMAT_G728_CELP | 0x0041 | Antex Electronics Corporation
WAVE_FORMAT_MPEG | 0x0050 | Microsoft Corporation
WAVE_FORMAT_MPEGLAYER3 | 0x0055 | ISO/MPEG Layer3 Format Tag
WAVE_FORMAT_CIRRUS | 0x0060 | Cirrus Logic
WAVE_FORMAT_ESPCM | 0x0061 | ESS Technology
WAVE_FORMAT_VOXWARE | 0x0062 | Voxware Inc.
WAVEFORMAT_CANOPUS_ATRAC | 0x0063 | Canopus, co., Ltd.
WAVE_FORMAT_G726_ADPCM | 0x0064 | APICOM
WAVE_FORMAT_G722_ADPCM | 0x0065 | APICOM
WAVE_FORMAT_DSAT | 0x0066 | Microsoft Corporation
WAVE_FORMAT_DSAT_DISPLAY | 0x0067 | Microsoft Corporation
WAVE_FORMAT_SOFTSOUND | 0x0080 | Softsound, Ltd.
WAVE_FORMAT_RHETOREX_ADPCM | 0x0100 | Rhetorex Inc.
WAVE_FORMAT_CREATIVE_ADPCM | 0x0200 | Creative Labs, Inc.
WAVE_FORMAT_CREATIVE_FASTSPEECH8 | 0x0202 | Creative Labs, Inc.
WAVE_FORMAT_CREATIVE_FASTSPEECH10 | 0x0203 | Creative Labs, Inc.
WAVE_FORMAT_QUARTERDECK | 0x0220 | Quarterdeck Corporation
WAVE_FORMAT_FM_TOWNS_SND | 0x0300 | Fujitsu Corp.
WAVE_FORMAT_BTV_DIGITAL | 0x0400 | Brooktree Corporation
WAVE_FORMAT_OLIGSM | 0x1000 | Ing C. Olivetti & C., S.p.A.
WAVE_FORMAT_OLIADPCM | 0x1001 | Ing C. Olivetti & C., S.p.A.
WAVE_FORMAT_OLICELP | 0x1002 | Ing C. Olivetti & C., S.p.A.
WAVE_FORMAT_OLISBC | 0x1003 | Ing C. Olivetti & C., S.p.A.
WAVE_FORMAT_OLIOPR | 0x1004 | Ing C. Olivetti & C., S.p.A.
WAVE_FORMAT_LH_CODEC | 0x1100 | Lernout & Hauspie
WAVE_FORMAT_NORRIS | 0x1400 | Norris Communications, Inc.

strWAVTagString (**)

string

Friendly string of the waveform-audio format type of the loaded WAV file. Format tags are registered with Microsoft Corporation for many compression algorithms.

strMP3Tag1Album (*)

string

ID3V1 tag Album

strMP3Tag1Title (*)

string

ID3V1 tag Title

strMP3Tag1Artist (*)

string

ID3V1 tag Artist

strMP3Tag1Year (*)

string

ID3V1 tag Year

strMP3Tag1Comment (*)

string

ID3V1 tag Comment

strMP3Tag1Track (*)

string

ID3V1 tag Track number

strMP3Tag1GenreCode (*)

string

ID3V1 tag Genre code

strMP3Tag1GenreString (*)

string

ID3V1 tag Genre string

strWMACodecString (***)

string

Codec used for encoding in WMA format

(*) The field is valid only if the loaded song is in MP3, MP2 or MP1 format

(**) The field is valid only if the loaded song is in WAV format

(***) The field is valid only if the loaded song is in WMA format


GetDirectXEffectParams method (Echo)

Effects.DirectXEffectParamsGet method (Echo)

Return to chapter overview

Remarks

Retrieves parameters related to the Echo 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsEcho

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsEcho fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsEcho __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSet 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.


GetDirectXEffectParams method (Flanger)

Effects.DirectXEffectParamsGet method (Flanger)

Return to chapter overview

Remarks

Retrieves parameters related to the Flanger 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsFlanger

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsFlanger fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsFlanger __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSet 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.


GetDirectXEffectParams method (Gargle)

Effects.DirectXEffectParamsGet method (Gargle)

Return to chapter overview

Remarks

Retrieves parameters related to the Gargle 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsGargle

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsGargle fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsGargle __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Reference to the effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSet 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.


GetDirectXEffectParams method (Chorus)

Effects.DirectXEffectParamsGet method (Chorus)

Return to chapter overview

Remarks

Retrieves parameters related to the Chorus 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsGet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsChorus

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsChorus fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsGet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsChorus __gc *fx

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
fx | Effect structure containing parameters to apply. For details about the fields of this structure see the related Effects.DirectXEffectParamsSet 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.


SetDirectXEffectParams method (Chorus)

Effects.DirectXEffectParamsSet method (Chorus)

Return to chapter overview

Remarks

Sets parameters related to the Chorus 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 IsDirectX8Available method returns TRUE.

See the How to apply special effects to a playing sound section for further details.

Syntax

[Visual Basic]

Public Function DirectXEffectParamsSet (

nPlayerIndex as Int16,

ByRef fx as Microsoft.DirectX.DirectSound.EffectsChorus

) as enumErrorCodes

[C#]

public enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

ref Microsoft.DirectX.DirectSound.EffectsChorus fx

);

[C++]

public: enumErrorCodes DirectXEffectParamsSet (

Int16 nPlayerIndex,

Microsoft::DirectX::DirectSound::EffectsChorus __gc *fx

);

Parameter

Description

nPlayerIndex

Number representing the zero-based index of the involved player

fx

Reference to the effect structure containing parameters to apply.

Property | Meaning
Delay | Retrieves and sets the number of milliseconds the input is delayed before it is played back. Can range from ChorusEffect.DelayMin to ChorusEffect.DelayMax. The default value is 16 ms.
Depth | Retrieves and sets the percentage by which the delay time is modulated by the low-frequency oscillator, in hundredths of a percentage point. Can range from ChorusEffect.DepthMin to ChorusEffect.DepthMax. The default value is 10.
Feedback | Retrieves and sets the percentage of output signal to feed back into the effect's input. Can range from ChorusEffect.FeedbackMin to ChorusEffect.FeedbackMax. The default value is 25.
Frequency | Retrieves and sets the frequency of the LFO Can range from ChorusEffect.FrequencyMin to ChorusEffect.FrequencyMax. The default value is 1.1.
Phase | Retrieves and sets the phase differential between left and right LFOs Can range from ChorusEffect.PhaseMin to ChorusEffect.PhaseMax. Can be set by the one values below: - ChorusEffect.PhaseZero - ChorusEffect.Phase90 - ChorusEffect.PhaseNegative90 - ChorusEffect.Phase180 - ChorusEffect.PhaseNegative180 The default value is ChorusEffect.Phase90.
Waveform | Retrieves and sets the waveform shape of the LFO Can be set by the one values below: - ChorusEffect.WaveSin - ChorusEffect.WaveTrianlge The default value is ChorusEffect.WaveSin.
WetDryMix | Retrieves and sets the ratio of wet (processed) signal to dry (unprocessed) signal Can range from ChorusEffect.WetDryMixMin to ChorusEffect.WetDryMixMax. The default value is 50.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details) Note that if you should fill the fx structure with values out of range, you could get an exception of type ArgumentException
enumErrorCodes.NOERROR (0) | The method call was successful.


DelayedPlayback.ListAddItem2

DelayedPlayback.ListAddItem

Remarks

Adds the song (item) currently contained into the given player 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]

Public Function ListAddItem (

nPlayerIndex as Int16,

nDelay as Int32

) as Int32

[C#]

public Int32 ListAddItem (

Int16 nPlayerIndex,

Int32 nDelay

);

[C++]

public: Int32 ListAddItem (

Int16 nPlayerIndex,

Int32 nDelay

);

Parameter | Description
nPlayer | Number representing the zero-based index of the involved player
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.ListAddItem method (A)

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]

Public Function ListAddItem (

nPlayerIndex as Int16,

strPathname as string,

nDelay as Int32

) as Int32

[C#]

public Int32 ListAddItem (

Int16 nPlayerIndex,

string strPathname,

Int32 nDelay

);

[C++]

public: Int32 ListAddItem (

Int16 nPlayerIndex,

string strPathname,

Int32 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.ListAddItem method (B)

DelayedPlayback.ListAddItem 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]

Public Function ListAddItem (

nPlayerIndex as Int16,

strPathname as string,

nDelay as Int32,

nStartPos as Int32,

nEndPos as Int32,

nLoopCount as Int32,

nFadeInLength as Int32,

nFadeOutLength as Int32

) as Int32

[C#]

public Int32 ListAddItem (

Int16 nPlayerIndex,

string strPathname,

Int32 nDelay,

Int32 nStartPos,

Int32 nEndPos,

Int32 nLoopCount,

Int32 nFadeInLength,

Int32 nFadeOutLength

);

[C++]

public: Int32 ListAddItem (

Int16 nPlayerIndex,

string strPathname,

Int32 nDelay,

Int32 nStartPos,

Int32 nEndPos,

Int32 nLoopCount,

Int32 nFadeInLength,

Int32 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 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

DelayedPlayback.ListAddItemByDate

Remarks

Adds the song (item) currently contained into the given player 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]

Public Function ListAddItemByDate (

nPlayerIndex as Int16,

nYear as Int32,

nMonth as Int32,

nDay as Int32,

nHour as Int32,

nMinute as Int32,

nSecond as Int32

) as Int32

[C#]

public Int32 ListAddItemByDate (

Int16 nPlayerIndex,

Int32 nYear,

Int32 nMonth,

Int32 nDay,

Int32 nHour,

Int32 nMinute,

Int32 nSecond

);

[C++]

public: Int32 ListAddItemByDate (

Int16 nPlayerIndex,

Int32 nYear,

Int32 nMonth,

Int32 nDay,

Int32 nHour,

Int32 nMinute,

Int32 nSecond

);

Parameter | Description
nPlayerIndex | Number representing the zero-based index of the involved player
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.ListAddItemByDate

DelayedPlayback.ListAddItemByDate

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]

Public Function ListAddItemByDate (

nPlayerIndex as Int16,

strPathname as string,

nYear as Int32,

nMonth as Int32,

nDay as Int32,

nHour as Int32,

nMinute as Int32,

nSecond as Int32

) as Int32

[C#]

public Int32 ListAddItemByDate (

Int16 nPlayerIndex,

string strPathname,

Int32 nYear,

Int32 nMonth,

Int32 nDay,

Int32 nHour,

Int32 nMinute,

Int32 nSecond

);

[C++]

public: Int32 ListAddItemByDate (

Int16 nPlayerIndex,

string strPathname,

Int32 nYear,

Int32 nMonth,

Int32 nDay,

Int32 nHour,

Int32 nMinute,

Int32 nSecond

);

Parameter | Description
nPlayerIndex | 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.ListAddItemByDate

DelayedPlayback.ListAddItemByDate

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]

Public Function ListAddItem (

nPlayerIndex as Int16,

strPathname as string,

nYear as Int32,

nMonth as Int32,

nDay as Int32,

nHour as Int32,

nMinute as Int32,

nSecond as Int32,

nStartPos as Int32,

nEndPos as Int32,

nLoopCount as Int32,

nFadeInLength as Int32,

nFadeOutLength as Int32

) as Int32

[C#]

public Int32 ListAddItem (

Int16 nPlayerIndex,

string strPathname,

Int32 nYear,

Int32 nMonth,

Int32 nDay,

Int32 nHour,

Int32 nMinute,

Int32 nSecond,

Int32 nStartPos,

Int32 nEndPos,

Int32 nLoopCount,

Int32 nFadeInLength,

Int32 nFadeOutLength

);

[C++]

public: Int32 ListAddItem (

Int16 nPlayerIndex,

string strPathname,

Int32 nYear,

Int32 nMonth,

Int32 nDay,

Int32 nHour,

Int32 nMinute,

Int32 nSecond,

Int32 nStartPos,

Int32 nEndPos,

Int32 nLoopCount,

Int32 nFadeInLength,

Int32 nFadeOutLength

);

Parameter | Description
nPlayerIndex | 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