Introduction

Copyright © 2006-2018 MultiMedia Soft

Introduction

Return to chapter overview

Audio Sound Recorder API for .NET is a .NET class developed by MultiMedia Soft that makes it easy to add sound recording and CD ripping 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 Sound Recorder API for .NET allows creating powerful audio recording applications

Audio Sound Recorder API for .NET is designed to work directly with a sound card or with CD/DVD player, so you can record almost any audio source including a microphone, a line-in jack or a CD player (CD ripping), at near-perfect quality. This makes it ideal for implementing a variety of audio applications from music recording and editing to powerful dictation applications.

Recorded sounds can be kept in memory for later use or stored on the hard disk in any of the supported formats or using the ACM codecs in the system. Once a recording session has been completed, it is possible to play the recorded audio using the embedded playback system. If you need more sophisticated playback features (such as changing tempo or pitch), consider using this API in conjunction with our Audio DJ Studio API for .NET.

Audio Sound Recorder API for .NET supports deep analysis of the recorded sound waveform with rich visualization capabilities including range selection, zooming and panning. Recorded sounds can be edited, resampled, mixed with other sounds and exported to different formats.

Derived from the experience with the Audio Sound Recorder 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 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 control.

Brief summary of available features:

Audio recording from physical devices

Audio recording from sound files

Audio recording from the Internet

Audio editing

Audio effects

Audio playback

Audio export

Audio analysis

Protocols and sound cards management

Ripping of CD tracks

Graphical features

Tagging features

Misc features

Supported target systems

Supported .NET frameworks

Audio recording from physical devices

· Recording from any DirectSound, ASIO or WASAPI compatible sound card available inside the system.
· Support for half-duplex devices (like the Phillips SpeechMike™).
· Sound Activation System (automatically skips silence periods).
· Support for switching the output file without stopping the recording session and without loosing any sound data.
· Support for adding position markers during a recording session.
· Recording sessions can be stored inside output files (on both disk or memory buffer) in the following audio formats:

- AAC (4) | - MP2 (5) | - PVF
- AAC+ (9) | - MP3 (6) | - RAW format
- AIFF | - MP4 (4) | - SVX
- AU | - NIST | - VOC
- CAF (1) | - OGG Vorbis (7) | - W64
- FLAC | - OPUS (8) | - WAV (2)
- IRCAM | - PAF | - WMA (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) Requires the availability of Windows Media Player modules on the target PC

(4) Requires the availability of the external Faac.exe encoder

(5) Requires the availability of the external TwoLame.exe encoder

(6) Requires the availability of the external Lame.exe encoder

(7) Requires the availability of the external OggEnc.exe encoder

(8) Requires the availability of the external OpusEnc.exe encoder

(9) Requires the availability of the external FdkAac.exe encoder

Audio recording from sound files

· Recording directly from sound files stored on disk, memory buffer or clipboard with resampling capabilities for the following input audio formats (see Audio recording from physical devices for the list of available output 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

· Through integration with our Audio DJ Studio API for .NET component, possibility to load the audio track of video clips.
· Extraction of the audio track of a video clip with possibility to store it into an output audio file of a chosen format.

Audio recording from the Internet

· Recording directly from HTTP, FTP or MMS sites with resampling capabilities (see Audio recording from physical devices for the list of available output audio formats).

Audio editing

· Restart of a stopped recording session in "Append mode", "Insert mode", "Mix mode" and "Overwrite mode".
· Sound editing basic capabilities with possibility to export portions of sound to the clipboard.
· A background sound can be applied to the current recording session, also in loop mode.
· Possibility to perform append and mixing automation operations on previously recorded audio tracks through integration with Audio Sound Editor API for .NET.

Audio effects

· Automatic Gain Controller applied to data coming from an input channel.
· Support for custom DSP effects.
· Support for basic filters (low-pass, high-pass, band-pass, stop-band).

Audio playback

· Play the recorded sound or any portion of the same.
· Sound card output choice.
· Support for playback in reverse.
· Support for changing sample rate during playback.

Audio export

· Exporting of the recorded sound into an audio file in the same audio formats available for recording sessions (see Audio recording from physical devices for the list of available output audio formats).

Audio analysis

· Deep analysis at different resolutions of the loaded sound's waveform.

Protocols and sound cards management

· DirectSound protocol
· ASIO protocol
· WASAPI protocol on Windows Vista and higher versions
· Management of audio endpoints (CoreAudio) on Windows Vista and higher versions
· Sound card output choice and volume setting for playback

Ripping of CD tracks

· Ripping of full CD tracks with resampling capabilities.
· CD ripping automation, allowing to rip a set of tracks inside one single output file or inside a separate file for each track.
· During a CD ripping session, possibility to normalize CD tracks before sending them to the encoder.
· Ripping of predefined portion of CD tracks.
· CDDB database queries through FreeDb servers.
· CD cover pictures retrieval through Amazon Web Services.

Graphical features

· Rich visualization capabilities of the waveform with possibility to perform range selection, zooming and panning: both waveform and spectral view are supported.
· Real-time visual feedback (VU-Meter, Oscilloscope, Spectrum, Waveform display).
· Creation of graphic bars for custom displaying of Vu-Meters, Spectrum and Progress bars.
· Waveform scroller allowing manual and automatic movement of the waveform.
· Support for drawing the waveform representation inside a graphical device context (HDC).
· Enhanced graphical spectrum analyzer.

Tagging features

· Support for adding basic tag information (Author, Title, Album, Year) to recording sessions in the following formats:

- MP3 | - OGG Vorbis
- MP4 | - WMA

Misc features

· Uploading of files and contents of the sound editing session into a FTP server.
· Recording of the output of audio streams mixed through Audio DJ Studio API for .NET.
· Encryption/decryption of recorded sounds, often required by medical confidentiality laws.
· Support for WMA profiles.
· Support for ZIP format.
· Support for splitting of a stereo recording session (from DirectSound device, file, memory, clipboard) into two separate destination mono files containing left and right channel respectively.
· Emulation of the "Listen to this device" feature of the Windows control panel
· Integration with our Audio Sound Editor API for .NET and Audio DJ Studio 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 2006-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 Sound Recorder 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

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

AudioSoundRecorderF4.dll if your application was targeted for .NET framework 4.0 or higher and the reference to AudioSoundRecorderF4 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

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

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

- the x86 version of the multimedia engine AdjMmsEng.dll

· If compiling specifically for x64

- the class assembly

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

AudioSoundRecorderF4.dll if your application was targeted for .NET framework 4.0 or higher and the reference to AudioSoundRecorderF4 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 Sound Recorder API for .NET (default "C:\Program Files\Audio Sound Recorder 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 | AudioSoundRecorderApi.dll
4.0 and higher | C:\Windows\Microsoft.NET\Framework\v4.0.30319\RegAsm.exe | AudioSoundRecorderApiF4.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 encoding of MP3 files, the Lame encoder (Lame.exe) must be available on the target system.
· For encoding of MP2 files, the TwoLame encoder (TwoLame.exe) must be available on the target system.
· For encoding of OGG Vorbis files, the OggEnc encoder (OggEnc.exe) must be available on the target system.
· For encoding of AAC and MP4 files, the Faac encoder (Faac.exe) must be available on the target system.
· For encoding of AAC+ files, the FdkAac encoder (FdkAac.exe) must be available on the target system.
· For encoding of OPUS files, the OPUS encoder (OpusEnc.exe) must be available on the target system.

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 AudioSoundRecorderApi
· 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 AudioSoundRecorderApi.dll (or AudioSoundRecorderApiF4.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 Sound Recorder 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 9.0.0.0

New features

· Added support for playing sound while manually scrolling the waveform scroller through the mouse
· Added support for recording and exporting in AAC+ format through the external encoder FdkAac.exe
· Added support for playing recorded sound in reverse
· Added support for playing recorded sound at a higher speed with the possibility to keep voices at their original pitch (tempo)
· Added support for recording Internet streams in HLS format (HTTP Live Streaming)
· Added the possibility to split a stereo recording session from a Wasapi capture or loopback device into two mono output files
· Added the possibility to switch the mono output files of a stereo splitting recording session
· New options for the waveform analyzer

- the waveform can now display detected peaks based upon absolute values

- more control over the format of the time string displayed on time rulers

- optional automatic vertical zoom for waveforms with low volume level

· Peaks displayed on the waveform visual feedback during recording and playback are now reported to the container application through a dedicated event
· Added support for retrieving, during recording and playback, peak levels and RMS (Root Mean Square) levels
· For capture and loopback devices, attached to a WASAPI stream mixer, added support for retrieving peak levels and RMS (Root Mean Square) levels for each of the attached devices
· Added the possibility to retrieve from the waveform analyzer the buffer containing waveform's peaks

New properties

EncodeFormats.AACPlus (class)

New methods

CallbackWaveformValueChangeSet

StartSplitFromWasapiCaptureDevice

StartSplitFromWasapiLoopbackDevice

SwitchOutputFilesOnSplit

StreamPeakLevelsGet

RecordedSound.PlaybackRateGet

RecordedSound.PlaybackRateSet

RecordedSound.PlaybackTempoGet

RecordedSound.PlaybackTempoSet

RecordedSound.PlaybackRateRatioGet

RecordedSound.SoundDirectionEnable

RecordedSound.SoundDirectionGet

RecordedSound.SoundDirectionIsEnabled

RecordedSound.SoundDirectionSet

WASAPI.MixerInputDevicePeakLevelsGet

WaveformAnalyzer.AutoZoomEnable

WaveformAnalyzer.SettingsRulersTimeFormatSet

WaveformAnalyzer.PeaksBufferLengthGet

WaveformAnalyzer.PeaksBufferGet

WaveformScroller.PlaybackOnScrollEnable

WaveformScroller.PlaybackOnScrollInfoGet

New callback delegates

CallbackWaveformValueChange

New COM events

OnWaveformValueChange

New classes

· EncodeAACplus

Properties

EncodeMode

CBR

CustomString

Methods

GetEncodeModesCount

GetEncodeModeDesc

Version 8.1.2.0

New features

· Added support for quickly loading a sound file stored on disk allowing an immediate playback without the need to record the full sound file in memory

New methods

LoadSoundForPlayback

Version 8.1.1.0

New features

· Added 64 bits support for returning sizes in bytes and duration of the recording session
· Added the possibility to be notified in real time, during a recording session, about the current duration of the new output file when the the SwitchOutputFile or SwitchOutputFileEx methods have been invoked.

New methods

RecordedSound.GetDuration64

Version 8.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

Version 8.0.1.0

New features

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

New methods

ContainerIsWindowsService


Deprecated elements

Deprecated elements

With respect to previous versions of the control some of the control's properties and methods have been deprecated. Deprecated elements should not be used in new development projects. They have been maintained internally for backward compatibility only and they will not be documented here nor supported in the future. Furthermore, deprecated elements will not be displayed by Intellisense.

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

Old property or method or event name | Current alternative
RecordedSound.GetDuration (811) | RecordedSound.GetDuration64 method

(811) Deprecated starting from version 8.1.1


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; if using a Windows NT based system (like Windows 2000 and Windows XP), specify which Service Pack has been installed.
· Name, Release and Version of the programming environment (e.g. Visual Studio.NET 2008).
· Eventually, 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 API 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 control in your projects

How to use the API in a Windows service

How to synchronize the container application with the control

How to enumerate audio input devices

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

How to manage audio flow through WASAPI

How to manage ASIO drivers

How to perform a recording session

How to protect your recording sessions through encryption

How to perform a CD ripping session

How to perform a CD ripping session with tracks Normalization

How to record from files, memory or clipboard

How to perform an Internet-based recording session

How to mix sounds to your recording session

How to export a recorded sound

How to use embedded Visual Feedbacks

How to use the Enhanced Spectrum Analyzer

How to use the Waveform Analyzer

How to add graphic items to the Waveform Analyzer

How to scroll the sound's waveform during playback

How to manage custom DSP effects

How the Sound Activation System works

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

How to get pictures of CD covers

How to use the Windows Audio Compression Manager

How to use the automatic gain controller

How to apply embedded filters

How to perform custom feedbacks rendering using graphic bars

How to manage ZIP files

How to access BASS library functionalities directly

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 asrecnetapi_X.exe file and follow the contained instructions: note that "X" represents a code related to the purchased edition (asrecnetapi_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 tutorial.


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 Sound Recorder API" as displayed below and, if your application targets .NET framework versions 2.0, 3.0 or 3.5, select "Audio Sound Recorder API v2" or, if your application targets .NET framework 4, select "Audio Sound Recorder 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 Sound Recorder API v2" or like this

if you selected "Audio Sound Recorder API v4"

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

Visual C#

// instance the API as a global variable

AudioSoundRecorderApi.AudioSoundRecorderApiObj m_audioRecorderAPI = new AudioSoundRecorderApi.AudioSoundRecorderApiObj();

// initialize the API at the beginning of your code

m_audioRecorderAPI.InitRecordingSystem();

· 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 Sound Recorder API" as displayed below and, if your application targets .NET framework versions 2.0, 3.0 or 3.5, select "Audio Sound Recorder API v2" or, if your application targets .NET framework 4, select "Audio Sound Recorder 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 Sound Recorder API v2" or like this

if you selected "Audio Sound Recorder API v4"

· At this point we need to create a new instance of the component's class and, before starting sound recording management, to initialize the component: for this purpose it's mandatory a call to the InitRecordingSystem 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_audioRecorderAPI As AudioSoundRecorderApi.AudioSoundRecorderApiObj = New AudioSoundRecorderApi.AudioSoundRecorderApiObj()

' initialize the API at the beginning of your code

m_audioRecorderAPI.InitRecordingSystem ()

· 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 Sound Recorder API" as displayed below and, if your application targets .NET framework versions 2.0, 3.0 or 3.5, select "Audio Sound Recorder API v2" or, if your application targets .NET framework 4, select "Audio Sound Recorder 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 Sound Recorder API v2" or like this

if you selected "Audio Sound Recorder 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 InitRecordingSystem 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 AudioSoundRecorderApi;

namespace WebApplication1

{

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

 {

  // instance the API as a global variable

  AudioSoundRecorderApi.AudioSoundRecorderApiObj m_audioAPI = new AudioSoundRecorderApi.AudioSoundRecorderApiObj();

   protected void Page_Load (object sender, EventArgs e)

   {

    // initialize the API

    m_audioAPI.InitRecordingSystem ();

     ....

   }

 }

}

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

In case you should need to provide the possibility to convert audio files stored inside the server into a different audio format requiring the usage of an external command line encoder, like Lame.exe for MP3 or OggEnc.exe for Ogg Vorbis, it's recommended that you install the external command line encoders inside the same server's folder of the assembly AudioSoundRecorderApi.dll and of the multimedia engines AdjMmsEng.dll and AdjMmsEng64.dll; for this purpose you may follow the exact same procedure described above for the multimedia engines.

· 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 AudioSoundRecorderApi.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 convert it from AIFF format to MP3 through a recording session, will analyze the waveform of the new MP3 file, will generate a picture of the waveform itself and finally will display the waveform's 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 AudioSoundEditorApi;

namespace WebApplication1

{

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

 {

  // instance the API as a global variable

  AudioSoundEditorApi.AudioSoundEditorApi m_audioAPI = new AudioSoundEditorApi.AudioSoundEditorApi();

   protected void Page_Load (object sender, EventArgs e)

   {

    // initialize the API

    m_audioAPI.InitEditorNoPlayback ();

    // convert an existing file, stored inside the server, from AIFF format to MP3

     string        strPathInput = Request.PhysicalApplicationPath;

     string        strPathOutput = Request.PhysicalApplicationPath;

     strPathInput += "myfile.aiff";

     strPathOutput += "myfile.mp3";

     form1.InnerHtml += "Input path: " + strPathInput + "<BR>";

     form1.InnerHtml += "Output path: " + strPathOutput + "<BR>";

     m_audioAPI.EncodeFormats.ForRecording = enumEncodingFormats.ENCODING_FORMAT_MP3;

     m_audioAPI.EncodeFormats.MP3.EncodeMode = enumMp3EncodeModes.MP3_ENCODE_PRESETS;

     m_audioAPI.EncodeFormats.MP3.Preset = enumMp3EncodePresets.MP3_PRESET_MEDIUM;

     enumErrorCodes err = m_audioAPI.StartFromFile (strPathOutput, strPathInput);

     if (err == enumErrorCodes.ERR_NOERROR)

     {

      // display the sound duration

       form1.InnerHtml += "Converted sound duration: ";

       form1.InnerHtml += m_audioAPI.RecordedSound.DurationStringGet (true, true, ":", ".", 3) + "<BR>";

      // analyze the sound's waveform

       m_audioAPI.DisplayWaveformAnalyzer.AnalyzeFullSound ();

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

       string strPath = Request.PhysicalApplicationPath;

       strPath += "bitmap.gif";

       m_audioAPI.DisplayWaveformAnalyzer.SnapshotViewSaveToFile (

                       enumWaveSnapshotViewMode.WAVE_SNAPSHOT_MODE_WAVEFORM, 0, -1, 200, 50,

                       enumWaveformChannels.WAVEFORM_CHAN_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\">";

     }

     else

     {

       form1.InnerHtml += "Conversion failed due to error: " + err.ToString () + "<BR>";

     }

     ...

    // 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 Sound Recorder 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\\AudioSoundRecorderApi.tlb"

#pragma warning(pop)

using namespace AudioSoundRecorderApi;

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 AudioSoundRecorderApi.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 AudioSoundRecorderApiF4.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\\AudioSoundRecorderApiF4.tlb"

#pragma warning(pop)

using namespace AudioSoundRecorderApiF4;

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 Sound Recorder API for .NET" API whose default is "C:\Program Files\Audio Sound Recorder API for .NET\bin\release").

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

Visual C++

IAudioSoundRecorderApiObjPtr    m_ptrAudioRecorderApi;

where IAudioSoundRecorderApiObjPtr 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(AudioSoundRecorderApiObj), NULL,

                CLSCTX_ALL, __uuidof(IAudioSoundRecorderApiObj), (void**)&m_ptrAudioRecorderApi);

// init the API

m_ptrAudioRecorderApi->InitRecordingSystem();

· 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 the recorder or about the percentage of advancement of some operation:

Visual C++

// manages the RecorderCallback delegate

void FAR PASCAL RecorderCallback (enumRecorderEvents nEvent, long nData1, long nData2,

long nDataHigh3, long nDataLow3, long nDataHigh4, long nDataLow4)

{

   switch (nEvent)

   {

   case enumRecorderEvents_EV_REC_START:

       printf ("\r\nRecording started");

       break;

   case enumRecorderEvents_EV_REC_STOP:

       printf ("\r\nRecording stopped");

       break;

   case enumRecorderEvents_EV_REC_WAVE_ANALYSIS_PERC:

       printf ("\rWaveform analysis advancement %d%%", nPercentage);

       break;

   }

}

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

Visual C++

// init callbacks for events

m_ptrAudioRecorderApi->CallbackForRecorderEventsSetPtr (UINT_PTR (RecorderCallback));

please, note the usage of the "Ptr" version of the CallbackForRecorderEventsSet method: 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_ptrAudioRecorderApi->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 Sound Recorder 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 Sound Recorder API for .NET"

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

1. the one ending with "v2" refers to the AudioSoundRecorderApi.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 AudioSoundRecorderApi.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 SoundRecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

where "SoundRecorderApi" 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 SoundRecorderApi = New AudioSoundRecorderApi.AudioSoundRecorderApiObj

' init the control

SoundRecorderApi.InitRecordingSystem

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

SoundRecorderApi.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 the status of the recorder:

Visual Basic 6

Private Sub SoundRecorderApi_OnRecorderEvents(ByVal nEvent As enumRecorderEvents, _

       ByVal nData1 As Long, ByVal nData2 As Long, _

       ByVal nDataHigh3 As Long, ByVal nDataLow3 As Long, _

       ByVal nDataHigh4 As Long, ByVal nDataLow4 As Long)

   Select Case nEvent

       Case enumRecorderEvents.enumRecorderEvents_EV_REC_START

           Debug.Print "Recording started"

       Case enumRecorderEvents.enumRecorderEvents_EV_REC_STOP

           Debug.Print "Recording Stopped"

   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

SoundRecorderApi.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 control 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 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 Sound Recorder.

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 Sound Recorder 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 recording management, how to initialize the component.

Before starting sounds recording, the component needs to be initialized: for this purpose it's mandatory a call to the InitRecordingSystem 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 InitRecordingSystem 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.

Main features provided by this control are the following:

· Recording from an input device, usually defined as "sound card": see the How to perform a recording session section for further details.
· Recording from other sources like sound files on disk or from an Internet URL: see the How to record from files, memory or clipboard and the How to perform an Internet-based recording session sections for further details.
· Ripping CD tracks: see the How to perform a CD ripping session section for further details.

An important topic to keep count of is how synchronization between the container application and events generated by this component works: see the How to synchronize the container application with the control tutorial for further details.

Further capabilities of the control, not directly related to sound recording, are the following:

· the ExtractAudioFromVideoFile method allows extracting the audio track from a video clip and to store it inside an output sound file that may be used later for further editing.
· 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.


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 CallbackVuMeterValueChange delegate and by invoking the Spectrum.GetTable method)
· Waveform analyzer (although partially supported for analyzing the sound's waveform and for creating bitmaps of the waveform in various graphic formats)
· Waveform scroller
· Graphic bars manager
· Enhanced spectrum

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 InitRecordingSystem 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 "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

A few words about events generated from secondary threads

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(IAudioSoundRecorderServiceCallback), SessionMode = SessionMode.Allowed)]

public interface IAudioSoundRecorderService

{

[OperationContract]

void PipeGetRecordingDevicesCount(ref short nDevices);

[OperationContract]

string PipeGetRecordingDeviceName(short nDevice);

[OperationContract]

enumErrorCodes PipeStartRecording(short nDevice, string strOutputPathname);

[OperationContract]

enumErrorCodes PipeStop(short nDevice);

[OperationContract]

void PipeStartRecordingFromFile (string strOutputPathname, string strInputPathname);

[OperationContract]

void PipeFreeMemory ();

[OperationContract]

void PipeSoundPlay ();

[OperationContract]

void PipeSoundPause ();

[OperationContract]

void PipeSoundStop ();

[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 IAudioSoundRecorderService, is linked to another interface, named IAudioSoundRecorderServiceCallback, 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 IAudioSoundRecorderServiceCallback

{

[OperationContract(IsOneWay=true)]

void PipeSendRecordingSize (Int32 nSizeInBytes);

[OperationContract(IsOneWay=true)]

void PipeSendRecordingDuration (string strDuration);

[OperationContract(IsOneWay=true)]

void PipeSendRecResult (enumErrorCodes nResult);

[OperationContract(IsOneWay=true)]

void PipeSendPercentage (short nPercentage);

[OperationContract(IsOneWay=true)]

void PipeOperationCompleted (string strOperation, enumErrorCodes nResult);

}

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 AudioSoundRecorderApiInstance, derived from our API AudioSoundRecorderApi.AudioSoundRecorderApiObj, that implements methods defined inside the IAudioSoundRecorderService 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 AudioSoundRecorderApiInstance : AudioSoundRecorderApi.AudioSoundRecorderApiObj, IAudioSoundRecorderService

{

....

}

Initialization of the API and connection to the client through the IAudioSoundRecorderServiceCallback 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 AudioSoundRecorderApiInstance : AudioSoundRecorderApi.AudioSoundRecorderApiObj, IAudioSoundRecorderService

{

// declare the WCF pipe channel callback

IAudioSoundRecorderServiceCallback callback = null;

public AudioSoundRecorderApiInstance ()

{

// initialize the API

this.ContainerIsWindowsService ();

this.InitRecordingSystem ();

...

// set the WCF pipe channel callback

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

}

}

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

Visual C#

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

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]

public class AudioSoundRecorderApiInstance : AudioSoundRecorderApi.AudioSoundRecorderApiObj, IAudioSoundRecorderService

{

// declare the WCF pipe channel callback

IAudioSoundRecorderServiceCallback        callback = null;

// declare management functions for callback delegates

CallbackVuMeterValueChange addrCallbackVuMeterValueChange;

CallbackForRecorderEvents addrCallbackForRecorderEvents;

void VuMeterValueChangeCallback(short nPeakLeft, short nPeakRight)

{

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

callback.PipeSendVuMeterValues (nPeakLeft, nPeakRight);

}

void RecorderCallback(enumRecorderEvents nEvent, Int32 nData1, Int32 nData2, Int32 nDataHigh3, Int32 nDataLow3, Int32 nDataHigh4, Int32 nDataLow4)

{

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

switch (nEvent)

{

case enumRecorderEvents.EV_REC_SIZE:

callback.PipeSendRecordingSize (nDataLow4);

break;

case enumRecorderEvents.EV_REC_DURATION:

{

Int32        nDurationInMs = nData1;

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

callback.PipeSendRecordingDuration (strDuration);

}

break;

case enumRecorderEvents.EV_REC_STOP:

break;

case enumRecorderEvents.EV_REC_FINALIZATION_DONE:

callback.PipeSendRecResult ((enumErrorCodes) nData1);

callback.PipeOperationCompleted (m_OperationToExec, (enumErrorCodes) nData1);

break;

case enumRecorderEvents.EV_REC_PERC:

callback.PipeSendPercentage ((short) nData1);

break;

default:

return;

}

}

}

// class constructor

public AudioSoundRecorderApiInstance ()

{

// initialize the API

this.ContainerIsWindowsService ();

this.InitRecordingSystem ();

// predispose the callback that will notify about vu meter changes

addrCallbackVuMeterValueChange = new CallbackVuMeterValueChange(VuMeterValueChangeCallback);

this.CallbackVuMeterValueChangeSet(addrCallbackVuMeterValueChange);

// predispose the callback that will notify about recorder events

addrCallbackForRecorderEvents = new CallbackForRecorderEvents(RecorderCallback);

this.CallbackForRecorderEventsSet(addrCallbackForRecorderEvents);

... do other stuffs

// set the WCF pipe channel callback

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

}

public void PipeGetRecordingDevicesCount(ref short nDevices)()

{

nDevices = this.GetInputDevicesCount ();

}

public string PipeGetRecordingDeviceName(short nDevice)

{

string        strName = this.GetInputDeviceDesc (nDevice);

return strName;

}

public enumErrorCodes PipeStartRecording(short nDevice, string strOutputPathname)

{

... do other stuffs like predisposing encoding parameters

return this.StartFromDirectSoundDevice(nDevice, 0, strOutputPathname);

}

public enumErrorCodes PipeStop(short nDevice)

{

return this.Stop ();

}

public void PipeStartRecordingFromFile (string strOutputPathname, string strInputPathname)

{

this.StartFromFile (strOutputPathname, strInputPathname);

}

public void PipeFreeMemory ()

{

// invoke the RecordedSound.FreeMemory method of the API

this.RecordedSound.FreeMemory ();

}

public void PipeSoundPlay()

{

// invoke the RecordedSound.Play method of the API

this.RecordedSound.Play ();

}

public void PipeSoundPause()

{

// invoke the RecordedSound.Pause method of the API

this.RecordedSound.Pause ();

}

public void PipeSoundStop()

{

// invoke the RecordedSound.Stop method of the API

this.RecordedSound.Stop ();

}

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(AudioSoundRecorderApiInstance), new Uri("net.pipe://localhost"));

host.AddServiceEndpoint(typeof(IAudioSoundRecorderService), new NetNamedPipeBinding(), "PipeAudioSoundRecorder");

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 PipeAudioSoundRecorder 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 IAudioSoundRecorderService and IAudioSoundRecorderServiceCallback 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, IAudioSoundRecorderServiceCallback

{

public Form1 ()

{

InitializeComponent ();

}

....

}

Once defined, we can implement methods of the callback IAudioSoundRecorderServiceCallback 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, IAudioSoundRecorderServiceCallback

{

public Form1 ()

{

InitializeComponent ();

}

// the pipe channel proxy for WCF communication

IAudioSoundRecorderService pipeProxy = null;

bool        m_bIsServiceAvailable = false;

short        m_nVuMeterValueLeft = 0;

short        m_nVuMeterValueRight = 0;

short        m_nPercentage = 0;

Int32        m_nRecSizeInBytes = 0;

string        m_strRecDuration = "";

public void PipeOperationCompleted (string strOperation, enumErrorCodes nResult)

{

... do something

}

public void PipeSendRecResult (enumErrorCodes nResult)

{

... do something

}

public void PipeSendVuMeterValues (short nLeft, short nRight)

{

// store passed value into variables

m_nVuMeterValueLeft = nLeft;

m_nVuMeterValueRight = nRight;

}

public void PipeSendPercentage (Int16 nPercentage)

{

// store passed value into a variable

m_nPercentage = nPercentage;

}

public void PipeSendRecordingSize (Int32 nSizeInBytes)

{

// store passed value into a variable

m_nRecSizeInBytes = nSizeInBytes;

}

public void PipeSendRecordingDuration (string strDuration)

{

// store passed value into a variable

m_strRecDuration = strDuration;

}

private void Form1_Load (object sender, EventArgs e)

{

// create the WCF service and related pipe channel

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

new NetNamedPipeBinding(),

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

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

{

pipeProxy.PipeGetRecordingDevicesCount (ref nDevices);

}

catch (Exception)

{

MessageBox.Show ("Audio Sound Recorder 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 PipeAudioSoundRecorder.

You may notice that implementation of methods of the IAudioSoundRecorderServiceCallback 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 AudioRecWindowsServiceClient) 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.

A few words about events generated from secondary threads

As you will see inside the tutorial How to synchronize the container application with the API, some of the methods exposed by the API, such as the StartFromFile method, may start a lengthy operation requiring a remarkable execution time that could block the user interface of the container application for a while: this is not a problem when the API is instanced directly inside a regular Winforms application because the component can keep the user interface of the container application alive, allowing to manage eventual events such as the percentage of advancement but, when the API is instanced inside a Windows service (which is isolated from other windows due to the “Session 0 Isolation” mentioned at the beginning of this tutorial) and you need to refresh a progress bar inside the client application, this could be a problem.

The best approach in these cases is to allow the server (our Windows service) to start a brand new thread for invoking the lengthy method, allowing the user interface of the client application to be refreshed when one of its WCF callback's methods is invoked from the server, so the implementation of the PipeStartRecordingFromFile method of the IAudioSoundRecorderService primary interface:

Visual C#

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

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]

public class AudioSoundRecorderApiInstance : AudioSoundRecorderApi.AudioSoundRecorderApiObj, IAudioSoundRecorderService

{

...

public void PipeStartRecordingFromFile (string strOutputPathname, string strInputPathname)

{

this.StartFromFile (strOutputPathname, strInputPathname);

}

...

}

could be replaced by something like this:

Visual C#

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

[ServiceBehavior(InstanceContextMode = InstanceContextMode.PerSession)]

public class AudioSoundRecorderApiInstance : AudioSoundRecorderApi.AudioSoundRecorderApiObj, IAudioSoundRecorderService

{

...

// worker thread for performing lengthy operations that would block the user interface, not allowing to update eventual progress bars

string        m_OperationToExec = "";

string        m_strOutputPathname = "";

string        m_strInputPathname = "";

public void ExecuteOperation()

{

enumErrorCodes nResult = enumErrorCodes.ERR_NOERROR;

switch (m_OperationToExec)

{

case "RecordFromFile":

nResult = this.StartFromFile (m_strOutputPathname, m_strInputPathname);

break;

}

}

public void PipeStartRecordingFromFile (string strOutputPathname, string strInputPathname)

{

m_strOutputPathname = strOutputPathname;

m_strInputPathname = strInputPathname;

... do other stuffs like predisposing encoding parameters

// create and start the thread that allows executing the requested operation without blocking the user interface

m_OperationToExec = "RecordFromFile";

Thread workerThread = new Thread(ExecuteOperation);

workerThread.Start();

}

...

}

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 "AudioRecWindowsService.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 "AudioRecWindowsServiceClient.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 Sound Recorder 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 "AudioRecWindowsServiceClient.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 Sound Recorder 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 Sound Recorder API for .NET gives the possibility to setup a certain number of callback delegates that inform about percentage of advancement of a lengthy operation or about manual operations performed by the user on elements of the user interface like the waveform analyzer.

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 | Corresponding callback delegates | Method for initializing the delegates
A method involving the usage of a recorder has been invoked, for example StartFromAsioDevice StartFromDirectSoundDevice StartFromWasapiCaptureDevice StartFromWasapiLoopbackDevice Pause Resume Stop ... and many others | CallbackForRecorderEvents | CallbackForRecorderEventsSet
The range of sound displayed on the waveform analyzer is modified after a zooming operation or after a mouse scrolling operation or after a call to the WaveformAnalyzer.SetDisplayRange method. | CallbackWaveformAnalyzerRange | CallbackWaveformAnalyzerRangeSet
A portion of the waveform on the waveform analyzer has been selected/deselected through a mouse operation or through a call to the WaveformAnalyzer.SetSelection method. | CallbackWaveformAnalyzerSelection | CallbackWaveformAnalyzerSelectionSet
The waveform analyzer has been resized horizontally, usually after a call to the WaveformAnalyzer.Move method. | CallbackWaveformAnalyzerWidth | CallbackWaveformAnalyzerWidthSet
A custom vertical line on the waveform analyzer has been moved through the mouse or through the WaveformAnalyzer.GraphicItemHorzPositionSet method. | CallbackWaveformAnalyzerLineMoved | CallbackWaveformAnalyzerLineMovedSet
A custom horizontal line on the waveform analyzer has been moved through the mouse or through the WaveformAnalyzer.GraphicItemHorzPositionSet method or through the WaveformAnalyzer.GraphicItemVertPositionSet method.. | CallbackWaveformAnalyzerHorzLineMoved | CallbackWaveformAnalyzerHorzLineMovedSet
The playback position of the sound under editing reaches a custom vertical line inside the waveform analyzer. | CallbackWaveformAnalyzerLineReached | CallbackWaveformAnalyzerLineReachedSet
The playback position of the sound under editing reaches the beginning of a custom horizontal line inside the waveform analyzer. | CallbackWaveformAnalyzerHorzLineReached | CallbackWaveformAnalyzerHorzLineReachedSet
The playback position of the sound under editing leaves the end of a custom horizontal line inside the waveform analyzer. | CallbackWaveformAnalyzerHorzLineLeaved | CallbackWaveformAnalyzerHorzLineLeavedSet
The playback position of the sound under editing reaches the beginning of a custom wave range inside the waveform analyzer. | WaveAnalyzerWaveRangeReached | WaveAnalyzerWaveRangeReachedSet
The playback position of the sound under editing leaves the end of a custom wave range inside the waveform analyzer. | WaveAnalyzerWaveRangeLeaved | WaveAnalyzerWaveRangeLeavedSet
A graphic item is clicked with the mouse on the waveform analyzer | CallbackWaveformAnalyzerGraphItemClick | CallbackWaveformAnalyzerGraphItemClickSet
A graphic item is double-clicked with the mouse on the waveform analyzer | CallbackWaveformAnalyzerGraphItemDblClick | CallbackWaveformAnalyzerGraphItemDblClickSet
A mouse event happens on the waveform analyzer. | CallbackWaveformAnalyzerMouseNotif | CallbackWaveformAnalyzerMouseNotifSet
The waveform analyzer has completed its graphic rendering and it's now possible adding custom graphics directly from the container application's code. | CallbackWaveformAnalyzerPaintDone | CallbackWaveformAnalyzerPaintDoneSet
A manual scroll happens on the waveform scroller. | CallbackWaveformScrollerManualScroll | CallbackWaveformScrollerManualScrollSet
A mouse event happens on the waveform scroller. | CallbackWaveformScrollerMouseNotif | CallbackWaveformScrollerMouseNotifSet
During playback there is a change on the VU-Meter peak values. | CallbackVuMeterValueChange | CallbackVuMeterValueChangeSet
During playback there is a change on the waveform values. | CallbackWaveformValueChange | CallbackWaveformValueChangeSet
During playback the status of the player changes | CallbackSoundPlaybackStatusChanged | CallbackSoundPlaybackStatusChangedSet
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 start a recording session from the system default recording device and display the sound duration and size on corresponding labels.

Visual Basic .NET

Imports AudioSoundRecorderApi

Namespace MyApplication

   Public Partial Class Form1

       Inherits Form

       Public Sub New()

           InitializeComponent()

       End Sub

      ' instance of the API

       Private m_audioRecorderAPI As AudioSoundRecorderApi.AudioSoundRecorderApiObj = New AudioSoundRecorderApi.AudioSoundRecorderApiObj()

      ' callback delegate

       Private addrRecorderCallback As CallbackForRecorderEvents = New CallbackForRecorderEvents(AddressOf RecorderCallback)

      ' callback that manages recorde's events

       Private Sub RecorderCallback(ByVal nEvent As enumRecorderEvents, ByVal nData1 As Int32, ByVal nData2 As Int32, _

                            ByVal nDataHigh3 As Int32, ByVal nDataLow3 As Int32, _

                            ByVal nDataHigh4 As Int32, ByVal nDataLow4 As Int32)

           Select Case nEvent

               Case enumRecorderEvents.EV_REC_START

                   Console.WriteLine ("Recording started")

               Case enumRecorderEvents.EV_REC_STOP

                   Console.WriteLine ("Recording stopped")

               Case enumRecorderEvents.EV_REC_SIZE

                   Dim nDataSize As Int64 = (Convert.ToInt64 (nDataHigh4) << 32) Or Convert.ToInt64 (nDataLow4)

                   labelSize.Text = "Recording size in bytes: " & nDataSize.ToString()

               Case enumRecorderEvents.EV_REC_DURATION

                   labelDuration.Text = "Recording duration: " & m_audioRecorderAPI.FromMsToFormattedTime (nData1, False, True, ":", ".", 3)

               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_audioRecorderAPI.InitSoundSystem(1, 0, 0, 0, 0)

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

           m_audioRecorderAPI.CallbackForRecorderEventsSet(addrRecorderCallback)

          ' use custom resampling format 44100 Hz Stereo and record in MP3 format

           m_audioRecorderAPI.EncodeFormats.ResampleMode = enumResampleModes.RESAMPLE_MODE_CUSTOM_FORMAT

           m_audioRecorderAPI.EncodeFormats.ResampleCustomFrequency = 44100

           m_audioRecorderAPI.EncodeFormats.ResampleCustomChannels = 2

           m_audioRecorderAPI.EncodeFormats.ForRecording == enumEncodingFormats.ENCODING_FORMAT_MP3

          ' start a recording session from the system default recording device

           m_audioRecorderAPI.StartFromDirectSoundDevice (0, 0, "c:\myrecording.mp3")

          ... do other stuffs

       End Sub

   End Class

End Namespace

Visual C#

using AudioSoundRecorderApi;

namespace MyApplication

{

   public partial class Form1 : Form

   {

       public Form1()

       {

           InitializeComponent();

       }

      // instance of the API

       static AudioSoundRecorderApi.AudioSoundRecorderApiObj m_audioRecorderAPI = new AudioSoundRecorderApi.AudioSoundRecorderApiObj();

      // callback delegate

       CallbackForRecorderEvents addrRecorderCallback;

      // callback that manages recorder's events

       void RecorderCallback(enumRecorderEvents nEvent, Int32 nData1, Int32 nData2, Int32 nDataHigh3, Int32 nDataLow3, Int32 nDataHigh4, Int32 nDataLow4)

       {

           switch (nEvent)

           {

           case enumRecorderEvents.EV_REC_START:

               Console.WriteLine ("Recording started");

               break;

           case enumRecorderEvents.EV_REC_STOP:

               Console.WriteLine ("Recording stopped");

               break;

           case enumRecorderEvents.EV_REC_SIZE:

               Int64 nDataSize = (Convert.ToInt64 (nDataHigh4) << 32) | Convert.ToInt64 (nDataLow4);

               labelSize.Text = "Recording size in bytes: " + nDataSize.ToString();

               break;

           case enumRecorderEvents.EV_REC_DURATION:

               labelDuration.Text = "Recording duration: " + m_audioRecorderAPI.FromMsToFormattedTime (nData1, false, true, ":", ".", 3);

               break;

           }

       }

       private void Form1_Load(object sender, EventArgs e)

       {

          // initialize the API

           m_audioRecorderAPI.InitRecordingSystem();

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

           addrRecorderCallback = new CallbackForRecorderEvents(RecorderCallback);

           m_audioRecorderAPI.CallbackForRecorderEventsSet(addrRecorderCallback);

          // use custom resampling format 44100 Hz Stereo and record in MP3 format

           m_audioRecorderAPI.EncodeFormats.ResampleMode = enumResampleModes.RESAMPLE_MODE_CUSTOM_FORMAT;

           m_audioRecorderAPI.EncodeFormats.ResampleCustomFrequency = 44100;

           m_audioRecorderAPI.EncodeFormats.ResampleCustomChannels = 2;

           m_audioRecorderAPI.EncodeFormats.ForRecording == enumEncodingFormats.ENCODING_FORMAT_MP3;

          // start a recording session from the system default recording device

           m_audioRecorderAPI.StartFromDirectSoundDevice (0, 0, @"c:\myrecording.mp3");

          ... do other stuffs

       }

      ...

   }

  ...

}

Callback delegates invoked from secondary threads

Some method available inside Audio Sound Editor 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, percentage of advancement of the thread's task is reported to the container application through a set of callback delegates. A list of methods that will start a secondary thread, with the corresponding callback delegate, can be found on the table below:

Situations | Corresponding callback delegates | Method for initializing the delegates
A method involving the usage of a recorder has been invoked, for example StartFromFile StartFromMemory ... and many others | CallbackForRecorderEvents | CallbackForRecorderEventsSet
Notifications from CoreAudio devices | CallbackForCoreAudioEvents | CallbackForCoreAudioEventsSet
A new spectral analysis is requested | CallbackWaveAnalyzerSpectralViewStart CallbackWaveAnalyzerSpectralViewDone | CallbackWaveAnalyzerSpectralViewStartSet CallbackWaveAnalyzerSpectralViewDoneSet
A playback session is completed | CallbackSoundPlaybackDone | CallbackSoundPlaybackDoneSet

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 start a recording session from a sound file stored locally and immediately proceed with the sound's waveform analysis: during the loading and the waveform analysis the recording percentage is displayed on a label and on progress bar.

Visual Basic .NET

Imports AudioSoundRecorderApi

Namespace MyApplication

   Public Partial Class Form1

       Inherits Form

       Public Sub New()

           InitializeComponent()

       End Sub

      ' instance of the API

       Private m_audioRecorderAPI As AudioSoundRecorderApi.AudioSoundRecorderApiObj = New AudioSoundRecorderApi.AudioSoundRecorderApiObj()

      ' delegate for managing callbacks invoked from secondary threads

       Private Delegate Sub RecorderCallbackDelegate(ByVal nEvent As enumRecorderEvents, _

                               ByVal nData1 As Int32, ByVal nData2 As Int32, _

                               ByVal nDataHigh3 As Int32, ByVal nDataLow3 As Int32, _

                               ByVal nDataHigh4 As Int32, ByVal nDataLow4 As Int32)

      ' callback delegate

       Private addrRecorderCallback As CallbackForRecorderEvents = New CallbackForRecorderEvents(AddressOf RecorderCallback)

      ' callback that manages recorde's events

       Private Sub RecorderCallback(ByVal nEvent As enumRecorderEvents, ByVal nData1 As Int32, ByVal nData2 As Int32, _

                            ByVal nDataHigh3 As Int32, ByVal nDataLow3 As Int32, _

                            ByVal nDataHigh4 As Int32, ByVal nDataLow4 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 RecorderCallbackDelegate(AddressOf RecorderCallback), nEvent, nData1, nData2, _

                                                      nDataHigh3, nDataLow3, nDataHigh4, nDataLow4)

               Return

           End If

           Select Case nEvent

               Case enumRecorderEvents.EV_REC_PERC:

                   strStatus = "Status: Loading sound file... " & nData1.ToString() & "%"

               Case enumRecorderEvents.EV_REC_WAVE_ANALYSIS_PERC:

                   strStatus = "Status: Analyzing waveform... " & nData1.ToString() & "%"

               Case Else

                   Return

           End Select

          ' safely update elements of the user interface

           LabelStatus.Text = strStatus

           progressBar1.Value = nData1

       End Sub

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

          ' initialize the API

           m_audioRecorderAPI.InitSoundSystem(1, 0, 0, 0, 0)

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

           m_audioRecorderAPI.CallbackForRecorderEventsSet(addrRecorderCallback)

           progressBar1.Visible = False

          ' load the new song

           m_audioRecorderAPI.StartFromFile("", "c:\mysound.mp3")

           LabelStatus.Text = "Status: Idle"

           progressBar1.Visible = False

          ' request full waveform analysis using default resolution

           progressBar1.Visible = True

           m_audioRecorderAPI.DisplayWaveformAnalyzer.AnalyzeFullSound()

           LabelStatus.Text = "Status: Idle"

           progressBar1.Visible = False

          ' display the full waveform

           m_audioRecorderAPI.DisplayWaveformAnalyzer.SetDisplayRange(0, -1)

       End Sub

   End Class

End Namespace

Visual C#

using AudioSoundRecorderApi;

namespace MyApplication

{

   public partial class Form1 : Form

   {

       public Form1()

       {

           InitializeComponent();

       }

      // instance of the API

       static AudioSoundRecorderApi.AudioSoundRecorderApiObj m_audioRecorderAPI = new AudioSoundRecorderApi.AudioSoundRecorderApiObj();

      // delegate for managing callbacks invoked from secondary threads

       delegate void RecorderCallbackDelegate(enumRecorderEvents nEvent, Int32 nData1, Int32 nData2,

                                               Int32 nDataHigh3, Int32 nDataLow3,

                                               Int32 nDataHigh4, Int32 nDataLow4);

      // callback delegate

       CallbackForRecorderEvents addrRecorderCallback;

      // callback that manages recorder's events

       void RecorderCallback(enumRecorderEvents nEvent, Int32 nData1, Int32 nData2,

                             Int32 nDataHigh3, Int32 nDataLow3, Int32 nDataHigh4, Int32 nDataLow4)

       {

          // 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 RecorderCallbackDelegate(RecorderCallback), nEvent, nData1, nData2, nDataHigh3, nDataLow3, nDataHigh4, nDataLow4);

               return;

           }

           switch (nEvent)

           {

           case enumRecorderEvents.EV_REC_PERC:

               strStatus = "Status: Loading sound file... " + nData1.ToString() + "%";

               break;

           case enumRecorderEvents.EV_REC_WAVE_ANALYSIS_PERC:

               strStatus = "Status: Analyzing waveform... " + nData1.ToString() + "%";

               break;

           }

          // safely update elements of the user interface

           LabelStatus.Text = strStatus;

           progressBar1.Value = nData1;

       }

       private void Form1_Load(object sender, EventArgs e)

       {

          // initialize the API

           m_audioRecorderAPI.InitRecordingSystem();

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

           addrRecorderCallback = new CallbackForRecorderEvents(RecorderCallback);

           m_audioRecorderAPI.CallbackForRecorderEventsSet(addrRecorderCallback);

           progressBar1.Visible = true;

           // load the new song

           m_audioRecorderAPI.StartFromFile("", @"c:\mysound.mp3");

           LabelStatus.Text = "Status: Idle";

           progressBar1.Visible = false;

           // request full waveform analysis using default resolution

           progressBar1.Visible = true;

           m_audioRecorderAPI.DisplayWaveformAnalyzer.AnalyzeFullSound();

           LabelStatus.Text = "Status: Idle";

           progressBar1.Visible = false;

          // display the full waveform

           m_audioRecorderAPI.DisplayWaveformAnalyzer.SetDisplayRange(0, -1);

       }

      ...

   }

  ...

}

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.

IMPORTANT NOTES ABOUT BEST PRACTICES

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

It's very important to remember that a call to a method of a specific component should be never performed from within a management function of an event generated by the same component: this is usually cause of errors and dead-lock situations and it's a practice that should be always avoided; in order to avoid issues the best approach would be using the callback to trigger a one-shot timer and to call methods for requesting new operations from within the management function of the timer's event.

How to create and use one-shot timers in C#

The procedure below allows using a single one-shot timer that could manage some of the situations described above:

· At design-time, from the Visual Studio toolbox, insert a Timer object inside the form containing the Audio Sound Recorder component: inside this sample it will be named TimerSync
· At design-time, set the Enabled property of the timer object to False
· At design-time, set the Interval property of the timer object to 50
· Inside your code add a global variable of type "String" that you could use for knowing the next operation that needs to be performed immediately after receiving the timer's tick: inside this sample it will be named g_strNextOperation

Supposing that we have have stopped a recording session and that we need to start the waveform analysis, the code below could not work correctly:

Visual C#

using AudioSoundRecorderApi;

namespace MyApplication

{

   public partial class Form1 : Form

   {

      ...

      // callback that manages recorder's events

       void RecorderCallback(enumRecorderEvents nEvent, Int32 nData1, Int32 nData2, Int32 nDataHigh3, Int32 nDataLow3, Int32 nDataHigh4, Int32 nDataLow4)

       {

           switch (nEvent)

           {

           case enumRecorderEvents.EV_REC_START:

               Console.WriteLine ("Recording started");

               break;

           case enumRecorderEvents.EV_REC_STOP:

               Console.WriteLine ("Recording stopped");

               m_audioRecorderAPI.DisplayWaveformAnalyzer.AnalyzeFullSound (); // <-- this call could fail and the application could hang

               break;

       }

      ...

   }

  ...

}

and you should prefer using something like this

Visual C#

using AudioSoundRecorderApi;

namespace MyApplication

{

   public partial class Form1 : Form

   {

      ...

      // callback that manages recorder's events

       void RecorderCallback(enumRecorderEvents nEvent, Int32 nData1, Int32 nData2, Int32 nDataHigh3, Int32 nDataLow3, Int32 nDataHigh4, Int32 nDataLow4)

       {

           switch (nEvent)

           {

           case enumRecorderEvents.EV_REC_START:

               Console.WriteLine ("Recording started");

               break;

           case enumRecorderEvents.EV_REC_STOP:

               Console.WriteLine ("Recording stopped");

               g_strNextOperation = "AnalyzeSound";

               TimerSync.Enabled = true;

               break;

       }

      ...

   }

  ...

}

Now let's catch the timer's tick and perform requested operation

Visual C#

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

{

   // reset the timer to avoid unwanted recursions

  TimerSync.Enabled = false;

  // start requested operation

  if (g_strNextOperation == "AnalyzeSound")

      m_audioRecorderAPI.DisplayWaveformAnalyzer.AnalyzeFullSound ();

}

As you may understand, you could expand the timer's handler above for all operations executed inside secondary threads by adding new values for the g_strNextOperation variable.

Visual C#

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

{

   // reset the timer to avoid unwanted recursions

  TimerSync.Enabled = false;

  // start requested operation

switch (g_strNextOperation)

  {

  case "AnalyzeSound":

       audioSoundRecorder1.DisplayWaveformAnalyzer.AnalyzeFullSound ();

      break;

  case "CreateWaveformBitmap":

       audioSoundRecorder1.DisplayWaveformAnalyzer.SnapshotViewSaveToFile (0, -1, etc.);

      break;

  }

}


How to enumerate audio input devices

How to enumerate audio input devices

By default Audio Sound Recorder API for .NET enumerates input devices (sound cards) supporting the DirectSound protocol and the standard way to enumerate input devices is the combination of GetInputDevicesCount and GetInputDeviceDesc methods but, in order to let Audio Sound Recorder enumerating devices supporting ASIO drivers or WASAPI drivers (only on Windows Vista and later versions), you need to make a prior call to the InitDriversType method and to specify which kind of drivers/protocols your application will support.

IMPORTANT NOTE: When using the Audio Sound Recorder API component in conjunction with our Audio DJ Studio API component, which also contains the InitDriversType method, it should be preferred calling the InitDriversType method from Audio DJ Studio API so it will automatically affect both input and output devices.

The call to the InitDriversType method is mandatory before performing calls to the InitRecordingSystem, GetInputDevicesCount and GetInputDeviceDesc 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 input devices through the GetInputDevicesCount and GetInputDeviceDesc methods.

4. ResetControl method

After having initialized the type of driver(s) in use through the InitDriversType method, it will be possible enumerating available input devices through the GetInputDevicesCount and GetInputDeviceDesc methods: depending upon the kind of drivers in use, these methods will return the overall list of available input devices.

When using ASIO and WASAPI drivers you can have more control over audio devices enumeration through a set of dedicated methods: refer to the How to manage ASIO drivers and How to manage audio flow through WASAPI tutorials for further details.

The full sequence of calls for enumerating audio input devices for recording purposes, keeping count of selected drivers type, is explained inside the How to perform a recording session tutorial.

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 dealing with Windows Vista and later versions which support jack-sensing, when the microphone's jack is inserted or removed from its connector. Let's see what may happen depending upon the Windows version in use:

Configuration change in Windows XP, Windows Server 2003 and older versions

When a new USB device is plugged-in or unplugged, the container application receives one or more notifications through the CallbackDeviceChange delegate: after receiving this notification, if you need to remain in sync with available sound cards, you will have to reset the multimedia engine with the procedure described above. Windows XP doesn't support jack-sensing so you won't be notified when the Microphone or Line-In jacks are unplugged.

As mentioned, you could receive more than one notification through the CallbackDeviceChange delegate at the same time so, when starting the reset procedure, you should ignore eventual notifications after the first one (typically for about 2 seconds).

Configuration change in Windows Vista and later versions

Configuration changes of audio devices installed inside the system are notified through the CallbackForCoreAudioEvents delegate whose nEvent parameter allows determining the type of change.

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.


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 Sound Recorder 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.

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


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 InitRecordingSystem, GetInputDevicesCount and GetInputDeviceDesc 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 input devices through the GetInputDevicesCount and GetInputDeviceDesc methods.

4. ResetControl method

After initializing the usage of WASAPI through the InitDriversType method, Audio Sound Recorder 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 input devices you can also use the GetInputDevicesCount and GetInputDeviceDesc methods. In both cases, only devices reported as "Enabled" by the system will be listed: unplugged or disabled devices will not be enumerated.

Before using an input device for recording or 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.

It's important to note that, also if the output device and the input device are both located on the same physical device, the system will see them as different entities so you will have to start them as separate devices using two calls to the DeviceStartExclusive or WASAPI.DeviceStartShared methods.

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.

Now, once the capture and loopback devices needed for recording have been started, we have two options:

· Start a recording session from a single input device

In order to start a recording session from a capture device you can use the StartFromWasapiCaptureDevice method.

Through WASAPI loopback it's also possible capturing the audio stream that is being played by a rendering endpoint device, also if the stream is being played by other external applications, for example by Windows Media Player or WinAmp: in order to start a recording session from a loopback device you can use the StartFromWasapiLoopbackDevice method.

As seen for other recording start methods described inside the How to perform a recording session tutorial, the recorded stream will be stored into an output file or into a memory buffer.

· Start a recording session from multiple input devices at the same time and have the streams mixed into one single output file

This solution allows getting various audio streams, incoming from different input devices (both capture and loopback devices), and to pass their contents to the WASAPI mixer that will combine them together in order to have in output a single audio stream, allowing to store the result into a single output file or into a memory buffer.

In order to achieve this feature, after having started the input devices you want to record from, you need to attach them to the WASAPI mixer through separate calls to the WASAPI.MixerInputDeviceAttach method (one call for each input device): once all of the input devices of interest have been attached, you can start the recording session through the StartFromWasapiMixer method.

It' important to note that, once the recording session has been started, you cannot attach further input devices until the recording session has been stopped through the Stop method. After stopping the recording session and before starting a new one, you may eventually detach one or more input devices through the WASAPI.MixerInputDeviceDetach method; you can know if a specific input device is already attached to the mixer using the WASAPI.MixerInputDeviceIsAttached method and you can enumerate attached input devices through the combination of the WASAPI.MixerInputDeviceAttachedCountGet and WASAPI.MixerInputDeviceAttachedInfoGet methods.

Although it would be possible to detach a specific input device from the WASAPI mixer during a recording session, as mentioned before you would not be able to attach it back again while the recording session is in place: for this reason, if you should need to temporarily "disable" a specific input device, it would be convenient setting its volume to 0 using the WASAPI.DeviceVolumeSet method and, when needed again, to "enable" back the specific input device by reapplying its original volume; further information about volume settings are described inside the next paragraph.

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.

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 Microphones or Line-In are physically inserted or removed from respective connectors. When the configuration of audio devices changes, it could be needed to enumerate again the available input 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.

If supported by the driver of the sound card, through WASAPI is also possible emulating the "Listen to this device" feature (see the screenshot below) available inside the "Listen" tab of the "Sound" applet of the Windows control panel:

The "Listen to this device" feature allows passing the audio incoming from the microphone through the PC speakers directly or, in alternative, you may connect your MP3 player (iPod, mobile phone, etc.) to the Line-In port (using the jack contact), and hear the music again through the PC speakers.

This feature can be emulated by invoking the WASAPI.ListenInputDeviceStart method, which receives the index of the capture device and of the render device,and can be stopped at a later time through the WASAPI.ListenInputDeviceStop method.

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:

- WasapiRecorder

- WasapiInputMixerRecorder


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 Sound Recorder enumerates input devices (sound cards) supporting the DirectSound protocol: in order to let Audio Sound Recorder 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.

IMPORTANT NOTE: When using the Audio Sound Recorder API component in conjunction with our Audio DJ Studio API component, which also contains the InitDriversType method, it should be preferred calling the InitDriversType method from Audio DJ Studio API so it will automatically affect both input and output devices.

The call to the InitDriversType method is mandatory before performing calls to the InitRecordingSystem, GetInputDevicesCount and GetInputDeviceDesc 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 input devices through the GetInputDevicesCount and GetInputDeviceDesc methods.

4. ResetControl method

After having initialized the type of driver(s) in use through the InitDriversType method, it will be possible enumerating available input devices through the GetInputDevicesCount and GetInputDeviceDesc methods: depending upon the driver set, these methods will return the overall list of available input devices (DirectSound + ASIO) so it will be possible setting them inside the nDeviceIndex parameter of the StartFromAsioDevice method. You can also obtain the driver in use by a specific input device through the GetInputDeviceDriverType 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 which 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 input devices as reported by the GetInputDevicesCount and GetInputDeviceDesc methods.
· Obtaining the zero-based index of an ASIO device inside the overall list of available input devices through the ASIO.DeviceGetInputIndex 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.DeviceGetIndexFromInput 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 be able starting a recording session on a specific ASIO device. You can know if a specific ASIO device is already started through the ASIO.DeviceIsStarted method.

IMPORTANT NOTE: When using Audio Sound Recorder API in conjunction with Audio DJ Studio API, you should prefer calling this method using the same ASIO.DeviceStart method available inside Audio DJ Studio API so you would have a better control over the playback mode.

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

· Starting a recording session on the device through the StartFromAsioDevice method.
· 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.

When dealing with sound cards having multiple input channels, like the M-Audio Delta 1010LT, there is the possibility to mix the input of all of the channels into one single recording session or, by using multiple instances of Audio Sound Recorder, you can record at the same time each channel or couple of channels on a separate destination file. Let's see these situations with a couple of small snippets of code.

In the first sample we need to record the first 8 input channels of an ASIO device selected from the comboInputDevices combobox and mix all of the channels inside the same output file:

Visual Basic .NET

' init some variable

Dim nInputChannel as Integer = 0

Dim nTotalChannels as Integer = 8

' start the recording session

audioSoundRecorder1.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   nFirstInputChannel, nTotalChannels, "c:\mydir\output.wav")

Visual C#

// init some variable

short nInputChannel = 0;

short nTotalChannels = 8;

// start the recording session

audioSoundRecorder1.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   nFirstInputChannel, nTotalChannels, @"c:\mydir\output.wav");

In the second sample we need to record the first 4 input channels of an ASIO device selected from the comboInputDevices combobox and keep them separated in 4 different output files:

Visual Basic .NET

' init some variable

Dim nTotalChannels as Integer = 1

' start the recording session from channel 0 and save it inside the output1.wav file

audioSoundRecorder1.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   0, nTotalChannels, "c:\mydir\output1.wav")

' start the recording session from channel 1 and save it inside the output2.wav file

audioSoundRecorder2.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   1, nTotalChannels, "c:\mydir\output2.wav")

' start the recording session from channel 2 and save it inside the output3.wav file

audioSoundRecorder3.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   2, nTotalChannels, "c:\mydir\output3.wav")

' start the recording session from channel 3 and save it inside the output4.wav file

audioSoundRecorder4.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   3, nTotalChannels, "c:\mydir\output4.wav")

Visual C#

// init some variable

short nTotalChannels = 1;

// start the recording session from channel 0 and save it inside the output1.wav file

audioSoundRecorder1.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   0, nTotalChannels, @"c:\mydir\output1.wav");

// start the recording session from channel 1 and save it inside the output2.wav file

audioSoundRecorder2.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   1, nTotalChannels, @"c:\mydir\output2.wav");

// start the recording session from channel 2 and save it inside the output3.wav file

audioSoundRecorder3.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   2, nTotalChannels, @"c:\mydir\output3.wav");

// start the recording session from channel 3 and save it inside the output4.wav file

audioSoundRecorder4.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   3, nTotalChannels, @"c:\mydir\output4.wav");

In the third sample we need to record the first 8 input channels of an ASIO device selected from the comboInputDevices combobox and keep them separated in 4 different output files having each 2 input channels mixed together:

Visual Basic .NET

 ' init some variable

Dim nTotalChannels as Integer = 2

' start the recording session from channels 0-1 and save it inside the output1.wav file

audioSoundRecorder1.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   0, nTotalChannels, "c:\mydir\output1.wav")

' start the recording session from channels 2-3 and save it inside the output2.wav file

audioSoundRecorder2.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   2, nTotalChannels, "c:\mydir\output2.wav")

' start the recording session from channels 4-5 and save it inside the output3.wav file

audioSoundRecorder3.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   4, nTotalChannels, "c:\mydir\output3.wav")

' start the recording session from channels 6-7 and save it inside the output4.wav file

audioSoundRecorder4.StartFromAsioDevice(comboInputDevices.SelectedIndex, _

                   6, nTotalChannels, "c:\mydir\output4.wav")

Visual C#

 ' init some variable

short nTotalChannels = 2;

' start the recording session from channels 0-1 and save it inside the output1.wav file

audioSoundRecorder1.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   0, nTotalChannels, @"c:\mydir\output1.wav");

' start the recording session from channels 2-3 and save it inside the output2.wav file

audioSoundRecorder2.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   2, nTotalChannels, @"c:\mydir\output2.wav");

' start the recording session from channels 4-5 and save it inside the output3.wav file

audioSoundRecorder3.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   4, nTotalChannels, @"c:\mydir\output3.wav");

' start the recording session from channels 6-7 and save it inside the output4.wav file

audioSoundRecorder4.StartFromAsioDevice(comboInputDevices.SelectedIndex,

                   6, nTotalChannels, @"c:\mydir\output4.wav");

It's important to note that code snippets above simply show how to call the StartFromAsioDevice method and don't show the calls to the InitDriversType method and to the ASIO.DeviceStart method which are in any case mandatory for starting the recording session: finally, don't forget that, when using multiple instances of the component as seen inside the latest 2 code snippets, the need to call these mandatory methods is only from one single instance of the component, for example from the instance identified by activeSoundRecorder1 because,.once an ASIO device is started, it can be automatically accessed by all of the other instances.

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.

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

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

- AsioList

- AsioSimpleRecorder


How to perform a recording session

How to perform a recording session

A recording session allows receiving a sound stream from the input channel of a physical sound card, eventually applying some custom DSP in order to perform analysis and/or special effects, encoding into a specific audio format (WAV, MP3, WMA, etc.) and finally storing the encoded audio stream inside an output file or inside a memory buffer. The architecture of the control is based upon the graph below:

Modern sound cards can perform a recording session through DirectSound drivers, ASIO drivers and, starting from Windows Vista, WASAPI drivers: you can choose the type of driver you want to support through the InitDriversType method; if you should omit this call, by default the control will use DirectSound.

Another recording possibility, not directly related to the usage of a sound card installed inside the system, is the availability of an external device (for example a hardware device or a telephony-based application) that could receive data in input and produce RAW audio in output that, through the usage of a queue, could be "manually" sent to the recorder as seen on the schema below:

Before starting a recording session, the component needs to be initialized: for this purpose it's mandatory a call to the InitRecordingSystem method; the best place to call this method is usually the container form initialization function: for example, when using Visual C#, it will be the Form_Load function.

At this point we must decide is the output format of the recorded sound: for this purpose you need to set the EncodeFormats.ForRecording property to one of the available encoding formats.

Each encoding format set into the EncodeFormats.ForRecording property have its own settings which can be controlled through sub-properties of the EncodeFormats property: for example, if the chosen encoding format should be ENCODING_FORMAT_WAV you would have to modify settings of the EncodeFormats.WAV property, if chosen encoding format should be ENCODING_FORMAT_MP3 you would have to modify settings of the EncodeFormats.MP3 property and so on for the remaining accepted encoding formats.

Before starting a recording session, you need to check if the Status property is set to RECORD_STATUS_READY: if the property value should be RECORD_STATUS_NOT_READY, this would mean that initialization of the control and negotiation with underlying drivers is still not completed.

In case there should be the need to resample incoming sound data, for example for reducing the final recording size, it could be convenient checking the EncodeFormats.ResampleMode property and choose which of the available resample modes would best fit your needs.

After having decided the supported driver type, having initialized the control and chosen the output format, we must decide from which input device we want to receive sound data: for this purpose we need to enumerate available audio devices; this enumeration may vary depending upon the type of driver chosen when the InitDriversType method was invoked:

Recording through DirectSound

Recording through ASIO

Recording through WASAPI (Only available on Windows Vista and later versions)

Recording through a raw audio queue

· Recording through DirectSound

When dealing with Windows XP or Windows Server 2003 and earlier versions, the number and friendly descriptions of available input devices (intended as sound cards) can be obtained through a call to the GetInputDevicesCount and GetInputDeviceDesc methods. The number and friendly descriptions of available input channels (Microphone, Line-In, etc.), relative to a certain input device, can be obtained through a call to the GetInputDeviceChannelsCount and GetInputDeviceChannelDesc methods.

When dealing with Windows Vista and higher versions, each input channel is seen as a separate input device so it will be enough enumerating them through the GetInputDevicesCount and GetInputDeviceDesc methods; eventual calls to the GetInputDeviceChannelsCount method will always return 1 and the GetInputDeviceChannelDesc method will return the string "Master volume".

The system default input channel for a certain input device can be changed at system level (so it will be reflected inside the "Sounds" applet of the Windows Control Panel) through a call to the SetInputDeviceChannelDefault method. The volume of the input channel can be changed, again at at system level, through the SetInputDeviceChannelVolume method.

At this point we can start the recording session calling the StartFromDirectSoundDevice method which needs to know the output file location: if an absolute pathname is specified, it can be a file on the system hard disk or, if the pathname is left empty, a memory file that could be used at a later time, for example in order to perform a custom encrypting before saving it to a file on disk: it's highly suggested avoiding the use of memory based recording sessions for a duration longer than 5 minutes because they could require a huge amount of memory: for a longer duration the output on files should be preferred.

· Recording through ASIO

Each ASIO device is seen as a combination of input and output channels so the way to enumerate ASIO devices and respective input channels is the following:

1. Enumerate available ASIO devices through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods.
2. For each ASIO device, enumerate the list of available input channels through the ASIO.DeviceGetChannelsCount and ASIO.DeviceGetChannelDesc methods by setting the respective bInputChannel parameter to "true".

At this point we need to start the device through the ASIO.DeviceStart method: you can know if a device is already started through the ASIO.DeviceIsStarted method.

Finally we can start the recording session through the StartFromAsioDevice method which needs to know the output file location: if an absolute pathname is specified, it can be a file on the system hard disk or, if the pathname is left empty, a memory file that could be used at a later time, for example in order to perform a custom encrypting before saving it to a file on disk: it's highly suggested avoiding the use of memory based recording sessions for a duration longer than 5 minutes because they could require a huge amount of memory: for a longer duration the output on files should be preferred.

You can refer to the How to manage ASIO drivers tutorial for further details about ASIO drivers.

· Recording through WASAPI (Only available on Windows Vista and later versions)

Each WASAPI device is seen as a combination of input, output and loopback devices; for recording purposes we can choose between input devices and loopback devices so the way to enumerate WASAPI input/loopback devices is through the WASAPI.DeviceGetCount and WASAPI.DeviceGetDesc methods by setting the respective nDeviceType parameter to WASAPI_DEVICE_TYPE_CAPTURE for input devices or WASAPI_DEVICE_TYPE_LOOPBACK for loopback devices.

At this point we need to start the device through the WASAPI.DeviceStartShared or through the WASAPI.DeviceStartExclusive method: you can know if a device is already started through the WASAPI.DeviceIsStarted method.

Finally we can start the recording session through the StartFromWasapiCaptureDevice method for input devices or through the StartFromWasapiLoopbackDevice method for loopback devices. Both methods need to know the output file location: if an absolute pathname is specified, it can be a file on the system hard disk or, if the pathname is left empty, a memory file that could be used at a later time, for example in order to perform a custom encrypting before saving it to a file on disk: it's highly suggested avoiding the use of memory based recording sessions for a duration longer than 5 minutes because they could require a huge amount of memory: for a longer duration the output on files should be preferred.

When using WASAPI there is also the possibility to record from multiple input devices (both capture and loopback devices) at the same time and to store the mixed result into an output file; after having started the input devices of interest, you can add them to the WASAPI input mixer through separate calls to the WASAPI.MixerInputDeviceAttach method (one call for each input device) and then you can start the recording session through the StartFromWasapiMixer method.

You can refer to the How to manage audio flow through WASAPI tutorial for further details about WASAPI.

· Recording through a raw audio queue

In order to start a recording session from an external physical or logical device that produces in output raw audio data, you need to perform a call to the StartFromQueueRaw method: as seen for other kinds of recording sessions, this method needs to know the output file location: if an absolute pathname is specified, it can be a file on the system hard disk or, if the pathname is left empty, a memory file that could be used at a later time, for example in order to perform a custom encrypting before saving it to a file on disk: it's highly suggested avoiding the use of memory based recording sessions for a duration longer than 5 minutes because they could require a huge amount of memory: for a longer duration the output on files should be preferred.

As a second information, the StartFromQueueRaw method needs to know the format of raw audio data, for example it could be an uncompressed PCM in stereo with 16 bits per sample and a sample rate of 44100 or a compressed GSM 6.10 in mono with a sample rate of 8000.

Once the recording session is started, your code can start feeding the queue with raw audio data taken from the output of the external device through the SendDataToQueueRaw method.

During the recording session, the container application can be notified about the current duration and about the current disk or memory occupation through the CallbackForRecordersEvents delegate having the nEvent parameter set to EV_REC_DURATION and EV_REC_SIZE respectively: note that, for reducing the amount of bytes requested for storing sound data, the control gives the possibility to discard silent data, i.e. portions of sounds that cannot be heard: see section How the Sound Activation System works for further details about this feature.

The current recording session can be stopped at any time through the Stop method.

The current recording session can be paused through the Pause method and resumed through the Resume method.

After stopping the current recording session, you have the possibility to start a new one without discarding the existing one: for this purpose you need to define how the new recording session will behave through a call to the SetRecordingMode method: this will allow appending the new recording session to the existing one or inserting/mixing/overwriting the new recording session to a given position of the existing one: see the SetInsertPos, SetMixingPos and SetOverwritePos methods for defining where the new recording session will be inserted/mixed/overwritten.

It's important to note that, after stopping a restarted recording session, the total recorded sound will not be immediately available because there will be the need to finalize and join the new recording session with the previous one: the container application will be informed about the start/end of the automatic finalization process through the CallbackForRecordersEvents delegate having the nEvent parameter set to EV_REC_FINALIZATION_STARTED and EV_REC_FINALIZATION_DONE.

Once a recording session has been stopped, the control can manage recorded sound data, stored on a disk file or inside a memory buffer, through the following methods:

· RecordedSound.Play
· RecordedSound.PlayRange
· RecordedSound.Pause
· RecordedSound.Resume
· RecordedSound.Stop
· RecordedSound.SeekPlayPosition
· RecordedSound.GetPlaybackPosition
· RecordedSound.GetFormattedPlaybackPosition
· RecordedSound.GetDuration64
· RecordedSound.GetFormattedDuration

The playback rate of the recorded stream can be modified through the following methods:

· RecordedSound.PlaybackRateSet
· RecordedSound.PlaybackTempoSet

allowing a faster listening of the recorded audio stream.

As a further playback feature, you may change playback direction through the RecordedSound.SoundDirectionSet method: using this feature requires enabling playback direction management through a previous call to the RecordedSound.SoundDirectionEnable method or, in case the waveform scroller should be in use, through the WaveformScroller.PlaybackOnScrollEnable method.

In case you should need more advanced playback features consider using this component in conjunction with our Audio DJ Studio API for .NET component.

The recorded sound can be edited through one of the following methods:

· RecordedSound.RequestReduceToRange
· RecordedSound.RequestDeleteRange
· RecordedSound.RequestInsertSilence
· RecordedSound.TrimSilence

Note that editing capabilities are quite limited: if you need more sophisticated editing features consider using this component in conjunction with our Audio Sound Editor API for .NET component.

The recorded sound can be exported to a disk file or inside a memory buffer using the RecordedSound.RequestExportToFile method: see the How to export a recorded sound section for further details

The recorded sound can be also uploaded to a FTP server through the RecordedSound.RequestUploadToFTP method (the upload session can be cancelled through the RecordedSound.CancelUploadToFTP method) and can be also copied into the system clipboard in CF_WAVE format through the RecordedSound.CopyRangeToClipboard method.

As already stated before, if the strOutputPath parameter of the StartFromDirectSoundDevice method has been left blank, recorded sound data will be stored inside a memory buffer; the operation that can be performed on this memory buffer are the following:

· RecordedSound.GetMemoryPtr
· RecordedSound.GetMemorySize
· RecordedSound.SaveToFile
· RecordedSound.FreeMemory

While performing a recording session whose output will be stored inside a file on the hard disk, it could be useful having the possibility to save the recording session in more than one file without any interruption of the audio flow: for this purpose you can use the SwitchOutputFile or the SwitchOutputFileEx methods: the call to one of these method makes the engine invoke the CallbackForRecordersEvents delegate having the nEvent parameter set to EV_REC_OUTPUT_FILE_SWITCH.

After switching the output file one or more times, you can verify how many times the output file was switched through the SwitchedOutputFileGetCount method and, for each single output file, you can obtain the absolute pathname through the SwitchedOutputFileGetPathname method, the size in bytes through the SwitchedOutputFileGetSize method and its duration through the SwitchedOutputFileGetDuration method.

In case you should need to split the recording session in separate files containing the left and right channels respectively, you could use the StartSplitFromDirectSoundDevice method. In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

The same splitting feature is also available for Wasapi capture and loopback devices through the StartSplitFromWasapiCaptureDevice and StartSplitFromWasapiLoopbackDevice methods.

While performing a split recording session whose output will be stored inside two file on the hard disk, it could be useful having the possibility to save the recording session in more than one file without any interruption of the audio flow: for this purpose you can use the SwitchOutputFileOnSplit: the call to one of these method makes the engine invokes the CallbackForRecordersEvents delegate having the nEvent parameter set to EV_REC_OUTPUT_FILE_SWITCH.

POSITION MARKERS

During a recording session it's sometime useful having the possibility to add one or more position markers: a position marker is like a bookmark, and it's used to mark a location within a document. This is useful if you need to return to that location quickly or frequently without the need to manually search for a specific position inside a long recording session.

During a recording session you can add position markers using the PositionMarkerAdd method and, when the recording session is completed and stopped, you can add further position markers through the PositionMarkerAddOffline method. Position markers can be removed at any time through the PositionMarkerRemove method.

You can retrieve the current number of available position markers through the PositionMarkerCountGet method. Each position marker is identified by a "unique identifier" which can be retrieved through the PositionMarkerUniqueIdGet method. The position in milliseconds of each marker can be obtained or changed through the PositionMarkerPosGet and PositionMarkerPosSet methods and its friendly descriptor can be obtained through the PositionMarkerDescGet method.

Position markers can be saved for later use through the PositionMarkerSave method: you have the choice to store them inside an external XML file or, if supported by the audio format of the output sound file created by the recording session, directly into the tag of the file. After loading again the sound file into the recorder through the StartFromFile method, saved position markers can be retrieved through the PositionMarkerLoad method.

During a playback session, position markers can be used to seek the current playback position through the PositionMarkerSeekPlayPositionTo method; in alternative they can be used to start the playback of a specific range within the recorded sound through the PositionMarkerPlayRange method.


How to protect your recording sessions through encryption

How to protect your recording sessions through encryption

Protecting recording sessions from fraudulent uses could be a must for many purposes and is already required from certain medical confidentiality laws.

Audio Sound Recorder API for .NET comes with two solutions for protecting your audio data:

· Through standard AES encrypted ZIP files: see the How to manage ZIP files tutorial for details about ZIP files management.
· Through its own protection schema: continue reading this document for details.

Although you could already use your own or third-party encryption/decryption schemas and re-load decrypted song's data through the StartFromMemory method; Audio Sound Recorder API for .NET comes with a proprietary solution that allows encrypting recording session, for safe redistribution or storage purposes, through the EncryptCurrentSession method. As an alternative for already existing and previously stored recording sessions, you could also use our CryptSound™ application.

Once encrypted, no available multimedia application will be able to playback the output of encrypted recording sessions while applications developed using Audio Sound Recorder API for .NET will be able to re-load encrypted songs through the StartFromFileEncrypted method: it's important to note that this will happen without the need to create decrypted temporary files: for best safety the full decryption process will be performed in memory until you won't set the strOutputPath parameter of the StartFromFileEncrypted method to an absolute pathname.

For security reasons encryption features and the CryptSound™ application are not included inside the Trial version and are disabled by default inside the Commercial version: if you own the Commercial version and if you wish using encryption features, please, contact us for instructions about enabling this specific feature or for receiving a copy of the CryptSound™ application.

In case you should need to test encryption capabilities, please, contact us and we will ask you to upload inside our FTP server a sample sound at this point we will send you back the encrypted sample with a dedicated decryption key that will have to be passed to the StartFromFileEncrypted method.

Another important feature brought by Audio Sound Recorder API for .NET is the capability to upload an encrypted recording session to a FTP site; for this purpose, after having called the EncryptCurrentSession method, you can upload the encrypted session through the RequestUploadFileToFTP method.

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 perform a CD ripping session

How to perform a CD ripping session

A CD ripper, CD grabber or CD extractor is a piece of software designed for "ripping" raw digital audio (in format commonly called CDDA) from a compact disc to a file or other output with a CD-ROM or DVD-ROM drive in a PC.

Before starting a CD ripping session, Audio Sound Recorder needs to be initialized: for this purpose it's mandatory a call to the InitRecordingSystem method; the best place to call this method is usually the container form initialization function: for example, when using Visual C#, it will be the Form_Load function.

Now the control needs to know where and how ripped sound data will be stored; the first thing to decide is the output format of the ripped sound: for this purpose you need to set the EncodeFormats.ForCdRipping property to one of the available encoding formats.

Each encoding format set into the EncodeFormats.ForCdRipping property have its own settings which can be controlled through sub-properties of the EncodeFormats property: for example, if the chosen encoding format should be ENCODING_FORMAT_WAV you would have to modify settings of the EncodeFormats.WAV property, if chosen encoding format should be ENCODING_FORMAT_MP3 you would have to modify settings of the EncodeFormats.MP3 property and so on for the remaining accepted encoding formats.

Before starting a recording session, you could have the need to resample incoming sound data, for example for reducing the final recording size: for this purpose you should check the EncodeFormats.ResampleMode property and choose which of the available resample modes would best fit your needs.

At this point we can proceed in two different ways:

1. Ripping single CD tracks through the CdRippingStart method which needs to know the following:

· the input CD drive: installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
· the CD audio track: the total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method: remember that CD tracks are 1-based so the first track will be identified by the index 1 instead of 0.
· the output file location: if an absolute pathname is specified, it can be a file on the system hard disk or, if the pathname is left empty, a memory file that can be used at a later time, for example in order to perform a custom encrypting before saving it to a file on disk.

The current ripping session can be stopped at any time through the CdRippingStop method.

The container application is notified about the start of the CD ripping session through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to the following values:

· EV_CD_RIPPING_START invoked once at the beginning
· EV_CD_RIPPING_PERC invoked multiple times reporting the current advancement percentage inside the nDataLow3 parameter
· EV_CD_RIPPING_SIZE invoked multiple times reporting the current size in bytes inside the combination of the nDataHigh3 and nDataLow3 parameters
· EV_CD_RIPPING_STOP invoked as soon as the ripping session is completed

2. Ripping multiple CD tracks at once through ripping automation methods:

· the ripping automation session is initialized through the CdRippingAutomationInit method: this method allows setting up the input CD drive and the output mode: you can decide to store each single track into a separate output file or to store all tracks inside a single output file: in this latest case you can also set the amount of silence that will be inserted between each ripped track. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
· CD tracks to rip are added to the automation through the CdRippingAutomationTrackAdd method: the total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method: remember that CD tracks are 1-based so the first track will be identified by the index 1 instead of 0. If the session was initialized to store each track into a separate output file, you can also specify the output pathname: if an absolute pathname is specified, it can be a file on the system hard disk or, if the pathname is left empty, a memory file that can be used at a later time, for example in order to perform a custom encrypting before saving it to a file on disk.
· the ripping session is started through the CdRippingAutomationExec method.

The current ripping automation session can be stopped at any time through the CdRippingStop method.

The container application is notified about the CD ripping automation session through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to the following values:

· EV_CD_RIPPING_AUTOMATION_START invoked once at the beginning
· EV_CD_RIPPING_PERC invoked multiple times reporting the current advancement percentage of each single track inside the nDataLow3 parameter
· EV_CD_RIPPING_AUTOMATION_TOTAL_PERC invoked multiple times reporting the advancement of the overall ripping automation session
· EV_CD_RIPPING_SIZE invoked multiple times reporting the current size in bytes of each single track inside the combination of the nDataHigh3 and nDataLow3 parameters
· EV_CD_RIPPING_AUTOMATION_STOP invoked as soon as the ripping automation session is completed

In either cases you can limit the ripped track's range through a call to the CdRippingSetRange method and reduce the overall output size through resampling: for this purpose you can define resampling parameters through the CdRippingSetResampleParams method.

After completing the ripping of a single CD audio track, output formats like WMA, MP3, OGG Vorbis and MP4 can add song information to the output file through the use of tags: tag's information can be obtained through public Internet databases that support the CDDB protocol: if the CddbAddTagOnCdRipping property is set to True and if an Internet connection is available and open, the control can automatically retrieve and add this information to the output file tags: see the How to get Audio CD info using CDDB servers and Amazon catalogue section for details. Note that CDDB information about the CD album can be retrieved from the server before starting the CD ripping session so, information like the song title and the author name, can be easily used to compose the output file name that will be sent to the CdRippingStart method.

Another feature that can be used before starting a CD ripping session is the ability of the control to retrieve, from the Amazon web site, the cover art of the CD inserted inside the CD drive: see the How to get a CD cover picture section for details.

An important feature for CD ripping session is the ability to normalize the level of audio tracks: see the How to perform a CD ripping session with tracks Normalization tutorial for details.

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

- CdRipper

- CdRipperAutomation


How to perform a CD ripping session with tracks Normalization

How to perform a CD ripping session with tracks Normalization

 Return to chapter overview

An important feature of CD ripping is the capability to set the overall volume of tracks to a certain target volume, a process known as Normalization. Due to volume differences between audio tracks, normalization allows you to set the volume consistent between tracks during the encoding process. In this process, the level of each track is adjusted so that the loudest moment (technically the largest sample value) is adjusted to peak at the largest allowed value by turning up the gain the required amount.

On the graphic below you can see the waveform of a CD track ripped without normalization enabled

while on the graphic below you can see the waveform of the same CD track ripped with normalization enabled

As already seen inside the How to perform a CD ripping session tutorial, Audio Sound Recorder supports CD ripping of single tracks and CD ripping automation which allows ripping multiple tracks in one single shot. As a further feature it allows performing normalization of CD tracks by applying a slightly different procedure to ripping sessions. Respect to the majority of normalization algorithms, Audio Sound Recorder allows configuring not only the highest peak to reach a specified level (expressed in percentage) but also to apply normalization only to peaks belonging to a specified range of volume levels.

When normalization is not enabled, the ripping session is performed through one single operation: CD track's raw sound data is extracted from the CD and sent directly to the encoder in charge; when normalization is enabled through the CdRippingNormalizationEnable method, each time a CD ripping session is started through the CdRippingStart method (for ripping of single tracks) or through the CdRippingAutomationExec method (for ripping of multiple tracks) the control will perform three distinct operations for each track:

1. extraction of the CD track's raw sound data into a memory buffer
2. normalization of sound levels inside the memory buffer
3. encoding of normalized sound data to the final destination (file on disk or memory buffer)

As you may understand, respect to a normal ripping session, the container application not only needs to be synchronized with the start and stop of the session through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to the following values:

· EV_CD_RIPPING_START (for ripping of single tracks) or EV_CD_RIPPING_AUTOMATION_START (for ripping of multiple tracks) invoked once at the beginning
· EV_CD_RIPPING_STOP (for ripping of single tracks) or EV_CD_RIPPING_AUTOMATION_STOP (for ripping of multiple tracks) invoked as soon as the ripping session is completed

but also with the following events:

· EV_CD_RIPPING_EXTRACT_PERC event informs the container application about the advancement of extraction of the CD track's raw sound data into a memory buffer (see point 1. above)
· EV_CD_RIPPING_NORM_PERC event informs the container application about the normalization advancement (see point 2. above)
· EV_CD_RIPPING_ENCODE_PERC event informs the container application about the encoding advancement (see point 3. above)

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

- CdRipperAutomation


How to record from files, memory or clipboard

How to record from files, memory or clipboard

Recording from a file stored on your hard-disk (or inside your pen drive or inside a memory buffer) must not be confused with a simple "file load": when you record from a file you have the possibility to perform a resampling and an automatic format conversion of sound data stored inside the file; suppose that you have a song, 3:31 minutes long, stored inside a CD quality WAV file (uncompressed, 44100 Hz, Stereo, 16 bits per sample): this kind of file requires almost 37 Mbytes of space: with a few methods call, Audio Sound Recorder API for .NET can record sound data directly from this file, resampling with a lower quality (for example 11025 Hz, Mono), converting the sound format to MP3 and, finally, store it again inside your hard-disk or inside a memory buffer for further uses.

In order to start recording from a file, the component needs to be initialised: for this purpose it's mandatory a call to the InitRecordingSystem method; the best place to call this method is usually the container form initialisation function: for example, when using Visual C#, it will be the Form_Load function.

After initialization you need to predispose a couple of settings as for any sound card based recording session; the first thing to decide is the output format of the recorded sound: for this purpose you need to set the EncodeFormats.ForRecording property to one of the available encoding formats.

Each encoding format set into the EncodeFormats.ForRecording property have its own settings which can be controlled through sub-properties of the EncodeFormats property: for example, if the chosen encoding format should be ENCODING_FORMAT_WAV you would have to modify settings of the EncodeFormats.WAV property, if chosen encoding format should be ENCODING_FORMAT_MP3 you would have to modify settings of the EncodeFormats.MP3 property and so on for the remaining accepted encoding formats.

Before starting a recording session, you could have the need to resample incoming sound data, for example for reducing the final recording size: for this purpose you should check the EncodeFormats.ResampleMode property and choose which of the available resample modes would best fit your needs.

Now we can start the file recording session calling the StartFromFile or StartFromFileRaw methods which need to know the output file location: if an absolute pathname is specified it can be a file on the system hard disk or, if the pathname is left empty, recorded sound data are stored inside a memory buffer that can be used at a later time, for example in order to perform a custom encrypting session before saving it to a file on disk.

If your source file has already been stored inside a memory buffer, you can record directly from this memory buffer using the StartFromMemory or StartFromMemoryRaw methods.

The recording range can be limited through the SetRecordingRange method.

If your source file is available in CF_WAVE format inside the system clipboard, you can record directly from the system clipboard using the StartFromClipboard method: you can know if a CF_WAVE format sound is available inside the system clipboard calling the IsSoundAvailableInClipboard method.

During the mentioned recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

As for a regular sound card based recording session, after completing a file based recording sessions you have the possibility to start a new one without discarding the existing one: for this purpose you need to define how the new recording session will behave through a call to the SetRecordingMode method: this will allow appending the new recording session to the existing one or inserting/mixing/overwriting the new recording session to a given position of the existing one: see the SetInsertPos, SetMixingPos and SetOverwritePos methods for defining where the new recording session will be inserted/mixed/overwritten. It's important to note that file based recording sessions can be merged/mixed with previous recording sessions performed through a sound card.

In case you should need to split the recording session in separate files containing the left and right channels respectively, you could use of the following methods:

· StartSplitFromFile or StartSplitFromFileRaw for recording sessions from files.
· StartSplitFromMemory or StartSplitFromMemoryRaw for recording sessions from memory buffers.
· StartSplitFromClipboard for recording sessions from clipboard
· StartSplitFromURL for recording sessions from an Internet URL
· StartSplitFromZipFile for recording sessions from a ZIP file

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.


How to perform an Internet-based recording session

How to perform an Internet-based recording session

In order to start recording from an Internet source (either a shoutcast/icecast stream or simply a sound file stored on a web site), the control needs to be initialised: for this purpose it's mandatory a call to the InitRecordingSystem method; the best place to call this method is usually the container form initialisation function: for example, when using Visual C#, it will be the Form_Load function.

After initialization you need to predispose a couple of settings as for any sound card based recording session; the first thing to decide is the output format of the recorded sound: for this purpose you need to set the EncodeFormats.ForRecording property to one of the available encoding formats.

Each encoding format set into the EncodeFormats.ForRecording property have its own settings which can be controlled through sub-properties of the EncodeFormats property: for example, if the chosen encoding format should be ENCODING_FORMAT_WAV you would have to modify settings of the EncodeFormats.WAV property, if chosen encoding format should be ENCODING_FORMAT_MP3 you would have to modify settings of the EncodeFormats.MP3 property and so on for the remaining accepted encoding formats.

Before starting a recording session, you could have the need to resample incoming sound data, for example for reducing the final recording size: for this purpose you should check the EncodeFormats.ResampleMode property and choose which of the available resample modes would best fit your needs.

Now we can start the Internet recording session calling the StartFromURL method which needs to know the output file location: if an absolute pathname is specified it can be a file on the system hard disk or, if the pathname is left empty, recorded sound data are stored inside a memory buffer that can be used at a later time, for example in order to perform a custom encrypting session before saving it to a file on disk.

As for a regular sound card based recording session, after completing an Internet based recording sessions you have the possibility to start a new one without discarding the existing one: for this purpose you need to define how the new recording session will behave through a call to the SetRecordingMode method: this will allow appending the new recording session to the existing one or inserting/mixing/overwriting the new recording session to a given position of the existing one: see the SetInsertPos, SetMixingPos and SetOverwritePos methods for defining where the new recording session will be inserted/mixed/overwritten. It's important to note that Internet based recording sessions can be merged/mixed with previous recording sessions performed through a sound card or from a disk file.

In case you should need to split the recording session in separate files containing the left and right channels respectively, you could use the StartSplitFromURL method. In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.


How to mix sounds to your recording session

How to mix sounds to your recording session

Active Sound Recorder allows mixing a sound, coming from different sources, to current contents of a recording session; mixing can be enabled by setting the recording mode to REC_MODE_MIX through a call to the SetRecordingMode method and configured through the following methods:

· if you simply need setting the mixing position where the new recorded sound will be mixed to the recording session contents use the SetMixingPos method.
· if you need setting the mixing position, a mixing range and volumes applied to both sounds use the SetMixingParams method: as a further feature, this method allows rendering in loop the new recorded sound, a very useful feature if you need applying a background sound to your recording session; it's important to note that, if the input sound file in loop mode should exceed the defined range limit, it would be in any case mixed until its completion so no unwanted cut would result on the input sound.

At this point you can start mixing the new recorded sound using one of the recording methods like StartFromDirectSoundDevice, StartFromFile, etc.


How to export a recorded sound

How to export a recorded sound

After completing one or more recording sessions, the current recorded sound, or a defined range within the recorded sound, can be resampled and exported into a disk file; the first thing to decide is the format of the exported sound: for this purpose you need to set the EncodeFormats.ForExporting property to one of the available encoding formats.

Each encoding format set into the EncodeFormats.ForExporting property has its own settings which can be controlled through sub-properties of the EncodeFormats property: for example, if the chosen encoding format should be ENCODING_FORMAT_WAV you would have to modify settings of the EncodeFormats.WAV property, if chosen encoding format should be ENCODING_FORMAT_MP3 you would have to modify settings of the EncodeFormats.MP3 property and so on for the remaining accepted encoding formats.

At this point the recorded sound can be resampled and exported to a disk file calling the RecordedSound.RequestExportToFile method: depending upon the size of the loaded sound, the export session could result in a lengthy operation so it will be performed on a separate thread: during the export session, the container application will be notified about the exporting advancement through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_SOUND_EXPORT_PERC

The exporting session can be canceled through the RecordedSound.CancelExportToFile method.

During an exporting session in which the recorded sound is being down-mixed to lower frequencies (for example from 44100 Hz to 11025 Hz), the SetDownmixFilterQuality method allows applying an anti-aliasing filter to exported sounds, allowing better quality results.


How to use embedded Visual Feedbacks

How to use embedded Visual Feedbacks

This component's version comes with the four embedded Visual Feedbacks listed below:

VU-Meter

Spectrum

Oscilloscope

Waveform

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.

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

HasPeaks: determines the "peaks" visibility.

ColorBands: determines the "bands" color.

ColorPeaks: determines the "peaks" color.

ColorBackground: determines the color of the background area.

ZoomPerc: determines the height zoom percentage of bands.

SetBackPictureFromFile: sets a background picture obtained from a BMP file

SetBackPictureFromHandle: sets a background picture obtained from a bitmap handle

below you can see a sample of the embedded VU-Meter:

If you shouldn't like the graphic representation of the embedded VU-Meter, note that you can implement your own VU-Meter graphics, driven by the values received through the CallbackVuMeterValueChange delegate.

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

HasPeaks: determines the "peaks" visibility.

ColorBands: determines the "bands" color.

ColorPeaks: determines the "peaks" color.

ColorBackground: determines the color of the background area.

ZoomPerc: determines the height zoom percentage of bands.

SetBackPictureFromFile: sets a background picture obtained from a BMP file

SetBackPictureFromHandle: sets a background picture obtained from a bitmap handle

below you can see a sample of the embedded Spectrum and, on the right, a zoomed detail of the Spectrum "bands":

If you don't like the graphic representation of the embedded Spectrum, note that you can implement your own Spectrum graphics, driven by the values obtained through the Spectrum.GetTable method which can be called after the CallbackVuMeterValueChange delegate is invoked.

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:


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 recording and during playback of the recorded sound through the usage of an enhanced FTT-based spectrum analyzer.

The enhanced spectrum analyzer can represent a FFT graph as seen inside the image below:

The FFT graph works by taking a small sample of audio and plotting a graph of frequency (on the x-axis expressed in Hz) versus intensity of the signal (on the y-axis expressed in dB). The graph features two different plots if the audio is stereo, otherwise just the one plot will be displayed.

In alternative enhanced spectrum analyzer can represent a TFFT graph, also known as "spectral view", as seen on the image below:

The TFFT graph works by plotting the intensity of the frequency spectrum of the audio across time, and represents intensity through color; during playback the signal intensity is rendered along the x-axis while the y-axis is used for frequency (expressed in Hz) and depicts the spectrum of the audio at any one point in time: for every point along the x-axis an intensity calculation is done and a dB figure is calculated: the lower the intensity, the darker the color; the higher the intensity, the brightest the color.

The enhanced spectrum analyzer can be accessed through the SpectrumEnh property which implements the SpectrumEnh COM object; an enhanced spectrum analyzer can be instanced 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 use the Waveform Analyzer

How to use the Waveform Analyzer

After recording a sound (see the How to perform a recording session section for recording details) the embedded Waveform Analyzer, implemented through the WaveformAnalyzer class, allows performing a detailed analysis of the sound itself with the purpose of generating a graphical representation of the sound's waveform.

The first step is to perform the sound's analysis through a call to the WaveformAnalyzer.AnalyzeFullSound method: the analysis can be more or less accurate depending upon the resolution set into the nResolution field of the WANALYZER_GENERAL_SETTINGS data structure: 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. When the results of an analysis are no more needed, the involved memory can be released through a call to the WaveformAnalyzer.FreeMemory method. The analysis can be aborted at any time through a call to the WaveformAnalyzer.AnalyzeAbort method.

After calling this method, the control will allow the container application to stay up-to-date about the analysis advancement through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_WAVE_ANALYSIS_PERC.

After completing the waveform analysis, you can request the level, expressed in percentage, of the highest and of the lowest peaks available inside a certain range of the waveform through the WaveformAnalyzer.GetMinMaxPeakLevelsForRange method.

At this point it's possible creating a graphical representation of analyzed sounds in one of the following modes:

Mode 1: Visual editing

Mode 2: Creation of bitmaps in various graphic formats

Mode 3: Rendering on a graphic Device Context (HDC)

Mode 1: Visual editing

In order to start the visual editing of the sound's waveform, we need to create the Waveform Analyzer user interface through a call to the WaveformAnalyzer.Create method. By default the Waveform Analyzer user interface will appear as in the picture below where the top waveform represents the left channel of a stereo sound while the bottom waveform represents the right channel of a stereo sound (sounds in mono are rendered using one single waveform):

Once the waveform analysis has been performed, you can immediately display the full waveform on the visible area of the analyzer through a call to the WaveformAnalyzer.SetDisplayRange method by passing 0 and -1 respectively to the nBeginPosInMs and nEndPosInMs parameters.

In alternative to the classical waveform's representation of maximum and minimum peaks values visible on the screenshot below

the waveform analyzer, through the WaveformAnalyzer.ViewModeSet method, can be set to display the waveform through its absolute values as seen on the screenshot below

or through the spectral view of the loaded sound as seen on the screenshot below

In this specific case, each time a spectral analysis is requested, the control will allow the container application to stay up-to-date about the spectral analysis advancement through the following callback delegates:

· CallbackWaveAnalyzerSpectralViewStart: fired when the spectral analysis begins.
· CallbackForRecordersEvents with the nEvent parameter set to EV_REC_SPECTRAL_ANALYSIS_PERC : fired several times during the analysis in order to inform the container application about the percentage of advancement.
· CallbackWaveAnalyzerSpectralViewDone: fired when the spectral analysis is completed

As most Windows controls with an user interface, the Waveform Analyzer can be:

· shown or hidden through the WaveformAnalyzer.Show method
· moved or resized through the WaveformAnalyzer.Move method
· refreshed through the WaveformAnalyzer.Refresh method
· destroyed through the WaveformAnalyzer.Destroy method
· scrolled through the WaveformAnalyzer.Scroll method: scrolling can be also performed panning the horizontal scrollbars with the mouse.
· it's also possible replacing the standard cursors, used for scrolling and resizing, operations through the WaveformAnalyzer.SetTrackerCursors method

The graphical rendering of this control is fully customizable and you can modify colors used to render the various elements and hide/show all of the elements surrounding the waveform 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 WANALYZER_GENERAL_SETTINGS data structure accessible through the combination of the WaveformAnalyzer.SettingsGeneralGet and WaveformAnalyzer.SettingsGeneralSet methods.
· rulers rendering settings are managed through the WANALYZER_RULERS_SETTINGS data structure accessible through the combination of the WaveformAnalyzer.SettingsRulersGet and WaveformAnalyzer.SettingsRulersSet methods.
· scrollbars rendering settings are managed through the WANALYZER_SCROLLBARS_SETTINGS data structure accessible through the combination of the WaveformAnalyzer.SettingsScrollbarsGet and WaveformAnalyzer.SettingsScrollbarsSet methods.
· waveform rendering settings are managed through the WANALYZER_WAVEFORM_SETTINGS data structure accessible through the combination of the WaveformAnalyzer.SettingsWaveGet and WaveformAnalyzer.SettingsWaveSet methods.

The Waveform Analyzer allows selecting/deselecting portions of the displayed waveform in two different ways:

· through code using the WaveformAnalyzer.SetSelection method.
· through mouse acting directly on the waveform area: simply press the left button, drag the mouse position keeping the left button pressed and then release the left button: the selected area will appear with its colors inverted and with two tracker handles that will allow further manual resizing of the selected range; this selection can be also moved performing a mouse panning. After these manual operations the control can obtain the selected area through the WaveformAnalyzer.GetSelection method.

The Waveform Analyzer allows zooming the displayed waveform in two different ways:

· through code using one of the following methods: WaveformAnalyzer.SetDisplayRange, WaveformAnalyzer.ZoomIn, WaveformAnalzyer.ZoomOut, WaveformAnalyzer.ZoomToFullSound, WaveformAnalyzer.ZoomToSelection. After zooming in and out, you can obtain the current sound's range displayed on the Waveform Analyzer calling the WaveformAnalyzer.GetDisplayRange method and to obtain the length of this range in milliseconds and pixels using the WaveformAnalyzer.GetDisplayWidth method.
· through mouse acting directly on the tracker handles of one of the available horizontal scrollbars as seen on the picture below:

Whenever a change occurs on the user interface, the container application is notified through one of the following events:

· CallbackWaveformAnalyzerSelection: this delegate, set through the CallbackWaveformAnalyzerSelectionSet method, is invoked when a selection/deselection is performed
· CallbackWaveformAnalyzerRange: this delegate, set through the CallbackWaveformAnalyzerRangeSet method, is invoked when a new range within the sound is displayed
· CallbackWaveformAnalyzerWidth: this delegate, set through the CallbackWaveformAnalyzerWidthSet method, is invoked when the control is resized horizontally

When the waveform analyzer, through the WaveformAnalyzer.ViewModeSet method, has been set to display the spectral view instead of the classical waveform and a zoom or panning operation is performed (through the scrollbars or by code), the spectral view is calculated again inside a secondary thread so scrollbars are enabled but the new spectral analysis is performed when the mouse button, acting on the "tracker handles", is released and not while the mouse is being moved.

In order to allow management of mouse interaction, you can catch the CallbackWaveformAnalyzerMouseNotif delegate, set through the CallbackWaveformAnalyzerMouseNotifSet method, which reports the exact position where the mouse was pressed on the waveform: accurate positioning is guaranteed also when the waveform is zoomed. Mouse interaction can be enabled/disabled through the WaveformAnalyzer.MouseSelectionEnable method. During a playback session the mouse interaction is automatically disabled and an eventual call to this method will be ignored.

Each graphical element composing the Waveform Analyzer visualization is referenced by a specific rectangle on the screen: coordinates and dimensions of this rectangle, expressed in pixels, can be obtained through the WaveformAnalyzer.GetRectangle method.

Each time the graphical rendering of the Waveform Analyzer is completed, the container application is informed through the CallbackWaveformAnalyzerPaintDone delegate set through the CallbackWaveformAnalyzerPaintDoneSet method: this delegate will pass as parameter the HWND of the Waveform Analyzer window, allowing to perform further custom graphic rendering on the Waveform Analyzer surface; for this purpose you can obtain the handle to the device context (HDC) of the Waveform Analyzer through the GetDC Windows API.

The Waveform Analyzer automatically manages two vertical lines, one for displaying the current position during a playback session and another one for displaying a position, selected through the mouse, within the loaded sound: the look of these two lines can be modified through the WANALYZER_GENERAL_SETTINGS data structure mentioned before.

The waveform analyzer allows adding further graphical items like vertical lines, horizontal lines and wave ranges: for details about graphic items management you can refer to the How to add graphic items to the Waveform analyzer tutorial.

Mode 2: Creation of bitmaps in various graphic formats

After completing the waveform analysis started through the WaveformAnalyzer.AnalyzeFullSound method, it will be possible requesting to the control the creation of the waveform's bitmap through a call to the WaveformAnalyzer.SnapshotViewSaveToFile and WaveformAnalyzer.SnapshotViewSaveToMemory methods. Through the WaveformAnalyzer.GetAnalysisInfo method you can know 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 WaveformAnalyzer.SnapshotViewGetWidthForWaveform method.

The generated waveform's bitmap will be rendered using colors set into the colorWaveLinePeak, colorWaveLineCenter and colorWaveBackground fields of the WANALYZER_WAVEFORM_SETTINGS data structure.

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 set into the nResolution property | Generated bitmap
WAVEANALYZER_RES_MAXIMUM |
WAVEANALYZER_RES_VERY_HIGH |
WAVEANALYZER_RES_HIGH |
WAVEANALYZER_RES_MIDDLE |
WAVEANALYZER_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 WaveformAnalyzer.SnapshotViewSaveToFile and WaveformAnalyzer.SnapshotViewSaveToMemory 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.

Mode 3: Rendering on a graphic Device Context (HDC)

After completing the waveform analysis, it will be also possible rendering the waveform directly inside a graphical device context (through its handle or HDC) using the WaveformAnalyzer.SnapshotViewDrawToHdc 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.

When rendering the waveform on a device context, you have the option to choose if the rendered waveform must contain eventual custom graphic items also (for details about graphic items management you can refer to the How to add graphic items to the Waveform analyzer tutorial) by setting the bShowGraphicItems parameter of the WaveformAnalyzer.SnapshotViewDrawToHdc method to "true" or "false": if this parameter should be set to "true", you may choose which combination of items should be rendered by setting the rendering mask through the WaveformAnalyzer.SnapshotViewGraphicItemsMaskSet method.

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 WaveformAnalyzer.PeaksBufferGet method.


How to add graphic items to the Waveform Analyzer

How to add graphic items to the Waveform Analyzer

As seen inside the tutorial How to use the Waveform Analyzer, the waveform analyzer allows selecting through the mouse a specific position on the visible waveform range, visualized through a vertical line, and to display the current playback position through a second vertical line.

The waveform analyzer allows adding through code further custom graphic items:

· Vertical lines through the WaveformAnalyzer.GraphicItemVerticalLineAdd method
· Horizontal lines through the WaveformAnalyzer.GraphicItemHorizontalLineAdd method
· Wave ranges through the WaveformAnalyzer.GraphicItemWaveRangeAdd method

On the screenshot below you can find a waveform with several graphic items inside, each having its own colors and positioning:

For each of these graphic items, through the mentioned methods you can define a friendly name, a description, the exact position expressed in milliseconds, the colors used for being drawn and some more specific parameter.

All of the methods mentioned above return a unique identification number that will be used by other methods to access settings of each graphic item at a later time; for example you may want to:

· obtain or change the friendly name through the WaveformAnalyzer.GraphicItemNameGet and WaveformAnalyzer.GraphicItemNameSet methods
· obtain or change the item's description through the WaveformAnalyzer.GraphicItemDescriptionGet and WaveformAnalyzer.GraphicItemDescriptionSet methods
· obtain or change the current position through the WaveformAnalyzer.GraphicItemHorzPositionGet and WaveformAnalyzer.GraphicItemHorzPositionSet methods
· hide or show items the visibility through the WaveformAnalyzer.GraphicItemShow method or through the WaveformAnalyzer.GraphicItemsTypeShow method
· remove items from the list of graphic items through the WaveformAnalyzer.GraphicItemRemove method or through the WaveformAnalyzer.GraphicItemsTypeRemove method

All of the graphic items added to the waveform analyzer can be saved into a disk file for later use through the WaveformAnalyzer.GraphicItemsSave and reloaded when needed through the WaveformAnalyzer.GraphicItemsLoad method.

Enumerating graphic items of a given type added to the waveform analyzer can be done using the WaveformAnalyzer.GraphicItemsTypeCountGet method, the unique identification number of each graphic item can be obtained through the WaveformAnalyzer.GraphicItemUniqueIdGet method; when knowing only the unique identification number, the respective type can be obtained through the WaveformAnalyzer.GraphicItemTypeGet method.

Graphic items can be rendered with other "buddy" elements that may help giving a more specific visual meaning to each item:

· Buddy pictures through the WaveformAnalyzer.GraphicItemBuddyPictureSetFromFile, WaveformAnalyzer.GraphicItemBuddyPictureSetFromHandle or WaveformAnalyzer.GraphicItemBuddyPictureSetFromMemory methods; the screenshot below shows a waveform containing a short conversation between two employees: with vertical lines and a couple of buddy pictures it's very immediate understanding the position where a specific employee starts speaking:

· Buddy texts through the WaveformAnalyzer.GraphicItemBuddyTextSet; the screenshot below shows the same conversation with buddy texts in place of buddy pictures:

Each type of graphic item implements further methods for acting on their settings and may generate specific events; let's see them in detail:

· Vertical lines

Settings specific to vertical lines can be obtained through the WaveformAnalyzer.GraphicItemVerticalLineParamsGet method and modified through the WaveformAnalyzer.GraphicItemVerticalLineParamsSet method.

Vertical lines can be manually moved through the mouse; this action will cause the component invoking the CallbackWaveformAnalyzerLineMoved delegate: you could receive many of these calls in order to be up to date with the current line position; this event is also generated when the line position is modified through the WaveformAnalyzer.GraphicItemHorzPositionSet method.

During playback you can be notified that the position of a vertical line has been reached through the CallbackWaveformAnalyzerLineReached delegate.

· Horizontal lines

Settings specific to horizontal lines can be obtained through the WaveformAnalyzer.GraphicItemHorizontalLineParamsGet method and modified through the WaveformAnalyzer.GraphicItemVerticalLineParamsSet method.

Horizontal lines can be manually moved through the mouse; this action will cause the component invoking the CallbackWaveformAnalyzerHorzLineMoved delegate: you could receive many of these calls in order to be up to date with the current line position; this event is also generated when the line position is modified through the WaveformAnalyzer.GraphicItemHorzPositionSet and WaveformAnalyzer.GraphicItemVertPositionSet methods.

During playback you can be notified that the start position of a horizontal line has been reached through the CallbackWaveformAnalyzerHorzLineReached delegate and that the end position of the line has been leaved through the CallbackWaveformAnalyzerHorzLineLeaved delegate.

· Wave ranges

Settings specific to horizontal lines can be obtained through the WaveformAnalyzer.GraphicItemWaveRangeParamsGet method and modified through the WaveformAnalyzer.GraphicItemWaveRangeParamsSet method.

During playback you can be notified that the start position of a wave range has been reached through the CallbackWaveformAnalyzerWaveRangeReached delegate and that the end position of the wave range has been leaved through the CallbackWaveformAnalyzerWaveRangeLeaved delegate.

· Buddy pictures

Settings specific to buddy pictures can be obtained through the WaveformAnalyzer.GraphicItemBuddyPictureParamsGet method and modified through the WaveformAnalyzer.GraphicItemBuddyPictureParamsSet method.

A memory copy of the buddy picture, accessible through a HBITMAP, can be obtained through the WaveformAnalyzer.GraphicItemBuddyPictureGet method.

· Buddy texts

Settings specific to buddy texts can be obtained through the WaveformAnalyzer.GraphicItemBuddyTextParamsGet method and modified through the WaveformAnalyzer.GraphicItemBuddyTextParamsSet method.

The current text string and the font used to render it on the screen can be retrieved through the WaveformAnalyzer.GraphicItemBuddyTextGet method.

Samples of usage of graphic items applied to the waveform analyzer in Visual C# and Visual Basic.NET can be found inside the following samples installed with the product's setup package:

- WaveformAnalyzerConfig


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 Sound Recorder 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 having performed a recording session, we need to analyze the sound's waveform through the WaveformAnalyzer object so we need to perform a call to the WaveformAnalyzer.AnalyzeFullSound method. The analysis can be more or less accurate depending upon the resolution passed to the nResolution parameter of the WANALYZER_GENERAL_SETTINGS class; higher resolutions will allow a better quality because more peaks will be detected: as a side effect, higher resolutions will require more memory; further details about sound's waveform analysis can be found inside the How to use the Waveform Analyzer tutorial.

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 RecordedSound.Play method or in case the current playback position should be moved through the RecordedSound.SeekPlayPosition method, the waveform scroller would automatically update the waveform view to keep the current position updated.

The waveform scroller can also display eventual graphic items previously added to the waveform analyzer through one of the following methods:

· WaveformAnalyzer.GraphicItemVerticalLineAdd method for vertical lines
· WaveformAnalyzer.GraphicItemHorizontalLineAdd method for horizontal lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd method for wave ranges

You are free to decide which type of these graphic items you want to display, for example you could need displaying wave ranges only and omitting the rendering of vertical and horizontal lines; this behaviour can be set through the nGraphicItemsMask field of the WSCROLLER_SETTINGS data structure.

For further details about graphic items management you can refer to the How to add graphic items to the Waveform analyzer tutorial.

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 informed about the new position through the CallbackWaveformScrollerManualScroll delegate set through the CallbackWaveformScrollerManualScrollSet method. 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 set through the CallbackWaveformScrollerMouseNotifSet method.

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 WaveformAnalyzerConfig sample.


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 input 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 Sound Recorder 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.

Both internal and external custom DSP effects can be discarded from memory using the CustomDSP.Free method.

In order to have a better understanding about the use and implementation of custom DSP effects, you will find some sample of usage of these internal and external DSP effects inside the CustomDSP and CustomDSPWithUI samples installed by the product's setup package. You will also find two projects, written in Visual C++ 6, that demonstrate the implementation of two external custom DSP effects, one containing an editor (named MyCustomDspWithUI) that will implement a simple "Bass Boost" effect and one without any editor (named MyCustomDsp) that will implement two different effects: a simple "Reverb" effect and a simple "Balance" effect.


How the Sound Activation System works

How the Sound Activation System works

The Sound Activation System allows skipping silent passages during a recording session: the sound activation system can be enabled or disabled through the nMode parameter of the SoundActivationSystemSet method. Current settings can be obtained through the SoundActivationSystemGet method.

When the Sound Activation System is enabled, the control will automatically recognize silent data during the recording session and will not store data inside the output file or in memory: the threshold that discriminates silent data from audible data is set through the nSilenceThreshold parameter and the minimal length the silent portions must have in order to be considered real silence can be set through the nSilenceMinLength parameter.

The use of Sound Activation System is especially useful in the following situations:

· when the control is recording streaming data from the Internet and a net congestion stops the stream, allowing to avoid having spots without audible sound on the final output.
· when you must optimize the memory or disk consumption during silent periods.
· when you are monitoring an input channel for audible data (for example a microphone) and have no need to record silent periods: in this case the control has the optional ability to automatically create a log file that will report the exact recording time and silence skipping time: all you have to do is to set the strLogFile parameter of the SoundActivationSystemSet method to a valid absolute pathname. This log file will have a format as shown below:

[Recording start]  1/17/2006 14:19:22 {453463328}

[Silence start]    1/17/2006 14:19:22 {453463437}

[Silence end]      1/17/2006 14:19:25 {453466437}

[Silence start]    1/17/2006 14:19:26 {453467031}

[Silence end]      1/17/2006 14:19:31 {453472031}

[Silence start]    1/17/2006 14:19:31 {453472140}

[Silence end]      1/17/2006 14:19:38 {453479234}

[Silence start]    1/17/2006 14:19:38 {453479343}

[Silence end]      1/17/2006 14:19:39 {453479843}

[Silence start]    1/17/2006 14:19:39 {453480437}

[Silence end]      1/17/2006 14:19:50 {453490843}

[Silence start]    1/17/2006 14:19:50 {453491531}

[Silence end]      1/17/2006 14:19:59 {453500140}

[Silence start]    1/17/2006 14:20:00 {453501031}

[Silence end]      1/17/2006 14:20:03 {453504531}

[Recording end]    1/17/2006 14:20:04 {453504640}

The structure of the file should be quite self-explanatory: on each line the log file logs the exact date and time of recording start ([Recording start]) and recording end ([Recording end]) and all the transitions from silent data ([Silence start]) to audible data ([Silence end]) and between {} characters reports the exact number of milliseconds returned by a call to the GetTickCount Windows API: as you may know, the GetTickCount function retrieves the number of milliseconds that have elapsed since the system was started.

When the Sound Activation System is enabled and the recording session finds silent data, the container application is notified CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_SILENT_DATA; when the recording session finds again audible data, the container application is notified through the same delegate having the nEvent parameter set to EV_REC_AUDIBLE_DATA.

As a further feature, the Sound Activation System can be set to report silent portions of sound through the mentioned events without really discarding silence from the recorded sound: this can be achieved by setting the nMode parameter of the SoundActivationSystemSet method to SOUND_ACTIVATION_SYSTEM_KEEP_SILENCE.

IMPORTANT: When using the Sound Activation System is highly recommended storing recorded sound data on a file instead of a memory buffer.

The Sound Activation System is also supported when recording from sound files through the StartFromFile method: in this specific case the nMode parameter of the SoundActivationSystemSet method must be set to SOUND_ACTIVATION_SYSTEM_DISCARD_SILENCE; it's important to note that, when recording from sound files, the log is not generated.


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 two ways to obtain information about an Audio CD:

· If a CD audio is physically available inside the CD drive: through 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 CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_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 CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_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 CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to:

· EV_REC_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_REC_CD_COVER_SMALL_FILE_AVAIL, EV_REC_CD_COVER_MEDIUM_FILE_AVAIL and EV_REC_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.

· If a CD audio is NOT physically available inside the CD drive: searching the Amazon catalogue through Amazon Web Services.

Differently from the method described above, where the artist name and the album title are obtained through a FreeDB server, the control can search information about an Audio CD inside the Amazon catalogue through the CdRequestAlbumInfo method: when requested information become available, the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to:

· EV_REC_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_REC_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_REC_D_COVER_SMALL_FILE_AVAIL, EV_REC_CD_COVER_MEDIUM_FILE_AVAIL and EV_REC_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.


How to get pictures of CD covers

Copyright © 2006-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 use the Windows Audio Compression Manager

How to use the Windows Audio Compression Manager

The Windows Audio Compression Manager (MSACM32.DLL) allows an application to convert data between different formats. By itself, the ACM is not capable of performing any conversions. Instead, it relies on installable drivers to perform specific conversions. These drivers are called codecs, converters, or filters (sometimes the term codec is used in a more generic sense, to refer to all three types of ACM drivers).

A codec converts from one format to another; for example, from PCM to MS-ADPCM. A converter converts between different types of the same format; for example, between 8 and 16 bit PCM, between mono and stereo, and between different PCM sampling frequencies. A filter modifies the audio data without changing the format; for example, an echo filter might make a 44,100 Hz PCM wave file sound different, but it would still be a 44,100 Hz PCM file.

There are several ACM drivers that are automatically installed with the Windows system (other ACM drivers can be installed at any time). There are drivers that provide support for the compressed formats MS-ADPCM, IMA ADPCM, the GSM 6.10 standard, the TrueSpeech voice and the MPEG Layer-3 coding format.

The first thing to do in order to take advantage of Audio Compression Manager features, is to set the ACM encoding format as follow:

· if you need to perform a recording session set the EncodeFormats.ForRecording property to ENCODING_FORMAT_ACM
· if you need to perform a CD ripping session set the EncodeFormats.ForCdRipping property to ENCODING_FORMAT_ACM
· if you need to perform an exporting session set the EncodeFormats.ForExporting property to ENCODING_FORMAT_ACM

after this first setting you can proceed with ACM codecs, using properties and methods exposed by the EncodeFormats.ACM property, in one between the following 2 ways:

· Enumerating the installed codecs and choosing a certain codec and codec format

This approach can be predisposed setting the EncodeFormats.ACM.EncodeMode property to ACM_ENCODE_USE_CODEC_INDEX

Then you need to enumerate codecs installed inside the target PC through a call to its EncodeFormats.ACM.InitCodecs method.

At this point you can obtain the total number of supported codecs through a call to the EncodeFormats.ACM.GetCodecsCount method: for each codec you can obtain the friendly name through the EncodeFormats.ACM.GetCodecDesc method. These two methods will allow filling a combobox as seen on the screenshot below:

Finally you can enumerate the formats supported by the codec chosen above; the total number of supported formats can be obtained through a call to the EncodeFormats.ACM.GetCodecFormatsCount method: for each of the available formats you can obtain the friendly description through the EncodeFormats.ACM.GetCodecFormatDesc method. Also in this case, these two methods will allow filling a combobox as seen on the screenshot below:

· Filling a WAVEFORMATEX data structure with information specific for a certain codec and codec format

As you may know, each codec's format is described through a WAVEFORMATEX data structure: the WAVEFORMATEX structure, common to all waveform-audio formats, is defined inside the Microsoft SDK as follows:

typedef struct {

 WORD  wFormatTag;

 WORD  nChannels;

 DWORD nSamplesPerSec;

 DWORD nAvgBytesPerSec;

 WORD  nBlockAlign;

 WORD  wBitsPerSample;

 WORD  cbSize;

} WAVEFORMATEX;

The cbSize parameter defines how many extra-bytes, specific for a certain codec, are appended to the end of the WAVEFORMATEX structure

In certain situations, for example if your application doesn't allow a user interaction for selecting from a combobox the codec and the respective format, you may require the possibility to fill a WAVEFORMATEX structure and to pass it directly to the EncodeACM class: in this case you can start setting the EncodeFormats.ACM.EncodeMode property to ACM_ENCODE_USE_WAV_FORMAT.

Once predisposed, the WAVEFORMATEX structure can be set into the control through a call to the EncodeFormats.ACM.SetCodecFormatWavData method.

It's important to note that further encoding through the format defined inside the WAVEFORMATEX structure will not work if the specific codec is not installed on the target PC.

Just for your information, if you have already enumerated the available codecs and respective formats, as seen inside the previous point, the total size in bytes of the WAVEFORMATEX data structure that describes a given format, including any extra-byte the specific format may require, can be obtained using the EncodeFormats.ACM.GetCodecFormatWavDataLength method. The returned size of the WAVEFORMATEX data structure, expressed in bytes, can be used to allocate a buffer that will be filled by a call to the EncodeFormats.ACM.GetCodecFormatWavData method.

Once chosen one between the ways above, you can start the needed recording, CD ripping or exporting session using one of the provided methods, such as StartFromDirectSoundDevice, CdRippingStart or RecordedSound.RequestExportToFile.

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

- AudioCompressionManager

- CdRipperWithACM

- InsertRecAtPos

- RecordedSoundEditor

- RewindRecPos

- SimpleRecorder


How to use the automatic gain controller

How to use the automatic gain controller

Audio level varies greatly among different input channels; for example certain Microphones, attached to low-priced sound cards, will result in a very low level audio signal if the user on the system is not speaking close enough to the microphone: for this purpose Audio Sound Recorder API for .NET comes with an embedded Automatic Gain Controller (aka AGC) which allows a good quality signal without saturating and/or cause distortions and other problems, even if the signal to be recorded varies in level.

The AGC keeps the receiver in its linear operating range by measuring the overall strength of the signal and automatically adjusting the gain of the receiver to maintain a constant level of output. When the signal is strong, the gain is reduced, and when weak, the gain is increased, or allowed to reach its normal maximum.

The AGC can be enabled/disabled through the EnableAutoGainController method: its settings can be retrieved using the GetAutoGainControllerSettings method and modified through the SetAutoGainControllerSettings.

A sample of use of the Automatic Gain Controller in Visual C#.NET and Visual Basic.NET can be found inside the AutomaticGainController sample installed with the product's setup package:


How to apply embedded filters

How to apply embedded filters

Audio Sound Recorder API for .NET allows applying different kinds of IIR (Infinite Impulse Response) and FIR filters (Finite Impulse Response) , like Low-Pass, High-Pass, Band-Pass and Stop-Band, in two situations:

· during a recording session by invoking the FilterApply method: in this case the filter is applied directly to the incoming audio data before being encoded and stored into the output audio file or memory buffer. The filter can be disabled at any time through the FilterReset method and its parameters can be modified by invoking the FilterParametersSet method.
· after the recording session is completed and finalized by invoking the RecordedSound.FilterApply method

Samples of usage of filters can be found inside the following samples installed with the product's setup package:

- Filters


How to perform custom feedbacks rendering using graphic bars

How to perform custom feedbacks rendering using graphic bars

Audio Sound Recorder 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 control, graphic bars have a range, defined through the GraphicBarsManager.GetRange and GraphicBarsManager.SetRange methods, and a value defined through the GraphicBarsManager.GetValue and GraphicBarsManager.SetValue methods.

Graphical settings related to a specific graphic bar can be retrieved and modified through the GraphicBarsManager.GetGraphicalSettings and GraphicBarsManager.SetGraphicalSettings methods: both of them receive in input a GRAPHIC_BAR_SETTINGS data structure which can manage the following settings:

· Orientation through the nOrientation member. This is quite important because .NET doesn't come with a native vertical progress bar. On the picture below you can see some sample of both vertical and horizontal graphic bars.

· Colors through the colorStart, colorEnd and colorBackground members: 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 member.

· Smoothing through the bSmoothing member; graphic bars can be led-based but they can also appear smoothed as seen on the images below:

· Automatic drop through the bAutomaticDrop member; 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 member; 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 through the CallbackVuMeterValueChange delegate 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 CallbackVuMeterValueChange delegate has been invoked, 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

- RecordedSoundEditor

- SimpleMp3Recorder


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 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 StartFromZipFile and the StartSplitFromZipFile methods can extract and automatically load the sound file from the ZIP.

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; if a recoding session should be available, you may add it to the opened ZIP file trough the RecordedSound.AddToZip method directly.

During lengthy operations for both compression and decompression, the container application is notified through the CallbackZipOperationPerc delegate which reports the current percentage of advancement.

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:

- RecorderWmaProfiles

- SimpleMp3Rec

- RecordedSoundEditor


How to access BASS library functionalities directly

How to access BASS library functionalities directly

For some of its many features, Audio Sound Recorder 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 and BASS_ChannelGetLevel functions 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 statements:

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 and BASS_ChannelGetLevel functions 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

<UnmanagedFunctionPointer(CallingConvention.Cdecl)> _

Private Delegate Function funcBASS_ChannelGetLevel(ByVal handle As Int32) As Int32

Private BASS_ChannelSetAttribute As funcBASS_ChannelSetAttribute

Private BASS_ChannelGetLevel As funcBASS_ChannelGetLevel

Visual C#

[UnmanagedFunctionPointer(CallingConvention.Cdecl)]

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

[UnmanagedFunctionPointer(CallingConvention.Cdecl)]

private delegate Int32 funcBASS_ChannelGetLevel(Int32 handle);

funcBASS_ChannelSetAttribute BASS_ChannelSetAttribute;

funcBASS_ChannelGetLevel BASS_ChannelGetLevel;

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 LoadBassFunctions()

Dim hModule As Int32 = 0

audioSoundRecorder1.BassModuleGet(enumBassModules.MODULE_BASS, hModule)

BASS_ChannelSetAttribute = CType(Marshal.GetDelegateForFunctionPointer( _

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

GetType(funcBASS_ChannelSetAttribute)), funcBASS_ChannelSetAttribute)

BASS_ChannelGetLevel = CType(Marshal.GetDelegateForFunctionPointer( _

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

GetType(funcBASS_ChannelGetLevel)), funcBASS_ChannelGetLevel)

End Sub

Visual C#

private void LoadBassFunctions()

{

Int32 hModule = 0;

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

BASS_ChannelSetAttribute = (funcBASS_ChannelSetAttribute) Marshal.GetDelegateForFunctionPointer(

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

typeof(funcBASS_ChannelSetAttribute));

BASS_ChannelGetLevel = (funcBASS_ChannelGetLevel)Marshal.GetDelegateForFunctionPointer(

GetProcAddress((IntPtr)hModule, "BASS_ChannelGetLevel"),

typeof(funcBASS_ChannelGetLevel));

}

That's all: we can now call the BASS function directly from our code: if for example we should need to lower a playback 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 hStreamPlay As Int32 = 0

audioSoundRecorder1.BassStreamGet(false, hStreamPlay)

BASS_ChannelSetAttribute(hStreamPlay, BASS_ATTRIB_VOL, 0.5f)

End Sub

Visual C#

private void button1_Click(object sender, EventArgs e)

{

Int32        hStreamPlay = 0;

audioSoundRecorder1.BassStreamGet(false, ref hStreamPlay);

BASS_ChannelSetAttribute(hStreamPlay, BASS_ATTRIB_VOL, 0.5f);

}

or if we should need to get the volume level of a recording stream we could do the following:

Visual Basic .NET

Dim hStreamRec As Int32 = 0

audioSoundRecorder1.BassStreamGet(True, hStreamRec)

Dim dwLevel As Int32 = BASS_ChannelGetLevel (hStreamRec)

Dim wLeft As Int16 = CShort(Fix(dwLevel))

Dim wRight As Int16 = CShort(Fix(dwLevel >> 16))

Visual C#

Int32 hStreamRec = 0;

audioSoundRecorder1.BassStreamGet(true, ref hStreamRec);

Int32 dwLevel = BASS_ChannelGetLevel (hStreamRec);

Int16 wLeft = (Int16)dwLevel;

Int16 wRight = (Int16)(dwLevel >> 16);

This brings another interesting point: on the first code snippets above we are acting on a playback stream, identified by the hStreamPlay variable and on the second code snippet we are acting on a recording stream, identified by the hStreamRec variable: how can we obtain those streams? This is quite simple: In case you should need to have direct access to the handle (HSTREAM or HRECORD) of a playback or recording stream created through BASS, you could use the BassStreamGet method.

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 and recording streams of type HSTREAM and HRECORD: 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 HSTREAM and HRECORD streams with these plugins.

As mentioned before, Audio Sound Recorder 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 developers belonging to the BASS community deliver new plugins for supporting other audio formats; also if not directly embedded inside the component, functions exported by the plugin for creating the 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 the StartFromFile, StartFromMemory or StartFromURL methods 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 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 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 property
enumRecorderStates | Status property
enumVuBandsMode | VUMeter.BandType property
enumOscillType | Oscilloscope.Type property
enumWaveformRes | Waveform.Resolution property
enumCdActions | nAction parameter of the PerformActionOnCd method
enumCdStates | return value of GetCdStatus method
enumCdIdCodes | nIdentType parameter of the GetCdIdentification method
enumCddbAlbumInfo | nInfo parameter of the CddbGetAlbumInfo method
enumCdCoverSizes | nCoverSize parameter of the GetCdCoverPictureURL, GetCdCoverPictureFile methods
enumEncodingFormats | EncodeFormats.ForRecording, EncodeFormats.ForCdRipping and EncodeFormats.ForExporting properties
enumResampleModes | EncodeFormats.ResampleMode property
enumWmaEncodeModes | EncodeFormats.WMA.EncodeMode property and nEncodeMode parameter of the EncodeFormats.WMA.GetEncodingProfileInfo, EncodeFormats.WMA.GetEncodingCBRCount, EncodeFormats.WMA.GetEncodingCBR, EncodeFormats.WMA.GetEncodingProfileProCount and EncodeFormats.WMA.GetEncodingProfileProInfo methods.
enumMp2EncodeModes | EncodeFormats.MP2.EncodeMode property
enumMp3EncodeModes | EncodeFormats.MP3.EncodeMode property
enumMp3EncodePresets | EncodeFormats.MP3.Preset property
enumOggEncodeModes | EncodeFormats.OGG.EncodeMode property
enumAacEncodeModes | EncodeFormats.AAC.EncodeMode property
enumWavEncodeModes | EncodeFormats.WAV.EncodeMode property
enumAcmEncodeModes | EncodeFormats.ACM.EncodeMode property
enumW64EncodeModes | EncodeFormats.W64.EncodeMode property
enumAIFFEncodeModes | EncodeFormats.AIFF.EncodeMode property
enumAUEncodeModes | EncodeFormats.AU.EncodeMode property
enumPAFEncodeModes | EncodeFormats.PAF.EncodeMode property
enumSVXEncodeModes | EncodeFormats.SVX.EncodeMode property
enumNISTEncodeModes | EncodeFormats.NIST.EncodeMode property
enumVOCEncodeModes | EncodeFormats.VOC.EncodeMode property
enumIRCAMEncodeModes | EncodeFormats.IRCAM.EncodeMode property
enumPVFEncodeModes | EncodeFormats.PVF.EncodeMode property
enumCAFEncodeModes | EncodeFormats.CAF.EncodeMode property
enumFLACEncodeModes | EncodeFormats.FLAC.EncodeMode property
enumRAWEncodeModes | EncodeFormats.RAW.EncodeMode property and nEncodeMode parameter of the StartFromFileRaw, StartFromMemoryRaw and StartFromQueueRaw methods
enumRecordingModes | nMode parameter of the SetRecordingMode method
enumScaleUnits | nScaleUnits parameter of the RecordedSound.SeekPlayPosition and CdRippingSetRange methods
enumWaveformTypes | nWaveformType parameter of the WaveformAnalyzer.GetMinMaxPeakLevelsForRange method
enumTrackerCursorModes | nCursorMode parameter of the WaveformAnalyzer.SetTrackerCursors method
enumGraphicBarOrientations | nOrientation member of the GRAPHIC_BAR_SETTINGS class
enumGraphicBarShapes | nShape member of the GRAPHIC_BAR_SETTINGS class
enumAnalyzerResolutions | nResolution field of the WANALYZER_GENERAL_SETTINGS data structure
enumWaveformStereoModes | nStereoVisualizationMode field of the WANALYZER_WAVEFORM_SETTINGS and WSCROLLER_SETTINGS data structures
enumBitmapModes | nWaveformType parameter of the WaveformAnalyzer.SetBackPictureFromFile and WaveformAnalyzer.SetBackPictureFromHandle methods
enumVolumeScales | nScaleType parameter of the ASIO.DeviceChannelVolumeGet, ASIO.DeviceChannelVolumeSet, ASIO.DeviceMasterVolumeGet and ASIO.DeviceMasterVolumeSet, OutputVolumeSet and OutputVolumeGet methods and nAmplitudeScale field of the WANALYZER_RULERS_SETTINGS data structure
enumAsioChannelModes | nChannelMode parameter of the ASIO.DeviceStart method
enumDriverTypes | nDriverType parameter of the InitDriversType method and return value of the GetInputDeviceDriverType method
enumWaveAnalyzerRectangles | nIdRectangle parameter of the WaveformAnalyzer.GetRectangle method
enumInputChannelTypes | Return value of the GetInputDeviceChannelType method
enumVolumeScales | nScaleType parameter of the OutputVolumeSet and OutputVolumeGet methods.
enumGraphicFormats | nFormat parameter of the WaveformAnalyzer.SnapshotViewSaveToFile
enumPlaybackStatus | Return value of the GetPlaybackStatus 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
enumWasapiDeviceTypes | nDeviceType parameter of the 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
enumHorizontalLineHeadlineType | nHeadlineType parameter of the WaveformAnalyzer.GraphicItemHorizontalLineAdd and WaveformAnalyzer.GraphicItemHorizontalLineParamsSet methods
enumHorizontalLineChannel | nChannel parameter of the WaveformAnalyzer.GraphicItemHorizontalLineAdd, WaveformAnalyzer.GraphicItemHorizontalLineParamsSet methods and nChannel field of the WANALYZER_HORIZONTAL_LINE data structure
enumGraphicItemType | nType parameter of the WaveformAnalyzer.GraphicItemTypeGet, WaveformAnalyzer.GraphicItemsTypeShow and WaveformAnalyzer.GraphicItemUniqueIdGet methods
enumGraphicItemMaskValues | nGraphicItemsMask parameter of the WaveformAnalyzer.GraphicItemsMouseMoveEnable and WaveformAnalyzer.SnapshotViewGraphicItemsMaskSet methods and nGraphicItemsMask field of the WANALYZER_SCROLLBARS_SETTINGS and WSCROLLER_SETTINGS data structures
enumWaveformLineDashStyles | Some field of the WANALYZER_GENERAL_SETTINGS, WANALYZER_VERTICAL_LINE, WANALYZER_HORIZONTAL_LINE and WSCROLLER_SETTINGS data structures
enumLineCaps | Some field of the WANALYZER_GENERAL_SETTINGS, WANALYZER_VERTICAL_LINE, WANALYZER_HORIZONTAL_LINE and WSCROLLER_SETTINGS data structures
enumLineDashCaps | Some field of the WANALYZER_GENERAL_SETTINGS, WANALYZER_VERTICAL_LINE, WANALYZER_HORIZONTAL_LINE and WSCROLLER_SETTINGS data structures
enumBuddyAlignment | nAlignment field of the WANALYZER_BUDDY_PICTURE and WANALYZER_BUDDY_TEXT data structures
enumWaveformSelectionMode | nSelectionMode field of the WANALYZER_WAVEFORM_SETTINGS data structure
enumTranspGlassType | nTransparentGlassType field of the WANALYZER_WAVEFORM_SETTINGS and WANALYZER_SCROLLBARS_SETTINGS data structures
enumWaveScrollbarType | nType field of the WANALYZER_SCROLLBARS_SETTINGS data structure
enumScrollbarWaveVisibleRangeType | nVisibleRangeType field of the WANALYZER_SCROLLBARS_SETTINGS data structure
enumWaveScrollerAutoUpdate | nUpdateSpeed field of the WSCROLLER_SETTINGS data structure
enumAsioRecordMonoToStereoMode | nMonoChanToStereoOutMode parameter of the ASIO.DeviceRecordParamsGet and ASIO.DeviceRecordParamsSet methods
enumCommonDialogInfo | nInfo parameter of the CommonDialogGetInfoFromLastOpen and CommonDialogGetInfoFromLastSave methods
enumWaveSnapshotViewMode | nMode parameter of the WaveformAnalyzer.SnapshotViewSaveToFile, WaveformAnalyzer.SnapshotViewSaveToMemory , and WaveformAnalyzer.SnapshotViewDrawToHdc methods
enumWaveformChannels | nChannel parameter of the WaveformAnalyzer.SnapshotViewSaveToFile, WaveformAnalyzer.SnapshotViewSaveToMemory , and WaveformAnalyzer.SnapshotViewDrawToHdc methods
enumWaveAnalyzerViewModes | nMode parameter of the WaveformAnalyzer.ViewModeSet and WaveformAnalyzer.ViewModeGet methods
enumFilterNames | nFilterName parameter of the FilterApply, FilterParametersSet, FilterParametersGet and RecordedSound.FilterApply methods
enumFilterTypes | nFilterType parameter of the FilterApply, FilterParametersSet, FilterParametersGet and RecordedSound.FilterApply methods
enumZipEncryptionTypes | nEncryptionType parameter of the ZIP.Create method
enumAacPlusEncodeModes | EncodeFormats.AACPlus.EncodeMode property

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 AudioSoundRecorder1, exists on a form. The purpose of this sample code is to check if the recorder is currently ripping a CD track.

Microsoft Visual Basic.NET

Microsoft Visual C#.NET

Microsoft Visual Basic.NET

After typing the code

If AudioSoundRecorder1.Status

press the "=" key on your keyboard. IntelliSense displays the listbox of the possible values that can be assigned to the method parameter.

Select the AudioSoundRecorder.enumRecorderStates.RECORD_STATUS_CD_RIPPING value so the complete line of code will be:

If AudioSoundRecorder1.Status = AudioSoundRecorder.enumRecorderStates.RECORD_STATUS_CD_RIPPING

 ' 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 AudioSoundRecorder;

After typing the code...

if (audioSoundRecorder1.Status == enumRecorderStates

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

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

if (audioSoundRecorder1.Status == enumRecorderStates.RECORD_STATUS_CD_RIPPING)

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


CddbAddTagOnCdRipping property

CddbAddTagOnCdRipping property

Type

[Visual Basic]

Public Property CddbAddTagOnCdRipping As Boolean

[C#]

public bool CddbAddTagOnCdRipping {get; set;}

[C++]

public: __property bool get_CddbAddTagOnCdRipping();

public: __property void set_CddbAddTagOnCdRipping(bool);

Remarks

Boolean value that enables/disables adding the song's information, taken from a remote CDDB server, into a tag on the output song file created by a CD ripping session. Tags are supported for the following formats:

- MP3 (both id3v1 and id3v2 are inserted)

- WMA

- OGG Vorbis

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
False (default) | 0 | No tag will be added to the output song file.
True | 1 | A tag containing song's information will be added to the output song file.


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.


CustomDSP property (RO)

CustomDSP 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 for managing custom DSP effects.

This property encapsulates the functionality of the CustomDSP class.

For further details about managing custom DSP effects refer to the How to manage custom DSP effects section.


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 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 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 embedded Visual Feedbacks 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 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 embedded Visual Feedbacks section


DisplayWaveformAnalyzer property (RO)

DisplayWaveformAnalyzer property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property DisplayWaveformAnalyzer As WaveformAnalyzer

[C#]

public WaveformAnalyzer DisplayWaveformAnalyzer {get;}

[C++]

public: __property WaveformAnalyzer* get_DisplayWaveformAnalyzer ();

This property is Read-only

Remarks

The Waveform Analyzer object.

This property encapsulates the functionality of the WaveformAnalyzer class.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer 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.


EncodeFormats property (RO)

EncodeFormats property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property EncodeFormats As EncodeFormatsMan

[C#]

public EncodeFormatsMan EncodeFormats {get;}

[C++]

public: __property EncodeFormatsMan* get_EncodeFormats ();

This property is Read-only

Remarks

The object used to take advantage of encoding and resampling capabilities exposed by the control.

This property encapsulates the functionality of the EncodeFormatsMan class.


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 are not related directly to Audio Sound Recorder):

Mnemonic value | Numeric value | Meaning
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


RecordedSound property (RO)

RecordedSound property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property RecordedSound As RecordedSoundMan

[C#]

public RecordedSoundMan RecordedSound {get;}

[C++]

public: __property RecordedSoundMan* get_RecordedSound ();

This property is Read-only

Remarks

The RecordedSound object.

This property encapsulates the functionality of the RecordedSound class.


Status property (RO)

Status property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property Status As enumRecorderStates

[C#]

public enumRecorderStates Status {get;}

[C++]

public: __property enumRecorderStates get_Status();

This property is Read-only

Remarks

Contains the recording status of the control.

Supported values are the following:

Mnemonic Value | Value | Meaning
RECORD_STATUS_NOT_READY | -1 | The recorder is still not ready
RECORD_STATUS_READY | 0 | The recorder is ready. When recorder status is ready, it will be possible enumerating native input formats through the following methods: GetWmaEncodingBitratesCount GetWmaEncodingBitrate GetSupportedRecordFormatsCount GetSupportedRecordFormatDesc GetWmaEncodingVBRQualitiesCount GetWmaEncodingVBRQuality
RECORD_STATUS_RECORDING | 1 | The recorder is recording sound from an input device
RECORD_STATUS_SILENT | 2 | The recorder is recording sound but at the moment is receiving silent data that will be discarded. For further details see the How the Sound Activation System works section.
RECORD_STATUS_CD_RIPPING | 3 | The recorder is ripping a CD audio track
RECORD_STATUS_PAUSED | 4 | The recorder is paused
RECORD_STATUS_PLAYING | 5 | The recorder is playing back the latest recording session
RECORD_STATUS_PLAYING_PAUSED | 6 | The recorder is in paused state during the playback of the latest recording session
RECORD_STATUS_RECORDING_URL | 7 | The recorder is recording sound from an Internet URL
RECORD_STATUS_RECORDING_FILE | 8 | The recorder is recording sound from a file stored on the hard disk
RECORD_STATUS_RECORDING_MEMORY | 9 | The recorder is recording sound from a memory buffer
RECORD_STATUS_RECORDING_CLIPBOARD | 10 | The recorder is recording sound from the system clipboard


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 (

);


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 InitRecordingSystem 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 recording or playback stream created through BASS after starting a recording or playback session, 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.ERR_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.ERR_NOERROR (0 | The method call was successful.


BassStreamGet method

BassStreamGet method

Remarks

Obtains the handle to the recording stream (HRECORD) or to the playback stream (HSTREAM) created by BASS after starting a recording or playback session,

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 (

bRecordingStream as Boolean,

ByRef hStream as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes BassStreamGet (

bool bRecordingStream,

ref Int32 hStream

);

[C++]

public: enumErrorCodes BassStreamGet (

bool bRecordingStream,

Int32 __gc *hStream

);

Parameter

Description

bRecordingStream

Boolean value that specify if the handle to obtain is referred to a recording stream (HRECORD) or to a playback stream (HSTREAM).

Supported values are the following:

Mnemonic constant | Meaning
false | The requested handle is related to the.playback stream (HSTREAM)
true | The requested handle is related to the.recording stream (HRECORD)

hStream

Reference that, on return from the method call, will contain the handle to the requested stream.

This handle is valid only during the recording session or during the playback session.

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.


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 InitRecordingSystem 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 (

);


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 (

);


EnableSoundPreloadForPlayback method

EnableSoundPreloadForPlayback method

Remarks

Prepares the loaded sound for a playback session where the usage of a scrolling waveform may be needed.

In order to optimize system resources, when pre-loading is disabled (default situation), the stream to play is only loaded when specifically requested through a call to the RecordedSound.Play or RecordedSound.PlayRange methods and automatically discarded from memory after a call to the RecordedSound.Stop method or when the end of the song is reached. In this situation it's not possible to visually set an initial position through a scrolling waveform until the loaded sound is not in playback. By enabling pre-load through this method, the sound stream is immediately available in memory after a recording or editing session so could set an initial position for playback directly into a scrolling waveform as seen inside the WaveformAnalyzerConfig sample.

As a further feature, when pre-load is enabled there is the possibility to distinguish if the sound playback is stopped through the GetPlaybackStatus method..

For details about creating a scrolling waveform, refer to the section "Mode 3: Rendering on a graphic Device Context (HDC)" of the How to use the Waveform Analyzer tutorial.

Syntax

[Visual Basic]

Public Function EnableSoundPreloadForPlayback (

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EnableSoundPreloadForPlayback (

bool bEnable

);

[C++]

public: enumErrorCodes EnableSoundPreloadForPlayback (

bool bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if the control must enable pre-loading of the sound stream to play.

Supported values are the following:

Value | Meaning
false (default) | Disable pre-load
true | Enable pre-load

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.


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


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.


GetDirectSoundVersion method

GetDirectSoundVersion method

Remarks

Retrieves the DirectSound version implemented by the recorder's input device.

Variable Bit Rate (VBR) and lossless encoding require the availability of Windows Media 9: with this method it's possible to know if they can be used.

Syntax

[Visual Basic]

Public Function GetDirectSoundVersion (

) as Int16

[C#]

public Int16 GetDirectSoundVersion (

);

[C++]

public: Int16 GetDirectSoundVersion (

);

Return value

The DirectSound version (e.g. "9" means DirectSound version 9, "8" means DirectSound version 8, etc.)


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.


GetPlaybackStatus method

GetPlaybackStatus method

Remarks

Obtains the current playback status.

This method can be used in alternative to the CallbackSoundPlaybackStatusChanged delegate when the control has been set to work with sound pre-loading through a call to the EnableSoundPreloadForPlayback method: in order to optimize system resources, when pre-loading is disabled (default situation), the stream to play is only loaded when specifically requested through a call to the RecordedSound.Play or RecordedSound.PlayRange methods and automatically discarded from memory after a call to the RecordedSound.Stop method or when the end of the song is reached.

Syntax

[Visual Basic]

Public Function GetPlaybackStatus (

) as enumPlaybackStatus

[C#]

public enumPlaybackStatus GetPlaybackStatus (

);

[C++]

public: enumPlaybackStatus GetPlaybackStatus (

);

Return value

Return value

Value

Meaning

Negative value

An error occurred (see the LastError property for further error details)

Other values

The current playback status.

Possible values are the following:

Mnemonic Value | Value | Meaning
PLAYBACK_NO_SOUND | 0 | No sound is loaded for playback.
PLAYBACK_PLAYING | 1 | Sound is in playback after a call to one between the RecordedSound.Play or RecordedSound.PlayRange or RecordedSound.Resume methods.
PLAYBACK_PAUSED | 2 | Sound is paused after a call to the RecordedSound.Pause method.
PLAYBACK_STOPPED | 3 | Sound is stopped after a call to the RecordedSound.Stop method or after completing playback.


InitDriversType method

InitDriversType method

Remarks

Initializes the type of drivers (DirectSound and/or ASIO) for input devices managed by the control. This method can be called only once and will affect any other instance of the control inside the application. 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 use a recording related functionality, 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.

IMPORTANT NOTE: When using the Audio Sound Recorder API component in conjunction with our Audio DJ Studio API component, which also contains the InitDriversType method, it should be preferred calling the InitDriversType method from Audio DJ Studio API so it will automatically affect both input and output devices.

If only DirectSound output devices are needed, a call to this method can be omitted; if ASIO output devices are needed, this method should be called before any other method of the control because it will affect output devices enumeration performed through GetInputDevicesCount and GetInputDeviceDesc methods.

For further information about ASIO drivers management, refer to the How to manage ASIO drivers 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 output devices are supported and ASIO output devices will be ignored.
DRIVER_TYPE_ASIO | 1 | Only ASIO output devices are supported and DirectSound output devices will be ignored.
DRIVER_TYPE_BOTH_DS_FIRST | 2 | Both DirectSound and ASIO output devices are supported, DirectSound output devices will be listed first when enumerating output devices through GetInputDevicesCount and GetInputDeviceDesc methods.
DRIVER_TYPE_BOTH_ASIO_FIRST | 3 | Both DirectSound and ASIO output devices are supported, ASIO output devices will be listed first when enumerating output devices through GetInputDevicesCount and GetInputDeviceDesc methods.
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


InitRecordingSystem method

InitRecordingSystem method

Remarks

Initializes the control: the call to this method is mandatory and must be performed before calling any other method that will use a recording related functionality, 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.

In case the component should be instanced in conjunction with the Audio DJ Studio API for .NET component, this method should be always called after calling the InitSoundSystem initialization method of the other component.

Syntax

[Visual Basic]

Public Function InitRecordingSystem (

) As enumErrorCodes

[C#]

public enumErrorCodes InitRecordingSystem (

);

[C++]

public: enumErrorCodes InitRecordingSystem (

);

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.


IsSoundAvailableInClipboard method

IsSoundAvailableInClipboard method

Remarks

Checks if a CF_WAVE format sound is available inside the system clipboard.

Syntax

[Visual Basic]

Public Function IsSoundAvailableInClipboard (

) as Boolean

[C#]

public bool IsSoundAvailableInClipboard (

);

[C++]

public: bool IsSoundAvailableInClipboard (

);

Return value

Value | Meaning
false | A CF_WAVE sound is not available inside the clipboard
true | A CF_WAVE sound is available inside the clipboard


IsWmaAvailable method

IsWmaAvailable method

Remarks

Tells if the Microsoft Windows Media Format modules, needed for encoding 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


ResetControl method

ResetControl method

Remarks

Re-initialises the control after a reset of the multimedia engine: the call to this method is mandatory after a call to the ResetEngine method. The purpose of this method is mostly identical to the InitRecordingSystem method.

Syntax

[Visual Basic]

Public Function ResetControl (

nInputDevice as Int16,

nInputChannel as Int16

) As enumErrorCodes

[C#]

public enumErrorCodes ResetControl (

Int16 nInputDevice,

Int16 nInputChannel

);

[C++]

public: enumErrorCodes ResetControl (

Int16 nInputDevice,

Int16 nInputChannel

);

Parameter | Description
nInputDevice | Ignored, set it to 0.
nInputChannel | Ignored, set it to 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.


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 or ERR_INVALID_RECORDER error on next calls to methods of the control.

In case the component should be used in conjunction with the DJ Studio 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 (

);


SetDownmixFilterQuality method

SetDownmixFilterQuality method

Remarks

During an exporting session, performed through the RecordedSound.RequestExportToFile method, in which the recorded sound is being down-mixed to lower frequencies (for example from 44100 Hz to 11025 Hz), allows applying an anti-aliasing filter to the final sound.

Syntax

[Visual Basic]

Public Function SetDownmixFilterQuality (

nQuality as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SetDownmixFilterQuality (

Int16 nQuality

);

[C++]

public: enumErrorCodes SetDownmixFilterQuality (

Int16 nQuality

);

Parameter | Description
nQuality | Number representing the quality of the anti-aliasing filter expressed in percentage. Accepted values are from 0 to 100: - value 0 (default) disables the anti-aliasing filter - values from 1 to 100 enable the anti-aliasing filter: the higher the value, the best the final result but, obviously, higher values will require some more CPU.

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.


SoundActivationSystemGet method

SoundActivationSystemGet method

Remarks

Obtains information about the Sound Activation System during a recording session. The Sound Activation System can be enabled/disabled through the SoundActivationSystemSet method.

For further details see the How the Sound Activation System works tutorial.

Syntax

[Visual Basic]

Public Function SoundActivationSystemGet (

ByRef nMode as enumSoundActivationSystemModes,

ByRef nSilenceThreshold as Int16,

ByRef nSilenceMinLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SoundActivationSystemGet (

ref enumSoundActivationSystemModes nMode,

ref Int16 nSilenceThreshold,

ref Int32 nSilenceMinLength

);

[C++]

public: enumErrorCodes SoundActivationSystemGet (

enumSoundActivationSystemModes __gc *nMode,

Int16 __gc *nSilenceThreshold,

Int32 __gc *nSilenceMinLength

);

Parameter

Description

nMode

Reference that, on return from the method call, will contain the Sound Activation System mode.

Supported values are the following:

Mnemonic constant | Value | Meaning
SOUND_ACTIVATION_SYSTEM_DISABLED | 0 | The Sound Activation System is disabled
SOUND_ACTIVATION_SYSTEM_DISCARD_SILENCE | 1 | The Sound Activation System is enabled and silence will be discarded
SOUND_ACTIVATION_SYSTEM_KEEP_SILENCE | 2 | The Sound Activation System is enabled but silence is not discarded: this mode is not supported when recording from sound files through the StartFromFile method.

nSilenceThreshold

Reference that, on return from the method call, will contain the threshold for the Sound Activation System.

Supported values are in the range from 0 (Sound Activation System disabled, same as setting nMode parameter to SOUND_ACTIVATION_SYSTEM_DISABLED) to 32767 (sound recording always enabled).

If for example you should set a value of 800, any incoming sound having a volume level lower than 800 would be considered as silent and would be discarded.

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

Reference that, on return from the method call, will contain the minimal length of silence for the Sound Activation System. This property's value is expressed in milliseconds with default value 0.

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.


SoundActivationSystemSet method

SoundActivationSystemSet method

Remarks

Enables/disables the Sound Activation System during a recording session. Information about the Sound Activation System can be obtained through the SoundActivationSystemGet method.

If the recording session is from a sound file, the Sound Activation System is automatically disabled when the recording mode, set through the SetRecordingMode method, is REC_MODE_MIX or REC_MODE_OVERWRITE.

For further details see the How the Sound Activation System works tutorial.

Syntax

[Visual Basic]

Public Function SoundActivationSystemSet (

nMode as enumSoundActivationSystemModes,

nSilenceThreshold as Int16,

nSilenceMinLength as Int32,

strLogFile as String

) as enumErrorCodes

[C#]

public enumErrorCodes SoundActivationSystemSet (

enumSoundActivationSystemModes nMode,

Int16 nSilenceThreshold,

Int32 nSilenceMinLength,

string strLogFile

);

[C++]

public: enumErrorCodes SoundActivationSystemSet (

enumSoundActivationSystemModes nMode,

Int16 nSilenceThreshold,

Int32 nSilenceMinLength,

string strLogFile

);

Parameter

Description

nMode

Mode for activating the Sound Activation System.

Supported values are the following:

Mnemonic constant | Value | Meaning
SOUND_ACTIVATION_SYSTEM_DISABLED | 0 | The Sound Activation System is disabled
SOUND_ACTIVATION_SYSTEM_DISCARD_SILENCE | 1 | The Sound Activation System is enabled and silence will be discarded
SOUND_ACTIVATION_SYSTEM_KEEP_SILENCE | 2 | The Sound Activation System is enabled but silence is not discarded: this mode is not supported when recording from sound files through the StartFromFile method.

nSilenceThreshold

Sets the threshold for the Sound Activation System.

Supported values are in the range from 0 (Sound Activation System disabled, same as setting nMode parameter to SOUND_ACTIVATION_SYSTEM_DISABLED) to 32767 (sound recording always enabled).

If for example you should set a value of 800, any incoming sound having a volume level lower than 800 would be considered as silent and would be discarded.

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

Sets the minimal length of silence for the Sound Activation System. This property's value is expressed in milliseconds with default value 0.

strLogFile

Sets the absolute pathname for the Sound Activation System log file. This parameter is ignored when recording from sound files through the StartFromFile 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.


UseThreadsInSyncMode method

UseThreadsInSyncMode method

Remarks

Establishes if lengthy operations, for example loading and exporting sessions, are performed in synchronous or asynchronous mode respect to the code of the container application.

For further information refer to the How to synchronize the container application with the control tutorial.

Syntax

[Visual Basic]

Public Function UseThreadsInSyncMode (

bUseThreadsInSyncMode as bool

) as enumErrorCodes

[C#]

public enumErrorCodes UseThreadsInSyncMode (

bool bUseThreadsInSyncMode

);

[C++]

public: enumErrorCodes UseThreadsInSyncMode (

bool bUseThreadsInSyncMode

);

Parameter

Description

bUseThreadsInSyncMode

Boolean value that specifies if lengthy operations must be performed in synchronous or asynchronous mode respect to the container application code.

Supported values are the following:

Value | Meaning
false (default) | Lengthy operations are performed in asynchronous mode, meaning that each operation starts the secondary thread and immediately returns control to the application's code.
true | Lengthy operations are performed in synchronous mode, meaning that each operation starts the secondary thread and doesn't return control to the application's code until the secondary thread completes its tasks and closes.

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.


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.


CallbackForRecorderEventsSet method

CallbackForRecorderEventsSet method

Remarks

Sets a callback for receiving notification of events generated during recording or CD ripping session.

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 CallbackForRecorderEventsSet (

function as CallbackForRecorderEvents

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackForRecorderEventsSet (

CallbackForRecorderEvents function

);

[C++]

public: enumErrorCodes CallbackForRecorderEventsSet (

CallbackForRecorderEvents 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 CallbackForRecorderEventsSetPtr (

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


CallbackSoundPlaybackDoneSet method

CallbackSoundPlaybackDoneSet method

Remarks

Sets the function of the CallbackSoundPlaybackDone callback delegate which notifies about sound playback completed.

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

Syntax

[Visual Basic]

Public Function CallbackSoundPlaybackDoneSet (

function as CallbackSoundPlaybackDone

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackSoundPlaybackDoneSet (

CallbackSoundPlaybackDone function

);

[C++]

public: enumErrorCodes CallbackSoundPlaybackDoneSet (

CallbackSoundPlaybackDone 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 CallbackSoundPlaybackDoneSetPtr (

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


CallbackSoundPlaybackStatusChangedSet method

CallbackSoundPlaybackDoneSet method

Remarks

Sets the function of the CallbackSoundPlaybackStatusChanged callback delegate which notifies about changes of the playback status.

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

Syntax

[Visual Basic]

Public Function CallbackSoundPlaybackStatusChangedSet (

function as CallbackSoundPlaybackStatusChanged

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackSoundPlaybackStatusChangedSet (

CallbackSoundPlaybackStatusChanged function

);

[C++]

public: enumErrorCodes CallbackSoundPlaybackStatusChangedSet (

CallbackSoundPlaybackStatusChanged 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 CallbackSoundPlaybackStatusChangedSetPtr (

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


CallbackVuMeterValueChangeSet method

CallbackVuMeterValueChangeSet method

Remarks

Sets the function of the CallbackVuMeterValueChange callback delegate which notifies about VU meter value changes during a playback session.

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

For details about using graphic bars refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic]

Public Function CallbackVuMeterValueChangeSet (

function as CallbackVuMeterValueChange

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackVuMeterValueChangeSet (

CallbackVuMeterValueChange function

);

[C++]

public: enumErrorCodes CallbackVuMeterValueChangeSet (

CallbackVuMeterValueChange 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 CallbackVuMeterValueChangeSetPtr (

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


CallbackWaveformValueChangeSet method

CallbackWaveformValueChangeSet method

Remarks

Sets the function of the CallbackWaveformValueChange callback delegate which notifies about waveform value changes during a recording/playback session.

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

Syntax

[Visual Basic]

Public Function CallbackWaveformValueChangeSet (

function as CallbackWaveformValueChange

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformValueChangeSet (

CallbackWaveformValueChange function

);

[C++]

public: enumErrorCodes CallbackWaveformValueChangeSet (

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


CallbackWaveformAnalyzerGraphItemClickSet method

CallbackWaveformAnalyzerGraphItemClickSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerGraphItemClick callback delegate which notifies about button clicks on graphic items added to the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerGraphItemClickSet (

function as CallbackWaveformAnalyzerGraphItemClick

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerGraphItemClickSet (

CallbackWaveformAnalyzerGraphItemClick function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerGraphItemClickSet (

CallbackWaveformAnalyzerGraphItemClick 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 CallbackWaveformAnalyzerGraphItemClickSetPtr (

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


CallbackWaveformAnalyzerGraphItemDblClickSet method

CallbackWaveformAnalyzerGraphItemDblClickSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerGraphItemDblClick callback delegate which notifies about double clicks on graphic items added to the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerGraphItemDblClickSet (

function as CallbackWaveformAnalyzerGraphItemDblClick

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerGraphItemDblClickSet (

CallbackWaveformAnalyzerGraphItemDblClick function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerGraphItemDblClickSet (

CallbackWaveformAnalyzerGraphItemDblClick 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 CallbackWaveformAnalyzerGraphItemDblClickSetPtr (

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


CallbackWaveformAnalyzerHorzLineLeavedSet method

CallbackWaveformAnalyzerHorzLineLeavedSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerHorzLineLeaved callback delegate which notifies when the playback position leaves a graphic item of type "horizontal line" inside the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerHorzLineLeavedSet (

function as CallbackWaveformAnalyzerHorzLineLeaved

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerHorzLineLeavedSet (

CallbackWaveformAnalyzerHorzLineLeaved function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerHorzLineLeavedSet (

CallbackWaveformAnalyzerHorzLineLeaved 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 CallbackWaveformAnalyzerHorzLineLeavedSetPtr (

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


CallbackWaveformAnalyzerHorzLineMovedSet method

CallbackWaveformAnalyzerHorzLineMovedSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerHorzLineMoved callback delegate which notifies when a custom horizontal line on the waveform analyzer has been moved.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerHorzLineMovedSet (

function as CallbackWaveformAnalyzerHorzLineMoved

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerHorzLineMovedSet (

CallbackWaveformAnalyzerHorzLineMoved function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerHorzLineMovedSet (

CallbackWaveformAnalyzerHorzLineMoved 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 CallbackWaveformAnalyzerHorzLineMovedSetPtr (

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


CallbackWaveformAnalyzerHorzLineReachedSet method

CallbackWaveformAnalyzerHorzLineReachedSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerHorzLineReached callback delegate which notifies when the playback position reaches a graphic item of type "horizontal line" inside the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerHorzLineReachedSet (

function as CallbackWaveformAnalyzerHorzLineReached

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerHorzLineReachedSet (

CallbackWaveformAnalyzerHorzLineReached function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerHorzLineReachedSet (

CallbackWaveformAnalyzerHorzLineReached 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 CallbackWaveformAnalyzerHorzLineReachedSetPtr (

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


CallbackWaveformAnalyzerLineMovedSet method

CallbackWaveformAnalyzerLineMovedSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerLineMoved callback delegate which notifies when a graphic item of type "vertical line" inside the waveform analyzer has been moved.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerLineMovedSet (

function as CallbackWaveformAnalyzerLineMoved

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerLineMovedSet (

CallbackWaveformAnalyzerLineMoved function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerLineMovedSet (

CallbackWaveformAnalyzerLineMoved 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 CallbackWaveformAnalyzerLineMovedSetPtr (

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


CallbackWaveformAnalyzerLineReachedSet method

CallbackWaveformAnalyzerLineReachedSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerLineReached callback delegate which notifies when the playback position reaches a graphic item of type "vertical line" inside the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerLineReachedSet (

function as CallbackWaveformAnalyzerLineReached

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerLineReachedSet (

CallbackWaveformAnalyzerLineReached function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerLineReachedSet (

CallbackWaveformAnalyzerLineReached 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 CallbackWaveformAnalyzerLineReachedSetPtr (

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


CallbackWaveformAnalyzerPaintDoneSet method

CallbackWaveformAnalyzerPaintDoneSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerPaintDone callback delegate which notifies when the waveform analyzer has completed its graphic rendering.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerPaintDoneSet (

function as CallbackWaveformAnalyzerPaintDone

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerPaintDoneSet (

CallbackWaveformAnalyzerPaintDone function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerPaintDoneSet (

CallbackWaveformAnalyzerPaintDone 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 CallbackWaveformAnalyzerPaintDoneSetPtr (

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


CallbackWaveformAnalyzerRangeSet method

CallbackWaveformAnalyzerRangeSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerRange callback delegate which notifies about changes on the displayed range of waveform on the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerRangeSet (

function as CallbackWaveformAnalyzerRange

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerRangeSet (

CallbackWaveformAnalyzerRange function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerRangeSet (

CallbackWaveformAnalyzerRange 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 CallbackWaveformAnalyzerRangeSetPtr (

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


CallbackWaveformAnalyzerSelectionSet method

CallbackWaveformAnalyzerSelectionSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerSelection callback delegate which notifies about changes on the selected portion of waveform on the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerSelectionSet (

function as CallbackWaveformAnalyzerSelection

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerSelectionSet (

CallbackWaveformAnalyzerSelection function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerSelectionSet (

CallbackWaveformAnalyzerSelection 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 CallbackWaveformAnalyzerSelectionSetPtr (

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


CallbackWaveAnalyzerSpectralViewStartSet method

CallbackWaveAnalyzerSpectralViewStartSet method

Remarks

Sets the function of the CallbackWaveAnalyzerSpectralViewStart callback delegate which notifies when a new spectral view analysis begins.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveAnalyzerSpectralViewStartSet (

function as CallbackWaveAnalyzerSpectralViewStart

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveAnalyzerSpectralViewStartSet (

CallbackWaveAnalyzerSpectralViewStart function

);

[C++]

public: enumErrorCodes CallbackWaveAnalyzerSpectralViewStartSet (

CallbackWaveAnalyzerSpectralViewStart 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 CallbackWaveAnalyzerSpectralViewStartSetPtr (

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


CallbackWaveAnalyzerSpectralViewDoneSet method

CallbackWaveAnalyzerSpectralViewDoneSet method

Remarks

Sets the function of the CallbackWaveAnalyzerSpectralViewDone callback delegate which notifies when a spectral view analysis is completed.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveAnalyzerSpectralViewDoneSet (

function as CallbackWaveAnalyzerSpectralViewDone

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveAnalyzerSpectralViewDoneSet (

CallbackWaveAnalyzerSpectralViewDone function

);

[C++]

public: enumErrorCodes CallbackWaveAnalyzerSpectralViewDoneSet (

CallbackWaveAnalyzerSpectralViewDone 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 CallbackWaveAnalyzerSpectralViewDoneSetPtr (

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


CallbackWaveformAnalyzerWaveRangeLeavedSet method

CallbackWaveformAnalyzerWaveRangeLeavedSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerWaveRangeLeaved callback delegate which notifies when the playback position leaves a graphic item of type "wave range" inside the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerWaveRangeLeavedSet (

function as CallbackWaveformAnalyzerWaveRangeLeaved

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerWaveRangeLeavedSet (

CallbackWaveformAnalyzerWaveRangeLeaved function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerWaveRangeLeavedSet (

CallbackWaveformAnalyzerWaveRangeLeaved 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 CallbackWaveformAnalyzerWaveRangeLeavedSetPtr (

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


CallbackWaveformAnalyzerWaveRangeReachedSet method

CallbackWaveformAnalyzerWaveRangeReachedSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerWaveRangeReached callback delegate which notifies when the playback position reaches a graphic item of type "wave range" inside the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerWaveRangeReachedSet (

function as CallbackWaveformAnalyzerWaveRangeReached

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerWaveRangeReachedSet (

CallbackWaveformAnalyzerWaveRangeReached function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerWaveRangeReachedSet (

CallbackWaveformAnalyzerWaveRangeReached 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 CallbackWaveformAnalyzerWaveRangeReachedSetPtr (

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


CallbackWaveformAnalyzerWidthSet method

CallbackWaveformAnalyzerWidthSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerWidth callback delegate which notifies about changes of the waveform analyzer's width.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerWidthSet (

function as CallbackWaveformAnalyzerWidth

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerWidthSet (

CallbackWaveformAnalyzerWidth function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerWidthSet (

CallbackWaveformAnalyzerWidth 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 CallbackWaveformAnalyzerWidthSetPtr (

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


CallbackWaveformAnalyzerMouseNotifSet method

CallbackWaveformAnalyzerMouseNotifSet method

Remarks

Sets the function of the CallbackWaveformAnalyzerMouseNotif callback delegate which notifies about mouse actions on the waveform analyzer.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function CallbackWaveformAnalyzerMouseNotifSet (

function as CallbackWaveformAnalyzerMouseNotif

) as enumErrorCodes

[C#]

public enumErrorCodes CallbackWaveformAnalyzerMouseNotifSet (

CallbackWaveformAnalyzerMouseNotif function

);

[C++]

public: enumErrorCodes CallbackWaveformAnalyzerMouseNotifSet (

CallbackWaveformAnalyzerMouseNotif 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 CallbackWaveformAnalyzerMouseNotifSetPtr (

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


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


CddbGetAlbumInfo method

CddbGetAlbumInfo method

Remarks

Retrieves a specific CDDB information about the CD currently inside the given CD drive.

See the How to get Audio CD info using CDDB servers and Amazon catalogue 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

When CD album info is obtained through a previous call the the CddbRequestAlbumInfo method, this parameter represents the zero-based index of the CD drive containing the Audio CD. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

When CD album info is obtained through a previous call the the CdRequestAlbumInfo method, set this value to -1.

nInfo

Number representing the requested information code.

Supported values are the following:

Mnemonic value | Numeric value | Meaning
CDDB_ALBUM_TITLE | 0 | The CD album title
CDDB_ALBUM_ARTIST | 1 | The CD album artist
CDDB_ALBUM_YEAR | 2 | The CD album year
CDDB_ALBUM_GENRE | 3 | The CD album genre
CDDB_ALBUM_CLIENT_INFO | 4 | The CD album client info

Return value

Value | Meaning
Empty string | An error occurred. Check the LastError property value in order to see the last error.
Valid string | The requested information


CddbGetServerName method

CddbGetServerName method

Remarks

Obtains the friendly name of the given CDDB server.

The total number of available CDDB servers can be requested through the CddbRequestServersList method: the method will fail if called before before being notified about servers availability through the CallbackForRecordersEvents delegate having the nEvent parameter set to EV_REC_CDDB_SERVERS_AVAIL.

See the How to get Audio CD info using CDDB servers and Amazon catalogue 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


CddbGetTrackTitle method

CddbGetTrackTitle method

Remarks

Retrieves the title of the given track for the CD currently inside the given CD drive: track titles can be obtained from a CDDB server or from the Amazon Web Service.

See the How to get Audio CD info using CDDB servers and Amazon catalogue and tutorials 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

When CD album info is obtained through a previous call the the CddbRequestAlbumInfo method, this parameter represents the zero-based index of the CD drive containing the Audio CD. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

When CD album info is obtained through a previous call the the CdRequestAlbumInfo method, set this value to -1.

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 the CD info will be available, the CallbackForRecordersEvents delegate is invoked with the nEvent parameter set to EV_REC_CDDB_ALBUM_INFO_AVAIL and 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 CallbackForRecordersEvents delegate is invoked with the nEvent parameter set to

· EV_REC_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_REC_D_COVER_SMALL_FILE_AVAIL, EV_REC_CD_COVER_MEDIUM_FILE_AVAIL and EV_REC_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.

See the How to get Audio CD info using CDDB servers and Amazon catalogue 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 CallbackForRecordersEvents delegate having the nEvent parameter set to EV_REC_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 Audio CD info using CDDB servers and Amazon catalogue 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.


CddbSetProxyDetails method

CddbSetProxyDetails method

Remarks

Sets details for reaching CDDB information from behind a HTTP proxy.

See the How to get Audio CD info using CDDB servers and Amazon catalogue tutorial for further details.

Syntax

[Visual Basic]

Public Sub CddbSetProxyDetails (

strHost as string,

nPort as long,

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


CdDriveAutoSpeedSet method

CdDriveAutoSpeedSet method

Remarks

Specifies if the speed of CD drive must be automatically halved after getting an error during the reading of a sector of CD track.

When the speed is automatically changed, the container application is notified through the CallbackForRecordersEvents delegate having the nEvent parameter set to EV_CD_SPEED_CHANGE.

Syntax

[Visual Basic]

Public Sub CdDriveAutoSpeedSet (

bAutoSpeed as Boolean

)

[C#]

public void CdDriveAutoSpeedSet (

bool bAutoSpeed

);

[C++]

public: void CdDriveAutoSpeedSet (

bool bAutoSpeed

);

Parameter

Description

bAutoSpeed

Boolean flag that specifies if the speed change must be automatic.

Supported values are the following:

Value | Meaning
false (default) | Disables automatic speed change.
true | Enables automatic speed change.

Return value

None


CdDriveMaxSpeedGet method

CdDriveMaxSpeedGet method

Remarks

Obtains the maximum speed supported by the given CD drive.

Syntax

[Visual Basic]

Public Function CdDriveMaxSpeedGet (

nCdDriveIndex as Int16,

ByRef nMaxSpeed as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CdDriveMaxSpeedGet (

Int16 nCdDriveIndex,

ref Int32 nMaxSpeed

);

[C++]

public: enumErrorCodes CdDriveMaxSpeedGet (

Int16 nCdDriveIndex,

Int32 __gc *nMaxSpeed

);

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.

nMaxSpeed

Reference that, after returning from the method call, will contain the maximum speed supported by the CD drive expressed in Kbytes per second.

You can divide the speed by 176.4 to get the real-time speed multiplier; if for example the returned values should be 7096, the operation to perform would be

7096 / 176.4 = "40x".

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.


CdDriveReadMaxAllowedErrors method

CdDriveReadMaxAllowedErrors method

Remarks

Sets the maximum number of allowed errors, before stopping the CD ripping session, when an error persists during the reading of the same sector of a CD track.

Syntax

[Visual Basic]

Public Function CdDriveReadMaxAllowedErrors (

nMaxErrors as Int32

)

[C#]

public void CdDriveReadMaxAllowedErrors (

Int32 nMaxErrors

);

[C++]

public: void CdDriveReadMaxAllowedErrors (

Int32 nMaxErrors

);

Parameter

Description

nMaxErrors

Maximum number of allowed errors. Set this parameter to -1 if you don't want blocking the ripping in case of many read errors. By default this value is set to -1.

This number has a different meaning respect to the number of retries set through the CdDriveReadRetriesNumberSet method: the number of retries fixes the maximum number of attempts a CD sector should be read before giving up and replacing faulty sectors with silence while this parameter sets the maximum number of allowed errors before forcing the stop of the CD ripping session.

Return value

None


CdDriveReadOffsetSet method

CdDriveReadOffsetSet method

Remarks

Sets the read offset of the given CD drive.

This method can be used to compensate for the fact that most drives will read audio data from CDs at a slight offset from where they ideally should. Different drive models will have differing offsets, a list of which can be found on this link.

Syntax

[Visual Basic]

Public Function CdDriveReadOffsetSet (

nCdDriveIndex as Int16,

nOffset as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CdDriveReadOffsetSet (

Int16 nCdDriveIndex,

Int32 nOffset

);

[C++]

public: enumErrorCodes CdDriveReadOffsetSet (

Int16 nCdDriveIndex,

Int32 nOffset

);

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.
nOffset | Number representing the read offset expressed in bytes. When a negative offset is used, reading the beginning of the first track will require accessing the lead-in, and when a positive offset is used, reading the end of the last track will require accessing the lead-out. The drive may not support that (overreading), in which case those parts will be replaced with silence.

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.


CdDriveReadRetriesNumberSet method

CdDriveReadRetriesNumberSet method

Remarks

Sets the number of times to retry, before skipping the current CD sector, when an error occurs during the ripping of a CD track.

Each time a read error occurs, the container application is notified through the CallbackForRecordersEvents delegate having the nEvent parameter set to EV_CD_ERROR.

When the number of errors exceeds the number of retries, audio data contained inside the bad sector is replaced with silence on the output file.

Syntax

[Visual Basic]

Public Function CdDriveReadRetriesNumberSet (

nRetries as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes CdDriveReadRetriesNumberSet (

Int16 nRetries

);

[C++]

public: enumErrorCodes CdDriveReadRetriesNumberSet (

Int16 nRetries

);

Parameter | Description
nRetries | Number of retries. When this value is set to 0, no retry is performed. By default the number of retries is 2.

Return value

None


CdDriveSpeedGet method

CdDriveSpeedGet method

Remarks

Obtains the current speed of the CD drive. The speed can be modified through the CdDriveSpeedSet method.

Syntax

[Visual Basic]

Public Function CdDriveSpeedGet (

nCdDriveIndex as Int16,

ByRef nSpeed as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CdDriveSpeedGet (

Int16 nCdDriveIndex,

ref Int32 nSpeed

);

[C++]

public: enumErrorCodes CdDriveSpeedGet (

Int16 nCdDriveIndex,

Int32 __gc *nSpeed

);

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.

nSpeed

Reference that, after returning from the method call, will contain the speed of the CD drive expressed in Kbytes per second.

You can divide the speed by 176.4 to get the real-time speed multiplier; if for example the returned values should be 7096, the operation to perform would be

7096 / 176.4 = "40x".

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.


CdDriveSpeedSet method

CdDriveSpeedSet method

Remarks

Sets the speed of the CD drive. The current speed can be obtained through the CdDriveSpeedGet method.

Syntax

[Visual Basic]

Public Function CdDriveSpeedSet (

nCdDriveIndex as Int16,

nSpeed as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CdDriveSpeedSet (

Int16 nCdDriveIndex,

Int32 nSpeed

);

[C++]

public: enumErrorCodes CdDriveSpeedSet (

Int16 nCdDriveIndex,

Int32 nSpeed

);

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.

nSpeed

Number representing the speed of the CD drive expressed in Kbytes per second.

In order to use a real-time speed multiplier, multiply it by 176.4 (and round up) to get the "Kbytes per second" speed to use with this function, if for example the speed you would like to set should be "40x", the operation to perform would be

40 * 176.4 = 7096

The speed is automatically restricted (rounded down) to what is supported by the CD drive, so may not be exactly what was requested. The CdDriveSpeedGet method can be used to check that. The maximum supported speed for the given CD drive can be retrieved through the CdDriveMaxSpeedGet 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.


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 the CD info will be available, the CallbackForRecordersEvents delegate is invoked with the nEvent parameter set to EV_REC_CDDB_ALBUM_INFO_AVAIL and 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 CallbackForRecordersEvents delegate is invoked with the nEvent parameter set to

· EV_REC_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_REC_D_COVER_SMALL_FILE_AVAIL, EV_REC_CD_COVER_MEDIUM_FILE_AVAIL and EV_REC_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.

See the How to get pictures of CD covers 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.


CdRippingAutomationExec method

CdRippingAutomationExec method

Remarks

Starts the CD ripping automation session.

The ripping automation must have been previously initialized through the CdRippingAutomationInit method and one or more tracks should have been added through the CdRippingAutomationTrackAdd method.

If tracks normalization is disabled, the container application is notified about the CD ripping automation session through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to the following values:

· EV_CD_RIPPING_AUTOMATION_START invoked once at the beginning
· EV_CD_RIPPING_PERC invoked multiple times reporting the current advancement percentage of each single track inside the nDataLow3 parameter
· EV_CD_RIPPING_AUTOMATION_TOTAL_PERC invoked multiple times reporting the advancement of the overall ripping automation session
· EV_CD_RIPPING_SIZE invoked multiple times reporting the current size in bytes of each single track inside the combination of the nDataHigh3 and nDataLow3 parameters
· EV_CD_RIPPING_AUTOMATION_STOP invoked as soon as the ripping automation session is completed

If tracks normalization should be enabled through a previous call to the CdRippingNormalizationEnable method, the call to this method would cause the CallbackForRecordersEvents delegate to be invoked with the nEvent parameter having the same values described above but also with the following values:

· EV_CD_RIPPING_EXTRACT_PERC event informs the container application about the advancement of extraction of the CD track's raw sound data into a memory buffer (see point 1. above)
· EV_CD_RIPPING_NORM_PERC event informs the container application about the normalization advancement (see point 2. above)
· EV_CD_RIPPING_ENCODE_PERC event informs the container application about the encoding advancement (see point 3. above)

For details about the encoding format and parameters see the How to perform a CD ripping session section.

Syntax

[Visual Basic]

Public Function CdRippingAutomationExec (

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingAutomationExec (

);

[C++]

public: enumErrorCodes CdRippingAutomationExec (

);

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.


CdRippingAutomationInit method

CdRippingAutomationInit method

Remarks

Initializes a CD ripping automation session.

Once initialized you can start adding CD tracks to the automation session through the CdRippingAutomationTrackAdd method and, at a later stage, the automation can be started through the CdRippingAutomationExec method.

For details about the encoding format and parameters see the How to perform a CD ripping session section.

Syntax

[Visual Basic]

Public Function CdRippingAutomationInit (

nCdDriveIndex as Int16,

bSingleOutputFile as Boolean,

nSingleFileInterTrackSilence as Int32,

strSingleFileOutputPath as String

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingAutomationInit (

Int16 nCdDriveIndex,

Int16 bSingleOutputFile,

Int32 nSingleFileInterTrackSilence,

string strSingleFileOutputPath

);

[C++]

public: enumErrorCodes CdRippingAutomationInit (

Int16 nCdDriveIndex,

Int16 bSingleOutputFile,

Int32 nSingleFileInterTrackSilence,

string strSingleFileOutputPath

);

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.

bSingleOutputFile

Boolean flag that determines if ripped CD tracks will be stored inside a single output file or inside one output file for each track.

Supported values are the following:

Mnemonic constant | Meaning
false | Each ripped track will be stored inside a separate file
true | All ripped tracks will be stored inside a single output file

nSingleFileInterTrackSilence

Length of silence, expressed in milliseconds, added between each ripped track when the bSingleOutputFile parameter is set to "true" and ripped tracks are stored inside a single output file.

strSingleFileOutputPath

String representing the absolute pathname of the single output file. This parameter is ignored when the bSingleOutputFile parameter is set to "false" in which case the string representing the absolute pathname of each output file is initialized through the strOutputPath parameter of the CdRippingAutomationTrackAdd 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.


CdRippingAutomationTrackAdd method

CdRippingAutomationTrackAdd method

Remarks

Adds a CD track to the CD ripping automation.

The ripping automation must have been previously initialized through the CdRippingAutomationInit method and can be started at a later stage through the CdRippingAutomationExec method..

For details about the encoding format and parameters see the How to perform a CD ripping session section.

Syntax

[Visual Basic]

Public Function CdRippingAutomationTrackAdd (

nCdDriveIndex as Int16,

strOutputPath as String

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingAutomationTrackAdd (

Int16 nCdDriveIndex,

string strOutputPath

);

[C++]

public: enumErrorCodes CdRippingAutomationTrackAdd (

Int16 nCdDriveIndex,

string strOutputPath

);

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.
strOutputPath | String representing the absolute pathname of the output file for this specific track. This parameter is ignored when the bSingleOutputFile parameter of the CdRippingAutomationInit method is set to BOOL_TRUE in which case the string representing the absolute pathname of the single output file where this track will be stored is initialized through the strSingleFileOutputPath parameter of the CdRippingAutomationInit method itself.

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.


CdRippingNormalizationEnable method

CdRippingNormalizationEnable method

Remarks

Enables/disables normalization of tracks during a CD ripping session.

For details about the encoding format and parameters see the How to perform a CD ripping session section.

Syntax

[Visual Basic]

Public Function CdRippingNormalizationEnable (

bEnable as Boolean,

fTargetLevelPerc as Single,

fBelowLevelPerc as Single,

fAboveLevelPerc as Single

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingNormalizationEnable (

bool bEnable

float fTargetLevelPerc,

float fBelowLevelPerc,

float fAboveLevelPerc

);

[C++]

public: enumErrorCodes CdRippingNormalizationEnable (

bool bEnable

float fTargetLevelPerc,

float fBelowLevelPerc,

float fAboveLevelPerc

);

Parameter

Description

bEnable

Boolean value that specifies if normalization must be enabled or disabled.

Supported values are the following:

Mnemonic constant | Meaning
false | Disabled 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.ERR_NOERROR (0) | The call was successful.


CdRippingSetRange method

CdRippingSetRange method

Remarks

Sets a range that will be used in order to define the start and end position of a CD ripping session

For details about the encoding format and parameters see the How to perform a CD ripping session section.

Syntax

[Visual Basic]

Public Function CdRippingSetRange (

nStartPosition as Int32,

nEndPosition as Int32,

nScaleUnits as enumScaleUnits

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingSetRange (

Int32 nStartPosition,

Int32 nEndPosition,

enumScaleUnits nScaleUnits

);

[C++]

public: enumErrorCodes CdRippingSetRange (

Int32 nStartPosition,

Int32 nEndPosition,

enumScaleUnits nScaleUnits

);

Parameter

Description

nStartPosition

Number representing the position where the CD track's ripping will begin; it's effective value depends upon the value of the nScaleUnits parameter.

nEndPosition

Number representing the position where the CD track's ripping will end; it's effective value depends upon the value of the nScaleUnits parameter.

nScaleUnits

The unit used to define the nStartPosition and nEndPosition parameters.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_MILLISECONDS | 0 | Milliseconds
SCALE_SECONDS | 1 | Seconds
SCALE_MINUTES | 2 | Minutes
SCALE_HOURS | 3 | Hours
SCALE_PERCENTAGE | 4 | Percentage (expressed with values from 0 to 100)

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.


CdRippingSetResampleParams method

CdRippingSetResampleParams method

Remarks

Sets the parameters used for resampling sound data coming from the CD ripping session.

For details about the encoding format and parameters see the How to perform a CD ripping session section.

Syntax

[Visual Basic]

Public Function CdRippingSetResampleParams (

nResampleFrequency as Int32,

nResampleChannels as Int32,

nResampleBitsPerSample as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingSetResampleParams (

Int32 nResampleFrequency,

Int32 nResampleChannels,

Int32 nResampleBitsPerSample

);

[C++]

public: enumErrorCodes CdRippingSetResampleParams (

Int32 nResampleFrequency,

Int32 nResampleChannels,

Int32 nResampleBitsPerSample

);

Parameter | Description
nResampleFrequency | Number representing the frequency, expressed in Hz, used for resampling sound data (e.g. 11025, 22050, 44100, 48000, etc.)
nResampleChannels | The number of channels (use 1 for Mono or 2 for Stereo) used for resampling sound data
nResampleBitsPerSample | The number of bits per sample (8 or 16) used for resampling sound data

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.


CdRippingStart method

CdRippingStart method

Remarks

Starts ripping the given CD track of the given CD drive.

A successful call to this method will cause the CallbackForRecordersEvents delegate to be invoked with the nEvent parameter set to the following values:

· EV_CD_RIPPING_START invoked once at the beginning
· EV_CD_RIPPING_PERC invoked multiple times reporting the current advancement percentage inside the nDataLow3 parameter
· EV_CD_RIPPING_SIZE invoked multiple times reporting the current size in bytes inside the combination of the nDataHigh3 and nDataLow3 parameters
· EV_CD_RIPPING_STOP invoked as soon as the ripping session is completed

For details about the encoding format and parameters see the How to perform a CD ripping session section.

Syntax

[Visual Basic]

Public Function CdRippingStart (

nCdDriveIndex as Int16,

nTrackIndex as Int16,

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingStart (

Int16 nCdDriveIndex,

Int16 nTrackIndex,

string strOutputPath

);

[C++]

public: enumErrorCodes CdRippingStart (

Int16 nCdDriveIndex,

Int16 nTrackIndex,

string strOutputPath

);

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.
strOutputPath | String representing the absolute pathname of the output file that will contain the song's ripped data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


CdRippingStartUsingCodec method

CdRippingStartUsingCodec method

Remarks

Starts ripping the given CD track of the given CD drive using the given Audio Compression Manager codec and format.

A successful call to this method will cause the CallbackForRecordersEvents delegate to be invoked with the nEvent parameter set to the following values:

· EV_CD_RIPPING_START invoked once at the beginning
· EV_CD_RIPPING_PERC invoked multiple times reporting the current advancement percentage inside the nDataLow3 parameter
· EV_CD_RIPPING_SIZE invoked multiple times reporting the current size in bytes inside the combination of the nDataHigh3 and nDataLow3 parameters
· EV_CD_RIPPING_STOP invoked as soon as the ripping session is completed

For further details about the Windows Audio Compression Manager refer to the AudioComprMan class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

See the How to perform a CD ripping session section for further details.

Syntax

[Visual Basic]

Public Function CdRippingStartUsingCodec (

nCdDriveIndex as Int16,

nTrackIndex as Int16,

nCodecIndex as Int16,

nCodecFormatIndex as Int16,

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingStartUsingCodec (

Int16 nCdDriveIndex,

Int16 nTrackIndex,

Int16 nCodecIndex,

Int16 nCodecFormatIndex,

string strOutputPath

);

[C++]

public: enumErrorCodes CdRippingStartUsingCodec (

Int16 nCdDriveIndex,

Int16 nTrackIndex,

Int16 nCodecIndex,

Int16 nCodecFormatIndex,

string strOutputPath

);

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.
nCodecIndex | Number representing the index of the ACM codec. Installed codecs can be enumerated using the AudioCompressionManager.GetCodecsCount method and their friendly description can be retrieved through the AudioCompressionManager.GetCodecDesc method.
nCodecFormatIndex | Number representing the index of the format for the given ACM codec. Available formats for the given codec can be enumerated using the AudioCompressionManager.GetCodecFormatsCount method and their friendly description can be retrieved through the AudioCompressionManager.GetCodecFormatDesc method.
strOutputPath | String representing the absolute pathname of the output file that will contain the song's ripped data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


CdRippingStartUsingCodecWavFormat method

CdRippingStartUsingCodecWavFormat method

Remarks

Starts ripping the given CD track of the given CD drive using the given Audio Compression Manager format.

A successful call to this method will cause the CallbackForRecordersEvents delegate to be invoked with the nEvent parameter set to the following values:

· EV_CD_RIPPING_START invoked once at the beginning
· EV_CD_RIPPING_PERC invoked multiple times reporting the current advancement percentage inside the nDataLow3 parameter
· EV_CD_RIPPING_SIZE invoked multiple times reporting the current size in bytes inside the combination of the nDataHigh3 and nDataLow3 parameters
· EV_CD_RIPPING_STOP invoked as soon as the ripping session is completed

For further details about the Windows Audio Compression Manager refer to the AudioComprMan class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

See the How to perform a CD ripping session section for further details.

Syntax

[Visual Basic]

Public Function CdRippingStartUsingCodecWavFormat (

nCdDriveIndex as Int16,

nTrackIndex as Int16,

pWavData() as Byte,

sizeWavData as Int32,

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingStartUsingCodecWavFormat (

Int16 nCdDriveIndex,

Int16 nTrackIndex,

byte [] pWavData,

Int32 sizeWavData,

string strOutputPath

);

[C++]

public: enumErrorCodes CdRippingStartUsingCodecWavFormat (

Int16 nCdDriveIndex,

Int16 nTrackIndex,

unsigned char __gc[] pWavData,

Int32 sizeWavData,

string strOutputPath

);

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.

pWavData

Memory buffer containing the codec's format description based upon the WAVEFORMATEX structure, common to all waveform-audio formats and defined inside the Microsoft SDK as follows:

typedef struct {

 WORD  wFormatTag;

 WORD  nChannels;

 DWORD nSamplesPerSec;

 DWORD nAvgBytesPerSec;

 WORD  nBlockAlign;

 WORD  wBitsPerSample;

 WORD  cbSize;

} WAVEFORMATEX;

The cbSize member defines how many extra-bytes are appended to the end of the WAVEFORMATEX structure.

This buffer could be filled with custom contents or, in alternative, using the AudioCompressionManager.GetCodecFormatWavData method.

sizeWavData

Size in bytes of the memory buffer

strOutputPath

String representing the absolute pathname of the output file that will contain the song's ripped data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


CdRippingStop method

CdRippingStop method

Remarks

Stops the current CD ripping started through a call to the CdRippingStart method or through the CdRippingAutomationExec method.

Depending upon the fact that the control is performing the ripping of a single track or a ripping automation session, calling this method will cause the CallbackForRecordersEvents delegate to be invoked with the nEvent parameter set to the following values:

· EV_CD_RIPPING_STOP invoked for ripping of single tracks
· EV_CD_RIPPING_AUTOMATION_STOP invoked for ripping automation sessions

See the How to perform a CD ripping session section for further details.

Syntax

[Visual Basic]

Public Function CdRippingStop (

) as enumErrorCodes

[C#]

public enumErrorCodes CdRippingStop (

);

[C++]

public: enumErrorCodes CdRippingStop (

);

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.


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.
true | CD drives will be monitored.

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

nCdDriveIndex as Int16

) as String

[C#]

public string GetCdDriveDesc (

Int16 nCdDriveIndex

);

[C++]

public: string GetCdDriveDesc (

Int16 nCdDriveIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the CD drive whose friendly name must be retrieved. Installed CD drives can be enumerated using the GetCdDrivesCount method.

Return value

Value | Meaning
Empty string | The value of the nCdDriveIndex parameter was out of range. Use the value returned by the GetCdDrivesCount method in order to know how many CD drive are currently installed on the system.
Valid string | The string containing the friendly description of the requested CD drive.


GetCdDriveLetter method

GetCdDriveLetter method

Remarks

Retrieves the drive letter of the requested CD drive: for example it will return "D" (without quotes) for the drive "D:\".

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

Syntax

[Visual Basic]

Public Function GetCdDriveLetter (

nCdDriveIndex as Int16

) as String

[C#]

public string GetCdDriveLetter (

Int16 nCdDriveIndex

);

[C++]

public: string GetCdDriveLetter (

Int16 nCdDriveIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the CD drive whose letter must be retrieved. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

Return value

Value | Meaning
Empty string | The value of the nCdDriveIndex parameter was out of range. Use the value returned by the GetCdDrivesCount method in order to know how many CD drive are currently installed on the system.
Valid string | The string containing the letter of the requested CD drive.


GetCdDrivesCount method

GetCdDrivesCount method

Remarks

Retrieves the number of CD drives currently installed on the system.

The friendly name of each CD drive can be obtained using the GetCdDriveDesc method.

Syntax

[Visual Basic]

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.

Syntax

[Visual Basic]

Public Function GetCdIdentification (

nCdDriveIndex as Int16,

nIdentType as enumCdIdCodes

) as enumErrorCodes

[C#]

public enumErrorCodes GetCdIdentification (

Int16 nCdDriveIndex,

enumCdIdCodes nIdentType

);

[C++]

public: enumErrorCodes GetCdIdentification (

Int16 nCdDriveIndex,

enumCdIdCodes nIdentType

);

Parameter

Description

nCdDriveIndex

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

Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

nIdentType

Number representing the kind of identification we need to retrieve.

Supported values are the following:

Mnemonic constant

Value

Meaning

CD_IDENTIF_TEXT

0

Retrieves the CD-Text information.

CD Text is a technology developed by Sony Corporation and Philips Electronics in 1996 that allows storing information about an audio CD and its tracks (such as artist name, album, or song name) directly on the disk. Currently, many commercially available audio CDs contain CD Text information.

If CD Text is written on a CD, it is no need to query Internet databases for artist name or track list. CD-Text Reader delivers this information fast and right from the disk. No typos or misspelled names: the information comes directly from the publisher.

CD-Text is still not available on the majority of CDs.

CD_IDENTIF_CDDB

1

Retrieves a CDDB identifier that can be used to get details on the CD from a CDDB server. Refer to the documentation available on the http://www.cddb.com and http://www.freedb.org web sites for more information on using a CDDB server.

CD_IDENTIF_MS

2

Retrieves an identifier, usually adopted by Windows Media Player, that can be used to get details on the CD from a Microsoft server.

CD_IDENTIF_UPC

3

Retrieves the catalog number of the CD. The number is an UPC/EAN barcode. This information might not be available for all CDs.

CD_IDENTIF_MUSICBRAINZ

4

Retrieves an identifier that can be used to get details on the CD's contents from MusicBrainz servers.

Return value

Value | Meaning
Empty string | The requested identification information was not found or an error occurred (see the LastError property for further error details)
Valid string | The identification string.


GetCdNumTracks method

GetCdNumTracks method

Remarks

Retrieves the number of audio tracks inside the given CD.

Syntax

[Visual Basic]

Public Function GetCdNumTracks (

nCdDriveIndex as Int16

) as Int16

[C#]

public Int16 GetCdNumTracks (

Int16 nCdDriveIndex

);

[C++]

public: Int16 GetCdNumTracks (

Int16 nCdDriveIndex

);

Parameter

Description

nCdDriveIndex

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

Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

If the number of tracks to report has been obtained through a search through the Amazon catalogue, by calling the CdRequestAlbumInfo method, set this parameter to -1.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 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 (

nCdDriveIndex as Int16

) as enumCdStatus

[C#]

public enumCdStatus GetCdStatus (

Int16 nCdDriveIndex

);

[C++]

public: enumCdStatus GetCdStatus (

Int16 nCdDriveIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.

Return value

Mnemonic value | 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 of the given CD track into the CD drive.

Syntax

[Visual Basic]

Public Function GetCdTrackDuration (

nCdDriveIndex as Int16,

nTrackIndex as Int16

) as Int32

[C#]

public Int32 GetCdTrackDuration (

Int16 nCdDriveIndex,

Int16 nTrackIndex

);

[C++]

public: Int32 GetCdTrackDuration (

Int16 nCdDriveIndex,

Int16 nTrackIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
nTrackIndex | Number representing the one-based index of the CD audio track. The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 0 | The audio track duration expressed in seconds


GetCdTrackDurationMs method

GetCdTrackDurationMs method

Remarks

Retrieves the duration of the given CD track into the CD drive.

Syntax

[Visual Basic]

Public Function GetCdTrackDurationMs (

nCdDriveIndex as Int16,

nTrackIndex as Int16

) as Int32

[C#]

public Int32 GetCdTrackDurationMs (

Int16 nCdDriveIndex,

Int16 nTrackIndex

);

[C++]

public: Int32 GetCdTrackDurationMs (

Int16 nCdDriveIndex,

Int16 nTrackIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
nTrackIndex | Number representing the one-based index of the CD audio track. The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
> 0 | The audio track duration expressed in milliseconds


GetCdTrackPathname method

GetCdTrackPathname method

Remarks

Given an audio track number, retrieves the relative file pathname.

Syntax

[Visual Basic]

Public Function GetCdTrackPathname (

nCdDriveIndex as Int16,

nTrackIndex as Int16

) as String

[C#]

public string GetCdTrackPathname (

Int16 nCdDriveIndex,

Int16 nTrackIndex

);

[C++]

public: string GetCdTrackPathname (

Int16 nCdDriveIndex,

Int16 nTrackIndex

);

Parameter | Description
nCdDriveIndex | Number representing the zero-based index of the involved CD drive. Installed CD drives can be enumerated using the GetCdDrivesCount method and their friendly description can be retrieved through the GetCdDriveDesc method.
nTrackIndex | Number representing the one-based index of the CD audio track. The total number of available audio tracks on the given CD can be obtained using the GetCdNumTracks method.

Return value

Value | Meaning
Empty string | An error occurred (see the LastError property for further error details)
Valid string | The string containing the CD track file pathname.


PerformActionOnCd method

PerformActionOnCd method

Remarks

Performs an action on the given CD drive.

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

Syntax

[Visual Basic]

Public Function PerformActionOnCd (

nCdDriveIndex as Int16,

nAction as enumCdActions

) as enumErrorCodes

[C#]

public enumErrorCodes PerformActionOnCd (

Int16 nCdDriveIndex,

enumCdActions nAction

);

[C++]

public: enumErrorCodes PerformActionOnCd (

Int16 nCdDriveIndex,

enumCdActions nAction

);

Parameter

Description

nCdDriveIndex

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


EnableOutputDevice method

EnableOutputDevice method

Remarks

Enables/disables an output device in order to allow recording on half-duplex devices.

Normal sound cards work in full-duplex, allowing input and output channels working at the same time: some other device used for dictation purposes, like some model of Philips SpeechMike™ devices, work in half duplex so, before starting a recording session, there is the need to disable their sound output functionality through a call to this method with the bEnable parameter set to false; once the recording session has been completed their sound output functionality can be enabled again through a call to this method with the bEnable parameter set to true.

The total number of available output devices can be obtained using the GetOutputDevicesCount method and their friendly description can be obtained using the GetOutputDeviceDesc method.

Syntax

[Visual Basic]

Public Function EnableOutputDevice (

nOutputIndex as Int16,

bEnable as bool

) as enumErrorCodes

[C#]

public enumErrorCodes EnableOutputDevice (

Int16 nOutputIndex,

bool bEnable

);

[C++]

public: enumErrorCodes EnableOutputDevice (

Int16 nOutputIndex,

bool bEnable

);

Parameter

Description

nOutputIndex

Number representing the zero-based index of the output device which needs to be enabled/disabled

bEnable

Boolean value that specifies if the given output device must be enabled or disabled.

Supported values are the following:

Value | Meaning
false | Disables the output device
true (default) | Enables the output device

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.


GetInputDeviceChannelDefault method

GetInputDeviceChannelDefault method

Remarks

Retrieves the current default channel for the given input device.

The friendly name of each input channel can be obtained using the GetInputDeviceChannelDesc method.

Syntax

[Visual Basic]

Public Function GetInputDeviceChannelDefault (

nInputDevice as Int16

) as Int16

[C#]

public Int16 GetInputDeviceChannelDefault (

Int16 nInputDevice

);

[C++]

public: Int16 GetInputDeviceChannelDefault (

Int16 nInputDevice

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
>= 0 | The zero-based index of the current channel default


GetInputDeviceChannelDesc method

GetInputDeviceChannelDesc method

Remarks

Retrieves the friendly description of the requested input channel. This method is very useful when you have to fill a combo box with the friendly names of the available input channels.

The total number of available input channels for the given input device can be obtained using the GetInputDeviceChannelsCount method.

Syntax

[Visual Basic]

Public Function GetInputDeviceChannelsDesc (

nInputDevice as Int16,

nInputChannel as Int16

) as String

[C#]

public string GetInputDeviceChannelsDesc (

Int16 nInputDevice,

Int16 nInputChannel

);

[C++]

public: string GetInputDeviceChannelsDesc (

Int16 nInputDevice,

Int16 nInputChannel

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device whose input channel must be retrieved
nInputChannel | Number representing the zero-based index of the requested input channel (Microphone, Stereo Mix, Line-In, etc.)

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 friendly description of the requested input channel.


GetInputDeviceChannelsCount method

GetInputDeviceChannelsCount method

Remarks

Retrieves the number of input channels (e.g. Microphone, Stereo Mix, Line-In, etc.) available inside the given input device.

The friendly name of each input channel can be obtained using the GetInputDeviceChannelDesc method.

Syntax

[Visual Basic]

Public Function GetInputDeviceChannelsCount (

nInputDevice as Int16

) as Int16

[C#]

public Int16 GetInputDeviceChannelsCount (

Int16 nInputDevice

);

[C++]

public: Int16 GetInputDeviceChannelsCount (

Int16 nInputDevice

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device whose input channels must be retrieved

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


GetInputDeviceChannelType method

GetInputDeviceChannelType method

Remarks

Tries to obtain the type of a given input channel.

Syntax

[Visual Basic]

Public Function GetInputDeviceChannelType (

nInputDevice as Int16,

nInputChannel as Int16

) as enumInputChannelTypes

[C#]

public enumInputChannelTypes GetInputDeviceChannelType (

Int16 nInputDevice,

Int16 nInputChannel

);

[C++]

public: enumInputChannelTypes GetInputDeviceChannelType (

Int16 nInputDevice,

Int16 nInputChannel

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nInputChannel | Number representing the zero-based index of the requested input channel

Return value

Value

Meaning

Negative value

An error occurred, check the LastError property value in order to see the error code meaning

>= 0

Type of channel.

Supported values are the following:

Mnemonic constant | Value | Meaning
INPUT_CHANNEL_TYPE_UNDEF | 0 | Undefined channel type
INPUT_CHANNEL_TYPE_MIC | 1 | Microphone
INPUT_CHANNEL_TYPE_LINEIN | 2 | Line In
INPUT_CHANNEL_TYPE_DIGITAL_INTERFACE | 3 | Digital interface
INPUT_CHANNEL_TYPE_MIDI_SYNTH | 4 | MIDI synthesizer
INPUT_CHANNEL_TYPE_ANALOG_AUDIO_CD | 5 | Analog audio CD
INPUT_CHANNEL_TYPE_PHONE | 6 | Phone
INPUT_CHANNEL_TYPE_PC_SPEAKER | 7 | PC Speaker
INPUT_CHANNEL_TYPE_WAVEMIX | 8 | Wave mixer
INPUT_CHANNEL_TYPE_AUX | 9 | Auxiliary
INPUT_CHANNEL_TYPE_ANALOG | 10 | Analog input


GetInputDeviceChannelVolume method

GetInputDeviceChannelVolume method

Remarks

Retrieves the current volume for the given channel on the given input device.

The chosen channel's volume can be modified using the SetInputDeviceChannelVolume method.

The total number of available input channels for the given input device can be obtained using the GetInputDeviceChannelsCount method.

Syntax

[Visual Basic]

Public Function GetInputDeviceChannelVolume (

nInputDevice as Int16,

nInputChannel as Int16

) as Int16

[C#]

public Int16 GetInputDeviceChannelVolume (

Int16 nInputDevice,

Int16 nInputChannel

);

[C++]

public: Int16 GetInputDeviceChannelVolume (

Int16 nInputDevice,

Int16 nInputChannel

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nInputChannel | Number representing the zero-based index of the requested input channel (Microphone, Stereo Mix, Line-In, etc.)

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
>= 0 | The channel's volume: can be a value between 0 and 100


GetInputDeviceDesc method

GetInputDeviceDesc method

Remarks

Retrieves the friendly description of the requested input device (sound card). This method is very useful when you have to fill a combo box with the friendly names of the available input devices.

The total number of available input devices can be obtained using the GetInputDevicesCount method.

Syntax

[Visual Basic]

Public Function GetInputDeviceDesc (

nInputDevice as Int16

) as String

[C#]

public string GetInputDeviceDesc (

Int16 nInputDevice

);

[C++]

public: string GetInputDeviceDesc (

Int16 nInputDevice

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device whose friendly name must be retrieved

Return value

Value | Meaning
Empty string | The value of the nInputDevice parameter was out of range. Use the value returned by the GetInputDevicesCount method in order to know how many input devices are currently installed on the system.
Valid string | The string containing the friendly description of the requested input device.


GetInputDeviceDriverType method

GetInputDeviceDriverType method

Remarks

Given the index of an input device returns its type of driver.

For further information about ASIO drivers management, refer to the How to manage ASIO drivers tutorial.

Syntax

[Visual Basic]

Public Function GetInputDeviceDriverType (

nInputDevice as Int16

) as enumDriverTypes

[C#]

public enumDriverTypes GetInputDeviceDriverType (

Int16 nInputDevice

);

[C++]

public: enumDriverTypes GetInputDeviceDriverType (

Int16 nInputDevice

);

Parameter | Description
nInputDevice | Zero-based index of the input device as enumerated by the combination of the GetInputDevicesCount and GetInputDeviceDesc methods.

Return value

Value

Meaning

Negative value

An error occurred, check the LastError property value in order to see the error code meaning

>= 0

Type of driver.

Supported values are the following:

Mnemonic constant | Value | Meaning
DRIVER_TYPE_DIRECT_SOUND | 0 | The input devices is DirectSound
DRIVER_TYPE_ASIO | 1 | The input devices is ASIO


GetInputDevicesCount method

GetInputDevicesCount method

Remarks

Retrieves the number of input devices (sound cards) currently installed on the system.

The friendly name of each input device can be obtained using the GetInputDeviceDesc method.

Syntax

[Visual Basic]

Public Function GetInputDevicesCount (

) as Int16

[C#]

public Int16 GetInputDevicesCount (

);

[C++]

public: Int16 GetInputDevicesCount (

);

Return value

The number of input devices currently installed on the system.


GetOutputDeviceDesc method

GetOutputDeviceDesc method

Remarks

Retrieves the friendly description of the requested output device (sound card). This method is very useful when you have to fill a combo box with the friendly names of the available output devices.

The total number of available output devices can be obtained using the GetOutputDevicesCount 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 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.


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.

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 GetOutputDevicesCount (

) as Int16

[C#]

public Int16 GetOutputDevicesCount (

);

[C++]

public: Int16 GetOutputDevicesCount (

);

Return value

The number of output devices currently installed on the system.


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


MixerMuteSet method

MixerMuteSet method

Remarks

Modifies the mute state for a specific component of the given mixer.

The current mute state can be modified using the MixerMuteGet method.

The number of mixers currently installed on the system can be retrieved 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.ERR_NOERROR (0) | The method call was successful


MixerVolumeGet method

MixerVolumeGet method

Remarks

Obtains the volume from a specific component of the given mixer.

The returned volume can be modified using the MixerVolumeSet method.

The number of mixers currently installed on the system can be retrieved using the MixerGetCount method. A friendly description of the mixer can be retrieved using the MixerGetDesc method.

IMPORTANT NOTE ABOUT THE WINDOWS VERSION: This method is only intended for usage when the operating system is Windows XP or older versions; for Windows Vista and higher versions it's recommended using methods exposed by the 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.ERR_NOERROR (0) | The method call was successful


MixerVolumeSet method

MixerVolumeSet method

Remarks

Sets the volume on a specific component of the given mixer: changing this volume will affect the volume also for other applications currently using the given mixer inside the system.

The current volume can be retrieved using the MixerVolumeGet method.

The number of mixers currently installed on the system can be retrieved using the MixerGetCount method. A friendly description of the mixer can be retrieved using the MixerGetDesc method.

IMPORTANT NOTE ABOUT THE WINDOWS VERSION: This method is only intended for usage when the operating system is Windows XP or older versions; for Windows Vista and higher versions it's recommended using methods exposed by the 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.ERR_NOERROR (0) | The method call was successful


SetInputDeviceChannelDefault method

SetInputDeviceChannelDefault method

Remarks

Sets the new default channel for the given input device.

The friendly name of each input channel can be obtained using the GetInputDeviceChannelDesc 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 SetInputDeviceChannelDefault (

nInputDevice as Int16,

nInputChannel as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SetInputDeviceChannelDefault (

Int16 nInputDevice,

Int16 nInputChannel

);

[C++]

public: enumErrorCodes SetInputDeviceChannelDefault (

Int16 nInputDevice,

Int16 nInputChannel

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nInputChannel | Number representing the zero-based index of the new default input channel (Microphone, Stereo Mix, Line-In, etc.)

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.


SetInputDeviceChannelVolume method

SetInputDeviceChannelVolume method

Remarks

Sets the new volume for the given channel on the given input device

The chosen channel's current volume can be retrieved using the GetInputDeviceChannelVolume method.

The total number of available input channels for the given input device can be obtained using the GetInputDeviceChannelsCount 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 SetInputDeviceChannelVolume (

nInputDevice as Int16,

nInputChannel as Int16,

nVolume as Int16

) as Int16

[C#]

public Int16 SetInputDeviceChannelVolume (

Int16 nInputDevice,

Int16 nInputChannel,

Int16 nVolume

);

[C++]

public: Int16 SetInputDeviceChannelVolume (

Int16 nInputDevice,

Int16 nInputChannel,

Int16 nVolume

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nInputChannel | Number representing the zero-based index of the requested input channel (Microphone, Stereo Mix, Line-In, etc.)
nVolume | The new channel's volume: can be a value between 0 and 100

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.


VerifyDirectSoundInputDevice method

VerifyDirectSoundInputDevice method

Remarks

Verifies if the given DirectSound input device can be used for recording.

Syntax

[Visual Basic]

Public Function VerifyDirectSoundInputDevice (

nInputDevice as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes VerifyDirectSoundInputDevice (

Int16 nInputDevice

);

[C++]

public: enumErrorCodes VerifyDirectSoundInputDevice (

Int16 nInputDevice

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device

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.


PositionMarkerAdd method

PositionMarkerAdd method

Remarks

During a recording session, started from one between the StartFromDirectSoundDevice, StartFromAsioDevice, StartFromDjStudioMixer, StartFromWasapiCaptureDevice, StartFromWasapiLoopbackDevice or StartFromWasapiMixer methods, adds a new position marker using the current position of the live recording session. Position markers can be useful to easily retrieve a specific position after completing the recording session.

Although there is no limit to the number of position markers that can be added to a recording session, only one position marker can be added on a specific position. It's not allowed adding a position marker at position 0 of the recording session.

When the recording session has been completed, you can still add further position markers through the PositionMarkerAddOffline method.

The number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerAdd (

nUniqueId as Int32,

strDescription as string

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerAdd (

Int32 nUniqueId,

string strDescription

);

[C++]

public: enumErrorCodes PositionMarkerAdd (

Int32 nUniqueId,

string strDescription

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the position marker.
strDescription | String representing the friendly description of the position marker

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.


PositionMarkerAddOffline method

PositionMarkerAddOffline method

Remarks

Adds a new position marker: differently from the PositionMarkerAdd method, which requires a live recording session, this method can be invoked when the recording session has already been stopped.

Although there is no limit to the number of position markers that can be added to a recording session, only one position marker can be added on a specific position. It's not allowed adding a position marker at position 0 of the recording session.

The number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerAddOffline (

nUniqueId as Int32,

strDescription as string,

nPositionMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerAddOffline (

Int32 nUniqueId,

string strDescription,

Int32 nPositionMs

);

[C++]

public: enumErrorCodes PositionMarkerAddOffline (

Int32 nUniqueId,

string strDescription,

Int32 nPositionMs

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the position marker.
strDescription | String representing the friendly description of the position marker
nPositionMs | The position, expressed in milliseconds, of the position marker

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.


PositionMarkerCountGet method

PositionMarkerCountGet method

Remarks

Obtains the number of position markers previously added through calls to the PositionMarkerAdd method.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerCountGet (

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerCountGet (

ref Int32 nCount

);

[C++]

public: enumErrorCodes PositionMarkerCountGet (

Int32 __gc *nCount

);

Parameter | Description
nCount | Reference that, after returning from the method call, will contain the number of available position markers

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.


PositionMarkerDescGet method

PositionMarkerDescGet method

Remarks

Obtains the friendly description of the given position marker.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerDescGet (

nUniqueId as Int32

) as string

[C#]

public string PositionMarkerDescGet (

Int32 nUniqueId

);

[C++]

public: string PositionMarkerDescGet (

Int32 nUniqueId

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the position marker. The number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method and, for each position marker inside the list, the related unique identifier.can be obtained through the PositionMarkerUniqueIdGet method.

Return value

Value | Meaning
Empty string | The value of the nUniqueId parameter was invalid or the friendly descriptor of the position marker was left empty when calling the PositionMarkerAdd method.
Valid string | The string containing the friendly description of the requested position marker.


PositionMarkerLoad method

PositionMarkerLoad method

Remarks

Loads position markers, previously saved through the PositionMarkerSave method, from an existing XML file or, if supported by the audio format of the latest sound file recorded through the StartFromFile method, directly from the file's tags.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerLoad (

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerLoad (

string strPathname

);

[C++]

public: enumErrorCodes PositionMarkerLoad (

string strPathname

);

Parameter

Description

strPathname

String containing the absolute pathname of the source XML file or an empty string to indicate a different behaviour:

· if the string contains an absolute pathname, position markers are loaded from the given file
· if the string is empty and the audio format of the latest recorded sound file is one of the following, position markers are loaded from a comment field of the tag:

- MP3 (stored inside a COMM field of the ID3V2 tag)

- OGG Vorbis

- WMA

- MP4

- FLAC

· if the string is empty and the audio format of the latest recorded sound file is not on the list above, position markers are automatically loaded from a XML file having exactly the same pathname and filename of the sound file but with extension ".XML"

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.


PositionMarkerPlayRange method

PositionMarkerPlayRange method

Remarks

Plays the sound range, identified by two given position markers, of the last recorded sound. This method can be considered as an alternative to the RecordedSound.PlayRange method.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerPlayRange (

nUniqueIdStart as Int32,

nUniqueIdEnd as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerPlayRange (

Int32 nUniqueIdStart,

Int32 nUniqueIdEnd

);

[C++]

public: enumErrorCodes PositionMarkerPlayRange (

Int32 nUniqueIdStart,

Int32 nUniqueIdEnd

);

Parameter | Description
nUniqueIdStart | Number representing the unique identifier of the start position marker. The number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method and, for each position marker inside the list, the related unique identifier.can be obtained through the PositionMarkerUniqueIdGet method.
nUniqueIdEnd | Number representing the unique identifier of the end position marker. Set this value to -1 if you want to play till the end of the recorded sound.

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.


PositionMarkerPosGet method

PositionMarkerPosGet method

Remarks

Obtains the position of the given position marker. The current position can be modified through the PositionMarkerPosSet method.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerPosGet (

nUniqueId as Int32,

ByRef nPositionInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerPosGet (

Int32 nUniqueId,

ref Int32 nPositionInMs

);

[C++]

public: enumErrorCodes PositionMarkerPosGet (

Int32 nUniqueId,

Int32 __gc *nPositionInMs

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the position marker. The number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method and, for each position marker inside the list, the related unique identifier.can be obtained through the PositionMarkerUniqueIdGet method.
nPositionInMs | Reference that, after returning from the method call, will contain the position, expressed in milliseconds, of the position marker.

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.


PositionMarkerPosSet method

PositionMarkerPosSet method

Remarks

Sets the position of the given position marker. The current position can be retrieved through the PositionMarkerPosGet method.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerPosSet (

nUniqueId as Int32,

nPositionInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerPosSet (

Int32 nUniqueId,

Int32 nPositionInMs

);

[C++]

public: enumErrorCodes PositionMarkerPosSet (

Int32 nUniqueId,

Int32 nPositionInMs

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the position marker. The number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method and, for each position marker inside the list, the related unique identifier.can be obtained through the PositionMarkerUniqueIdGet method.
nPositionInMs | The position, expressed in milliseconds, of the position marker.

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.


PositionMarkerRemove method

PositionMarkerRemove method

Remarks

Removes the given position marker.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerRemove (

nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerRemove (

Int32 nUniqueId

);

[C++]

public: enumErrorCodes PositionMarkerRemove (

Int32 nUniqueId

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the position marker. The number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method and, for each position marker inside the list, the related unique identifier.can be obtained through the PositionMarkerUniqueIdGet 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.


PositionMarkerSave method

PositionMarkerSave method

Remarks

Saves existing position markers added during the latest recording session into a destination file in XML format or, if supported by the output audio format of the recoding session, directly into the file's tags. Saved position markers can be loaded at a later time through the PositionMarkerLoad method.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerSave (

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerSave (

string strPathname

);

[C++]

public: enumErrorCodes PositionMarkerSave (

string strPathname

);

Parameter

Description

strPathname

String containing the absolute pathname of the destination XML file or an empty string to indicate a different behaviour:

· if the string contains an absolute pathname, position markers are stored inside the given file
· if the string is empty and the output audio format is one of the following, position markers are stored inside a comment field of the tag:

- MP3 (stored inside a COMM field of the ID3V2 tag)

- OGG Vorbis

- WMA

- MP4

- FLAC

· if the string is empty and the output audio format is not on the list above, position markers are stored inside a XML file having exactly the same pathname and filename of the audio file being recorded but with extension ".XML"; if for example the recording session should be in WAV format and the output pathname should be set to "C:\myfolder\file.wav", the corresponding position markers file would be saved to "C:\myfolder\file.xml"

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.


PositionMarkerSeekPlayPositionTo method

PositionMarkerSeekPlayPositionTo method

Remarks

During a playback session, started through the RecordedSound.Play or RecordedSound.PlayRange methods, seeks playback position to the position of the given marker.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerSeekPlayPositionTo (

nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerSeekPlayPositionTo (

Int32 nUniqueId

);

[C++]

public: enumErrorCodes PositionMarkerSeekPlayPositionTo (

Int32 nUniqueId

);

Parameter | Description
nUniqueId | Number representing the unique identifier of the position marker. The number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method and, for each position marker inside the list, the related unique identifier.can be obtained through the PositionMarkerUniqueIdGet 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.


PositionMarkerUniqueIdGet method

PositionMarkerUniqueIdGet method

Remarks

Obtains the unique ID of a given position marker.

For details about recording from input devices see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function PositionMarkerUniqueIdGet (

nIndex as Int32,

ByRef nUniqueId as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionMarkerUniqueIdGet (

Int32 nIndex,

ref Int32 nUniqueId

);

[C++]

public: enumErrorCodes PositionMarkerUniqueIdGet (

Int32 nIndex,

Int32 __gc *nUniqueId

);

Parameter | Description
nIndex | Zero-based inside of the position marker. The total number of available position markers can be retrieved at the end of the recording session through the PositionMarkerCountGet method.
nUniqueId | Reference that, after returning from the method call, will contain the unique identifier of the position marker.

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.


EnableAutoGainController method

EnableAutoGainController method

Remarks

Enables/disables the Automatic Gain Controller.

For further information about the use of the the Automatic Gain Controller refer to the How to use the automatic gain controller section.

Syntax

[Visual Basic]

Public Sub EnableAutoGainController (

bEnable as Boolean

)

[C#]

public void EnableAutoGainController (

bool bEnable

);

[C++]

public: void EnableAutoGainController (

bool bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if the control must enable the Automatic Gain Controller.

Supported values are the following:

Value | Meaning
false (default) | Disable the Automatic Gain Controller
true | Enable the Automatic Gain Controller

Return value

None


EncryptCurrentSession method

EncryptCurrentSession method

Remarks

Encrypts the latest recording session using the provided key and stores the final result into an output file. The encryption process won't modify contents of the original recording session but will create an encrypted copy of the recording session itself.

Encrypted sound files can be decrypted and loaded at a later time through the StartFromFileEncrypted method.

For security reasons this feature is not included inside the Trial version and is disabled by default inside the Commercial version: if you own the Commercial version and if you wish using encryption features, please, contact us for instructions about enabling this specific feature.

For details about encryption/decryption features see the How to protect your recording sessions through encryption tutorial.

Syntax

[Visual Basic]

Public Function EncryptCurrentSession (

strOutputPath as String,

strEncryptionKey as String

bFreeContents as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EncryptCurrentSession (

string strOutputPath,

string strEncryptionKey,

bool bFreeContents

);

[C++]

public: enumErrorCodes EncryptCurrentSession (

string strOutputPath,

string strEncryptionKey,

bool bFreeContents

);

Parameter

Description

strOutputPath

Absolute pathname of the encrypted destination file.

strEncryptionKey

String containing the key used to encrypt the song: its length can be from a minimum of 16 characters to a maximum of 32 characters.

bFreeContents

Boolean flag that specifies if contents of the current session must be discarded from memory after encryption.

Supported values are the following:

Mnemonic constant

Meaning

false

Doesn't discard current session.

true

Discards current session.

For memory-based recording sessions, this setting is equivalent to calling the RecordedSound.FreeMemory method.

For file-based recording sessions, the original output file won't be deleted but the control will no more consider it as belonging to the latest recording session.

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.


ExtractAudioAbort method

ExtractAudioAbort method

Remarks

Stops extraction of the audio track from a video clip started through a call to the ExtractAudioFromVideoFile method.

Syntax

[Visual Basic]

Public Function ExtractAudioAbort (

) as enumErrorCodes

[C#]

public enumErrorCodes ExtractAudioAbort (

);

[C++]

public: enumErrorCodes ExtractAudioAbort (

);

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.


ExtractAudioFromVideoFile method

ExtractAudioFromVideoFile method

Remarks

Starts extraction of the audio track from a video clip into an output sound file: in this case contents of the resulting output file is not loaded into the recorder directly so, in case you should need to edit the output sound file, once extraction will be completed, you will have to load it with a call to the StartFromFile method.

Loading of video clips is implemented through interaction with DirectShow so, in order to open some specific video format, there may be the need of a specific DirectShow filter.

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.

This method can only work with the EncodeFormats.ResampleMode property set to RESAMPLE_MODE_CUSTOM_FORMAT.

As seen for recording sessions, the format of the output sound file can be set through the EncodeFormats.ForRecording property.

An extraction session can be stopped at any time through a call to the ExtractAudioAbort method.

During the extraction, the container application will be notified about the exporting advancement through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_AUDIO_EXTRACT_PERC.

Syntax

[Visual Basic]

Public Function ExtractAudioFromVideoFile (

nFrequency as Int32,

nChannels as Int32,

strOutputPath as string,

strInputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes ExtractAudioFromVideoFile (

Int32 nFrequency,

Int32 nChannels,

string strOutputPath

string strInputPath

);

[C++]

public: enumErrorCodes ExtractAudioFromVideoFile (

Int32 nFrequency,

Int32 nChannels,

string strOutputPath

string strInputPath

);

Parameter

Description

nFrequency

Frequency used to resample the sound to export (44100, 22050, etc.). This parameter is ignored when:

· the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE
· the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM

nChannels

Number of channels used to resample the sound to export (1 for Mono or 2 for Stereo). This parameter is ignored when:

· the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE
· the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM

strOutputPath

String containing the absolute pathname of the destination audio file. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

strInputPath

String containing the absolute pathname of the source video file. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


FilterApply method

FilterApply method

Remarks

Applies an embedded filter to the recording stream. Current parameters can be modified through the FilterParametersSet method.

For further information about the use of embedded filters refer to the How to apply embedded filters section.

Syntax

[Visual Basic]

Public Function FilterApply (

nFilterName as enumFilterNames,

nFilterType as enumFilterTypes,

fFrequency1 as Single,

fFrequency2 as Single,

fGain as Single,

fTransitionTime as Single

) as enumErrorCodes

[C#]

public enumErrorCodes FilterApply (

enumFilterNames nFilterName,

enumFilterTypes nFilterType,

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

[C++]

public: enumErrorCodes FilterApply (

enumFilterNames nFilterName,

enumFilterTypes nFilterType,

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

Parameter

Description

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 recording which can be determined in two ways:

· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_CUSTOM_FORMAT, through the EncodeFormats.ResampleCustomFrequency property
· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_NATIVE_FORMAT, through the frequency established by the value set into the EncodeFormats.ResampleNativeFormat property

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 under editing; the frequency of the recording which can be determined in two ways:

· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_CUSTOM_FORMAT, through the EncodeFormats.ResampleCustomFrequency property
· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_NATIVE_FORMAT, through the frequency established by the value set into the EncodeFormats.ResampleNativeFormat property

fGain

Gain applied to the filter, expressed in percentage: typically this parameter should be set to 100 which leaves the original sound level unchanged during filtering; values under 100 reduce the sound level while values above 100 amplify the sound level.

This parameter is ignored by IIR filters like Bessel and Butterworth.

fTransitionTime

Transition time, expressed in milliseconds, describes how quickly a filter transitions from a pass band to a stop band, or vice versa.

The minimum accepted value is 201 milliseconds.

This parameter is ignored by IIR filters like Bessel and Butterworth.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


FilterParametersGet method

FilterParametersGet method

Remarks

Obtains parameters of the filter currently applied to the recording stream through the FilterApply method. Current parameters can be modified through the FilterParametersSet method.

For further information about the use of embedded filters refer to the How to apply embedded filters section.

Syntax

[Visual Basic]

Public Function FilterParametersGet (

ByRef nFilterName as enumFilterNames,

ByRef nFilterType as enumFilterTypes,

ByRef fFrequency1 as Single,

ByRef fFrequency2 as Single,

ByRef fGain as Single,

ByRef fTransitionTime as Single

) as enumErrorCodes

[C#]

public enumErrorCodes FilterParametersGet (

ref enumFilterNames nFilterName,

ref enumFilterTypes nFilterType,

ref float fFrequency1,

ref float fFrequency2,

ref float fGain,

ref float fTransitionTime

);

[C++]

public: enumErrorCodes FilterParametersGet (

enumFilterNames __gc *nFilterName,

enumFilterTypes __gc *nFilterType,

float __gc *fFrequency1,

float __gc *fFrequency2,

float __gc *fGain,

float __gc *fTransitionTime

);

Parameter

Description

nFilterName

Reference that, after returning from the method call, will contain the 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

Reference that, after returning from the method call, will contain the 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

Reference that, after returning from the method call, will contain the 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 recording which can be determined in two ways:

· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_CUSTOM_FORMAT, through the EncodeFormats.ResampleCustomFrequency property
· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_NATIVE_FORMAT, through the frequency established by the value set into the EncodeFormats.ResampleNativeFormat property

fFrequency2

Reference that, after returning from the method call, will contain the 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 the recording which can be determined in two ways:

· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_CUSTOM_FORMAT, through the EncodeFormats.ResampleCustomFrequency property
· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_NATIVE_FORMAT, through the frequency established by the value set into the EncodeFormats.ResampleNativeFormat property

fGain

Reference that, after returning from the method call, will contain the 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

Reference that, after returning from the method call, will contain the transition time, expressed in milliseconds, describes how quickly a filter transitions from a pass band to a stop band, or vice versa.

The minimum accepted value is 201 milliseconds.

This parameter is ignored by IIR filters like Bessel and Butterworth.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


FilterParametersSet method

FilterParametersSet method

Remarks

Modifies parameters of the filter currently applied to the recording stream through the FilterApply method. Current parameters can be obtained through the FilterParametersGet method.

For further information about the use of embedded filters refer to the How to apply embedded filters section.

Syntax

[Visual Basic]

Public Function FilterParametersSet (

fFrequency1 as Single,

fFrequency2 as Single,

fGain as Single,

fTransitionTime as Single

) as enumErrorCodes

[C#]

public enumErrorCodes FilterParametersSet (

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

[C++]

public: enumErrorCodes FilterParametersSet (

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

Parameter

Description

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 recording which can be determined in two ways:

· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_CUSTOM_FORMAT, through the EncodeFormats.ResampleCustomFrequency property
· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_NATIVE_FORMAT, through the frequency established by the value set into the EncodeFormats.ResampleNativeFormat property

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 under editing; the frequency of the recording which can be determined in two ways:

· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_CUSTOM_FORMAT, through the EncodeFormats.ResampleCustomFrequency property
· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_NATIVE_FORMAT, through the frequency established by the value set into the EncodeFormats.ResampleNativeFormat property

fGain

Gain applied to the filter, expressed in percentage: typically this parameter should be set to 100 which leaves the original sound level unchanged during filtering; values under 100 reduce the sound level while values above 100 amplify the sound level.

This parameter is ignored by IIR filters like Bessel and Butterworth.

fTransitionTime

Transition time, expressed in milliseconds, describes how quickly a filter transitions from a pass band to a stop band, or vice versa.

The minimum accepted value is 201 milliseconds.

This parameter is ignored by IIR filters like Bessel and Butterworth.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


FilterReset method

FilterReset method

Remarks

Resets the filter previously applied to the recording stream through the FilterApply method..

For further information about the use of embedded filters refer to the How to apply embedded filters section.

Syntax

[Visual Basic]

Public Function FilterReset (

) as enumErrorCodes

[C#]

public enumErrorCodes FilterReset (

);

[C++]

public: enumErrorCodes FilterReset (

);

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.


GetAutoGainControllerSettings method

GetAutoGainControllerSettings method

Remarks

Gets the current Automatic Gain Controller settings.

For further information about the use of the the Automatic Gain Controller refer to the How to use the automatic gain controller section.

Syntax

[Visual Basic]

Public Function GetAutoGainControllerSettings (

ByRef nAmplificationTargetLevel as Int16,

ByRef nAmplificationQuietLevel as Int16,

ByRef nAmplificationAdjustmentRate as Int16,

ByRef nAmplificationGain as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes GetAutoGainControllerSettings (

ref Int16 nAmplificationTargetLevel,

ref Int16 nAmplificationQuietLevel,

ref Int16 nAmplificationAdjustmentRate,

ref Int16 nAmplificationGain

);

[C++]

public: enumErrorCodes GetAutoGainControllerSettings (

Int16 __gc *nAmplificationTargetLevel,

Int16 __gc *nAmplificationQuietLevel,

Int16 __gc *nAmplificationAdjustmentRate,

Int16 __gc *nAmplificationGain

);

Parameter

Description

nAmplificationTargetLevel

Reference that, after returning from the method call, will contain the target volume level, expressed in percentage.

The default value is 92%

nAmplificationQuietLevel

Reference that, after returning from the method call, will contain the quiet volume level, expressed in percentage.

The default value is 3%

nAmplificationAdjustmentRate

Reference that, after returning from the method call, will contain the amplification adjustment rate, expressed in percentage.

The default value is 2%

nAmplificationGain

Reference that, after returning from the method call, will contain the amplification gain level, expressed in percentage.

The default value is 100% which means that the input sound level will not be changed. Higher values (200, 300, 400, etc.) mean that the incoming sound level will be amplified while smaller values mean that the incoming sound level will be attenuated.

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


LoadSoundForPlayback method

LoadSoundForPlayback method

Remarks

Loads a sound from a given pathname for playback purposes only. After this call the sound is not available for editing or analysis purposes: for editing purposes you should use the StartFromFile method.

Accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, M4A, AC3, FLAC, WavPack, ALAC, WAV, OGG Vorbis, OPUS, WMA (*), ASF (**), WMV (**), AIFF, AU, W64, PAF, SVX, NIST, VOC, IRCAM, PVF and CAF.

Multichannel WAV, AIFF, OGG Vorbis, OPUS and WMA formats are not supported and will be resampled and converted to stereo during the loading procedure.

Accepted MOD formats are: MOD, MTM, S3M, XM, IT and MO3.

Accepted CD audio tracks format is CDA.

No event is generated by this method and the loaded sound file is immediately available for playback after the call.

Syntax

[Visual Basic]

Public Function LoadSoundForPlayback (

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes LoadSoundForPlayback (

string strPathname

);

[C++]

public: enumErrorCodes LoadSoundForPlayback (

string strPathname

);

Parameter | Description
strPathname | String representing the absolute pathname of the input file.

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.

(*) 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 only sound tracks (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs only sound frames (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).


OutputDeviceGetCount method

OutputDeviceGetCount 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 OutputDeviceGetDesc method.

Syntax

[Visual Basic]

Public Function OutputDeviceGetCount (

) as Int16

[C#]

public Int16 OutputDeviceGetCount (

);

[C++]

public: Int16 OutputDeviceGetCount (

);

Return value

The number of output devices currently installed on the system.


OutputDeviceGetDesc method

OutputDeviceGetDesc 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 OutputDeviceGetCount method.

Syntax

[Visual Basic]

Public Function OutputDeviceGetDesc (

nOutputIndex as Int16

) as String

[C#]

public string OutputDeviceGetDesc (

Int16 nOutputIndex

);

[C++]

public: string OutputDeviceGetDesc (

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 nIndex parameter was out of range. Use the value returned by the OutputDeviceGetCount 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.


OutputDeviceGet method

OutputDeviceGet method

Remarks

Retrieves the current output device (sound card) used for playback. The output device can be changed at any time through the OutputDeviceSet method.

Syntax

[Visual Basic]

Public Function OutputDeviceGet (

) as Int16

[C#]

public Int16 OutputDeviceGet (

);

[C++]

public: Int16 OutputDeviceGet (

);

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


OutputDeviceSet method

OutputDeviceSet method

Remarks

Changes the output device (sound card) used for playback. This method can be called at any time, also during playback. The current selected device can be obtained through the OutputDeviceGet method.

Use the value returned by the OutputDeviceGetCount method in order to know how many output devices are currently installed on the system and the OutputDeviceGetDesc method in order to retrieve the friendly name of every output device.

Syntax

[Visual Basic]

Public Function OutputDeviceSet (

nOutputIndex as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes OutputDeviceSet (

Int16 nOutputIndex

);

[C++]

public: enumErrorCodes OutputDeviceSet (

Int16 nOutputIndex

);

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


OutputVolumeGet method

OutputVolumeGet method

Remarks

Retrieves the current volume. The volume can be changed through the OutputVolumeSet method.

Syntax

[Visual Basic]

Public OutputVolumeGet (

nScaleType as enumVolumeScales

) as float

[C#]

public float OutputVolumeGet (

enumVolumeScales nScaleType

);

[C++]

public: float OutputVolumeGet (

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 volume


OutputVolumeSet method

OutputVolumeSet method

Remarks

Changes the playback volume: changing this volume will not affect the volume of other applications. The current volume can be retrieved through the OutputVolumeGet method.

Syntax

[Visual Basic]

Public Function OutputVolumeSet (

nVolume as float,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes OutputVolumeSet (

float nVolume,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes OutputVolumeSet (

float nVolume,

enumVolumeScales nScaleType

);

Parameter

Description

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


Pause method

Pause method

Remarks

Pauses the current recording session.

Calling this method will cause the container application to be notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_PAUSED.

Syntax

[Visual Basic]

Public Function Pause (

) as enumErrorCodes

[C#]

public enumErrorCodes Pause (

);

[C++]

public: enumErrorCodes Pause (

);

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.


RequestUploadFileToFTP method

RequestUploadFileToFTP method

Remarks

Requests to start an uploading session of a given file to a FTP server.

This method can be used in place of the RecordedSound.RequestUploadToFTP method when you need to upload the encrypted file generated by a previous call to the EncryptCurrentSession method or when you need to transfer a generic file.

An uploading session can be terminated before completion through a call to the RecordedSound.CancelUploadToFTP method.

During uploading session the container application is notified about the advancement percentage through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_SOUND_UPLOAD_PERC.

For details about encryption/decryption features see the How to protect your recording sessions through encryption tutorial.

Syntax

[Visual Basic]

Public Function RequestUploadFileToFTP (

strInputPathname as String,

strHost as String,

strUsername as String,

strPassword as String,

nPort as Int32,

bPassiveMode as Boolean,

strDirectory as String,

strFilename as String,

) as enumErrorCodes

[C#]

public enumErrorCodes RequestUploadFileToFTP (

string strInputPathname,

string strHost,

string strUsername,

string strPassword,

Int32 nPort,

bool bPassiveMode,

string strDirectory,

string strFilename

);

[C++]

public: enumErrorCodes RequestUploadFileToFTP (

string strInputPathname,

string strHost,

string strUsername,

string strPassword,

Int32 nPort,

bool bPassiveMode,

string strDirectory,

string strFilename

);

Parameter

Description

strInputPathname

Absolute pathname of the file that needs to be uploaded to the FTP site.

strHost

String representing the FTP host address, without the protocol prefix (for example "ftp.multimediasoft.com" instead of "ftp://ftp.multimediasoft.com")

strUsername

String representing the FTP account username

strPassword

String representing the FTP account password

nPort

FTP port number (for example 21)

bPassiveMode

Boolean value for FTP "passive mode" flag.

Supported values are the following:

Mnemonic Value | Meaning
false | Don't use passive mode
true | Use passive mode

strDirectory

String representing the destination directory on FTP server

strFilename

String representing the destination filename

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.


Resume method

Resume method

Remarks

Resumes a paused recording session.

Calling this method will cause the container application to be notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_RESUMED.

Syntax

[Visual Basic]

Public Function Resume (

) as enumErrorCodes

[C#]

public enumErrorCodes Resume (

);

[C++]

public: enumErrorCodes Resume (

);

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.


SendDataToQueueRaw method

SendDataToQueueRaw method

Remarks

Sends raw PCM audio data to the queue previously started through the StartFromQueueRaw method..

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SendDataToQueueRaw (

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SendDataToQueueRaw (

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes SendDataToQueueRaw (

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
pBuffer | Input buffer containing RAW audio data in the same format established by the StartFromQueueRaw method
nBufferLen | Length of the input 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.


SetAutoGainControllerSettings method

SetAutoGainControllerSettings method

Remarks

Sets the current Automatic Gain Controller settings.

For further information about the use of the the Automatic Gain Controller refer to the How to use the automatic gain controller section.

Syntax

[Visual Basic]

Public Function SetAutoGainControllerSettings (

nAmplificationTargetLevel as Int16,

nAmplificationQuietLevel as Int16,

nAmplificationAdjustmentRate as Int16,

nAmplificationGain as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SetAutoGainControllerSettings (

Int16 nAmplificationTargetLevel,

Int16 nAmplificationQuietLevel,

Int16 nAmplificationAdjustmentRate,

Int16 nAmplificationGain

);

[C++]

public: enumErrorCodes SetAutoGainControllerSettings (

Int16 nAmplificationTargetLevel,

Int16 nAmplificationQuietLevel,

Int16 nAmplificationAdjustmentRate,

Int16 nAmplificationGain

);

Parameter | Description
nAmplificationTargetLevel | The target volume level, expressed in percentage. The default value is 92%
nAmplificationQuietLevel | The quiet volume level, expressed in percentage. The default value is 3%
nAmplificationAdjustmentRate | The amplification adjustment rate, expressed in percentage. The default value is 2%
nAmplificationGain | The amplification gain level, expressed in percentage. The default value is 100% which means that the input sound level will not be changed: Setting higher values (200, 300, 400, etc.) will amplify the incoming sound level while setting smaller values will attenuate the incoming sound level.

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


SetInsertPos method

SetInsertPos method

Remarks

Sets the position where a new recording session (whose recording mode has been set to REC_MODE_INSERT through a call to the SetRecordingMode method) will inserted into the existing one.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SetInsertPos (

nPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetInsertPos (

Int32 nPosition

);

[C++]

public: enumErrorCodes SetInsertPos (

Int32 nPosition

);

Parameter | Description
nPosition | Insertion position expressed in milliseconds.

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.


SetMixingParams method

SetMixingParams method

Remarks

Sets the parameters used for mixing an existing sound to the actual recording session contents.

This feature is very useful if you want to apply a background sound to your recording session. The background sound can be also put in loop for a given range.

For details about applying a background sound to your recording session, take a look to the How to mix sounds to your recording session tutorial.

Syntax

[Visual Basic]

Public Function SetMixingParams (

nStartPosition as Int32,

nEndPosition as Int32,

nNewSoundSeekPosition as Int32,

bStopMixOnCompletion as Boolean,

bLoop as Boolean,

fVolumeOriginalSound as Single,

fVolumeNewSound as Single,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes SetMixingParams (

Int32 nStartPosition,

Int32 nEndPosition,

Int32 nNewSoundSeekPosition,

bool bStopMixOnCompletion,

bool bLoop,

float fVolumeOriginalSound,

float fVolumeNewSound,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes SetMixingParams (

Int32 nStartPosition,

Int32 nEndPosition,

Int32 nNewSoundSeekPosition,

bool bStopMixOnCompletion,

bool bLoop,

float fVolumeOriginalSound,

float fVolumeNewSound,

enumVolumeScales nScaleType

);

Parameter

Description

nStartPosition

Number representing the start position, expressed in milliseconds, inside the recording session where the mixing will begin

nEndPosition

Number representing the end position, expressed in milliseconds, inside the recording session where the mixing will end: if this parameter is set to -1, the mixing will be applied till the end of the recording session

nNewSoundSeekPosition

Initial seek position, expressed in milliseconds, inside the loaded sound: sound data before this position will be ignored and not mixed to the actual contents of the recording session

bStopMixOnCompletion

Boolean value that specifies if the mixing session should stop when the end of the current recording session or the nEndPosition position are reached

bLoop

Boolean value that specifies if the sound mixed to the recording session must be put in loop: it's important to note that, if the input sound file in loop mode should exceed the defined range limit, it would be in any case mixed until its completion so no unwanted cut would result on the input sound.

fVolumeOriginalSound

Floating point value representing the volume applied to the portion of recording session affected by the mixing session

fVolumeNewSound

Floating point value representing the volume applied to the loaded sound that will be mixed to the actual recording session contents

nScaleType

The volume scaling type.

Supported values are the following:

Mnemonic constant

Value

Meaning

SCALE_LINEAR

0

The passed volume is based upon a linear scale and can be in the range from 0.0 (silence) to 100.0 (max volume)

SCALE_LOG

1

The passed volume, expressed in dB, is based upon a logarithmic scale and can be in the range from -100 (silence) to 0 (max volume)

The actual applied formula for converting a linear volume into a logarithmic volume is the following:

VolumeInDB = 20 * log10 (VolumeLinear/100)

The C syntax for converting a logarithmic volume into a linear volume is the following:

VolumeLinear = 100 * pow (10, VolumeInDB/20);

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


SetMixingPos method

SetMixingPos method

Remarks

Sets the position where a new recording session (whose recording mode has been set to REC_MODE_MIX through a call to the SetRecordingMode method) will be mixed into the existing one.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SetMixingPos (

nPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetMixingPos (

Int32 nPosition

);

[C++]

public: enumErrorCodes SetMixingPos (

Int32 nPosition

);

Parameter | Description
nPosition | Mixing position expressed in milliseconds.

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.


SetOverwritePos method

SetOverwritePos method

Remarks

Sets the position where a new recording session (whose recording mode has been set to REC_MODE_OVERWRITE through a call to the SetRecordingMode method) will overwrite an existing one.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SetOverwritePos (

nPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetOverwritePos (

Int32 nPosition

);

[C++]

public: enumErrorCodes SetOverwritePos (

Int32 nPosition

);

Parameter | Description
nPosition | Overwrite position expressed in milliseconds.

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.


SetRecordingMode method

SetRecordingMode method

Remarks

Sets the recording mode which will determine where incoming sound data will be stored inside a new recording session.

It's important to remember that recording sessions whose recording mode is set to a value different from REC_MODE_NEW must be always of the same nature, i.e. with output to memory or with output to file: trying to mix memory based sessions with file based session will cause an error.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SetRecordingMode (

nMode as enumRecordingModes

) as enumErrorCodes

[C#]

public enumErrorCodes SetRecordingMode (

enumRecordingModes nMode

);

[C++]

public: enumErrorCodes SetRecordingMode (

enumRecordingModes nMode

);

Parameter

Description

nMode

Number representing the recording mode that will affect the behaviour of the next recording session started by methods like StartFromDirectSoundDevice.

Supported values are the following:

Mnemonic constant | Value | Meaning
REC_MODE_NEW (Default) | 0 | Creates a fresh new recording session.
REC_MODE_APPEND | 1 | Appends the new recording session to the previous one.
REC_MODE_MIX | 2 | Mixes the new recording session at a given position of the previous one. You can set the exact mixing position through a call to the SetMixingPos method: if you don't define a mixing position, the new recording session will be mixed starting from the beginning of the previous recording session.
REC_MODE_INSERT | 3 | Inserts the new recording session at a given position of the previous one. You can set the exact insert position through a call to the SetInsertPos method: if you don't define an insertion position, the new recording session will be inserted on the beginning of the previous recording session.
REC_MODE_OVERWRITE | 4 | Overwrites the previous recording session at a given position with the latest one. You can set the exact overwrite position through a call to the SetOverwritePos method: if you don't define an overwrite position, the new recording session will overwrite the previous one from its beginning.

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.


SetRecordingRange method

SetRecordingRange method

Remarks

Sets a recording range that automatically stops a file recording session when a given position is reached.

Syntax

[Visual Basic]

Public Function SetRecordingRange (

nStartPosition as Int32,

nEndPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetRecordingRange (

Int32 nStartPosition,

Int32 nEndPosition

);

[C++]

public: enumErrorCodes SetRecordingRange (

Int32 nStartPosition,

Int32 nEndPosition

);

Parameter | Description
nStartPosition | Start position expressed in milliseconds. This parameter is used only when the recording session has been started through the StartFromClipboard, StartFromFile, StartFromFileRaw, StartFromMemory and StartFromMemoryRaw methods while is ignored when the recording sessions has been started through other recording methods like StartFromDirectSoundDevice, StartFromURL and so on.
nEndPosition | End position expressed in milliseconds. Set this parameter to -1 for recording till the end of a sound file or till the moment in which the recording session will be manually stopped through a call to the Stop 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.


SplitWavRecordingEnable method

SplitWavRecordingEnable method

Remarks

Enables/disables the splitting in chunks of a recording session whose EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV and the EncodeFormats.WAV.EncodeMode property is set to one between WAV_ENCODE_PCM_U8, WAV_ENCODE_PCM_S16 or WAV_ENCODE_FLOAT32: this method call will be ignored when using other encoding formats and/or encoding modes.

Splitting is disabled by default. When splitting is enabled, the control will automatically save on output files (chunks) the given duration of sound data: it's important to note that the recording session will in any case continue storing sound data on the original output file.

Each time a chunk is completed and saved the container application to be notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_WAV_CHUNK_SAVED.

Syntax

[Visual Basic]

Public Function SplitWavRecordingEnable (

bEnable as Boolean,

nChunkDurationInMs as Int32,

strChunkOutputPath as string,

strChunkFilenamePrefix as string

) as enumErrorCodes

[C#]

public enumErrorCodes SplitWavRecordingEnable (

bool bEnable,

Int32 nChunkDurationInMs,

string strChunkOutputPath,

string strChunkFilenamePrefix

);

[C++]

public: enumErrorCodes SplitWavRecordingEnable (

bool bEnable,

Int32 nChunkDurationInMs,

string strChunkOutputPath,

string strChunkFilenamePrefix

);

Parameter

Description

bEnable

Boolean flag that enables/disables the splitting procedure.

Supported values are the following:

Value | Meaning
false | Disables splitting
true | Enables splitting

nChunkDurationInMs

Numeric values which defines the duration for each saved chunk expressed in milliseconds

strChunkOutputPath

String representing the absolute path where chunks will be saved, for example "C:\MyFolder\"

strChunkFilenamePrefix

String representing the prefix of the chunk filename, for example "MyChunk": each time a new chunk is saved, the filename will be modified adding the number of the chunk followed by the ".wav" extension (MyChunk1.wav, MyChunk2.wav, MyChunk3.wav, etc.)

If this parameter is left empty, the control will automatically set the filename prefix to "WavChunk".

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.


StartFromAsioDevice method

StartFromAsioDevice method

Remarks

Starts a recording session getting sound data from one or more input channels of the given ASIO device.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the Stop method.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

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 StartFromAsioDevice (

nInputDevice as Int16,

nFirstChannel as Int16,

nTotalChannels as Int16,

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromAsioDevice (

Int16 nInputDevice,

Int16 nFirstChannel,

Int16 nTotalChannels,

string strOutputPath

);

[C++]

public: enumErrorCodes StartFromAsioDevice (

Int16 nInputDevice,

Int16 nFirstChannel,

Int16 nTotalChannels,

string strOutputPath

);

Parameter

Description

nInputDevice

Number representing the zero-based index of the ASIO device that will be used for recording. 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 ASIO.DeviceGetDesc method in order to retrieve the friendly name of each ASIO device.

nFirstChannel

Number representing the zero-based index of the first ASIO input channel that will be used for recording on the ASIO device set through the nInputDevice parameter.

nTotalChannels

Total number of ASIO input channels that will be mixed together, starting from the input channel set into the nFirstChannel parameter, and recorded.

All ASIO channels are in mono so let's make some example of use:

- if you should need recording the first pair of input channels, you should specify 0 for the nFirstChannel parameter and 2 for the nTotalChannels parameter.

- if you should need recording 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.

strOutputPath

String representing the absolute pathname of the output file that will contain recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

If this parameter is left empty, recorded data will be stored inside a memory buffer.

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.


StartFromClipboard method

StartFromClipboard method

Remarks

Starts a new recording session from a sound contained inside the system clipboard.

In order to understand if a CF_WAVE format sound is available inside the clipboard you can call the IsSoundAvailableInClipboard method.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartFromClipboard (

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromClipboard (

string strOutputPath

);

[C++]

public: enumErrorCodes StartFromClipboard (

string strOutputPath

);

Parameter | Description
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character. If the string is left empty, the recording session will be performed in memory.

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.


StartFromDirectSoundDevice method

StartFromDirectSoundDevice method

Remarks

Starts a recording session through the given input device and channel.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the Stop method.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function StartFromDirectSoundDevice (

nInputDevice as Int16,

nInputChannel as Int16,

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromDirectSoundDevice (

Int16 nInputDevice,

Int16 nInputChannel,

string strOutputPath

);

[C++]

public: enumErrorCodes StartFromDirectSoundDevice (

Int16 nInputDevice,

Int16 nInputChannel,

string strOutputPath

);

Parameter | Description
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 in order to know how many input devices are currently installed on the system and the GetInputDeviceDesc method 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).
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.. If the string is left empty, the recording session will be performed in memory.

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.


StartFromDjStudioMixer method

StartFromDjStudioMixer method

Remarks

Starts a recording session getting sound data from the output of a given custom stream mixer instanced by Audio DJ Studio API for .NET.

In case the output of the stream mixer should be multi-channel meaning that it was created using the StreamMixerCreateWithSurround method of Audio DJ Studio API for .NET, the recorder could keep channels separated only in case the format of the output file should support multi-channel too, like WAV, Ogg Vorbis, Opus and WMA formats.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the Stop method.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

For details about the use of custom stream mixers, see the "How to use custom Stream Mixers" tutorial inside the documentation of Audio DJ Studio API for .NET.

Syntax

[Visual Basic]

Public Function StartFromDjStudioMixer (

nStreamMixerID as Int16,

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromDjStudioMixer (

Int16 nStreamMixerID,

string strOutputPath

);

[C++]

public: enumErrorCodes StartFromDjStudioMixer (

Int16 nStreamMixerID,

string strOutputPath

);

Parameter | Description
nStreamMixerID | Number representing the unique identifier of the stream mixer. This unique identifier is assigned by Audio DJ Studio API for .NET after calling its StreamMixerCreate or StreamMixerCreateWithSurround method.
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.. If the string is left empty, the recording session will be performed in memory.

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.


StartFromEditingSession method

StartFromEditingSession method

Remarks

Starts a new recording session getting sound data from the given instance of Audio Sound Editor for .NET or from the given instance of Audio Sound Editor API for .NET .

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

Syntax

[Visual Basic]

Public Function StartFromEditingSession (

hWndEditorCtrl as IntPtr,

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromEditingSession (

IntPtr hWndEditorCtrl,

string strOutputPath

);

[C++]

public: enumErrorCodes StartFromEditingSession (

IntPtr hWndEditorCtrl,

string strOutputPath

);

Parameter | Description
hWndEditorCtrl | The value of the Handle property of an instance of Audio Sound Editor for .NET or Audio Sound Editor API for .NET
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.. If the string is left empty, the recording session will be performed in memory.

Return value

Value | Meaning
enumErrorCodes.ERR_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.


StartFromFile method

StartFromFile method

Remarks

Starts a new recording session from an input sound file.

Accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, M4A, AC3, FLAC, WavPack, ALAC, WAV, OGG Vorbis, OPUS, WMA (*), ASF (**), WMV (**), AIFF, AU, W64, PAF, SVX, NIST, VOC, IRCAM, PVF and CAF.

Multichannel WAV, AIFF, OGG Vorbis, OPUS and WMA formats are not supported and will be resampled and converted to stereo during the loading procedure.

Accepted MOD formats are: MOD, MTM, S3M, XM, IT and MO3.

Accepted CD audio tracks format is CDA.

Sound files in various RAW formats can be loaded using the StartFromFileRaw method.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartFromFile (

strOutputPath as string,

strInputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromFile (

string strOutputPath,

string strInputPath

);

[C++]

public: enumErrorCodes StartFromFile (

string strOutputPath,

string strInputPath

);

Parameter | Description
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character. If the string is left empty, the recording session will be performed in memory.
strInputPath | String representing the absolute pathname of the input sound file.

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.

(*) 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 only sound tracks (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs only sound frames (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).


StartFromFileEncrypted method

StartFromFileEncrypted method

Remarks

Starts a new recording session from an input sound file that was previously encrypted through the EncryptCurrentSession method or through the CryptSound™ application.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

For details about encryption/decryption features see the How to protect your recording sessions through encryption tutorial.

Syntax

[Visual Basic]

Public Function StartFromFileEncrypted (

strOutputPath as String,

strInputPath as String,

strDecryptionKey as String

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromFileEncrypted (

string strOutputPath,

string strInputPath,

string strDecryptionKey

);

[C++]

public: enumErrorCodes StartFromFileEncrypted (

string strOutputPath,

string strInputPath,

string strDecryptionKey

);

Parameter | Description
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.. If the string is left empty, the recording session will be performed in memory.
strInputPath | String representing the absolute pathname of the encrypted input sound file.
strDecryptionKey | 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
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.


StartFromFileRaw method

StartFromFileRaw method

Remarks

Starts a new recording session from an input sound file in RAW format.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartFromFileRaw (

strOutputPath as string,

strInputPath as string,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as Boolean,

nFrequency as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromFileRaw (

string strOutputPath,

string strInputPath,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

[C++]

public: enumErrorCodes StartFromFileRaw (

string strOutputPath,

string strInputPath,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

Parameter

Description

strOutputPath

String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

If the string is left empty, the recording session will be performed in memory.

strInputPath

String representing the absolute pathname of the input file.

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | 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. Check the LastError property value in order to see the last error.
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


StartFromMemory method

StartFromMemory method

Remarks

Starts a new recording session from a sound contained inside a memory buffer.

The sound contained inside the memory buffer can be in any of the sound formats supported by the StartFromFile method.

Sound files in various RAW formats can be loaded using the StartFromMemoryRaw method.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartFromMemory (

strOutputPath as string,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromMemory (

string strOutputPath,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes StartFromMemory (

string strOutputPath,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character. If the string is left empty, the recording session will be performed in memory.
pBuffer | Input buffer containing the original sound
nBufferLen | Length of the input 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.

Sample

Below you can find a couple of samples that demonstrate how to record from 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 inside a memory buffer.

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)

 ' record sound from memory buffer and resample its contents using the first available format (index '0' is usually 11025, mono, 8 bits)

 If AudioSoundRecorder1.RecorderStartFromMemory(0, "c:\output.wav", m_byteBuffer, streamFile.Length) = AudioDjStudio.enumErrorCodes.ERR_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);

 // record sound from memory buffer and resample its contents using the first available format (index '0' is usually 11025, mono, 8 bits)

 if (AudioSoundRecorder1.RecorderStartFromMemory(0, "c:\output.wav", m_byteBuffer, (Int32) streamFile.Length) == enumErrorCodes.ERR_NOERROR)

 {

     // do something

     ...

 }

}


StartFromMemoryRaw method

StartFromMemoryRaw method

Remarks

Starts a new recording session from a sound file in RAW format contained inside a memory buffer.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartFromMemoryRaw (

strOutputPath as string,

pBuffer() as Byte,

nBufferLength as Int32,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as Boolean,

nFrequency as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromMemoryRaw (

string strOutputPath,

byte[] pBuffer,

Int32 nBufferLength,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

[C++]

public: enumErrorCodes StartFromMemoryRaw (

string strOutputPath,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

Parameter | Description
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character. If the string is left empty, the recording session will be performed in memory.
pBuffer | Input buffer containing the original sound
nBufferLen | Length of the input buffer expressed in bytes

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | 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. Check the LastError property value in order to see the last error.
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


StartFromQueueRaw method

StartFromQueueRaw method

Remarks

Starts a new recording session from a queue filled with raw PCM audio data. The queue can be filled in real time using the SendDataToQueueRaw method.

When using this method to start a recording session, the EncodeFormats.ResampleMode property must be set to RESAMPLE_MODE_CUSTOM_FORMAT.

A successful call to this method causes the container application to be notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function StartFromQueueRaw (

strOutputPath as string

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as Boolean,

nFrequency as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromQueueRaw (

string strOutputPath

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

[C++]

public: enumErrorCodes StartFromQueueRaw (

string strOutputPath

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

Parameter

Description

strOutputPath

String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

If the string is left empty, the recording session will be performed in memory.

nEncodeMode

Encode mode used to encode RAW audio data.

Supported values are the following:

Mnemonic constant | 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 RAW audio data (e.g. 44100)

nChannels

Number of channels of RAW audio data: 1 for Mono or 2 for Stereo

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.


StartFromURL method

StartFromURL method

Remarks

Starts a new recording session from a sound stream pointed by an Internet URL. The source stream can be either a shoutcast/icecast stream or simply a sound file stored on a web site.

When calling this method the container application is notified about the status of the connection to the given Internet URL through the CallbackForRecordersEvents delegate, invoked with the nEvent parameter set to EV_REC_CONNECTION_STARTED and EV_REC_CONNECTION_DONE.

Once connected successfully, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the RecorderStop method.

This method fails if the SetRecordingMode method has been previously invoked with the nMode parameter set to REC_MODE_MIX or REC_MODE_INSERT or REC_MODE_OVERWRITE.

For details about recording from the Internet see the How to perform an Internet-based recording session section.

Syntax

[Visual Basic]

Public Function StartFromURL (

strOutputPath as string,

strURL as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromURL (

string strOutputPath,

string strURL

);

[C++]

public: enumErrorCodes StartFromURL (

string strOutputPath,

string strURL

);

Parameter

Description

strOutputPath

String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

If the string is left empty, the recording session will be performed in memory.

strURL

String representing the Internet URL (HTTP, FTP or MMS) pointing to the casting stream or remote file.

Accepted formats for casting streams are WMA, MP3, OGG Vorbis, OPUS, AAC and AC3 while accepted formats for remote files are MP1, MP2, MP3, MP4, AIFF, WAV, OGG Vorbis, AAC, MP4, AC3, FLAC, WMA, OPUS and MPC.

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.


StartFromWasapiCaptureDevice method

StartFromWasapiCaptureDevice method

Remarks

Starts a recording session through the given WASAPI capture 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.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the Stop method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function StartFromWasapiCaptureDevice (

nCaptureDevice as Int32,

strOutputPath as String

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromWasapiCaptureDevice (

Int32 nCaptureDevice,

string strOutputPath

);

[C++]

public: enumErrorCodes StartFromWasapiCaptureDevice (

Int32 nCaptureDevice,

string strOutputPath

);

Parameter | Description
nCaptureDevice | Number representing the zero-based index of the WASAPI capture device of interest. The total number of available WASAPI capture devices can be obtained using the WASAPI.DeviceGetCount method having the nDeviceType parameter set to WASAPI_DEVICE_TYPE_CAPTURE.
strOutputPath | String representing the absolute pathname of the output file that will contain recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character. If this parameter is left empty, recorded data will be stored inside a memory buffer.

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.


StartFromWasapiLoopbackDevice method

StartFromWasapiLoopbackDevice method

Remarks

Starts a recording session through the given WASAPI loopback 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.

Recording from a loopback device is only possible if the corresponding output device has not been started in exclusive mode; A loopback device can only deliver audio data when the corresponding output device is effectively producing audio data.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the Stop method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function StartFromWasapiLoopbackDevice (

nLoopbackDevice as Int32,

strOutputPath as String

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromWasapiLoopbackDevice (

Int32 nLoopbackDevice,

string strOutputPath

);

[C++]

public: enumErrorCodes StartFromWasapiLoopbackDevice (

Int32 nLoopbackDevice,

string strOutputPath

);

Parameter | Description
nLoopbackDevice | Number representing the zero-based index of the WASAPI loopback device of interest. The total number of available WASAPI loopback devices can be obtained using the WASAPI.DeviceGetCount method having the nDeviceType parameter set to WASAPI_DEVICE_TYPE_LOOPBACK.
strOutputPath | String representing the absolute pathname of the output file that will contain recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character. If this parameter is left empty, recorded data will be stored inside a memory buffer.

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.


StartFromWasapiMixer method

StartFromWasapiMixer method

Remarks

Starts a recording session from the WASAPI input mixer which gets and mixes PCM data incoming from capture and loopback devices attached to the mixer through previous calls to the WASAPI.MixerInputDeviceAttach method.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the Stop method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function StartFromWasapiMixer (

strOutputPath as String

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromWasapiMixer (

string strOutputPath

);

[C++]

public: enumErrorCodes StartFromWasapiMixer (

string strOutputPath

);

Parameter | Description
strOutputPath | String representing the absolute pathname of the output file that will contain recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character. If this parameter is left empty, recorded data will be stored inside a memory buffer.

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.


StartFromZipFile method

StartFromZipFile method

Remarks

Starts a new recording session from an input sound file stored inside the given ZIP file.

Accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, M4A, AC3, FLAC, WavPack, ALAC, WAV, OGG Vorbis, OPUS, WMA (*), ASF (**), WMV (**), AIFF, AU, W64, PAF, SVX, NIST, VOC, IRCAM, PVF and CAF.

Multichannel WAV, AIFF, OGG Vorbis, OPUS and WMA formats are not supported and will be resampled and converted to stereo during the loading procedure.

Accepted MOD formats are: MOD, MTM, S3M, XM, IT and MO3.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function StartFromZipFile (

strOutputPath as string,

strZipPathname as string,

strPassword as string,

strEntryName as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartFromZipFile (

string strOutputPath,

string strZipPathname,

string strPassword,

string strEntryName

);

[C++]

public: enumErrorCodes StartFromZipFile (

string strOutputPath,

string strZipPathname,

string strPassword,

string strEntryName

);

Parameter | Description
strOutputPath | String representing the absolute pathname of the destination file that will contain recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strZipPathname | String representing the absolute pathname of the ZIP file.
strEntryName | String representing the name of the entry to extract and load.
strPassword | String containing the optional password for accessing the requested entry; 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.

(*) 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 only sound tracks (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs only sound frames (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).


StartSplitFromClipboard method

StartSplitFromClipboard method

Remarks

Starts a new recording session from a sound contained inside the system clipboard and splits incoming sound in left and right channels.

In order to understand if a CF_WAVE format sound is available inside the clipboard you can call the IsSoundAvailableInClipboard method.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA, the only supported encoding mode for the EncodeFormats.WMA.EncodeMode property is WMA_ENCODE_CBR_STD_16 and the WMA.CBR property must be set to a value that can support both stereo and mono, so the only compatible combinations are the following:

· for sounds at 16000 Hz CBR must be set to 16000 (16 kbps)
· for sounds at 22050 Hz CBR must be set to 20000 (20 kbps)
· for sounds at 44100 Hz CBR must be set to 32000 (32 kbps) or 48000 (48 kbps)

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV, the splitting will only work if the EncodeFormats.WAV.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like WAV_ENCODE_GSM_610 or WAV_ENCODE_G721_ADPCM_32.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF, the splitting will only work if the EncodeFormats.AIFF.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AIFF_ENCODE_GSM_610.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU, the splitting will only work if the EncodeFormats.AU.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AU_ENCODE_G721_ADPCM_32 or AU_ENCODE_G723_ADPCM_24 or AU_ENCODE_G723_ADPCM_40.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM, the splitting will only work if the selected codec supports both mono and stereo formats meaning that, for example, it will not work for mono-only codecs like GSM 6.10 or G721 ADPCM.

The split doesn't work if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC because this format doesn't support creating mono sounds.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartSplitFromClipboard (

strOutputPathLeft as string,

strOutputPathRight as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromClipboard (

string strOutputPathLeft,

string strOutputPathRight

);

[C++]

public: enumErrorCodes StartSplitFromClipboard (

string strOutputPathLeft,

string strOutputPathRight

);

Parameter | Description
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


StartSplitFromDirectSoundDevice method

StartSplitFromDirectSoundDevice method

Remarks

Starts a new recording session from the given DirectSound input device and channel and splits incoming sound in left and right channels.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

During the recording session you can be notified about recorded size for both channels through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_SPLIT_SIZE.

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA, the only supported encoding mode for the EncodeFormats.WMA.EncodeMode property is WMA_ENCODE_CBR_STD_16 and the WMA.CBR property must be set to a value that can support both stereo and mono, so the only compatible combinations are the following:

· for sounds at 16000 Hz CBR must be set to 16000 (16 kbps)
· for sounds at 22050 Hz CBR must be set to 20000 (20 kbps)
· for sounds at 44100 Hz CBR must be set to 32000 (32 kbps) or 48000 (48 kbps)

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV, the splitting will only work if the EncodeFormats.WAV.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like WAV_ENCODE_GSM_610 or WAV_ENCODE_G721_ADPCM_32.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF, the splitting will only work if the EncodeFormats.AIFF.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AIFF_ENCODE_GSM_610.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU, the splitting will only work if the EncodeFormats.AU.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AU_ENCODE_G721_ADPCM_32 or AU_ENCODE_G723_ADPCM_24 or AU_ENCODE_G723_ADPCM_40.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM, the splitting will only work if the selected codec supports both mono and stereo formats meaning that, for example, it will not work for mono-only codecs like GSM 6.10 or G721 ADPCM.

The split doesn't work if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC because this format doesn't support creating mono sounds.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function StartSplitFromDirectSoundDevice (

nInputDevice as Int16,

nInputChannel as Int16,

strOutputPathLeft as string,

strOutputPathRight as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromDirectSoundDevice (

Int16 nInputDevice,

Int16 nInputChannel,

string strOutputPathLeft,

string strOutputPathRight

);

[C++]

public: enumErrorCodes StartSplitFromDirectSoundDevice (

Int16 nInputDevice,

Int16 nInputChannel,

string strOutputPathLeft,

string strOutputPathRight

);

Parameter | Description
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 in order to know how many input devices are currently installed on the system and the GetInputDeviceDesc method 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).
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


StartSplitFromFile method

StartSplitFromFile method

Remarks

Starts a new recording session from an input stereo sound file and splits incoming sound in left and right channels.

Accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, M4A, AC3, FLAC, WavPack, ALAC, WAV, OGG Vorbis, OPUS, WMA (*), ASF (**), WMV (**), AIFF, AU, W64, PAF, SVX, NIST, VOC, IRCAM, PVF and CAF.

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

Source sound files cannot be in mono and multichannel WAV, AIFF, OGG Vorbis, OPUS and WMA formats are not supported and will be resampled and converted to stereo during the loading procedure.

Accepted MOD formats are: MOD, MTM, S3M, XM, IT and MO3.

Accepted CD audio tracks format is CDA.

Sound files in various RAW formats can be loaded using the StartSplitFromFileRaw method.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA, the only supported encoding mode for the EncodeFormats.WMA.EncodeMode property is WMA_ENCODE_CBR_STD_16 and the WMA.CBR property must be set to a value that can support both stereo and mono, so the only compatible combinations are the following:

· for sounds at 16000 Hz CBR must be set to 16000 (16 kbps)
· for sounds at 22050 Hz CBR must be set to 20000 (20 kbps)
· for sounds at 44100 Hz CBR must be set to 32000 (32 kbps) or 48000 (48 kbps)

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV, the splitting will only work if the EncodeFormats.WAV.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like WAV_ENCODE_GSM_610 or WAV_ENCODE_G721_ADPCM_32.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF, the splitting will only work if the EncodeFormats.AIFF.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AIFF_ENCODE_GSM_610.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU, the splitting will only work if the EncodeFormats.AU.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AU_ENCODE_G721_ADPCM_32 or AU_ENCODE_G723_ADPCM_24 or AU_ENCODE_G723_ADPCM_40.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM, the splitting will only work if the selected codec supports both mono and stereo formats meaning that, for example, it will not work for mono-only codecs like GSM 6.10 or G721 ADPCM.

The split doesn't work if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC because this format doesn't support creating mono sounds.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartSplitFromFile (

strOutputPathLeft as string,

strOutputPathRight as string,

strInputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromFile (

string strOutputPathLeft,

string strOutputPathRight,

string strInputPath

);

[C++]

public: enumErrorCodes StartSplitFromFile (

string strOutputPathLeft,

string strOutputPathRight,

string strInputPath

);

Parameter | Description
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strInputPath | String representing the absolute pathname of the input sound file.

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.

(*) 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 only sound tracks (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs only sound frames (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).


StartSplitFromFileRaw method

StartSplitFromFileRaw method

Remarks

Starts a new recording session from an input sound file in RAW format and splits incoming sound in left and right channels.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA, the only supported encoding mode for the EncodeFormats.WMA.EncodeMode property is WMA_ENCODE_CBR_STD_16 and the WMA.CBR property must be set to a value that can support both stereo and mono, so the only compatible combinations are the following:

· for sounds at 16000 Hz CBR must be set to 16000 (16 kbps)
· for sounds at 22050 Hz CBR must be set to 20000 (20 kbps)
· for sounds at 44100 Hz CBR must be set to 32000 (32 kbps) or 48000 (48 kbps)

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV, the splitting will only work if the EncodeFormats.WAV.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like WAV_ENCODE_GSM_610 or WAV_ENCODE_G721_ADPCM_32.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF, the splitting will only work if the EncodeFormats.AIFF.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AIFF_ENCODE_GSM_610.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU, the splitting will only work if the EncodeFormats.AU.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AU_ENCODE_G721_ADPCM_32 or AU_ENCODE_G723_ADPCM_24 or AU_ENCODE_G723_ADPCM_40.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM, the splitting will only work if the selected codec supports both mono and stereo formats meaning that, for example, it will not work for mono-only codecs like GSM 6.10 or G721 ADPCM.

The split doesn't work if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC because this format doesn't support creating mono sounds.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartSplitFromFileRaw (

strOutputPathLeft as string,

strOutputPathRight as string,

strInputPath as string,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as Boolean,

nFrequency as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromFileRaw (

string strOutputPathLeft,

string strOutputPathRight,

string strInputPath,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

[C++]

public: enumErrorCodes StartSplitFromFileRaw (

string strOutputPathLeft,

string strOutputPathRight,

string strInputPath,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

Parameter

Description

strOutputPathLeft

String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

strOutputPathRight

String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

strInputPath

String representing the absolute pathname of the input file.

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | 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: must be set to 2 for stereo because splitting of mono files is not supported.

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.


StartSplitFromMemory method

StartSplitFromMemory method

Remarks

Starts a new recording session from a sound contained inside a memory buffer and splits incoming sound in left and right channels.

The sound contained inside the memory buffer can be in any of the sound formats supported by the StartSplitFromFile method.

Sound files in various RAW formats can be loaded using the StartSplitFromMemoryRaw method.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA, the only supported encoding mode for the EncodeFormats.WMA.EncodeMode property is WMA_ENCODE_CBR_STD_16 and the WMA.CBR property must be set to a value that can support both stereo and mono, so the only compatible combinations are the following:

· for sounds at 16000 Hz CBR must be set to 16000 (16 kbps)
· for sounds at 22050 Hz CBR must be set to 20000 (20 kbps)
· for sounds at 44100 Hz CBR must be set to 32000 (32 kbps) or 48000 (48 kbps)

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV, the splitting will only work if the EncodeFormats.WAV.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like WAV_ENCODE_GSM_610 or WAV_ENCODE_G721_ADPCM_32.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF, the splitting will only work if the EncodeFormats.AIFF.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AIFF_ENCODE_GSM_610.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU, the splitting will only work if the EncodeFormats.AU.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AU_ENCODE_G721_ADPCM_32 or AU_ENCODE_G723_ADPCM_24 or AU_ENCODE_G723_ADPCM_40.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM, the splitting will only work if the selected codec supports both mono and stereo formats meaning that, for example, it will not work for mono-only codecs like GSM 6.10 or G721 ADPCM.

The split doesn't work if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC because this format doesn't support creating mono sounds.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartSplitFromMemory (

strOutputPathLeft as string,

strOutputPathRight as string,

pBuffer() as Byte,

nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromMemory (

string strOutputPathLeft,

string strOutputPathRight,

byte[] pBuffer,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes StartSplitFromMemory (

string strOutputPathLeft,

string strOutputPathRight,

unsigned char __gc[] pBuffer,

Int32 nBufferLength

);

Parameter | Description
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
pBuffer | Input buffer containing the original sound
nBufferLen | Length of the input 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.


StartSplitFromMemoryRaw method

StartSplitFromMemoryRaw method

Remarks

Starts a new recording session from a sound in RAW format contained inside a memory buffer and splits incoming sound in left and right channels

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA, the only supported encoding mode for the EncodeFormats.WMA.EncodeMode property is WMA_ENCODE_CBR_STD_16 and the WMA.CBR property must be set to a value that can support both stereo and mono, so the only compatible combinations are the following:

· for sounds at 16000 Hz CBR must be set to 16000 (16 kbps)
· for sounds at 22050 Hz CBR must be set to 20000 (20 kbps)
· for sounds at 44100 Hz CBR must be set to 32000 (32 kbps) or 48000 (48 kbps)

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV, the splitting will only work if the EncodeFormats.WAV.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like WAV_ENCODE_GSM_610 or WAV_ENCODE_G721_ADPCM_32.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF, the splitting will only work if the EncodeFormats.AIFF.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AIFF_ENCODE_GSM_610.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU, the splitting will only work if the EncodeFormats.AU.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AU_ENCODE_G721_ADPCM_32 or AU_ENCODE_G723_ADPCM_24 or AU_ENCODE_G723_ADPCM_40.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM, the splitting will only work if the selected codec supports both mono and stereo formats meaning that, for example, it will not work for mono-only codecs like GSM 6.10 or G721 ADPCM.

The split doesn't work if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC because this format doesn't support creating mono sounds.

For details about recording from files see the How to record from files, memory or clipboard section.

Syntax

[Visual Basic]

Public Function StartSplitFromMemoryRaw (

strOutputPathLeft as string,

strOutputPathRight as string,

pBuffer() as Byte,

nBufferLength as Int32,

nEncodeMode as enumRAWEncodeModes,

bIsBigEndian as Boolean,

nFrequency as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromMemoryRaw (

string strOutputPathLeft,

string strOutputPathRight,

byte[] pBuffer,

Int32 nBufferLength,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

[C++]

public: enumErrorCodes StartSplitFromMemoryRaw (

string strOutputPathLeft,

string strOutputPathRight,

unsigned char __gc[] pBuffer,

Int32 nBufferLength,

enumRAWEncodeModes nEncodeMode,

bool bIsBigEndian,

Int32 nFrequency,

Int32 nChannels

);

Parameter

Description

strOutputPathLeft

String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

strOutputPathRight

String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

pBuffer

Input buffer containing the original sound

nBufferLen

Length of the input buffer expressed in bytes

nEncodeMode

Encode mode used to encode the RAW file.

Supported values are the following:

Mnemonic constant | 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: must be set to 2 for stereo because splitting of mono files is not supported.

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.


StartSplitFromURL method

StartSplitFromURL method

Remarks

Starts a new recording session from a sound stream pointed by an Internet URL and splits incoming sound in left and right channels. The source stream can be either a shoutcast/icecast stream or simply a sound file stored on a web site.

When calling this method the container application is notified about the status of the connection to the given Internet URL through the CallbackForRecordersEvents delegate, invoked with the nEvent parameter set to EV_REC_CONNECTION_STARTED and EV_REC_CONNECTION_DONE.

Once connected successfully, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the RecorderStop method.

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA, the only supported encoding mode for the EncodeFormats.WMA.EncodeMode property is WMA_ENCODE_CBR_STD_16 and the WMA.CBR property must be set to a value that can support both stereo and mono, so the only compatible combinations are the following:

· for sounds at 16000 Hz CBR must be set to 16000 (16 kbps)
· for sounds at 22050 Hz CBR must be set to 20000 (20 kbps)
· for sounds at 44100 Hz CBR must be set to 32000 (32 kbps) or 48000 (48 kbps)

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV, the splitting will only work if the EncodeFormats.WAV.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like WAV_ENCODE_GSM_610 or WAV_ENCODE_G721_ADPCM_32.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF, the splitting will only work if the EncodeFormats.AIFF.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AIFF_ENCODE_GSM_610.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU, the splitting will only work if the EncodeFormats.AU.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AU_ENCODE_G721_ADPCM_32 or AU_ENCODE_G723_ADPCM_24 or AU_ENCODE_G723_ADPCM_40.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM, the splitting will only work if the selected codec supports both mono and stereo formats meaning that, for example, it will not work for mono-only codecs like GSM 6.10 or G721 ADPCM.

The split doesn't work if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC because this format doesn't support creating mono sounds.

For details about recording from the Internet see the How to perform an Internet-based recording session section.

Syntax

[Visual Basic]

Public Function StartSplitFromURL (

strOutputPathLeft as string,

strOutputPathRight as string,

strURL as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromURL (

string strOutputPathLeft,

string strOutputPathRight,

string strURL

);

[C++]

public: enumErrorCodes StartSplitFromURL (

string strOutputPathLeft,

string strOutputPathRight,

string strURL

);

Parameter | Description
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strURL | String representing the Internet URL (HTTP, FTP or MMS) pointing to the sound stream or file. Accepted formats are WMA, MP3, OGG Vorbis, AAC and AC3.

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.


StartSplitFromWasapiCaptureDevice method

StartSplitFromWasapiCaptureDevice method

Remarks

Starts a new recording session from the given WASAPI capture device and splits incoming sound in left and right channels.

The given WASAPI capture device must be 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.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the Stop method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function StartSplitFromWasapiCaptureDevice (

nCaptureDevice as Int32,

strOutputPathLeft as String,

strOutputPathRight as String

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromWasapiCaptureDevice (

Int32 nCaptureDevice,

string strOutputPathLeft,

string strOutputPathRight

);

[C++]

public: enumErrorCodes StartSplitFromWasapiCaptureDevice (

Int32 nCaptureDevice,

string strOutputPathLeft,

string strOutputPathRight

);

Parameter | Description
nCaptureDevice | Number representing the zero-based index of the WASAPI capture device of interest. The total number of available WASAPI capture devices can be obtained using the WASAPI.DeviceGetCount method having the nDeviceType parameter set to WASAPI_DEVICE_TYPE_CAPTURE.
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


StartSplitFromWasapiLoopbackDevice method

StartSplitFromWasapiLoopbackDevice method

Remarks

Starts a new recording session from the given WASAPI loopback device and splits incoming sound in left and right channels.

The given WASAPI loopback device must be 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.

After calling this method, the container application is notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_START.

The recording session can be stopped at any time through a call to the Stop method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the WASAPI object and the How to manage audio flow through WASAPI tutorial.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function StartSplitFromWasapiLoopbackDevice (

nLoopbackDevice as Int32,

strOutputPathLeft as String,

strOutputPathRight as String

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromWasapiLoopbackDevice (

Int32 nLoopbackDevice,

string strOutputPathLeft,

string strOutputPathRight

);

[C++]

public: enumErrorCodes StartSplitFromWasapiLoopbackDevice (

Int32 nLoopbackDevice,

string strOutputPathLeft,

string strOutputPathRight

);

Parameter | Description
nLoopbackDevice | Number representing the zero-based index of the WASAPI loopback device of interest. The total number of available WASAPI loopback devices can be obtained using the WASAPI.DeviceGetCount method having the nDeviceType parameter set to WASAPI_DEVICE_TYPE_LOOPBACK..
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


StartSplitFromZipFile method

StartSplitFromZipFile method

Remarks

Starts a new recording session from an input stereo sound file, stored inside the given ZIP file, and splits incoming sound in left and right channels.

Accepted stream formats are: MP1, MP2, MP3, MP4 (***), AIFF, AAC, M4A, AC3, FLAC, WavPack, ALAC, WAV, OGG Vorbis, OPUS, WMA (*), ASF (**), WMV (**), AIFF, AU, W64, PAF, SVX, NIST, VOC, IRCAM, PVF and CAF.

In this case the recording session wouldn't be kept inside the RecordedSound object so the only accepted recording mode, set through the SetRecordingMode method, is REC_MODE_NEW.

Source sound files cannot be in mono and multichannel WAV, AIFF, OGG Vorbis, OPUS and WMA formats are not supported and will be resampled and converted to stereo during the loading procedure.

Accepted MOD formats are: MOD, MTM, S3M, XM, IT and MO3.

During the recording sessions the container application is notified through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_START at the beginning and to EV_REC_STOP at the end. The current percentage of advancement is notified through the EV_REC_PERC event.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA, the only supported encoding mode for the EncodeFormats.WMA.EncodeMode property is WMA_ENCODE_CBR_STD_16 and the WMA.CBR property must be set to a value that can support both stereo and mono, so the only compatible combinations are the following:

· for sounds at 16000 Hz CBR must be set to 16000 (16 kbps)
· for sounds at 22050 Hz CBR must be set to 20000 (20 kbps)
· for sounds at 44100 Hz CBR must be set to 32000 (32 kbps) or 48000 (48 kbps)

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV, the splitting will only work if the EncodeFormats.WAV.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like WAV_ENCODE_GSM_610 or WAV_ENCODE_G721_ADPCM_32.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF, the splitting will only work if the EncodeFormats.AIFF.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AIFF_ENCODE_GSM_610.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU, the splitting will only work if the EncodeFormats.AU.EncodeMode property is set to a format supporting both mono and stereo formats meaning that, for example, it will not work for mono-only formats like AU_ENCODE_G721_ADPCM_32 or AU_ENCODE_G723_ADPCM_24 or AU_ENCODE_G723_ADPCM_40.

If the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM, the splitting will only work if the selected codec supports both mono and stereo formats meaning that, for example, it will not work for mono-only codecs like GSM 6.10 or G721 ADPCM.

The split doesn't work if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC because this format doesn't support creating mono sounds.

For details about using ZIP management refer to the How to manage ZIP files tutorial.

Syntax

[Visual Basic]

Public Function StartSplitFromZipFile (

strOutputPathLeft as string,

strOutputPathRight as string,

strZipPathname as string,

strPassword as string,

strEntryName as string

) as enumErrorCodes

[C#]

public enumErrorCodes StartSplitFromZipFile (

string strOutputPathLeft,

string strOutputPathRight,

string strZipPathname,

string strPassword,

string strEntryName

);

[C++]

public: enumErrorCodes StartSplitFromZipFile (

string strOutputPathLeft,

string strOutputPathRight,

string strZipPathname,

string strPassword,

string strEntryName

);

Parameter | Description
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strZipPathname | String representing the absolute pathname of the ZIP file.
strEntryName | String representing the name of the entry to extract and load.
strPassword | String containing the optional password for accessing the requested entry; 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.

(*) 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 only sound tracks (no video): requires Microsoft Windows Media Format modules already installed on the target PC

(***) Performs only sound frames (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).


Stop method

Stop method

Remarks

Stops the current recording session.

Calling this method will cause the container application to be notified through the CallbackForRecordersEvents delegate invoked with the nEvent parameter set to EV_REC_STOP.

For details about the encoding format and parameters applied during recording see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function Stop (

) as enumErrorCodes

[C#]

public enumErrorCodes Stop (

);

[C++]

public: enumErrorCodes Stop (

);

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.


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 CallbackVuMeterValueChange delegate is used for the purpose of retrieving peak levels of the audio stream during recording/playback: this method can be used as an integration of the existing CallbackVuMeterValueChange delegate in order to obtain RMS (Root-Mean-Square) levels: a good place to invoke this method is indeed inside the handler function of the CallbackVuMeterValueChange delegate.

Syntax

[Visual Basic]

Public StreamPeakLevelsGet (

tPeakLevels() as Single,

nLengthInMs as Int32,

bRms as Boolean,

bStereo as Boolean,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes StreamPeakLevelsGet (

float[] tPeakLevels,

Int32 nLengthInMs,

bool bRms,

bool bStereo,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes StreamPeakLevelsGet (

float[] tPeakLevels,

Int32 nLengthInMs,

bool bRms,

bool bStereo,

enumVolumeScales nScaleType

);

Parameter

Description

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.


SwitchedOutputFileGetCount method

SwitchedOutputFileGetCount method

Remarks

Returns the number of output files switched through the SwitchOutputFile or the SwitchOutputFileEx methods during a recording session.

For further details about output files switching see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function SwitchedOutputFileGetCount (

) as Int32

[C#]

public Int32 SwitchedOutputFileGetCount (

);

[C++]

public: Int32 SwitchedOutputFileGetCount (

);

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
Value >= 0 | The number of switched output files.


SwitchedOutputFileGetDuration method

SwitchedOutputFileGetDuration method

Remarks

Returns the duration, expressed in milliseconds, of an output file switched through the SwitchOutputFile or the SwitchOutputFileEx methods during a recording session.

For further details about output files switching see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function SwitchedOutputFileGetDuration (

nFileId as Int32

) as Int32

[C#]

public Int32 SwitchedOutputFileGetDuration (

Int32 nFileId

);

[C++]

public: Int32 SwitchedOutputFileGetDuration (

Int32 nFileId

);

Parameter | Description
nFileId | Number representing the zero-based index of the switched output file. This index is the same notified by the nData1 parameter of the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_OUTPUT_FILE_SWITCH.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
Value >= 0 | Duration, expressed in milliseconds, of the switched output file


SwitchedOutputFileGetPathname method

SwitchedOutputFileGetPathname method

Remarks

Returns the absolute pathname of an output file switched through the SwitchOutputFile or the SwitchOutputFileEx methods during a recording session.

For further details about output files switching see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function SwitchedOutputFileGetPathname (

nFileId as Int32

) as String

[C#]

public string SwitchedOutputFileGetPathname (

Int32 nFileId

);

[C++]

public: string SwitchedOutputFileGetPathname (

Int32 nFileId

);

Parameter | Description
nFileId | Number representing the zero-based index of the switched output file. This index is the same notified by the nData1 parameter of the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_OUTPUT_FILE_SWITCH.

Return value

Value | Meaning
Empty string | The value of the nFileId parameter was out of range. Use the value returned by the SwitchedOutputFileGetCount method in order to know how many files have been switched.
Valid string | The string containing the absolute pathname of the switched output file.


SwitchedOutputFileGetSize method

SwitchedOutputFileGetSize method

Remarks

Returns the size, expressed in bytes, of an output file switched through the SwitchOutputFile or the SwitchOutputFileEx methods during a recording session.

For further details about output files switching see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function SwitchedOutputFileGetSize (

nFileId as Int32

) as Int32

[C#]

public Int32 SwitchedOutputFileGetSize (

Int32 nFileId

);

[C++]

public: Int32 SwitchedOutputFileGetSize (

Int32 nFileId

);

Parameter | Description
nFileId | Number representing the zero-based index of the switched output file. This index is the same notified by the nData1 parameter of the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_OUTPUT_FILE_SWITCH.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
Value >= 0 | Size, expressed in bytes, of the switched output file


SwitchOutputFile method

SwitchOutputFile method

Remarks

During a recording session, whose output is being sent to an output file, switches to a different output file without stopping the recording session itself: in this way no sound data will be lost.

This method will return an error for memory-based recording sessions or for recording sessions whose recording mode, set through the SetRecordingMode method, is different from REC_MODE_NEW.

This method can only work when the recording session is started through one of the following methods: StartFromDirectSoundDevice, StartFromAsioDevice, StartFromWasapiCaptureDevice, StartFromWasapiLoopbackDevice and StartFromDjStudioMixer.

Each time an output file is switched, the CallbackForRecordersEvents delegate is invoked with the nEvent parameter set to EV_REC_OUTPUT_FILE_SWITCH.

For further details about output files switching see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function SwitchOutputFile (

strOutputPath as string

) as enumErrorCodes

[C#]

public enumErrorCodes SwitchOutputFile (

string strOutputPath

);

[C++]

public: enumErrorCodes SwitchOutputFile (

string strOutputPath

);

Parameter | Description
strOutputPath | String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character..

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.


SwitchOutputFileEx method

SwitchOutputFileEx method

Remarks

During a recording session, whose output is being sent to an output file, switches to a different output file without stopping the recording session itself: in this way no sound data will be lost.

This method will return an error for memory-based recording sessions or for recording sessions whose recording mode, set through the SetRecordingMode method, is different from REC_MODE_NEW.

This method can only work when the recording session is started through one of the following methods: StartFromDirectSoundDevice, StartFromAsioDevice, StartFromWasapiCaptureDevice, StartFromWasapiLoopbackDevice and StartFromDjStudioMixer.

Each time an output file is switched, the CallbackForRecordersEvents delegate is invoked with the nEvent parameter set to EV_REC_OUTPUT_FILE_SWITCH.

For further details about output files switching see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function SwitchOutputFileEx (

strOutputPath as string,

bResetEncoderCmdLine as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SwitchOutputFileEx (

string strOutputPath,

bool bResetEncoderCmdLine

);

[C++]

public: enumErrorCodes SwitchOutputFileEx (

string strOutputPath,

bool bResetEncoderCmdLine

);

Parameter

Description

strOutputPath

String representing the absolute pathname of the output file that will contain the recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character..

bResetEncoderCmdLine

Boolean value that, when recording through an external encoder (MP3, Ogg Vorbis and AAC/MP4) determines if the command line of the external encoder needs to be reset allowing to apply different encoding settings updated through the EncodeFormats object or different tags updated through the TagInfoAddToRecSession method..

.Supported values are the following:

Mnemonic constant | Meaning
false | Doesn't reset the command line and continue using the original one
true | Resets the command line

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.


SwitchOutputFilesOnSplit method

SwitchOutputFilesOnSplit method

Remarks

During a splitting recording session started through the StartSplitFromDirectSoundDevice, StartSplitFromWasapiCaptureDevice and StartSplitFromWasapiLoopbackDevice methods, switches to two different output files without stopping the recording session itself: in this way no sound data will be lost.

This method will return an error for memory-based recording sessions or for recording sessions whose recording mode, set through the SetRecordingMode method, is different from REC_MODE_NEW.Each time an output file is switched, the CallbackForRecordersEvents delegate is invoked with the nEvent parameter set to EV_REC_OUTPUT_FILE_SWITCH.

For further details about output files switching see the How to perform a recording session tutorial.

Syntax

[Visual Basic]

Public Function SwitchOutputFilesOnSplit (

strOutputPathLeft as string,

strOutputPathRight as string

) as enumErrorCodes

[C#]

public enumErrorCodes SwitchOutputFilesOnSplit (

string strOutputPathLeft,

string strOutputPathRight

);

[C++]

public: enumErrorCodes SwitchOutputFilesOnSplit (

string strOutputPathLeft,

string strOutputPathRight

);

Parameter | Description
strOutputPathLeft | String representing the absolute pathname of the destination file that will contain the left channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.
strOutputPathRight | String representing the absolute pathname of the destination file that will contain the right channel of recorded data. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


TagInfoAddToRecSession method

TagInfoAddToRecSession method

Remarks

Allows adding basic tag information to the next recording session.

This method is effective only with recording sessions performed through external encoders so it currently works only with MP3, Ogg Vorbis, MP4 and WMA; other formats will ignore this setting. In order to reset contents and to avoid adding tag information to the next recording session, set all the string to empty; no check is performed over string contents and size.

When the output format is MP4, don't forget to set the EncodeFormats.AAC.WrapInMP4 property to "true" because tag information cannot be stored inside AAC format directly but there is the need to wrap the AAC compressed file inside a MP4 container.

Syntax

[Visual Basic]

Public Function TagInfoAddToRecSession (

strAuthor as String,

strTitle as String,

strAlbum as String,

strYear as String

) as enumErrorCodes

[C#]

public enumErrorCodes TagInfoAddToRecSession (

string strAuthor,

string strTitle,

string strAlbum,

string strYear

);

[C++]

public: enumErrorCodes TagInfoAddToRecSession (

string strAuthor,

string strTitle,

string strAlbum,

string strYear

);

Parameter | Description
strAuthor | String containing the author name
strTitle | String containing the sound title
strAlbum | String containing the album title
strYear | String containing the year

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.


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 (

)


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.


CallbackForRecordersEvents delegate

CallbackForRecordersEvents delegate

Remarks

Callback delegate invoked when an event related to a player occurs: this callback can be set through a call to the CallbackForRecordersEventsSet 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 CallbackForRecordersEvents (

ByVal nEvent as enumRecorderEvents,

ByVal nData1 as Int32,

ByVal nData2 as Int32,

ByVal nDataHigh3 as Int32,

ByVal nDataLow3 as Int32,

ByVal nDataHigh4 as Int32,

ByVal nDataLow4 as Int32

)

[C#]

public delegate void CallbackForRecordersEvents (

enumRecorderEvents nEvent,

Int32 nData1,

Int32 nData2,

Int32 nDataHigh3,

Int32 nDataLow3,

Int32 nDataHigh4,

Int32 nDataLow4

)

[C++]

public delegate void CallbackForRecordersEvents (

enumRecorderEvents nEvent,

Int32 nData1,

Int32 nData2,

Int32 nDataHigh3,

Int32 nDataLow3,

Int32 nDataHigh4,

Int32 nDataLow4

)

Parameter

Description

nEvent

Event reported by the recorder.

Supported values are the following:

Mnemonic constant

Value

Meaning with data parameters

EV_CD_RIPPING_PERC

0

Notifies the advancement status, expressed in percentage, of the current CD ripping session.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the ripping percentage.

EV_CD_RIPPING_ENCODE_PERC

1

Notifies the advancement status, expressed in percentage, of the track encoding performed during the current CD ripping session.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the encoding percentage.during a CD ripping session

EV_CD_RIPPING_SIZE

2

Occurs, during a CD ripping session, to notify the actual size of ripped sound data.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataHigh4: Number representing the higher 32 bits of the size in bytes

nDataLow4: Number representing the lower 32 bits of the size in bytes

EV_CD_RIPPING_START

3

Occurs at the beginning of a new CD ripping session started through the CdRippingStart method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

EV_CD_RIPPING_STOP

4

Occurs whenever a CD ripping session is completed or stopped through a call to the CdRippingStop method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Boolean value stating if the CD ripping session was completed.Supported values are the following:

Value | Meaning
0 | The ripping of the given CD track was interrupted: interruption's possible causes are the CD drive door being opened or a call to the CdRippingStop method. Check the LastError property value in order to see the last error.
1 | The ripping of the given CD track was completed.

EV_CD_RIPPING_AUTOMATION_START

5

Occurs when a CD ripping automation session is started through the CdRippingAutomationExec method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

EV_CD_RIPPING_AUTOMATION_TOTAL_PERC

6

Occurs, during a CD ripping automation session, to notify the actual total advancement percentage. The advancement related to each CD track added to the ripping automation session is notified through the EV_CD_RIPPING_PERC event.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nDataLow3: Number representing the automation percentage

EV_CD_RIPPING_AUTOMATION_STOP

7

Occurs when a CD ripping automation session is completed or stopped through the CdRippingStop method or after opening the CD drive door.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nDataLow3: Boolean value stating if the CD ripping automation session was completed.Supported values are the following:

Value | Meaning
0 | The ripping automation session was interrupted: interruption's possible causes are the CD drive door being opened or a call to the CdRippingStop method. Check the LastError property value in order to see the last error.
1 | The CD ripping automation was completed.

EV_CD_RIPPING_EXTRACT_PERC

8

Notifies the advancement status, expressed in percentage, of the track extraction performed during the current CD ripping session; during this phase, the CD track is extracted into a memory buffer in order to allow the volume level normalization process.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the track extraction percentage.

EV_CD_RIPPING_NORM_PERC

9

Notifies the advancement status, expressed in percentage, of the track normalization performed during the current CD ripping session.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the track normalization percentage.

EV_REC_START

10

Occurs at the beginning of a new recording session.

Involved data parameters: none

EV_REC_STOP

11

Occurs whenever a recording session is stopped through a call to the RecorderStop method or when an error occurs.

Involved data parameters:

nData1: Boolean value that indicates the result of the recording session. Supported values are the following:

Value | Meaning
0 | The recording session failed. Check the LastError property value in order to see the last error.
1 | The recording session succeeded.

EV_REC_AUDIBLE_DATA

12

Occurs during a recording session, having the Sound Activation System enabled, whenever audible data are being recorded again.

Involved data parameters: none

EV_REC_SILENT_DATA

13

Occurs during a recording session, having the Sound Activation System enabled, whenever a silent portion is being encountered.

Involved data parameters: none

EV_REC_SIZE

14

Occurs, during a recording session, to notify the amount of recorded PCM bytes.

This event is useful when recording PCM data in memory or with the purpose of saving recorded data into a destination WAV file.

Note that, when recording and encoding directly into MP3, OGG Vorbis or WMA formats, the reported size doesn't match the effective amount of memory occupied by the recording system because, in this case, recorded data are encoded directly into the destination file and immediately discarded from memory.

Involved data parameters:

nDataHigh4: Number representing the higher 32 bits of the size in bytes of the current recording session

nDataLow4: Number representing the lower 32 bits of the size in bytes of the current recording session

EV_REC_PAUSED

15

Occurs whenever a recording session is paused through a call to the RecorderPause method.

Involved data parameters: none

EV_REC_RESUMED

16

Occurs whenever a paused recording session is resumed through a call to the RecorderResume method.

Involved data parameters: none

EV_REC_DURATION

17

Occurs, during a recording session, to notify the actual recording duration in milliseconds.

It's important to note that, in case the recording session should have been started in append, mix, overwrite or insert mode (through the SetRecordingMode method), this event would only report the duration of the current recording session and not the overall duration that would result after finalizing the recording session with the previous one. If you want to know the current position of the recording session, which would take count of a previous recording session, the EV_REC_POSITION event would be the way to go.

Involved data parameters:

nDataHigh4: Number representing the higher 32 bits of the duration of the current recording session expressed in milliseconds

nDataLow4: Number representing the lower 32 bits of the duration of the current recording session expressed in milliseconds

EV_REC_POSITION

18

Occurs, during a recording session, to notify the actual recording position in milliseconds.

In case the recording session should have been started in append, mix, overwrite or insert mode (through the SetRecordingMode method), the position reported by this event would keep count of the previous recording session as well; if you want to know the duration of the current recording session only, the EV_REC_DURATION event would be the way to go.

Involved data parameters:

nDataHigh4: Number representing the higher 32 bits of the position of the current recording session in milliseconds

nDataLow4: Number representing the lower 32 bits of the position of the current recording session in milliseconds

EV_REC_PERC

19

Occurs to notify the current recording percentage during a file/memory/clipboard/URL based recording session started through one of the following methods:

StartFromClipboard

StartFromFile

StartFromFileEncrypted

StartFromFileRaw

StartFromMemory

StartFromMemoryRaw

StartFromURL

Involved data parameters:

nData1: Number representing the current advancement percentage of the recording session

EV_REC_SPLIT_SIZE

20

Occurs, during a recording session with stereo splitting started through the StartSplitFromDirectSoundDevice method, to notify the amount of recorded bytes for the left and right channels.

Involved data parameters:

nDataHigh3: Number representing the higher 32 bits of the amount of bytes of PCM data recorded on the left channel

nDataLow3: Number representing the lower 32 bits of the amount of bytes of PCM data recorded on the left channel

nDataHigh4: Number representing the higher 32 bits of the amount of bytes of PCM data recorded on the right channel.

nDataLow4: Number representing the lower 32 bits of the amount of bytes of PCM data recorded on the right channel.

EV_REC_WAV_CHUNK_SAVED

21

Occurs during a recording session in WAV format when a chunk file is saved to disk: this event is only generated after enabling the splitting of the recording session in chunks through a previous call to the SplitWavRecordingEnable method.

Involved data parameters:

nData1: Number representing the progressive number of the saved chunk

EV_REC_FINALIZATION_STARTED

22

Occurs when the finalization of a recording session begins: during the finalization process a new recording session is appended, mixed or inserted into a previous one.

Involved data parameters: none

EV_REC_FINALIZATION_DONE

23

Occurs when the finalization of a recording session is completed: during the finalization process a new recording session is appended, mixed or inserted into a previous one.

Involved data parameters:

nData1: The result of the finalization process.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_REC_OUTPUT_FILE_SWITCH

24

Occurs, during a recording session, when the output file is switched through a call to the SwitchOutputFile or the SwitchOutputFileEx methods.

Involved data parameters:

nData1: Number representing the zero-based index of the file that has been switched to another one.

EV_REC_CONNECTION_STARTED

25

Occurs when the connection to an Internet URL is started through a call to the StartFromURL method.

Involved data parameters: none

EV_REC_CONNECTION_DONE

26

Occurs when the connection to an Internet URL, started through a call to the StartFromURL method, is completed.

Involved data parameters:

nData1: The result of the connection.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_CD_ERROR

27

Occurs, during a CD ripping session, as a consequence of a CD read error.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the position within the CD track, expressed in bytes, where the read error occurred.

nDataLow4: Number representing the position within the CD track, expressed in milliseconds, where the read error occurred.

EV_CD_SPEED_CHANGE

28

Occurs when the speed of the CD drive is automatically reduced after an error occurs during the reading of a CD track.

Automatic speed reduction, disabled by default, can be enabled through the CdDriveAutoSpeedSet method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the new speed of the CD drive expressed in Kbytes per second. You can divide the speed by 176.4 to get the real-time speed multiplier; if for example the returned values should be 7096, the operation to perform would be

7096 / 176.4 = "40x".

EV_REC_CDDB_SERVERS_AVAIL

29

Occurs when the list of CDDB servers, requested through a previous call to the CddbRequestServersList method, is available.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: 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_REC_CDDB_ALBUM_INFO_AVAIL

30

Occurs when the CDDB server returns the CD album information requested through a previous call to the CddbRequestAlbumInfo method or when the Amazon Web Service returns the CD album information requested through a previous call to the CdRequestAlbumInfo method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Boolean value that specifies if the CDDB information was retrieved successfully. Supported values are the following:

Value

Meaning

0

The request failed

1

The request succeeded and CDDB information is available.

In this case the control can perform the following further requests passing the value of the nData1 parameter:

· Obtain the CD album info through the CddbGetAlbumInfo method.
· Get the number of tracks through the GetCdNumTracks method.
· Get each track title through the CddbGetTrackTitle method.

EV_REC_CD_COVER_URLS_AVAIL

31

Occurs when the Internet URLs of the CD cover's pictures have been obtained from the Amazon Web Service.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_REC_CD_COVER_SMALL_FILE_AVAIL

32

Occurs when the small version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: 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_REC_CD_COVER_MEDIUM_FILE_AVAIL

33

Occurs when the medium version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: 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_REC_CD_COVER_LARGE_FILE_AVAIL

34

Occurs when the large version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: 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_REC_WAVE_ANALYSIS_PERC

35

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 WaveformAnalyzer.AnalyzeFullSound method.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current sound analysis

EV_REC_SOUND_UPLOAD_PERC

36

Notifies the advancement status, expressed in percentage, of an uploading session to a FTP server started through a previous call to the RecordedSound.RequestUploadToFTP method.

Involved data parameters:

nData1: Number representing the current percentage of the uploading session to a FTP server

EV_REC_SPECTRAL_ANALYSIS_PERC

37

Occurs during the spectral analysis of a sound's waveform in order to notify the container application about the analysis advancement.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current sound analysis

EV_REC_SOUND_EXPORT_PERC

38

Occurs during the sound exporting session in order to notify the container application about the export advancement.

Involved data parameters:

nData1: Number representing the percentage of advancement for the exporting session

EV_REC_AUDIO_EXTRACT_PERC

39

Occurs during the extraction of the audio track from a video clip in order to notify the container application about the extraction advancement.

Involved data parameters:

nData1: Number representing the percentage of advancement for the extraction session

EV_REC_DURATION_AFTER_SWITCH

40

Occurs, during a recording session, to notify the actual recording duration in milliseconds of a sound file after switching the output file through the SwitchOutputFile or SwitchOutputFileEx methods.

Involved data parameters:

nDataHigh4: Number representing the higher 32 bits of the duration of the switched output file expressed in milliseconds

nDataLow4: Number representing the lower 32 bits of the duration of the switched output file expressed in milliseconds

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.

nDataHigh3

Higher 32 bits of the third argument of the event, if any; its value and meaning depends upon the specific event received: see the table above for possible values.

nDataLow3

Lower 32 bits of the third argument of the event, if any; its value and meaning depends upon the specific event received: see the table above for possible values.

nDataHigh4

Higher 32 bits of the fourth argument of the event, if any; its value and meaning depends upon the specific event received: see the table above for possible values.

nDataLow4

Lower 32 bits of the fourth argument of the event, if any; its value and meaning depends upon the specific event received: see the table above for possible values.


CallbackSoundPlaybackDone delegate

CallbackSoundPlaybackDone delegate

Remarks

Callback delegate invoked when the playback of a sound started through one between the RecordedSound.Play, RecordedSound.PlayRange or RecordedSound.Resume methods is completed: this callback can be set through a call to the CallbackSoundPlaybackDoneSet 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 CallbackSoundPlaybackDone(

)

[C#]

public delegate void CallbackSoundPlaybackDone(

)

[C++]

public delegate void CallbackSoundPlaybackDone(

)


CallbackSoundPlaybackStatusChanged delegate

CallbackSoundPlaybackStatusChanged delegate

Remarks

Callback delegate invoked when the playback status of a sound being played changes: this callback can be set through a call to the CallbackSoundPlaybackStatusChangedSet 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 CallbackSoundPlaybackStatusChanged (

nStatus As enumPlaybackStatus

)

[C#]

public delegate void CallbackSoundPlaybackStatusChanged (

enumPlaybackStatus nStatus

)

[C++]

public delegate void CallbackSoundPlaybackStatusChanged (

enumPlaybackStatus nStatus

)

Parameters

Description

nStatus

Identifier of the sound playback status

Supported values are the following:

Mnemonic Value | Value | Meaning
PLAYBACK_NO_SOUND | 0 | Occurs when the sound is closed through the RecordedSound.FreeMemory method
PLAYBACK_PLAYING | 1 | Occurs when sound playback is started through a call to RecordedSound.Play, RecordedSound.PlayRange or RecordedSound.Resume methods
PLAYBACK_PAUSED | 2 | Occurs when sound playback is paused through a call to RecordedSound.Pause method.
PLAYBACK_STOPPED | 3 | Occurs when sound playback is stopped through a call to RecordedSound.Stop method or when playback of the loaded sound is completed: in the latest case the CallbackSoundPlaybackDone delegate is invoked as well.


CallbackVuMeterValueChange delegate

CallbackVuMeterValueChange delegate

Remarks

Callback delegate invoked 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 callback can be set through a call to the CallbackVuMeterValueChangeSet method.

In case you should need to retrieve RMS (Root-Mean-Square) levels, you could use the StreamPeakLevelsGet method.

For details about using graphic bars refer to the How to perform custom feedbacks rendering using graphic bars section.

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

Syntax

[Visual Basic]

Public Delegate Sub CallbackVuMeterValueChange (

nPeakLeft as Int16,

nPeakRight as Int16

)

[C#]

public delegate void CallbackVuMeterValueChange (

Int16 nPeakLeft,

Int16 nPeakRight

)

[C++]

public delegate void CallbackVuMeterValueChange (

Int16 nPeakLeft,

Int16 nPeakRight

)

Parameter | Description
nPeakLeft | Number representing the peak value for the left channel: can assume values from 0 (no sound) to 32767 (max volume).
nPeakRight | Number representing the peak value for the right channel: can assume values from 0 (no sound) to 32767 (max volume). If the sound is in Mono, the nLeftPeak and nRightPeak parameters assume the same value.


CallbackWaveformValueChange delegate

CallbackWaveformValueChange delegate

Remarks

Callback delegate invoked whenever there is a change on the waveform peak values: this event, generated every 15 milliseconds, can be useful if you need to implement your own waveform graphical representation. This callback can be set through a call to the CallbackWaveformValueChangeSet 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 CallbackWaveformValueChange (

nPeakMin as Int16,

nPeakMax as Int16

)

[C#]

public delegate void CallbackWaveformValueChange (

Int16 nPeakMin,

Int16 nPeakMax

)

[C++]

public delegate void CallbackWaveformValueChange (

Int16 nPeakMin,

Int16 nPeakMax

)

Parameter | Description
nPeakMin | Number representing the min peak value: can assume values from 0 (no sound) to 32767 (max volume).
nPeakMax | Number representing the max peak value: can assume values from 0 (no sound) to 32767 (max volume).


CallbackWaveformAnalyzerGraphItemClick delegate

CallbackWaveformAnalyzerGraphItemClick delegate

Remarks

Callback delegate for notifying when a graphic item on the waveform analyzer is clicked: this callback can be set through a call to the CallbackWaveformAnalyzerGraphItemClickSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerGraphItemClick (

nButton as enumMouseButtons,

nUniqueId as Int16,

nType as enumGraphicItemType,

nFlags as Int32,

xPos as Int32,

yPos as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerGraphItemClick (

enumMouseButtons nButton,

Int16 nUniqueId,

enumGraphicItemType nType,

Int32 nFlags,

Int32 xPos,

Int32 yPos

)

[C++]

public delegate void CallbackWaveformAnalyzerGraphItemClick (

enumMouseButtons nButton,

Int16 nUniqueId,

enumGraphicItemType nType,

Int32 nFlags,

Int32 xPos,

Int32 yPos

)

Parameter

Description

nButton

Clicked mouse button.

Supported values are the following:

Mnemonic constant | Value | Meaning
MOUSE_BTN_LEFT | 0 | Left mouse button
MOUSE_BTN_RIGHT | 1 | Right mouse button
MOUSE_BTN_MIDDLE | 2 | Middle mouse button

nUniqueID

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

nGraphicItemType

Type of graphic item.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical line
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal line
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave range

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


CallbackWaveformAnalyzerGraphItemDblClick delegate

CallbackWaveformAnalyzerGraphItemDblClick delegate

Remarks

Callback delegate for notifying when a graphic item on the waveform analyzer is double clicked: this callback can be set through a call to the CallbackWaveformAnalyzerGraphItemDblClickSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerGraphItemDblClick (

nButton as enumMouseButtons,

nUniqueId as Int16,

nType as enumGraphicItemType,

nFlags as Int32,

xPos as Int32,

yPos as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerGraphItemDblClick (

enumMouseButtons nButton,

Int16 nUniqueId,

enumGraphicItemType nType,

Int32 nFlags,

Int32 xPos,

Int32 yPos

)

[C++]

public delegate void CallbackWaveformAnalyzerGraphItemDblClick (

enumMouseButtons nButton,

Int16 nUniqueId,

enumGraphicItemType nType,

Int32 nFlags,

Int32 xPos,

Int32 yPos

)

Parameter

Description

nButton

Clicked mouse button.

Supported values are the following:

Mnemonic constant | Value | Meaning
MOUSE_BTN_LEFT | 0 | Left mouse button
MOUSE_BTN_RIGHT | 1 | Right mouse button
MOUSE_BTN_MIDDLE | 2 | Middle mouse button

nUniqueID

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

nGraphicItemType

Type of graphic item.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical line
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal line
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave range

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


CallbackWaveformAnalyzerHorzLineLeaved delegate

CallbackWaveformAnalyzerHorzLineLeaved delegate

Remarks

Callback delegate invoked when the playback position leaves a graphic item of type "horizontal line" inside the waveform analyzer: this callback can be set through a call to the CallbackWaveformAnalyzerHorzLineLeavedSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerHorzLineLeaved (

nUniqueID as Int16,

nStartPosInMs as Int32

nEndPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerHorzLineLeaved (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerHorzLineLeaved (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

Parameter | Description
nUniqueID | Unique identifier of the horizontal line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemHorizontalLineAdd method.
nStartPosInMs | Start position of the horizontal line expressed in milliseconds
nEndPosInMs | End position of the horizontal line expressed in milliseconds


CallbackWaveformAnalyzerHorzLineMoved delegate

CallbackWaveformAnalyzerHorzLineMoved delegate

Remarks

Callback delegate invoked every time a graphic item of type "horizontal line" inside the waveform analyzer has been moved through the mouse or through the WaveformAnalyzer.GraphicItemHorzPositionSet method or through the WaveformAnalyzer.GraphicItemVertPositionSet method: this callback can be set through a call to the CallbackWaveformAnalyzerLineMovedSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerLineMoved (

nUniqueID as Int16,

nStartPosInMs as Int32

nEndPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerLineMoved (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerLineMoved (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

Parameter | Description
nUniqueID | Unique identifier of the horizontal line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemHorizontalLineAdd method.
nStartPosInMs | New start position of the horizontal line expressed in milliseconds
nEndPosInMs | New end position of the horizontal line expressed in milliseconds


CallbackWaveformAnalyzerHorzLineReached delegate

CallbackWaveformAnalyzerHorzLineReached delegate

Remarks

Callback delegate invoked when the playback position reaches a graphic item of type "horizontal line" inside the waveform analyzer: this callback can be set through a call to the CallbackWaveformAnalyzerHorzLineReachedSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerHorzLineReached (

nUniqueID as Int16,

nStartPosInMs as Int32

nEndPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerHorzLineReached (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerHorzLineReached (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

Parameter | Description
nUniqueID | Unique identifier of the horizontal line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemHorizontalLineAdd method.
nStartPosInMs | Start position of the horizontal line expressed in milliseconds
nEndPosInMs | End position of the horizontal line expressed in milliseconds


CallbackWaveformAnalyzerLineMoved delegate

CallbackWaveformAnalyzerLineMoved delegate

Remarks

Callback delegate invoked every time a custom vertical line on the waveform analyzer has been moved through the mouse or through the WaveformAnalyzer.GraphicItemHorzPositionSet method: this callback can be set through a call to the CallbackWaveformAnalyzerLineMovedSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerLineMoved (

nUniqueID as Int16,

nPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerLineMoved (

Int16 nUniqueID,

Int32 nPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerLineMoved (

Int16 nUniqueID,

Int32 nPosInMs

)

Parameter | Description
nUniqueID | Unique identifier of the vertical line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemVerticalLineAdd method.
nPosInMs | New position of the vertical line expressed in milliseconds


CallbackWaveformAnalyzerLineReached delegate

CallbackWaveformAnalyzerLineReached delegate

Remarks

Callback delegate invoked when the playback position reaches a custom vertical line inside the waveform analyzer: this callback can be set through a call to the CallbackWaveformAnalyzerLineReachedSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerLineReached (

nUniqueID as Int16,

nEndPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerLineReached (

Int16 nUniqueID,

Int32 nEndPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerLineReached (

Int16 nUniqueID,

Int32 nEndPosInMs

)

Parameter | Description
nUniqueID | Unique identifier of the vertical line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemVerticalLineAdd method.
nPosInMs | Position of the vertical line expressed in milliseconds


CallbackWaveformAnalyzerMouseNotif delegate

CallbackWaveformAnalyzerMouseNotif delegate

Remarks

Callback delegate invoked every time a mouse event happens on the waveform analyzer: this callback can be set through a call to the CallbackWaveformAnalyzerMouseNotifSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerMouseNotif (

nAction as enumMouseActions,

nFlags as Int32,

xPos as Int32,

yPos as Int32,

nPressPosInPix as Int32,

nPressPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerMouseNotif (

enumMouseActions nAction,

Int32 nFlags,

Int32 xPos,

Int32 yPos,

Int32 nPressPosInPix,

Int32 nPressPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerMouseNotif (

enumMouseActions nAction,

Int32 nFlags,

Int32 xPos,

Int32 yPos,

Int32 nPressPosInPix,

Int32 nPressPosInMs

)

Parameter

Description

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. This notification is not generated when the waveform analyzer is empty.
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 client area of the whole user interface of the waveform analyzer, where the mouse generated the notification

yPos

Vertical position, expressed in pixels respect to the client area of the whole user interface of the waveform analyzer, 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.


CallbackWaveformAnalyzerPaintDone delegate

CallbackWaveformAnalyzerPaintDone delegate

Remarks

Callback delegate invoked when the waveform analyzer has completed its graphic rendering, allowing to add custom graphics directly from the container application's code: this callback can be set through a call to the CallbackWaveformAnalyzerPaintDoneSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerPaintDone (

hWnd as IntPtr

)

[C#]

public delegate void CallbackWaveformAnalyzerPaintDone (

IntPtr hWnd

)

[C++]

public delegate void CallbackWaveformAnalyzerPaintDone (

IntPtr hWnd

)

Parameter | Description
hWnd | Handle (HWND) to the window of the Waveform Analyzer: through this handle its possible accessing the handle to the device context (HDC) of the Waveform Analyzer using Windows API, for example through the GetDC and ReleaseDC functions.


CallbackWaveformAnalyzerRange delegate

CallbackWaveformAnalyzerRange delegate

Remarks

Callback delegate invoked every time the displayed range of waveform is changed after a zooming operation or after a scrolling operation or after a call to the WaveformAnalyzer.SetDisplayRange method: this callback can be set through a call to the CallbackWaveformAnalyzerRangeSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerRange (

nBeginPosInMs as Int32,

nEndPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerRange (

Int32 nBeginPosInMs,

Int32 nEndPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerRange (

Int32 nBeginPosInMs,

Int32 nEndPosInMs

)

Parameter | Description
nBeginPosInMs | Displayed range start position, expressed in milliseconds
nEndPosInMs | Displayed range end position, expressed in milliseconds


CallbackWaveformAnalyzerSelection delegate

CallbackWaveformAnalyzerSelection delegate

Remarks

Callback delegate invoked every time a portion of the waveform on the waveform analyzer has been selected/deselected through a mouse operation or through a call to the WaveformAnalyzer.SetSelection method: this callback can be set through a call to the CallbackWaveformAnalyzerSelectionSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerSelection (

bSelectionAvailable as Boolean,

nBeginPosInMs as Int32,

nEndPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerSelection (

bool bSelectionAvailable,

Int32 nBeginPosInMs,

Int32 nEndPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerSelection (

bool bSelectionAvailable,

Int32 nBeginPosInMs,

Int32 nEndPosInMs

)

Parameter

Description

bSelectionAvailable

Flag for selection availability.

Supported values are the following:

Value | Meaning
false | No selection is currently available. In this case values passed through nBeginPosInMs and nEndPosInMs parameters must be ignored.
true | A selection is currently available and the start and end positions are inside nBeginPosInMs and nEndPosInMs parameters.

nBeginPosInMs

The selection's start position, expressed in milliseconds

nEndPosInMs

The selection's end position, expressed in milliseconds


CallbackWaveAnalyzerSpectralViewStart delegate

CallbackWaveAnalyzerSpectralViewStart delegate

Remarks

Callback delegate invoked when a new spectral view analysis begins: this callback can be set through a call to the CallbackWaveAnalyzerSpectralViewStartSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveAnalyzerSpectralViewStart (

)

[C#]

public delegate void CallbackWaveAnalyzerSpectralViewStart (

)

[C++]

public delegate void CallbackWaveformAnalyzerWidth (

)


CallbackWaveAnalyzerSpectralViewDone delegate

CallbackWaveAnalyzerSpectralViewDone delegate

Remarks

Callback delegate invoked when a spectral view analysis is completed: this callback can be set through a call to the CallbackWaveAnalyzerSpectralViewDoneSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveAnalyzerSpectralViewDone (

nResult as enumErrorCodes

)

[C#]

public delegate void CallbackWaveAnalyzerSpectralViewDone (

enumErrorCodes nResult

)

[C++]

public delegate void CallbackWaveAnalyzerSpectralViewDone (

enumErrorCodes nResult

)

Parameter

Description

nResult

The result of the spectral analysis.

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 spectral view analysis completed successfully.


CallbackWaveformAnalyzerWaveRangeLeaved delegate

CallbackWaveformAnalyzerWaveRangeLeaved delegate

Remarks

Callback delegate invoked when the playback position leaves a graphic item of type "wave range" inside the waveform analyzer: this callback can be set through a call to the CallbackWaveformAnalyzerWaveRangeLeavedSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerWaveRangeLeaved (

nUniqueID as Int16,

nStartPosInMs as Int32

nEndPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerWaveRangeLeaved (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerWaveRangeLeaved (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

Parameter | Description
nUniqueID | Unique identifier of the wave range; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemWaveRangeAdd method.
nStartPosInMs | Start position of the horizontal line expressed in milliseconds
nEndPosInMs | End position of the horizontal line expressed in milliseconds


CallbackWaveformAnalyzerWaveRangeReached delegate

CallbackWaveformAnalyzerWaveRangeReached delegate

Remarks

Callback delegate invoked when the playback position reaches a graphic item of type "wave range" inside the waveform analyzer: this callback can be set through a call to the CallbackWaveformAnalyzerWaveRangeReachedSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerWaveRangeReached (

nUniqueID as Int16,

nStartPosInMs as Int32

nEndPosInMs as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerWaveRangeReached (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

[C++]

public delegate void CallbackWaveformAnalyzerWaveRangeReached (

Int16 nUniqueID,

Int32 nStartPosInMs,

Int32 nEndPosInMs

)

Parameter | Description
nUniqueID | Unique identifier of the wave range; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemWaveRangeAdd method.
nStartPosInMs | Start position of the horizontal line expressed in milliseconds
nEndPosInMs | End position of the horizontal line expressed in milliseconds


CallbackWaveformAnalyzerWidth delegate

CallbackWaveformAnalyzerWidth delegate

Remarks

Callback delegate invoked every time the waveform analyzer has been resized horizontally, usually after a call to the WaveformAnalyzer.Move method: this callback can be set through a call to the CallbackWaveformAnalyzerWidthSet method.

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

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Delegate Sub CallbackWaveformAnalyzerWidth (

nWidthInMs as Int32,

nWidthInPixels as Int32

)

[C#]

public delegate void CallbackWaveformAnalyzerWidth (

Int32 nWidthInMs,

Int32 nWidthInPixels

)

[C++]

public delegate void CallbackWaveformAnalyzerWidth (

Int32 nWidthInMs,

Int32 nWidthInPixels

)

Parameter | Description
nWidthInMs | Width of the waveform analyzer's display surface, expressed in milliseconds
nWidthInPixels | Width of the waveform analyzer's display surface, expressed in pixels


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 InitRecordingSystem 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 recorder through the OnRecorderEvents event handler when a recording session is started and stopped:

Visual Basic 6

' declare the API

Public WithEvents m_SoundRecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Private Sub m_SoundRecorderApi_OnRecorderEvents(ByVal nEvent As enumRecorderEvents, _

       ByVal nData1 As Long, ByVal nData2 As Long, _

       ByVal nDataHigh3 As Long, ByVal nDataLow3 As Long, _

       ByVal nDataHigh4 As Long, ByVal nDataLow4 As Long _

       )

   Select Case nEvent

       Case enumRecorderEvents.enumRecorderEvents_EV_REC_START:

           Debug.Print "Recording started"

       Case enumRecorderEvents.enumRecorderEvents_EV_REC_STOP:

           If nData1 = 1 Then

               MsgBox "Recording session completed"

           Else

               MsgBox "Recording session failed due to error " & m_SoundRecorderApi.LastError

           End If

   End Select

End Sub

Private Sub Form_Load()

  ' instance the API

   Set m_SoundRecorderApi = New AudioSoundRecorderApi.AudioSoundRecorderApiObj

  ' init the control

   m_SoundRecorderApi.InitRecordingSystem

  ' enable events for COM clients like VB6

   m_SoundRecorderApi.COMEventsEnable

  ' start a recording session from the system default recording device

   m_audioRecorderAPI.StartFromDirectSoundDevice (0, 0, "c:\myrecording.mp3")

  ... do other stuffs

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_SoundRecorderApi" which was originally declared with the "WithEvents" attribute) followed by the underscore "_" character and by the name of the event (in this case "OnRecorderEvents") and related parameters.


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 RecorderApi_OnCoreAudioEvents ( _

ByVal nEvent as enumCoreAudioEvents, _

ByVal nData1 as Long, _

ByVal nData2 as Long, _

ByVal nData3 as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

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


OnRecorderEvents event

OnRecorderEvents 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 RecorderApi_OnRecorderEvents ( _

ByVal nEvent as enumRecorderEvents, _

ByVal nData1 as Int32, _

ByVal nData2 as Int32, _

ByVal nDataHigh3 as Int32, _

ByVal nDataLow3 as Int32, _

ByVal nDataHigh4 as Int32, _

ByVal nDataLow4 as Int32 _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameter

Description

nEvent

Event reported by the recorder.

Supported values are the following:

Mnemonic constant

Value

Meaning with data parameters

EV_CD_RIPPING_PERC

0

Notifies the advancement status, expressed in percentage, of the current CD ripping session.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the ripping percentage.

EV_CD_RIPPING_ENCODE_PERC

1

Notifies the advancement status, expressed in percentage, of the track encoding performed during the current CD ripping session.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the encoding percentage.during a CD ripping session

EV_CD_RIPPING_SIZE

2

Occurs, during a CD ripping session, to notify the actual size of ripped sound data.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataHigh3: Number representing the higher 32 bits of the size in bytes

nDataLow3: Number representing the lower 32 bits of the size in bytes

EV_CD_RIPPING_START

3

Occurs at the beginning of a new CD ripping session started through the CdRippingStart method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

EV_CD_RIPPING_STOP

4

Occurs whenever a CD ripping session is completed or stopped through a call to the CdRippingStop method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Boolean value stating if the CD ripping session was completed.Supported values are the following:

Value | Meaning
0 | The ripping of the given CD track was interrupted: interruption's possible causes are the CD drive door being opened or a call to the CdRippingStop method. Check the LastError property value in order to see the last error.
1 | The ripping of the given CD track was completed.

EV_CD_RIPPING_AUTOMATION_START

5

Occurs when a CD ripping automation session is started through the CdRippingAutomationExec method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

EV_CD_RIPPING_AUTOMATION_TOTAL_PERC

6

Occurs, during a CD ripping automation session, to notify the actual total advancement percentage. The advancement related to each CD track added to the ripping automation session is notified through the EV_CD_RIPPING_PERC event.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nDataLow3: Number representing the automation percentage

EV_CD_RIPPING_AUTOMATION_STOP

7

Occurs when a CD ripping automation session is completed or stopped through the CdRippingStop method or after opening the CD drive door.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nDataLow3: Boolean value stating if the CD ripping automation session was completed.Supported values are the following:

Value | Meaning
0 | The ripping automation session was interrupted: interruption's possible causes are the CD drive door being opened or a call to the CdRippingStop method. Check the LastError property value in order to see the last error.
1 | The CD ripping automation was completed.

EV_CD_RIPPING_EXTRACT_PERC

8

Notifies the advancement status, expressed in percentage, of the track extraction performed during the current CD ripping session; during this phase, the CD track is extracted into a memory buffer in order to allow the volume level normalization process.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the track extraction percentage.

EV_CD_RIPPING_NORM_PERC

9

Notifies the advancement status, expressed in percentage, of the track normalization performed during the current CD ripping session.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the track normalization percentage.

EV_REC_START

10

Occurs at the beginning of a new recording session.

Involved data parameters: none

EV_REC_STOP

11

Occurs whenever a recording session is stopped through a call to the RecorderStop method or when an error occurs.

Involved data parameters:

nData1: Boolean value that indicates the result of the recording session. Supported values are the following:

Value | Meaning
0 | The recording session failed. Check the LastError property value in order to see the last error.
1 | The recording session succeeded.

EV_REC_AUDIBLE_DATA

12

Occurs during a recording session, having the Sound Activation System enabled, whenever audible data are being recorded again.

Involved data parameters: none

EV_REC_SILENT_DATA

13

Occurs during a recording session, having the Sound Activation System enabled, whenever a silent portion is being encountered.

Involved data parameters: none

EV_REC_SIZE

14

Occurs, during a recording session, to notify the amount of recorded PCM bytes.

This event is useful when recording PCM data in memory or with the purpose of saving recorded data into a destination WAV file.

Note that, when recording and encoding directly into MP3, OGG Vorbis or WMA formats, the reported size doesn't match the effective amount of memory occupied by the recording system because, in this case, recorded data are encoded directly into the destination file and immediately discarded from memory.

Involved data parameters:

nDataHigh4: Number representing the higher 32 bits of the size in bytes

nDataLow4 Number representing the lower 32 bits of the size in bytes

EV_REC_PAUSED

15

Occurs whenever a recording session is paused through a call to the RecorderPause method.

Involved data parameters: none

EV_REC_RESUMED

16

Occurs whenever a paused recording session is resumed through a call to the RecorderResume method.

Involved data parameters: none

EV_REC_DURATION

17

Occurs, during a recording session, to notify the actual recording duration in milliseconds.

It's important to note that, in case the recording session should have been started in append, mix, overwrite or insert mode (through the SetRecordingMode method), this event would only report the duration of the current recording session and not the overall duration that would result after finalizing the recording session with the previous one. If you want to know the current position of the recording session, which would take count of a previous recording session, the EV_REC_POSITION event would be the way to go.

Involved data parameters:

nData1: Number representing the duration, expressed in milliseconds, of the current recording session

EV_REC_POSITION

18

Occurs, during a recording session, to notify the actual recording position in milliseconds.

In case the recording session should have been started in append, mix, overwrite or insert mode (through the SetRecordingMode method), the position reported by this event would keep count of the previous recording session as well; if you want to know the duration of the current recording session only, the EV_REC_DURATION event would be the way to go.

Involved data parameters:

nData1: Number representing the position, expressed in milliseconds, of the current recording session

EV_REC_PERC

19

Occurs to notify the current recording percentage during a file/memory/clipboard/URL based recording session started through one of the following methods:

StartFromClipboard

StartFromFile

StartFromFileEncrypted

StartFromFileRaw

StartFromMemory

StartFromMemoryRaw

StartFromURL

Involved data parameters:

nData1: Number representing the current advancement percentage of the recording session

EV_REC_SPLIT_SIZE

20

Occurs, during a recording session with stereo splitting started through the StartSplitFromDirectSoundDevice method, to notify the amount of recorded bytes for the left and right channels.

Involved data parameters:

nDataHigh3: Number representing the higher 32 bits of the amount of bytes of PCM data recorded on the left channel

nDataLow3 Number representing the lower 32 bits of the amount of bytes of PCM data recorded on the left channel

nDataHigh4: Number representing the higher 32 bits of the amount of bytes of PCM data recorded on the right channel.

nDataLow4 Number representing the lower 32 bits of the amount of bytes of PCM data recorded on the right channel.

EV_REC_WAV_CHUNK_SAVED

21

Occurs during a recording session in WAV format when a chunk file is saved to disk: this event is only generated after enabling the splitting of the recording session in chunks through a previous call to the SplitWavRecordingEnable method.

Involved data parameters:

nData1: Number representing the progressive number of the saved chunk

EV_REC_FINALIZATION_STARTED

22

Occurs when the finalization of a recording session begins: during the finalization process a new recording session is appended, mixed or inserted into a previous one.

Involved data parameters: none

EV_REC_FINALIZATION_DONE

23

Occurs when the finalization of a recording session is completed: during the finalization process a new recording session is appended, mixed or inserted into a previous one.

Involved data parameters:

nData1: The result of the finalization process.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_REC_OUTPUT_FILE_SWITCH

24

Occurs, during a recording session, when the output file is switched through a call to the SwitchOutputFile or the SwitchOutputFileEx methods.

Involved data parameters:

nData1: Number representing the zero-based index of the file that has been switched to another one.

EV_REC_CONNECTION_STARTED

25

Occurs when the connection to an Internet URL is started through a call to the StartFromURL method.

Involved data parameters: none

EV_REC_CONNECTION_DONE

26

Occurs when the connection to an Internet URL, started through a call to the StartFromURL method, is completed.

Involved data parameters:

nData1: The result of the connection.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_CD_ERROR

27

Occurs, during a CD ripping session, as a consequence of a CD read error.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the one-based index of the CD audio track that is being ripped.

nDataLow3: Number representing the position within the CD track, expressed in bytes, where the read error occurred.

nDataLow4: Number representing the position within the CD track, expressed in milliseconds, where the read error occurred.

EV_CD_SPEED_CHANGE

28

Occurs when the speed of the CD drive is automatically reduced after an error occurs during the reading of a CD track.

Automatic speed reduction, disabled by default, can be enabled through the CdDriveAutoSpeedSet method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Number representing the new speed of the CD drive expressed in Kbytes per second. You can divide the speed by 176.4 to get the real-time speed multiplier; if for example the returned values should be 7096, the operation to perform would be

7096 / 176.4 = "40x".

EV_REC_CDDB_SERVERS_AVAIL

29

Occurs when the list of CDDB servers, requested through a previous call to the CddbRequestServersList method, is available.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: 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_REC_CDDB_ALBUM_INFO_AVAIL

30

Occurs when the CDDB server returns the CD album information requested through a previous call to the CddbRequestAlbumInfo method or when the Amazon Web Service returns the CD album information requested through a previous call to the CdRequestAlbumInfo method.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: Boolean value that specifies if the CDDB information was retrieved successfully. Supported values are the following:

Value

Meaning

0

The request failed

1

The request succeeded and CDDB information is available.

In this case the control can perform the following further requests passing the value of the nData1 parameter:

· Obtain the CD album info through the CddbGetAlbumInfo method.
· Get the number of tracks through the GetCdNumTracks method.
· Get each track title through the CddbGetTrackTitle method.

EV_REC_CD_COVER_URLS_AVAIL

31

Occurs when the Internet URLs of the CD cover's pictures have been obtained from the Amazon Web Service.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: The result of the CD cover retrieval attempt.

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to see the error code meaning
enumErrorCodes.ERR_NOERROR (0) | The operation was successful.

EV_REC_CD_COVER_SMALL_FILE_AVAIL

32

Occurs when the small version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: 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_REC_CD_COVER_MEDIUM_FILE_AVAIL

33

Occurs when the medium version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: 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_REC_CD_COVER_LARGE_FILE_AVAIL

34

Occurs when the large version of the CD cover's picture file has been downloaded from the Amazon web site.

Involved data parameters:

nData1: Number representing the zero-based index of the CD drive reporting the event

nData2: 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_REC_WAVE_ANALYSIS_PERC

35

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 WaveformAnalyzer.AnalyzeFullSound method.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current sound analysis

EV_REC_SOUND_UPLOAD_PERC

36

Notifies the advancement status, expressed in percentage, of an uploading session to a FTP server started through a previous call to the RecordedSound.RequestUploadToFTP method.

Involved data parameters:

nData1: Number representing the current percentage of the uploading session to a FTP server

EV_REC_SPECTRAL_ANALYSIS_PERC

37

Occurs during the spectral analysis of a sound's waveform in order to notify the container application about the analysis advancement.

Involved data parameters:

nData1: Number representing the percentage of advancement for the current sound analysis

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.

nDataHigh3

Higher 32 bits of the third argument of the event, if any; its value and meaning depends upon the specific event received: see the table above for possible values.

nDataLow3

Lower 32 bits of the third argument of the event, if any; its value and meaning depends upon the specific event received: see the table above for possible values.

nDataHigh4

Higher 32 bits of the fourth argument of the event, if any; its value and meaning depends upon the specific event received: see the table above for possible values.

nDataLow4

Lower 32 bits of the fourth argument of the event, if any; its value and meaning depends upon the specific event received: see the table above for possible values.


OnSoundPlaybackDone event

OnSoundPlaybackDone event

Remarks

Occurs whenever a playback session, started or resumed through a previous call to RecordedSound.Play, RecordedSound.PlayRange or RecordedSound.Resume methods, is completed.

This event replaces the usage of the CallbackSoundPlaybackDone 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 RecorderApi_OnSoundPlaybackDone ( _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj


OnSoundPlaybackStatusChanged event

OnSoundPlaybackStatusChanged event

Remarks

Occurs whenever the status of a playback session changes.

This event replaces the usage of the CallbackSoundPlaybackStatusChanged 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 RecorderApi_OnSoundPlaybackStatusChanged ( _

ByVal nStatus As enumPlaybackStatus _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters

Description

nStatus

Identifier of the sound playback status

Supported values are the following:

Mnemonic Value | Value | Meaning
PLAYBACK_NO_SOUND | 0 | Occurs when the sound is closed through the RecordedSound.FreeMemory method
PLAYBACK_PLAYING | 1 | Occurs when sound playback is started through a call to RecordedSound.Play, RecordedSound.PlayRange or RecordedSound.Resume methods
PLAYBACK_PAUSED | 2 | Occurs when sound playback is paused through a call to RecordedSound.Pause method.
PLAYBACK_STOPPED | 3 | Occurs when sound playback is stopped through a call to RecordedSound.Stop method or when playback of the loaded sound is completed: in the latest case the OnSoundPlaybackDone event is generated as well.


OnVUMeterValueChange event

OnVUMeterValueChange event

Remarks

Occurs whenever there is a change on the VU-Meter peak values: this event, generated every 15 milliseconds, can be useful if you need to implement your own VU-Meter graphical representation.

This event replaces the usage of the CallbackVuMeterValueChange 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 graphic bars refer to the How to perform custom feedbacks rendering using graphic bars section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnVUMeterValueChange ( _

ByVal nPeakLeft as Integer, _

ByVal nPeakRight as Integer _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nPeakLeft | Number representing the peak value for the left channel: can assume values from 0 (no sound) to 32767 (max volume).
nPeakRight | Number representing the peak value for the right channel: can assume values from 0 (no sound) to 32767 (max volume). If the sound is in Mono, the nLeftPeak and nRightPeak parameters assume the same value.


OnWaveformValueChange event

OnWaveformValueChange event

Remarks

Occurs whenever there is a change on the waveform peak values: this event, generated every 15 milliseconds, can be useful if you need to implement your own waveform graphical representation.

This event replaces the usage of the CallbackWaveformValueChange 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 synchronization through Events see the How to synchronize the container application with the control tutorial.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformValueChange ( _

ByVal nPeakMin as Integer, _

ByVal nPeakMax as Integer _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameter | Description
nPeakMin | Number representing the min peak value: can assume values from 0 (no sound) to 32767 (max volume).
nPeakMax | Number representing the max peak value: can assume values from 0 (no sound) to 32767 (max volume).


OnWaveformAnalyzerGraphicItemClick event

OnWaveformAnalyzerGraphicItemClick event

Remarks

Occurs when a mouse button is clicked over a graphic item available on the waveform analyzer.

This event replaces the usage of the CallbackWaveformAnalyzerGraphItemClick 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerGraphicItemClick ( _

ByVal nButton as enumMouseButtons, _

ByVal nUniqueID as Integer, _

ByVal nGraphicItemType as enumGraphicItemType, _

ByVal nFlags as Long, _

ByVal xPos as Long, _

ByVal yPos as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters

Description

nButton

Clicked mouse button.

Supported values are the following:

Mnemonic constant | Value | Meaning
MOUSE_BTN_LEFT | 0 | Left mouse button
MOUSE_BTN_RIGHT | 1 | Right mouse button
MOUSE_BTN_MIDDLE | 2 | Middle mouse button

nUniqueID

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

nGraphicItemType

Type of graphic item.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical line
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal line
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave range

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


OnWaveformAnalyzerGraphicItemDblClick event

OnWaveformAnalyzerGraphicItemDblClick event

Remarks

Occurs when a mouse button is double clicked over a graphic item available on the waveform analyzer.

This event replaces the usage of the CallbackWaveformAnalyzerGraphItemDblClick 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerGraphicItemDblClick ( _

ByVal nButton as enumMouseButtons, _

ByVal nUniqueID as Integer, _

ByVal nGraphicItemType as enumGraphicItemType, _

ByVal nFlags as Long, _

ByVal xPos as Long, _

ByVal yPos as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters

Description

nButton

Clicked mouse button.

Supported values are the following:

Mnemonic constant | Value | Meaning
MOUSE_BTN_LEFT | 0 | Left mouse button
MOUSE_BTN_RIGHT | 1 | Right mouse button
MOUSE_BTN_MIDDLE | 2 | Middle mouse button

nUniqueID

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

nGraphicItemType

Type of graphic item.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical line
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal line
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave range

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


OnWaveformAnalyzerHorzLineLeaved event

OnWaveformAnalyzerHorzLineLeaved event

Remarks

Occurs when the playback position leaves a graphic item of type "horizontal line" inside the waveform analyzer.

This event replaces the usage of the CallbackWaveformAnalyzerHorzLineLeaved 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 graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerHorzLineLeaved ( _

ByVal nUniqueID as Integer, _

ByVal nStartPosInMs as Long, _

ByVal nEndPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nUniqueID | Unique identifier of the horizontal line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemHorizontalLineAdd method.
nStartPosInMs | Start position of the horizontal line expressed in milliseconds
nEndPosInMs | End position of the horizontal line expressed in milliseconds


OnWaveformAnalyzerHorzLineMoved event

OnWaveformAnalyzerHorzLineMoved event

Remarks

Occurs when a graphic item of type "horizontal line" inside the waveform analyzer is being moved through the mouse or through the WaveformAnalyzer.GraphicItemHorzPositionSet method.

This event replaces the usage of the CallbackWaveformAnalyzerHorzLineMoved 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 graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerHorzLineMoved ( _

ByVal nUniqueID as Integer, _

ByVal nStartPosInMs as Long, _

ByVal nEndPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nUniqueID | Unique identifier of the horizontal line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemHorizontalLineAdd method.
nStartPosInMs | New start position of the horizontal line expressed in milliseconds
nEndPosInMs | New end position of the horizontal line expressed in milliseconds


OnWaveformAnalyzerHorzLineReached event

OnWaveformAnalyzerHorzLineReached event

Remarks

Occurs when the playback position reaches a graphic item of type "horizontal line" inside the waveform analyzer.

This event replaces the usage of the CallbackWaveformAnalyzerHorzLineReached 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 graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerHorzLineReached ( _

ByVal nUniqueID as Integer, _

ByVal nStartPosInMs as Long, _

ByVal nEndPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nUniqueID | Unique identifier of the horizontal line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemHorizontalLineAdd method.
nStartPosInMs | Start position of the horizontal line expressed in milliseconds
nEndPosInMs | End position of the horizontal line expressed in milliseconds


OnWaveformAnalyzerLineMoved event

OnWaveformAnalyzerLineMoved event

Remarks

Occurs when a graphic item of type "vertical line" inside the waveform analyzer is being moved through the mouse or through the WaveformAnalyzer.GraphicItemHorzPositionSet method.

This event replaces the usage of the CallbackWaveformAnalyzerLineMoved 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 graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerLineMoved ( _

ByVal nUniqueID as Integer, _

ByVal nPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nUniqueID | Unique identifier of the vertical line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemVerticalLineAdd method.
nPosInMs | New position of the vertical line expressed in milliseconds


OnWaveformAnalyzerLineReached event

OnWaveformAnalyzerLineReached event

Remarks

Occurs when the playback position reaches a graphic item of type "vertical line" inside the waveform analyzer.

This event replaces the usage of the CallbackWaveformAnalyzerLineReached 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 graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerLineReached ( _

ByVal nUniqueID as Integer, _

ByVal nPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nUniqueID | Unique identifier of the vertical line; this unique identifier matches the unique identifier used when the custom line was created through the WaveformAnalyzer.GraphicItemVerticalLineAdd method.
nPosInMs | Position of the vertical line expressed in milliseconds


OnWaveformAnalyzerMouseNotif event

OnWaveformAnalyzerMouseNotif event

Remarks

Occurs when a mouse action happens over the waveform analyzer.

This event replaces the usage of the CallbackWaveformAnalyzerMouseNotif 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerMouseNotif ( _

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 "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters

Description

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. This notification is not generated when the waveform analyzer is empty.
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 client area of the whole user interface of the waveform analyzer, where the mouse generated the notification

yPos

Vertical position, expressed in pixels respect to the client area of the whole user interface of the waveform analyzer, 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.


OnWaveformAnalyzerPaintDone event

OnWaveformAnalyzerPaintDone event

Remarks

Occurs when the waveform analyzer has completed its graphic rendering, allowing to add custom graphics directly from the container application's code.

This event replaces the usage of the CallbackWaveformAnalyzerPaintDone 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerPaintDone ( _

ByVal hWnd as Long, _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
hWnd | Handle (HWND) to the window of the Waveform Analyzer: through this handle its possible accessing the handle to the device context (HDC) of the Waveform Analyzer using Windows API, for example through the GetDC and ReleaseDC functions.


OnWaveformAnalyzerRange event

OnWaveformAnalyzerRange event

Remarks

Occurs when the sound waveform's range displayed on the Waveform Analyzer's display has been changed after a zooming operation or after a scrolling operation or after a call to the WaveformAnalyzer.SetDisplayRange method.

This event replaces the usage of the CallbackWaveformAnalyzerRange 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerRange ( _

ByVal nBeginPosInMs as Long, _

ByVal nEndPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nBeginPosInMs | Displayed range start position, expressed in milliseconds
nEndPosInMs | Displayed range end position, expressed in milliseconds


OnWaveformAnalyzerSelection event

OnWaveformAnalyzerSelection event

Remarks

Occurs when a portion of the waveform on the Waveform Analyzer's display has been selected/deselected through a mouse operation or through a call to the WaveformAnalyzer.SetSelection method.

This event replaces the usage of the CallbackWaveformAnalyzerSelection 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerSelection ( _

ByVal bSelectionAvailable as Boolean, _

ByVal nBeginPosInMs as Long, _

ByVal nEndPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters

Description

bSelectionAvailable

Flag for selection availability.

Supported values are the following:

Value | Meaning
false | No selection is currently available. In this case values passed through nBeginPosInMs and nEndPosInMs parameters must be ignored.
true | A selection is currently available and the start and end positions are inside nBeginPosInMs and nEndPosInMs parameters.

nBeginPosInMs

The selection's start position, expressed in milliseconds

nEndPosInMs

The selection's end position, expressed in milliseconds


OnWaveAnalyzerSpectralViewStart event

OnWaveAnalyzerSpectralViewStart event

Remarks

Occurs when a new spectral view analysis begins.

This event replaces the usage of the CallbackWaveAnalyzerSpectralViewStart 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub EditorApi_OnWaveAnalyzerSpectralViewStart ( _

)

where "EditorApi" is declared in Visual Basic 6 code as:

Dim WithEvents EditorApi As AudioSoundEditorApi.AudioSoundEditorApiObj


OnWaveAnalyzerSpectralViewDone event

OnWaveAnalyzerSpectralViewDone event

Remarks

Occurs when a spectral view analysis is completed.

This event replaces the usage of the CallbackWaveAnalyzerSpectralViewDone 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub EditorApi_OnWaveAnalyzerSpectralViewDone ( _

nResult as enumErrorCodes

)

where "EditorApi" is declared in Visual Basic 6 code as:

Dim WithEvents EditorApi As AudioSoundEditorApi.AudioSoundEditorApiObj

Event Data

Parameter

Description

nResult

The result of the spectral analysis.

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 spectral view analysis completed successfully.


OnWaveformAnalyzerWaveRangeLeaved event

OnWaveformAnalyzerWaveRangeLeaved event

Remarks

Occurs when the playback position leaves a graphic item of type "wave range" inside the waveform analyzer.

This event replaces the usage of the CallbackWaveformAnalyzerWaveRangeLeaved 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 graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerWaveRangeLeaved ( _

ByVal nUniqueID as Integer, _

ByVal nStartPosInMs as Long, _

ByVal nEndPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nUniqueID | Unique identifier of the wave range; this unique identifier matches the unique identifier used when the wave range was created through the WaveformAnalyzer.GraphicItemWaveRangeAdd method.
nStartPosInMs | Start position of the wave range expressed in milliseconds
nEndPosInMs | End position of the wave range expressed in milliseconds


OnWaveformAnalyzerWaveRangeReached event

OnWaveformAnalyzerWaveRangeReached event

Remarks

Occurs when the playback position reaches a graphic item of type "wave range" inside the waveform analyzer.

This event replaces the usage of the CallbackWaveformAnalyzerWaveRangeReached 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 graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerWaveRangeReached ( _

ByVal nUniqueID as Integer, _

ByVal nStartPosInMs as Long, _

ByVal nEndPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nUniqueID | Unique identifier of the wave range; this unique identifier matches the unique identifier used when the wave range was created through the WaveformAnalyzer.GraphicItemWaveRangeAdd method.
nStartPosInMs | Start position of the wave range expressed in milliseconds
nEndPosInMs | End position of the wave range expressed in milliseconds


OnWaveformAnalyzerWidth event

OnWaveformAnalyzerWidth event

Remarks

Occurs when the waveform analyzer's display has been resized horizontally, usually after a call to the WaveformAnalyzer.Move method.

This event replaces the usage of the CallbackWaveformAnalyzerWidth 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 the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic 6]

Private Sub RecorderApi_OnWaveformAnalyzerWidth ( _

ByVal nWidthInMs as Long, _

ByVal nWidthInPixels as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

Event Data

Parameters | Description
nWidthInMs | Width of the display surface, expressed in milliseconds
nWidthInPixels | Width of the display surface, expressed in pixels


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 RecorderApi_OnWaveformScrollerManualScroll ( _

ByVal hWndWaveformScroller as Long, _

ByVal nNewPosInMs as Long _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

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 RecorderApi_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 "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

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 for notifying the percentage of advancement of a ZIP operation.

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 RecorderApi_OnZipOperationPerc ( _

ByVal nPercentage as Integer _

)

where "RecorderApi" is declared in Visual Basic 6 code as:

Dim WithEvents RecorderApi As AudioSoundRecorderApi.AudioSoundRecorderApiObj

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

The ASIOMan class is implemented through the following methods:

ControlPanelDisplay

DeviceChannelVolumeGet

DeviceChannelVolumeSet

DeviceGetChannelDesc

DeviceGetChannelsCount

DeviceGetCount

DeviceGetDesc

DeviceGetDriverPathname

DeviceGetIndexFromOutput

DeviceGetOutputIndex

DeviceIsStarted

DeviceLatencyGet

DeviceListenInputStart

DeviceListenInputPause

DeviceListenInputResume

DeviceMasterVolumeGet

DeviceMasterVolumeSet

DeviceRecordParamsGet

DeviceRecordParamsSet

DeviceSampleRateCurrentGet

DeviceSampleRateSupportedCountGet

DeviceSampleRateSupportedGet

DeviceStart

DeviceStop

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

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

- AsioStreamMixer (requires the installation of Audio DJ Studio API for .NET)


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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods which may contain both DirectSound and ASIO devices.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


ASIO.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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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.ERR_NOERROR (0) | The method call was successful.


ASIO.DeviceGetChannelDesc method

ASIO.DeviceGetChannelDesc method

Remarks

Retrieves the friendly description of the requested ASIO channel. This method is useful when you have to fill a combo box with the friendly names of available ASIO channels.

The total number of available ASIO channels can be obtained using the ASIO.DeviceGetChannelsCount method.

For further details about the use of ASIO drivers see the 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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.DeviceGetIndexFromIntput method

ASIO.DeviceGetIndexFromIntput method

Remarks

Given the zero-index of a generic input device, obtains the zero-based index of the corresponding ASIO device inside the list of available ASIO devices.

The list of generic input devices, which may include both DirectSound and ASIO devices, can be enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods. The list of ASIO devices, which includes ASIO devices only, can be enumerated through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods.

When the InitDriversType method has been called with the nDriverType parameter set to DRIVER_TYPE_ASIO or DRIVER_TYPE_BOTH_ASIO_FIRST, indexes of generic input 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 input devices will be listed first inside the list of available generic input devices so indexes of generic input devices will not match indexes of ASIO devices: in this case this specific method allows matching a generic input 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 input 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 DeviceGetIndexFromInput (

nOutputIndex as Int16

) as Int16

[C#]

public Int16 DeviceGetIndexFromInput (

Int16 nOutputIndex

);

[C++]

public: Int16 DeviceGetIndexFromInput (

Int16 nOutputIndex

);

Parameter | Description
nOutputIndex | Zero-based index of the input device as enumerated by the combination of the GetInputDevicesCount and GetInputDeviceDesc 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.DeviceGetInputIndex method

ASIO.DeviceGetInputIndex method

Remarks

Given the zero-index of an ASIO device, obtains the zero-based index of the corresponding input device inside the list of available generic input devices.

The list of generic input devices, which may include both DirectSound and ASIO devices, can be enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods. The list of ASIO devices, which includes ASIO devices only, can be enumerated through the ASIO.DeviceGetCount and ASIO.DeviceGetDesc methods.

When the InitDriversType method has been called with the nDriverType parameter set to DRIVER_TYPE_ASIO or DRIVER_TYPE_BOTH_ASIO_FIRST, indexes of generic input 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 input devices will be listed first inside the list of available generic input devices so indexes of generic input devices will not match indexes of ASIO devices: in this case this specific method allows matching a generic input device to a specific ASIO device.

If you know the zero-based index of an input device inside the list of available generic input devices and you need to know its zero-based index inside the list of ASIO devices, you can use the ASIO.DeviceGetIndexFromInput 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 DeviceGetInputIndex (

nDeviceIndex as Int16

) as Int16

[C#]

public Int16 DeviceGetInputIndex (

Int16 nDeviceIndex

);

[C++]

public: Int16 DeviceGetInputIndex (

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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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.

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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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.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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc 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.ERR_NOERROR (0) | The method call was successful.


ASIO.DeviceRecordParamsGet method

ASIO.DeviceRecordParamsGet method

Remarks

Obtains parameters for determining how ASIO mono channels are managed during a recording session. These parameters can be modified through the ASIO.DeviceRecordParamsSet 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 DeviceRecordParamsGet (

nDeviceIndex as Int16,

ByRef bPerformMixOnStereoOut as Boolean,

ByRef nMonoChanToStereoOutMode as enumAsioRecordMonoToStereoMode

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceRecordParamsGet (

Int16 nDeviceIndex,

ref bool bPerformMixOnStereoOut,

ref enumAsioRecordMonoToStereoMode DeviceRecordParamsGet

);

[C++]

public: enumErrorCodes DeviceRecordParamsSet (

Int16 nDeviceIndex,

bool __gc *bPerformMixOnStereoOut,

enumAsioRecordMonoToStereoMode __gc *nMonoChanToStereoOutMode

);

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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods which may contain both DirectSound and ASIO devices.

bPerformMixOnStereoOut

Reference that, on return from the method call, will contain the boolean value that determines if ASIO mono channels are mixed together before being sent to the stereo output.

Supported values are the following:

Mnemonic constant | Meaning
false | Mono channels are kept separated
true (default) | Mono channels are mixed

nMonoChanToStereoOutMode

Reference that, on return from the method call, will contain the value that determines how a single ASIO mono channel is rendered on a stereo output.

Supported values are the following:

Mnemonic constant | Value | Meaning
ASIO_REC_MONO_BOTH_CHANS (default) | 0 | The ASIO mono channel is rendered on both left and right channels of the stereo output
ASIO_REC_MONO_LEFT_CHAN | 1 | The ASIO mono channel is rendered on the left channel only of the stereo output
ASIO_REC_MONO_RIGHT_CHAN | 2 | The ASIO mono channel is rendered on the right channel only of the stereo output

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


ASIO.DeviceRecordParamsSet method

ASIO.DeviceRecordParamsSet method

Remarks

Sets parameters for determining how ASIO mono channels are managed during a recording session. Current parameters can be obtained through the ASIO.DeviceRecordParamsGet 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 DeviceRecordParamsSet (

nDeviceIndex as Int16,

bPerformMixOnStereoOut as Boolean,

nMonoChanToStereoOutMode as enumAsioRecordMonoToStereoMode

) as enumErrorCodes

[C#]

public enumErrorCodes DeviceRecordParamsSet (

Int16 nDeviceIndex,

bool bPerformMixOnStereoOut,

enumAsioRecordMonoToStereoMode nMonoChanToStereoOutMode

);

[C++]

public: enumErrorCodes DeviceRecordParamsSet (

Int16 nDeviceIndex,

bool bPerformMixOnStereoOut,

enumAsioRecordMonoToStereoMode nMonoChanToStereoOutMode

);

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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods which may contain both DirectSound and ASIO devices.

bPerformMixOnStereoOut

Boolean value that determines if ASIO mono channels are mixed together before being sent to the stereo output.

Supported values are the following:

Mnemonic constant | Meaning
false | Mono channels are kept separated
true (default) | Mono channels are mixed

nMonoChanToStereoOutMode

Value that determines how a single ASIO mono channel is rendered on a stereo output.

Supported values are the following:

Mnemonic constant | Value | Meaning
ASIO_REC_MONO_BOTH_CHANS (default) | 0 | The ASIO mono channel is rendered on both left and right channels of the stereo output
ASIO_REC_MONO_LEFT_CHAN | 1 | The ASIO mono channel is rendered on the left channel only of the stereo output
ASIO_REC_MONO_RIGHT_CHAN | 2 | The ASIO mono channel is rendered on the right channel only of the stereo output

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


ASIO.DeviceSampleRateCurrentGet method

ASIO.DeviceSampleRateCurrentGet method

Remarks

Obtains the sample rate currently selected inside the given ASIO device.

This method can be only used after the ASIO device has been started through the ASIO.DeviceStart method.

For further details about the use of ASIO drivers see the 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods which may contain both DirectSound and ASIO devices.
nRate | Reference that, on return from the method call, will contain the sample rate currently selected inside the given ASIO device.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


ASIO.DeviceSampleRateSupportedCountGet method

ASIO.DeviceSampleRateSupportedCountGet method

Remarks

Obtains the number of sample rates supported by the given ASIO device. Single supported sample rates can be obtained through the ASIO.DeviceSampleRateSupportedGet method.

This method can be only used after the ASIO device has been started through the ASIO.DeviceStart method.

For further details about the use of ASIO drivers see the 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods which may contain both DirectSound and ASIO devices.
nCount | Reference that, on return from the method call, will contain the number of sample rates supported by the given ASIO device.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


ASIO.DeviceSampleRateSupportedGet method

ASIO.DeviceSampleRateSupportedGet method

Remarks

Obtains a specific sample rate supported by the given ASIO device.

This method can be only used after the ASIO device has been started through the ASIO.DeviceStart method.

For further details about the use of ASIO drivers see the 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods which may contain both DirectSound and ASIO devices.
nSampleRateIndex | Number representing the zero-based index of a specific sample rate supported by the given ASIO device. The total number of supported sample rates can be obtained through the ASIO.DeviceSampleRateSupportedCountGet method.
nRate | Reference that, on return from the method call, will contain the requested sample rate supported by the given ASIO device.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


ASIO.DeviceStart method

ASIO.DeviceStart method

Remarks

Starts the given ASIO device.

This call is mandatory in order to start working with a specific ASIO device; 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.

IMPORTANT NOTE: When using Audio Sound Recorder API in conjunction with Audio DJ Studio API, you should prefer calling this method using the same ASIO.DeviceStart method available inside Audio DJ Studio API so you would have a better control over the playback mode.

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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods which may contain both DirectSound and ASIO devices.

nSampleRate

Sample rate to set into the ASIO device (0=leave current).

nChannelMode

Channel mode.

IMPORTANT NOTE: When using Audio Sound Recorder API in conjunction with Audio DJ Studio API, as seen inside the AsioStreamMixer sample, you should prefer calling this method using the same ASIO.DeviceStart method available inside Audio DJ Studio API so you would have a better control over the playback mode.

Supported values are the following:

Mnemonic constant | Value | Meaning
ASIO_CHANNEL_MODE_MULTI | 0 | Enables multichannel playback mode.
ASIO_CHANNEL_MODE_STEREO | 1 | Enables stereo playback mode. When NOT using Audio Sound Recorder API in conjunction with Audio DJ Studio API you can use this setting.
ASIO_CHANNEL_MODE_MIRROR_STEREO | 2 | Enables stereo channels mirroring playback mode.
ASIO_CHANNEL_MODE_MIRROR_MONO | 3 | Enables mono channel mirroring playback mode.

nOutputChannelFirst

Zero-based index of the first output channel used for sound rendering: this parameter is only used when the nChannelMode parameter is set to ASIO_CHANNEL_MODE_STEREO and is ignored in all other cases.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


ASIO.DeviceStop method

ASIO.DeviceStop method

Remarks

Stops the given ASIO device previously started through a call to the ASIO.DeviceStart method or through the ASIO.DeviceListenInputStart method.

You can know if a certain device is started or stopped through the ASIO.DeviceIsStarted method.

For further details about the use of ASIO drivers see the 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 input devices enumerated through the GetInputDevicesCount and GetInputDeviceDesc methods which may contain both DirectSound and ASIO devices.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


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


CoreAudioDevices.Free method

CoreAudioDevices.Free method

Remarks

Frees the list of audio endpoint devices and related resources.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.CapturePartChannelCountGet method

CoreAudioDevices.CapturePartChannelCountGet method

Remarks

Obtains the number of channels of a part embedded inside the given capture audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.CapturePartChannelVolumeGet method

CoreAudioDevices.CapturePartChannelVolumeGet method

Remarks

Obtains the channel's level of a part embedded inside the given capture audio endpoint device. The current level for the same part can be modified through the CoreAudioDevices.CapturePartChannelVolumeSet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.CapturePartChannelVolumeSet method

CoreAudioDevices.CapturePartChannelVolumeSet method

Remarks

Sets the channel's level of a part embedded inside the given capture audio endpoint device. The current level can be obtained through the CoreAudioDevices.CapturePartChannelVolumeGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.ChannelCountGet method

CoreAudioDevices.ChannelCountGet method

Remarks

After having enumerated the list of available audio endpoint devices through the CoreAudioDevices.Enum method, obtains the number of channels for a specific audio endpoint device having a specific data flow (playback or recording).

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.ChannelVolumeGet method

CoreAudioDevices.ChannelVolumeGet method

Remarks

Obtains the volume of a channel of the given audio endpoint device. The current channel volume can be modified through the CoreAudioDevices.ChannelVolumeSet method.

You can be notified in real-time about volume changes by catching the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.ChannelVolumeSet method

CoreAudioDevices.ChannelVolumeSet method

Remarks

Sets the volume of a channel of the given audio endpoint device. The current channel volume can be obtained through the CoreAudioDevices.ChannelVolumeGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.CountGet method

CoreAudioDevices.CountGet method

Remarks

After having enumerated the list of available audio endpoint devices through the CoreAudioDevices.Enum method, obtains the number of enumerated audio endpoint devices for a specific data flow (playback or recording).

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.DefaultGet method

CoreAudioDevices.DefaultGet method

Remarks

Obtains the system default device for the given role. The container application can be notified about changes to the system default device 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.DescGet method

CoreAudioDevices.DescGet method

Remarks

Obtains the friendly name of the audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.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.ERR_NOERROR (0) | The method call was successful.


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


CoreAudioDevices.JackDescriptorGet method

CoreAudioDevices.JackDescriptorGet method

Remarks

Obtains the description of an audio jack on the connector.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.MasterVolumeGet method

CoreAudioDevices.MasterVolumeGet method

Remarks

Obtains the master volume of the given audio endpoint device. The current master volume can be modified through the CoreAudioDevices.MasterVolumeSet method.

You can be notified in real-time about volume changes by catching the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.MasterVolumeSet method

CoreAudioDevices.MasterVolumeSet method

Remarks

Sets the master volume of the given audio endpoint device. The current master volume can be obtained through the CoreAudioDevices.MasterVolumeGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the CoreAudioDevicesMan class.

Syntax

[Visual Basic]

Public Function MasterVolumeSet (

nDataFlow as enumCoreAudioDataFlows,

nDeviceIndex as Int16,

nScaleType as enumVolumeScales,

ByRef fVolumeLevel as Single

) as enumErrorCodes

[C#]

public enumErrorCodes MasterVolumeSet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

enumVolumeScales nScaleType,

ref float fVolumeLevel

);

[C++]

public: enumErrorCodes MasterVolumeSet (

enumCoreAudioDataFlows nDataFlow,

Int16 nDeviceIndex,

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.

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 the returned 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.MuteGet method

CoreAudioDevices.MuteGet method

Remarks

Obtains the muting state of the audio stream that enters or leaves the given audio endpoint device.

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


CoreAudioDevices.MuteSet method

CoreAudioDevices.MuteSet method

Remarks

Applies the muting state of the audio stream that enters or leaves the given audio endpoint device. given 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 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.RenderPartChannelCountGet method

CoreAudioDevices.RenderPartChannelCountGet method

Remarks

Obtains the number of channels of a part embedded inside the given render audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.RenderPartChannelVolumeGet method

CoreAudioDevices.RenderPartChannelVolumeGet method

Remarks

Obtains the channel's level of a part embedded inside the given render audio endpoint device. The current level for the same part can be modified through the CoreAudioDevices.RenderPartChannelVolumeSet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.RenderPartChannelVolumeSet method

CoreAudioDevices.RenderPartChannelVolumeSet method

Remarks

Sets the channel's level of a part embedded inside the given render audio endpoint device. The current level can be obtained through the CoreAudioDevices.RenderPartChannelVolumeGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.RenderPartMuteGet method

CoreAudioDevices.RenderPartMuteGet method

Remarks

Obtains the muting state of the stream leaving the render part of the given audio endpoint device. The muting state can be modified through the CoreAudioDevices.RenderPartMuteSe t method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.RenderPartMuteSet method

CoreAudioDevices.RenderPartMuteSet method

Remarks

Applies the muting state of the stream leaving the render part of the given audio endpoint device. The current muting state can be obtained through the CoreAudioDevices.RenderPartMuteGet method.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.StatusGet method

CoreAudioDevices.StatusGet method

Remarks

Obtains the status of the given audio endpoint device. The container application can be informed in real time about changes of the device status 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.TypeGet method

CoreAudioDevices.TypeGet method

Remarks

Obtains the type of a specific audio endpoint device.

This method is only intended for usage with Windows Vista and later versions: further information about management of audio devices in Windows Vista and later versions can be found inside the How to access settings of audio devices in Windows Vista and later versions tutorial.

For further details about methods related to the management of core audio devices refer to the 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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.VuMeterChannelPeakValueGet method

CoreAudioDevices.VuMeterChannelPeakValueGet method

Remarks

Obtains the VU-Meter's peak value for a specific channel of the given audio endpoint device. You can be informed about changes of VU-meters peaks by enabling notification about VU-meters changes (through the CoreAudioDevices.VuMeterEnableNotifications method) and 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.ERR_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.ERR_NOERROR (0) | The method call was successful.


CoreAudioDevices.VuMeterMasterPeakValueGet method

CoreAudioDevices.VuMeterMasterPeakValueGet method

Remarks

Obtains the master VU-Meter's peak value for the given audio endpoint device. You can be informed about changes of VU-meters peaks by enabling notification about VU-meters changes (through the CoreAudioDevices.VuMeterEnableNotifications method) and 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.ERR_NOERROR (0) | The method call was successful.


CustomDSP class

CustomDSP class

The CustomDSPs class, accessible through the control's CustomDSP property, contains methods that allow processing sound data being recorded.

The CustomDSP class is implemented through the following methods:

Methods

Enable

ExternalEditorGetInfo

ExternalEditorShow

ExternalGetParameters

ExternalLoad

ExternalSendCommand

ExternalSetFunction

ExternalSetParameters

Free

InternalLoad

InternalSetFunction

UseFloatSamples

For further details about managing custom DSP effects refer to the How to manage custom DSP effects section.

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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function Enable (

nIdDsp as Int32,

bEnable as Boolean,

nUserData as Int32,

nPriority as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Enable (

Int32 nIdDsp,

bool bEnable,

Int32 nUserData,

Int32 nPriority

);

[C++]

public: enumErrorCodes Enable (

Int32 nIdDsp,

bool bEnable,

Int32 nUserData,

Int32 nPriority

);

Parameter

Description

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

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.


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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function ExternalEditorGetInfo (

nIdDsp as Int32,

pInfo as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalEditorGetInfo (

Int32 nIdDsp,

IntPtr pInfo

);

[C++]

public: enumErrorCodes ExternalEditorGetInfo (

Int32 nIdDsp,

IntPtr pInfo

);

Parameter | Description
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.ERR_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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function ExternalEditorShow (

nIdDsp as Int32,

bShow as Boolean,

hWndParent as IntPtr,

leftPos as Int32,

topPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalEditorShow (

Int32 nIdDsp,

bool bShow,

IntPtr hWndParent,

Int32 leftPos,

Int32 topPos

);

[C++]

public: enumErrorCodes ExternalEditorShow (

Int32 nIdDsp,

bool bShow,

IntPtr hWndParent,

Int32 leftPos,

Int32 topPos

);

Parameter

Description

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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function ExternalGetParameters (

nIdDsp as Int32,

pParameters as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalGetParameters (

Int32 nIdDsp,

IntPtr pParameters

);

[C++]

public: enumErrorCodes ExternalGetParameters (

Int32 nIdDsp,

IntPtr pParameters

);

Parameter | Description
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.ERR_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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function ExternalLoad (

strPathname as String

) as Int32

[C#]

public Int32 ExternalLoad (

string strPathname

);

[C++]

public: Int32 ExternalLoad (

string strPathname

);

Parameter

Description

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 | 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
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function ExternalSendCommand (

nIdDsp as Int32,

hWndParent as IntPtr,

strCommand as string

) as Int32

[C#]

public Int32 ExternalSendCommand (

Int32 nIdDsp,

IntPtr hWndParent,

string strCommand

);

[C++]

public: Int32 ExternalSendCommand (

Int32 nIdDsp,

IntPtr hWndParent,

string strCommand

);

Parameter

Description

nIdDsp

Unique identifier of the custom DSP

hWndParent

Handle of the window (HWND) containing the Audio Sound Recorder 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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function ExternalSetFunction (

nIdDsp as Int32,

nFunctionType as enumDspExternalFunctions,

strFunctionName as string

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalSetFunction (

Int32 nIdDsp,

enumDspExternalFunctions nFunctionType,

string strFunctionName

);

[C++]

public: enumErrorCodes ExternalSetFunction (

Int32 nIdDsp,

enumDspExternalFunctions nFunctionType,

string strFunctionName

);

Parameter

Description

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.ERR_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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function ExternalSetParameters (

nIdDsp as Int32,

pParameters as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes ExternalSetParameters (

Int32 nIdDsp,

IntPtr pParameters

);

[C++]

public: enumErrorCodes ExternalSetParameters (

Int32 nIdDsp,

IntPtr pParameters

);

Parameter | Description
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.ERR_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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function Free (

nIdDsp as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Free (

Int32 nIdDsp

);

[C++]

public: enumErrorCodes Free (

Int32 nIdDsp

);

Parameter | Description
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.ERR_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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function InternalLoad (

) as Int32

[C#]

public Int32 InternalLoad (

);

[C++]

public: Int32 InternalLoad (

);

Return value

Value | Meaning
> 0 | 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
Negative value | An error occurred: see the LastError property for further error details or for a list of the possible error values.


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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

Syntax

[Visual Basic]

Public Function InternalSetFunction (

nIdDsp as Int32,

function as DSPCallbackFunction

) as enumErrorCodes

[C#]

public enumErrorCodes InternalSetFunction (

Int32 nIdDsp,

DSPCallbackFunction function

);

[C++]

public: enumErrorCodes InternalSetFunction (

Int32 nIdDsp,

DSPCallbackFunction function

);

Parameter

Description

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 ReverbCallback(

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.ERR_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 managing a custom DSP effect refer to the How to manage custom DSP effects section.

For further details about methods related to the use of custom DSP effects refer to the CustomDSPs class.

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

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.


EncodeAAC class

EncodeAAC class

The EncodeAAC class, accessible through the control's EncodeFormats.AAC property, contains methods and properties needed to take advantage of encoding in AAC and MP4 format.

The EncodeAAC class is implemented through the following properties and methods:

Properties

EncodeMode

Quality

CustomString

WrapInMP4

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.AAC.CustomString property

EncodeFormats.AAC.CustomString property

Type

[Visual Basic]

Public Property CustomString As string

[C#]

public string CustomString {get; set;}

[C++]

public: __property string get_CustomString();

public: __property void set_CustomString(string);

Remarks

String containing custom AAC options to send to the Faac encoder.

For advanced users, this string allows applying all of the possible AAC encoding options available with Faac. See Appendix C - Faac command line for the complete set of available options.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC and the EncodeFormats.AAC.EncodeMode property is set to AAC_ENCODE_CUSTOM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_AAC and the EncodeFormats.AAC.EncodeMode property is set to AAC_ENCODE_CUSTOM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_AAC and the EncodeFormats.AAC.EncodeMode property is set to AAC_ENCODE_CUSTOM (for further details see the How to export a recorded sound section).

MPORTANT NOTE: As you may know, the Faac command line is as follows:

usage: Faac [options] <infile> [outfile]

Contents of the CustomString property are related to the [options] field only so you must omit entering the word faac and omit to specify the <infile> and [outfile] settings also. You should also omit the -P and -X options which are already applied internally.

For further details about encoding in AAC and MP4 format refer to the EncodeAAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AAC.EncodeMode property

EncodeFormats.AAC.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumAacEncodeModes

[C#]

public enumAacEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumAacEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumAacEncodeModes);

Remarks

The encoding mode used for AAC and MP4 format during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
AAC_ENCODE_VBR_QUALITY | 0 | Encode using the Variable Bitrate (VBR) quality specified inside the EncodeFormats.AAC.Quality property.
AAC_ENCODE_CUSTOM | 1 | Encode using the custom string defined inside the EncodeFormats.AAC.CustomString property.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_AAC (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_AAC (for further details see the How to export a recorded sound section).

For further details about encoding in AAC and MP4 format refer to the EncodeAAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AAC.Quality property

EncodeFormats.AAC.Quality property

Type

[Visual Basic]

Public Property Quality As float

[C#]

public float Quality {get; set;}

[C++]

public: __property float get_Quality();

public: __property void set_Quality(float);

Remarks

Sets encoding quality, expressed in percentage, used for AAC and MP4 format during recording, exporting or CD ripping sessions.

A default value of 100, averages at approx. 120 kbps VBR for a normal stereo input file with 16 bit and 44.1 kHz sample rate; max supported value is 500, min. supported value is 10.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC and the EncodeFormats.AAC.EncodeMode property is set to AAC_ENCODE_QUALITY (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_AAC and the EncodeFormats.AAC.EncodeMode property is set to AAC_ENCODE_QUALITY (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_AAC and the EncodeFormats.AAC.EncodeMode property is set to AAC_ENCODE_QUALITY (for further details see the How to export a recorded sound section).

This property is the same as entering the -q <quality> setting inside the Appendix C - Faac command line.

For further details about encoding in AAC and MP4 format refer to the EncodeAAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AAC.WrapInMP4 property

EncodeFormats.AAC.WrapInMP4 property

Type

[Visual Basic]

Public Property WrapInMP4 As bool

[C#]

public bool WrapInMP4 {get; set;}

[C++]

public: __property bool get_WrapInMP4();

public: __property void set_WrapInMP4(bool);

Remarks

Wraps AAC data in MP4 container.

Due to the fact that AAC format doesn't support tags, during CD ripping sessions this property is ignored if the CddbAddTagOnCdRipping property is set to True, condition where only MP4 is supported.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AAC (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_AAC (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_AAC (for further details see the How to export a recorded sound section).

This property is the same as entering the -w setting inside the Appendix C - Faac command line.

For further details about encoding in AAC and MP4 format refer to the EncodeAAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AAC.GetEncodeModeDesc method

EncodeFormats.AAC.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the AAC format.

The number of available encoding modes can be obtained using the EncodeFormats.AAC.GetEncodeModesCount method.

For further details about encoding in AAC and MP4 format refer to the EncodeAAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.AAC.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.AAC.GetEncodeModesCount method

EncodeFormats.AAC.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the AAC and MP4 format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.AAC.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.AAC.EncodeMode property.

For further details about encoding in AAC and MP4 format refer to the EncodeAAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeAACPlus class

EncodeAACPlus class

The EncodeAACPlus class, accessible through the control's EncodeFormats.AACPlus property, contains methods and properties needed to take advantage of encoding in AAC and MP4 format.

The EncodeAACPlus class is implemented through the following properties and methods:

Properties

EncodeMode

CBR

CustomString

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AACPlus.CBR property

EncodeFormats.AACPlus.CBR property

Type

[Visual Basic]

Public Property CBR As float

[C#]

public float CBR {get; set;}

[C++]

public: __property float get_CBR();

public: __property void set_CBR(float);

Remarks

The Constant Bitrate (CBR), expressed in bits per second (bps), used for AAC+ format.

This property is used only in the following situations:

During a recording session if the EncodeFormat.ForRecording property is set to ENCODING_FORMAT_AAC_PLUS (for further details see the How to perform a recording session section)..

During a CD ripping session if the EncodeFormat.ForCdRipping property is set to ENCODING_FORMAT_AAC_PLUS (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormat.ForExporting property is set to ENCODING_FORMAT_AAC_PLUS (for further details see the How to export a recorded sound section).

This property is the same as entering either the --bitrate <n> and --bitrate-mode 0 setting inside the Appendix F - FdkAac command line

For further details about encoding in AAC+ format refer to the EncodeAACPlus class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AACPlus.CustomString property

EncodeFormats.AACPlus.CustomString property

Type

[Visual Basic]

Public Property CustomString As string

[C#]

public string CustomString {get; set;}

[C++]

public: __property string get_CustomString();

public: __property void set_CustomString(string);

Remarks

String containing custom AAC+ options to send to the FdkAac encoder.

For advanced users, this string allows applying all of the possible AAC+ encoding options available with FdkAac. See Appendix F - FdkAac command line for the complete set of available options.

This property is used only in the following situations:

During a recording session if the EncodeFormat.ForRecording property is set to ENCODING_FORMAT_AAC_PLUS and the EncodeFormats.AACPlus.EncodeMode property is set to AACPLUS_ENCODE_CUSTOM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormat.ForCdRipping property is set to ENCODING_FORMAT_AAC_PLUS and the EncodeFormats.AACPlus.EncodeMode property is set to AACPLUS_ENCODE_CUSTOM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormat.ForExporting property is set to ENCODING_FORMAT_AAC_PLUS and the EncodeFormats.AACPlus.EncodeMode property is set to AACPLUS_ENCODE_CUSTOM (for further details see the How to export a recorded sound section).

IMPORTANT NOTE: As you may know, the Fdkaac command line is as follows:

usage: fdkaac [options] input_file

Contents of the CustomString property are related to the [options] field only so you must omit entering the word fdkaac and omit to specify the input_file and -o <filename> settings also. You should also omit the -S and --raw options which are already applied internally.

For further details about encoding in AAC+ format refer to the EncodeAACPlus class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AACPlus.EncodeMode property

EncodeFormats.AACPlus.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumAacEncodeModes

[C#]

public enumAacEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumAacEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumAacEncodeModes);

Remarks

The encoding mode used for AAC+ format during exporting sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
AACPLUS_ENCODE_MPEG4_LC | 0 | Encodes using the MPEG-4 AAC LC profile.
AACPLUS_ENCODE_MPEG4_HE | 1 | Encodes using the MPEG-4 HE-AAC profile.
AACPLUS_ENCODE_MPEG4_HE_V2 | 2 | Encodes using the MPEG-4 HE-AAC v2 profile.
AACPLUS_ENCODE_CUSTOM | 3 | Encode using the custom string defined inside the EncodeFormats.AACPlus.CustomString property.

This property is used only in the following situations:

During a recording session if the EncodeFormat.ForRecording property is set to ENCODING_FORMAT_AAC_PLUS (for further details see the How to perform a recording session section)..

During a CD ripping session if the EncodeFormat.ForCdRipping property is set to ENCODING_FORMAT_AAC_PLUS (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormat.ForExporting property is set to ENCODING_FORMAT_AAC_PLUS (for further details see the How to export a recorded sound section).

For further details about encoding in AAC+ format refer to the EncodeAACPlus class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AACPlus.GetEncodeModeDesc method

EncodeFormats.AACPlus.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the AAC+ format.

The number of available encoding modes can be obtained using the EncodeFormats.AACPlus.GetEncodeModesCount method.

For further details about encoding in AAC+ format refer to the EncodeAACPlus class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.AACPlus.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.AACPlus.GetEncodeModesCount method

EncodeFormats.AACPlus.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the AAC+ format

The friendly description of each encoding mode can be obtained using the EncodeFormats.AACPlus.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.AACPlus.EncodeMode property.

For further details about encoding in AAC+ format refer to the EncodeAACPlus class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeACM class

EncodeACM class

The EncodeACM class, accessible through the control's EncodeFormats.ACM property, contains methods needed to take advantage of the Windows Audio Compression Manager.

For details about the use of the Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

The ACM class is implemented through the following properties and methods:

Properties

EncodeMode

CodecIndex

CodecFormatIndex

Methods

InitCodecs

GetCodecsCount

GetCodecDesc

GetCodecFormatsCount

GetCodecFormatDesc

GetCodecFormatWavData

GetCodecFormatWavDataLength

SetCodecFormatWavData

For further information about available encoding formats see the EncodeFormatsMan class.

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

- AudioCompressionManager

- CdRipperWithACM

- InsertRecAtPos

- RecordedSoundEditor

- RewindRecPos

- SimpleRecorder


EncodeFormats.ACM.CodecFormatIndex property

EncodeFormats.ACM.CodecFormatIndex property

Type

[Visual Basic]

Public Property CodecFormatIndex As Int16

[C#]

public Int16 CodecFormatIndex {get; set;}

[C++]

public: __property Int16 get_CodecFormatIndex();

public: __property void set_CodecFormatIndex(Int16);

Remarks

Zero-based index of the specific format for the ACM codec used for a recording, CD ripping or exporting session: the ACM codec can be modified through the EncodeFormats.ACM.CodecIndex property.

This property is used only when the EncodeFormats.ACM.EncodeMode property is set to ACM_ENCODE_USE_CODEC_INDEX and in one of the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_ACM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_ACM (for further details see the How to export a recorded sound section).

For further details about using the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.ACM.CodecIndex property

EncodeFormats.ACM.CodecIndex property

Type

[Visual Basic]

Public Property CodecIndex As Int16

[C#]

public Int16 CodecIndex {get; set;}

[C++]

public: __property Int16 get_CodecIndex();

public: __property void set_CodecIndex(Int16);

Remarks

Zero-based index of the ACM codec used for a recording, CD ripping or exporting session.

This property is used only when the EncodeFormats.ACM.EncodeMode property is set to ACM_ENCODE_USE_CODEC_INDEX and in one of the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_ACM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_ACM (for further details see the How to export a recorded sound section).

The specific format for the chosen ACM codec can be modified through the EncodeFormats.ACM.CodecFormatIndex property.

For further details about using the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.ACM.EncodeMode property

EncodeFormats.ACM.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumAcmEncodeModes

[C#]

public enumAcmEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumAcmEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumAcmEncodeModes);

Remarks

The encoding mode used during recording, exporting or CD ripping sessions using a codec of the Windows Audio Compression Manager.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
ACM_ENCODE_USE_CODEC_INDEX | 0 | Encode using the ACM codec defined inside the EncodeFormats.ACM.CodecIndex property and the related format defined inside the EncodeFormats.ACM.CodecFormatIndex property
ACM_ENCODE_USE_WAV_FORMAT | 1 | Encode using the ACM codec represented by the WAV format previously set through a call to the EncodeFormats.ACM.SetCodecFormatWavData method

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_ACM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_ACM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_ACM (for further details see the How to export a recorded sound section).

For further details about using the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.ACM.InitCodecs method

EncodeFormats.ACM.InitCodecs method

Remarks

Initializes the EncodeACM class which allows enumerating codecs and respective formats installed within the Windows Audio Compression Manager. The call to this method is mandatory if you need to start a recording, ripping or exporting session using one of the installed ACM codecs.

For further details about the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function InitCodecs (

) as enumErrorCodes

[C#]

public enumErrorCodes InitCodecs (

);

[C++]

public: enumErrorCodes InitCodecs (

);

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.


EncodeFormats.ACM.GetCodecsCount method

EncodeFormats.ACM.GetCodecsCount method

Remarks

Returns the number of ACM (Audio Compression Manager) codecs installed inside the system: this method will fail without a previous call to the EncodeFormats.ACM.InitCodecs method.

The friendly description of each ACM codec can be obtained using the EncodeFormats.ACM.GetCodecDesc method.

For further details about the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetCodecsCount (

) as Int16

[C#]

public Int16 GetCodecsCount (

);

[C++]

public: Int16 GetCodecsCount (

);

Return value

The number of ACM codecs installed inside the system


EncodeFormats.ACM.GetCodecDesc method

EncodeFormats.ACM.GetCodecDesc method

Remarks

Returns the friendly description of the given ACM (Audio Compression Manager) codec.

The total number of available ACM codecs can be obtained using the EncodeFormats.ACM.GetCodecsCount method.

For further details about the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetCodecDesc (

nCodecIndex as Int16

) as String

[C#]

public string GetCodecDesc (

Int16 nCodecIndex

);

[C++]

public: string GetCodecDesc (

Int16 nCodecIndex

);

Parameter | Description
nCodecIndex | Number representing the zero-based index of the ACM codec

Return value

Value | Meaning
Empty string | The value of the nCodecIndex parameter was out of range. Use the value returned by the EncodeFromats.ACM.GetCodecsCount method in order to know how many ACM codecs are currently installed on the system.
Valid string | The string containing the friendly description of the requested ACM codec.


EncodeFormats.ACM.GetCodecFormatsCount method

EncodeFormats.ACM.GetCodecFormatsCount method

Remarks

Returns the number of formats available for the given ACM codec.

The friendly description of each ACM format can be obtained using the EncodeFormats.ACM.GetCodecFormatDesc method.

For further details about the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetCodecFormatsCount (

nCodecIndex as integer

) as Int16

[C#]

public Int16 GetCodecFormatsCount (

Int16 nCodecIndex

);

[C++]

public: Int16 GetCodecFormatsCount (

Int16 nCodecIndex

);

Parameter | Description
nCodecIndex | Number representing the zero-based index of the ACM codec

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


EncodeFormats.ACM.GetCodecFormatDesc method

EncodeFormats.ACM.GetCodecFormatDesc method

Remarks

Returns the friendly description of the given format for a certain ACM codec.

The number of available formats for the given ACM codec can be obtained using the EncodeFormats.ACM.GetCodecFormatsCount method.

For further details about the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetCodecFormatDesc (

nCodecIndex as Int16,

nCodecFormatIndex as Int16

) as String

[C#]

public string GetCodecFormatDesc (

Int16 nCodecIndex,

Int16 nCodecFormatIndex

);

[C++]

public: string GetCodecFormatDesc (

Int16 nCodecIndex,

Int16 nCodecFormatIndex

);

Parameter | Description
nCodecIndex | Number representing the zero-based index of the ACM codec
nCodecFormatIndex | Number representing the zero-based index of the format for the given ACM codec

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 friendly description of the format


EncodeFormats.ACM.GetCodecFormatWavData method

EncodeFormats.ACM.GetCodecFormatWavData method

Remarks

Obtains the WAVEFORMATEX data structure, which defines the format of waveform-audio data, that describes the format of the given ACM codec including any extra-byte the specific format may require.

The WAVEFORMATEX structure, common to all waveform-audio formats, is defined inside the Microsoft SDK as follows:

typedef struct {

 WORD  wFormatTag;

 WORD  nChannels;

 DWORD nSamplesPerSec;

 DWORD nAvgBytesPerSec;

 WORD  nBlockAlign;

 WORD  wBitsPerSample;

 WORD  cbSize;

} WAVEFORMATEX;

The cbSize member defines how many extra-bytes are appended to the end of the WAVEFORMATEX structure: the total size in bytes of the WAVEFORMATEX data structure that describes the given format, including any extra-byte the specific format may require, can be obtained using the EncodeFormats.ACM.GetCodecFormatWavDataLength method.

For further details about the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetCodecFormatWavData (

nCodecIndex as Int16,

nCodecFormatIndex as Int16,

pWavData() as Byte,

sizeWavData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetCodecFormatWavData (

Int16 nCodecIndex,

Int16 nCodecFormatIndex,

byte [] pWavData,

Int32 sizeWavData

);

[C++]

public: enumErrorCodes GetCodecFormatWavData (

Int16 nCodecIndex,

Int16 nCodecFormatIndex,

unsigned char __gc[] pWavData,

Int32 sizeWavData

);

Parameter | Description
nCodecIndex | Number representing the zero-based index of the ACM codec
nCodecFormatIndex | Number representing the zero-based index of the format for the given ACM codec
pWavData | Memory buffer that, on exit from the method's call, will contain the given codec's format description: this buffer should be allocated through a global variable in order to avoid becoming invalid when the variable will go out of scope.
sizeWavData | The size in bytes of the WAVEFORMATEX data structure, including any extra-byte the specific format may require: this parameter should be initialized using a previous call to the EncodeFormats.ACM.GetCodecFormatWavDataLength 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


EncodeFormats.ACM.GetCodecFormatWavDataLength method

EncodeFormats.ACM.GetCodecFormatWavDataLength method

Remarks

Obtains the size in bytes of the WAVEFORMATEX data structure that describes the format of the given ACM codec.

The WAVEFORMATEX data structure that describes the given format can be obtained using the EncodeFormats.ACM.GetCodecFormatWavData method.

For further details about the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetCodecFormatWavDataLength (

nCodecIndex as Int16,

nCodecFormatIndex as Int16,

ByRef sizeWavData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetCodecFormatWavDataLength (

Int16 nCodecIndex,

Int16 nCodecFormatIndex,

ref Int32 sizeWavData

);

[C++]

public: enumErrorCodes GetCodecFormatWavDataLength (

Int16 nCodecIndex,

Int16 nCodecFormatIndex,

Int32 __gc *sizeWavData

);

Parameter | Description
nCodecIndex | Number representing the zero-based index of the ACM codec
nCodecFormatIndex | Number representing the zero-based index of the format for the given ACM codec
sizeWavData | Reference that, on return from the method call, will contain the size in bytes of the WAVEFORMATEX data structure: it's important to note that this value will be inclusive of any extra-byte required by the specific format.

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


EncodeFormats.ACM.SetCodecFormatWavData method

EncodeFormats.ACM.SetCodecFormatWavData method

Remarks

Sets the WAVEFORMATEX data structure including any extra-byte the specific format may require.

This method is useful for setting the WAV format of an ACM codec without the need to visually enumerate codecs currently installed on the target PC and is used for recording, CD ripping and exporting sessions when the EncodeFormats.ACM.EncodeMode property is set to ACM_ENCODE_USE_WAV_FORMAT.

The WAVEFORMATEX structure, common to all waveform-audio formats, is defined inside the Microsoft SDK as follows:

typedef struct {

 WORD  wFormatTag;

 WORD  nChannels;

 DWORD nSamplesPerSec;

 DWORD nAvgBytesPerSec;

 WORD  nBlockAlign;

 WORD  wBitsPerSample;

 WORD  cbSize;

} WAVEFORMATEX;

The cbSize member defines how many extra-bytes, specific for the needed codec, are appended to the end of the WAVEFORMATEX structure.

It's important to note that further encoding through the downloaded WAV format will not work if the specific codec is not installed on the target PC.

For further details about the Windows Audio Compression Manager refer to the EncodeACM class section.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function SetCodecFormatWavData (

pWavData() as Byte,

sizeWavData as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetCodecFormatWavData (

byte [] pWavData,

Int32 sizeWavData

);

[C++]

public: enumErrorCodes SetCodecFormatWavData (

unsigned char __gc[] pWavData,

Int32 sizeWavData

);

Parameter | Description
pWavData | Memory buffer that, on exit from the method's call, will contain the given codec's format description: this buffer should be allocated through a global variable in order to avoid becoming invalid when the variable will go out of scope.
sizeWavData | The size in bytes of the WAVEFORMATEX data structure, including any extra-byte the specific format may require

Return value

Value | Meaning
Negative value | An error occurred, check the LastError property value in order to get the error code
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


EncodeAIFF class

EncodeAIFF class

The EncodeAIFF class, accessible through the control's EncodeFormats.AIFF property, contains methods needed to take advantage of encoding in various Apple/SGI AIFF formats.

The EncodeAIFF class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.AIFF.EncodeMode property

EncodeFormats.AIFF.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumAIFFEncodeModes

[C#]

public enumAIFFEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumAIFFEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumAIFFEncodeModes);

Remarks

The Apple/SGI AIFF encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
AIFF_ENCODE_PCM_U8 | 0 | AIFF PCM 8 bits Unsigned
AIFF_ENCODE_PCM_S8 | 1 | AIFF PCM 8 bits Signed
AIFF_ENCODE_PCM_S16 | 2 | AIFF PCM 16 bits Signed
AIFF_ENCODE_PCM_S24 | 3 | AIFF PCM 24 bits Signed
AIFF_ENCODE_PCM_S32 | 4 | AIFF PCM 32 bits Signed
AIFF_ENCODE_FLOAT32 | 5 | AIFF 32 bits floating point
AIFF_ENCODE_G711_ULAW | 6 | AIFF G711 U-LAW
AIFF_ENCODE_G711_ALAW | 7 | AIFF G711 A-LAW
AIFF_ENCODE_GSM_610 | 8 | AIFF GSM 6.10

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AIFF (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_AIFF (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_AIFF (for further details see the How to export a recorded sound section).

For further details about using the Apple/SGI AIFF format refer to the EncodeAIFF class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AIFF.GetEncodeModeDesc method

EncodeFormats.AIFF.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Apple/SGI AIFF format.

The number of available encoding modes can be obtained using the EncodeFormats.AIFF.GetEncodeModesCount method.

For further details about encoding in Apple/SGI AIFF format refer to the EncodeAIFF class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.AIFF.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.AIFF.GetEncodeModesCount method

EncodeFormats.AIFF.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Apple/SGI AIFF format

The friendly description of each encoding mode can be obtained using the EncodeFormats.AIFF.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.AIFF.EncodeMode property.

For further details about encoding in Apple/SGI AIFF format refer to the EncodeAIFF class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeAU class

EncodeAU class

The EncodeAU class, accessible through the control's EncodeFormats.AU property, contains methods needed to take advantage of encoding in various Sun/NeXT AU formats.

The EncodeAU class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.AU.EncodeMode property

EncodeFormats.AU.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumAUEncodeModes

[C#]

public enumAUEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumAUEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumAUEncodeModes);

Remarks

The Sun/NeXT AU encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
AU_ENCODE_PCM_S8 | 0 | AU PCM 8 bits Signed
AU_ENCODE_PCM_S16 | 1 | AU PCM 16 bits Signed
AU_ENCODE_PCM_S24 | 2 | AU PCM 24 bits Signed
AU_ENCODE_PCM_S32 | 3 | AU PCM 32 bits Signed
AU_ENCODE_FLOAT32 | 4 | AU 32 bits floating point
AU_ENCODE_G711_ULAW | 5 | AU G711 U-LAW
AU_ENCODE_G711_ALAW | 6 | AU G711 A-LAW
AU_ENCODE_G721_ADPCM_32 | 7 | AU G721 ADPCM 32 kbps
AU_ENCODE_G723_ADPCM_24 | 8 | AU G723 ADPCM 24 kbps
AU_ENCODE_G723_ADPCM_40 | 9 | AU G723 ADPCM 40 kbps

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_AU (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_AU (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_AU (for further details see the How to export a recorded sound section).

For further details about using the Sun/NeXT AU format refer to the EncodeAU class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AU.GetEncodeModeDesc method

EncodeFormats.AU.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Sun/NeXT AU format.

The number of available encoding modes can be obtained using the EncodeFormats.AU.GetEncodeModesCount method.

For further details about encoding in Sun/NeXT AU format refer to the EncodeAU class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.AU.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.AU.GetEncodeModesCount method

EncodeFormats.AU.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Sun/NeXT AU format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.AU.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.AU.EncodeMode property.

For further details about encoding in Sun/NeXT AU format refer to the EncodeAU class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeCAF class

EncodeCAF class

The EncodeCAF class, accessible through the control's EncodeFormats.CAF property, contains methods needed to take advantage of encoding in various Core Audio File formats.

The EncodeCAF class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.CAF.EncodeMode property

EncodeFormats.CAF.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumCAFEncodeModes

[C#]

public enumCAFEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumCAFEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumCAFEncodeModes);

Remarks

The Core Audio File encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
CAF_ENCODE_PCM_S8 | 0 | CAF PCM 8 bits Signed
CAF_ENCODE_PCM_S16 | 1 | CAF PCM 16 bits Signed
CAF_ENCODE_PCM_S24 | 2 | CAF PCM 24 bits Signed
CAF_ENCODE_PCM_S32 | 3 | CAF PCM 32 bits Signed
CAF_ENCODE_FLOAT32 | 4 | CAF 32 bits floating point
CAF_ENCODE_G711_ULAW | 5 | CAF G711 U-LAW
CAF_ENCODE_G711_ALAW | 6 | CAF G711 A-LAW

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_CAF (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_CAF (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_CAF (for further details see the How to export a recorded sound section).

For further details about using the Core Audio File format refer to the EncodeCAF class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.CAF.GetEncodeModeDesc method

EncodeFormats.CAF.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Core Audio File format.

The number of available encoding modes can be obtained using the EncodeFormats.CAF.GetEncodeModesCount method.

For further details about encoding in Core Audio File format refer to the EncodeCAF class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.CAF.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.CAF.GetEncodeModesCount method

EncodeFormats.CAF.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Core Audio File format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.CAF.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.CAF.EncodeMode property.

For further details about encoding in Core Audio File format refer to the EncodeCAF class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeFLAC class

EncodeFLAC class

The EncodeFLAC class, accessible through the control's EncodeFormats.FLAC property, contains methods needed to take advantage of encoding in various FLAC formats.

The EncodeFLAC class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- SimpleRecorder


EncodeFormats.FLAC.EncodeMode property

EncodeFormats.FLAC.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumFLACEncodeModes

[C#]

public enumFLACEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumFLACEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumFLACEncodeModes);

Remarks

The Core Audio File encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
FLAC_ENCODE_PCM_S8 | 0 | FLAC PCM 8 bits Signed
FLAC_ENCODE_PCM_S16 | 1 | FLAC PCM 16 bits Signed
FLAC_ENCODE_PCM_S24 | 2 | FLAC PCM 24 bits Signed

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_FLAC (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_FLAC (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_FLAC (for further details see the How to export a recorded sound section).

For further details about using the FLAC format refer to the EncodeFLAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.FLAC.GetEncodeModeDesc method

EncodeFormats.FLAC.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the FLAC format.

The number of available encoding modes can be obtained using the EncodeFormats.FLAC.GetEncodeModesCount method.

For further details about encoding in FLAC format refer to the EncodeFLAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.FLAC.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.FLAC.GetEncodeModesCount method

EncodeFormats.FLAC.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the FLAC format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.FLAC.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.FLAC.EncodeMode property.

For further details about encoding in FLAC format refer to the EncodeFLAC class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeFormatsMan class

EncodeFormatsMan class

The EncodeFormats class, accessible through the control's EncodeFormats property, contains contains properties and methods needed to take advantage of encoding and resampling capabilities exposed by the component.

The EncodeFormats class is implemented through the following properties:

Properties

ForRecording

ForCdRipping

ForExporting

ResampleMode

ResampleCustomFrequency

ResampleCustomChannels

ResampleNativeFormat

MP3

MP2

OGG

OPUS

WAV

WMA

AAC

AACPlus

ACM

W64

AIFF

AU

PAF

SVX

NIST

VOC

IRCAM

PVF

CAF

FLAC

RAW

Methods

ResampleNativeFormatsGetCount

ResampleNativeFormatGetDesc

Most of the samples installed with the product's setup package show the usage of the EncodeFormats object in Visual Basic 6 and Visual C++ 6.


EncodeFormats.ForCdRipping property

EncodeFormats.ForCdRipping property

Type

[Visual Basic]

Public Property ForCdRipping As enumEncodingFormats

[C#]

public enumEncodingFormats ForCdRipping {get; set;}

[C++]

public: __property enumEncodingFormats get_ForCdRipping();

public: __property void set_ForCdRipping(enumEncodingFormats);

Remarks

The format used for encoding the result of the next CD ripping session.

Supported values are the following:

Mnemonic Value | Value | Meaning
ENCODING_FORMAT_WAV | 1 | WAV format
ENCODING_FORMAT_MP3 | 2 | MP3 format through the Lame.exe external encoder, if available on the target system.
ENCODING_FORMAT_WMA | 3 | WMA format through the Windows Media Audio components, if available on the target system: check the return value of the IsWmaAvailable method for this purpose.
ENCODING_FORMAT_OGG | 4 | OGG Vorbis format through the OggEnc.exe external encoder, if available on the target system.
ENCODING_FORMAT_WAV_IEEE_FLOAT | 5 | Deprecated value: use ENCODING_FORMAT_WAV format in conjunction with the EncodeFormats.WAV.EncodeMode property set to WAV_ENCODE_FLOAT32
ENCODING_FORMAT_AAC | 6 | AAC or MP4 format through the Faac.exe external encoder, if available on the target system; note that encoding in memory is currently not supported by Faac.exe encoder.
ENCODING_FORMAT_ACM | 7 | Format supported by one of the Audio Compression Manager codecs available on the target system
ENCODING_FORMAT_AIFF | 8 | Apple/SGI AIFF format
ENCODING_FORMAT_AU | 9 | Sun/NeXT AU format
ENCODING_FORMAT_PAF | 10 | Ensoniq PARIS format
ENCODING_FORMAT_SVX | 11 | Commodore Amiga IFF / SVX format
ENCODING_FORMAT_NIST | 12 | Sphere NIST format
ENCODING_FORMAT_IRCAM | 13 | Berkeley/IRCAM/CARL format
ENCODING_FORMAT_VOC | 14 | Creative VOC format
ENCODING_FORMAT_W64 | 15 | Sonic Foundry's 64 bit RIFF/WAV format
ENCODING_FORMAT_PVF | 16 | Portable Voice Format format
ENCODING_FORMAT_CAF | 17 | Core Audio File format
ENCODING_FORMAT_RAW | 18 | RAW format
ENCODING_FORMAT_FLAC | 19 | FLAC format
ENCODING_FORMAT_MP2 | 20 | MP2 format through the TwoLame.exe external encoder, if available on the target system.
ENCODING_FORMAT_OPUS | 21 | OPUS format through the OpusEnc.exe external encoder, if available on the target system.
ENCODING_FORMAT_AAC_PLUS | 22 | AAC+ (HE-AAC) format through the Fdkaac.exe external encoder, if available on the target system; note that encoding in memory is currently not supported by Fdkaac.exe encoder. The specific AAC+ encoding mode can be defined inside the EncodeFormats.AACPlus.EncodeMode property.

For further details see the How to perform a CD ripping session section.


EncodeFormats.ForExporting property

EncodeFormats.ForExporting property

Type

[Visual Basic]

Public Property ForExporting As enumEncodingFormats

[C#]

public enumEncodingFormats ForExporting {get; set;}

[C++]

public: __property enumEncodingFormats get_ForExporting();

public: __property void set_ForExporting(enumEncodingFormats);

Remarks

The format used for exporting sound data of the current recording session contents.

Supported values are the following:

Mnemonic Value | Value | Meaning
ENCODING_FORMAT_WAV | 1 | WAV format
ENCODING_FORMAT_MP3 | 2 | MP3 format through the Lame.exe external encoder, if available on the target system.
ENCODING_FORMAT_WMA | 3 | WMA format through the Windows Media Audio components, if available on the target system: check the return value of the IsWmaAvailable method for this purpose.
ENCODING_FORMAT_OGG | 4 | OGG Vorbis format through the OggEnc.exe external encoder, if available on the target system.
ENCODING_FORMAT_WAV_IEEE_FLOAT | 5 | Deprecated value: use ENCODING_FORMAT_WAV format in conjunction with the EncodeFormats.WAV.EncodeMode property set to WAV_ENCODE_FLOAT32
ENCODING_FORMAT_AAC | 6 | AAC or MP4 format through the Faac.exe external encoder, if available on the target system; note that encoding in memory is currently not supported by Faac.exe encoder.
ENCODING_FORMAT_ACM | 7 | Format supported by one of the Audio Compression Manager codecs available on the target system
ENCODING_FORMAT_AIFF | 8 | Apple/SGI AIFF format
ENCODING_FORMAT_AU | 9 | Sun/NeXT AU format
ENCODING_FORMAT_PAF | 10 | Ensoniq PARIS format
ENCODING_FORMAT_SVX | 11 | Commodore Amiga IFF / SVX format
ENCODING_FORMAT_NIST | 12 | Sphere NIST format
ENCODING_FORMAT_IRCAM | 13 | Berkeley/IRCAM/CARL format
ENCODING_FORMAT_VOC | 14 | Creative VOC format
ENCODING_FORMAT_W64 | 15 | Sonic Foundry's 64 bit RIFF/WAV format
ENCODING_FORMAT_PVF | 16 | Portable Voice Format format
ENCODING_FORMAT_CAF | 17 | Core Audio File format
ENCODING_FORMAT_RAW | 18 | RAW format
ENCODING_FORMAT_FLAC | 19 | FLAC format
ENCODING_FORMAT_MP2 | 20 | MP2 format through the TwoLame.exe external encoder, if available on the target system.
ENCODING_FORMAT_OPUS | 21 | OPUS format through the OpusEnc.exe external encoder, if available on the target system.
ENCODING_FORMAT_AAC_PLUS | 22 | AAC+ (HE-AAC) format through the Fdkaac.exe external encoder, if available on the target system; note that encoding in memory is currently not supported by Fdkaac.exe encoder. The specific AAC+ encoding mode can be defined inside the EncodeFormats.AACPlus.EncodeMode property.

For further details see the How to export a recorded sound section.


EncodeFormats.ForRecording property

EncodeFormats.ForRecording property

Type

[Visual Basic]

Public Property ForRecording As enumEncodingFormats

[C#]

public enumEncodingFormats ForRecording {get; set;}

[C++]

public: __property enumEncodingFormats get_ForRecording();

public: __property void set_ForRecording(enumEncodingFormats);

Remarks

The format used for encoding the result of the next recording session.

Supported values are the following:

Mnemonic Value | Value | Meaning
ENCODING_FORMAT_NOFILE | 0 | Recorded sound will not be stored inside an output file so no encoding will be performed: this setting is useful for displaying the audio input levels through the embedded visual feedbacks.
ENCODING_FORMAT_WAV | 1 | WAV format
ENCODING_FORMAT_MP3 | 2 | MP3 format through the Lame.exe external encoder, if available on the target system.
ENCODING_FORMAT_WMA | 3 | WMA format through the Windows Media Audio components, if available on the target system: check the return value of the IsWmaAvailable method for this purpose
ENCODING_FORMAT_OGG | 4 | OGG Vorbis format through the OggEnc.exe external encoder, if available on the target system.
ENCODING_FORMAT_WAV_IEEE_FLOAT | 5 | Deprecated value: use ENCODING_FORMAT_WAV format in conjunction with the EncodeFormats.WAV.EncodeMode property set to WAV_ENCODE_FLOAT32
ENCODING_FORMAT_AAC | 6 | AAC or MP4 format through the Faac.exe external encoder, if available on the target system; note that encoding in memory is currently not supported by Faac.exe encoder.
ENCODING_FORMAT_ACM | 7 | Format supported by one of the Audio Compression Manager codecs available on the target system
ENCODING_FORMAT_AIFF | 8 | Apple/SGI AIFF format
ENCODING_FORMAT_AU | 9 | Sun/NeXT AU format
ENCODING_FORMAT_PAF | 10 | Ensoniq PARIS format
ENCODING_FORMAT_SVX | 11 | Commodore Amiga IFF / SVX format
ENCODING_FORMAT_NIST | 12 | Sphere NIST format
ENCODING_FORMAT_IRCAM | 13 | Berkeley/IRCAM/CARL format
ENCODING_FORMAT_VOC | 14 | Creative VOC format
ENCODING_FORMAT_W64 | 15 | Sonic Foundry's 64 bit RIFF/WAV format
ENCODING_FORMAT_PVF | 16 | Portable Voice Format format
ENCODING_FORMAT_CAF | 17 | Core Audio File format
ENCODING_FORMAT_RAW | 18 | RAW format
ENCODING_FORMAT_FLAC | 19 | FLAC format
ENCODING_FORMAT_MP2 | 20 | MP2 format through the TwoLame.exe external encoder, if available on the target system.
ENCODING_FORMAT_OPUS | 21 | OPUS format through the OpusEnc.exe external encoder, if available on the target system.
ENCODING_FORMAT_AAC_PLUS | 22 | AAC+ (HE-AAC) format through the Fdkaac.exe external encoder, if available on the target system; note that encoding in memory is currently not supported by Fdkaac.exe encoder. The specific AAC+ encoding mode can be defined inside the EncodeFormats.AACPlus.EncodeMode property.

For further information about available encoding formats see the EncodeFormatsMan class.

For further details see the How to perform a recording session section.


EncodeFormats.ResampleCustomChannels property

EncodeFormats.ResampleCustomChannels property

Type

[Visual Basic]

Public Property ResampleCustomChannels As Int16

[C#]

public Int16 ResampleCustomChannels {get; set;}

[C++]

public: __property Int16 get_ResampleCustomChannels();

public: __property void set_ResampleCustomChannels(Int16);

Remarks

Specific number of channels for resampling purposes: accepted values are 1 for Mono or 2 for Stereo (default)

This property is ignored for recording sessions when the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE.

For further details about encoding and resampling options refer to the EncodeFormatsMan class section.


EncodeFormats.ResampleCustomFrequency property

EncodeFormats.ResampleCustomFrequency property

Type

[Visual Basic]

Public Property ResampleCustomFrequency As Int32

[C#]

public Int32 ResampleCustomFrequency {get; set;}

[C++]

public: __property Int32 get_ResampleCustomFrequency();

public: __property void set_ResampleCustomFrequency(Int32);

Remarks

Specific frequency for resampling purposes (default 44100).

This property is ignored for recording sessions when the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE.

For further details about encoding and resampling options refer to the EncodeFormatsMan class section.


EncodeFormats.ResampleMode property

EncodeFormats.ResampleMode property

Type

[Visual Basic]

Public Property ResampleMode As enumResampleModes

[C#]

public enumResampleModes ResampleMode {get; set;}

[C++]

public: __property enumResampleModes get_ResampleMode();

public: __property void set_ResampleMode(enumResampleModes);

Remarks

The resampling mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value

Numeric value

Meaning

RESAMPLE_MODE_CUSTOM_FORMAT (default)

0

Custom resampling format which requires specifying the resampling frequency inside the EncodeFormats.ResampleCustomFrequency and the number of channels inside the EncodeFormats.ResampleCustomChannels

RESAMPLE_MODE_NATIVE_FORMAT

1

Native resampling format which requires specifying, inside the EncodeFormats.ResampleNativeFormat property, the index of one of the resampling formats supported by the sound card in use.

Native formats can be used only in presence of a sound card.

This option is not supported when the InitDriversType method has been invoked with the nDriverType parameter set to DRIVER_TYPE_WASAPI.

This option is not supported when recording from a RAW audio queue started through the StartFromQueueRaw method.

This property is ignored for recording sessions when the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE.

For further details about encoding and resampling options refer to the EncodeFormatsMan class section.


EncodeFormats.ResampleNativeFormat property

EncodeFormats.ResampleNativeFormat property

Type

[Visual Basic]

Public Property ResampleNativeFormat As Int16

[C#]

public Int16 ResampleNativeFormat {get; set;}

[C++]

public: __property Int16 get_ResampleNativeFormat();

public: __property void set_ResampleNativeFormat(Int16);

Remarks

The index of one of the native resampling formats supported by the sound card in use.

The number of available native formats can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their respective friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc.

This property can be set to -1 when the recording session is performed from a file: in this case the control will start recording using the original parameters (frequency, channels and bits per sample) of the input file and will not perform any resampling.

This property is ignored for recording sessions when the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE.

For further details about encoding and resampling options refer to the EncodeFormatsMan class section.


EncodeFormats.AAC property (RO)

EncodeFormats.AAC property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property AAC As EncodeAAC

[C#]

public EncodeAAC AAC {get;}

[C++]

public: __property EncodeAAC* get_AAC ();

This property is Read-only

Remarks

The object that gives access to AAC and MP4 encoding.

This property encapsulates the functionality of the EncodeAAC class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AACPlus property (RO)

EncodeFormats.AACPlus property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property AACPlus As EncodeAACPlus

[C#]

public EncodeAACPlus AACPlus {get;}

[C++]

public: __property EncodeAACPlus* get_AACPlus ();

This property is Read-only

Remarks

The object that gives access to AAC+ (HE-AAC) encoding.

This property encapsulates the functionality of the EncodeAACPlus class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.ACM property (RO)

EncodeFormats.ACM property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property ACM As EncodeACM

[C#]

public EncodeACM ACM {get;}

[C++]

public: __property EncodeACM* get_ACM ();

This property is Read-only

Remarks

The Audio Compression Manager object.

This property encapsulates the functionality of the EncodeACM class.

For a tutorial about the use of the Windows Audio Compression Manager refer to the How to use the Windows Audio Compression Manager section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AIFF property (RO)

EncodeFormats.AIFF property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property AIFF As EncodeAIFF

[C#]

public EncodeAIFF AIFF {get;}

[C++]

public: __property EncodeAIFF* get_AIFF ();

This property is Read-only

Remarks

The object that gives access to AIFF encoding.

This property encapsulates the functionality of the EncodeAIFF class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.AU property (RO)

EncodeFormats.AU property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property AU As EncodeAU

[C#]

public EncodeAU AU {get;}

[C++]

public: __property EncodeAU* get_AU ();

This property is Read-only

Remarks

The object that gives access to Sun/NeXT AU encoding.

This property encapsulates the functionality of the EncodeAU class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.CAF property (RO)

EncodeFormats.CAF property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property CAF As EncodeCAF

[C#]

public EncodeCAF CAF {get;}

[C++]

public: __property EncodeCAF* get_CAF ();

This property is Read-only

Remarks

The object that gives access to Core Audio File encoding.

This property encapsulates the functionality of the EncodeCAF class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.FLAC property (RO)

EncodeFormats.FLAC property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property FLAC As EncodeFLAC

[C#]

public EncodeFLAC FLAC {get;}

[C++]

public: __property EncodeFLAC* get_FLAC ();

This property is Read-only

Remarks

The object that gives access to FLAC encoding.

This property encapsulates the functionality of the EncodeFLAC class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.IRCAM property (RO)

EncodeFormats.IRCAM property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property IRCAM As EncodeIRCAM

[C#]

public EncodeIRCAM IRCAM {get;}

[C++]

public: __property EncodeIRCAM* get_IRCAM ();

This property is Read-only

Remarks

The object that gives access to Berkeley/IRCAM/CARL encoding.

This property encapsulates the functionality of the EncodeIRCAM class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP2 property (RO)

EncodeFormats.MP2 property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property MP2 As EncodeMP2

[C#]

public EncodeMP2 MP2 {get;}

[C++]

public: __property EncodeMP2* get_MP2 ();

This property is Read-only

Remarks

The object that gives access to MP2 encoding.

This property encapsulates the functionality of the EncodeMP2 class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP3 property (RO)

EncodeFormats.MP3 property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property MP3 As EncodeMP3

[C#]

public EncodeMP3 MP3 {get;}

[C++]

public: __property EncodeMP3* get_MP3 ();

This property is Read-only

Remarks

The object that gives access to MP3 encoding.

This property encapsulates the functionality of the EncodeMP3 class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.NIST property (RO)

EncodeFormats.NIST property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property NIST As EncodeNIST

[C#]

public EncodeNIST NIST {get;}

[C++]

public: __property EncodeNIST* get_NIST ();

This property is Read-only

Remarks

The object that gives access to Sphere NIST encoding.

This property encapsulates the functionality of the EncodeNIST class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OGG property (RO)

EncodeFormats.OGG property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property OGG As EncodeOGG

[C#]

public EncodeOGG OGG {get;}

[C++]

public: __property EncodeOGG* get_OGG ();

This property is Read-only

Remarks

The object that gives access to OGG Vorbis encoding.

This property encapsulates the functionality of the EncodeOGG class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OPUS property (RO)

EncodeFormats.OPUS property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property OPUS As EncodeOPUS

[C#]

public EncodeOPUS OPUS {get;}

[C++]

public: __property EncodeOPUS* get_OPUS ();

This property is Read-only

Remarks

The object that gives access to OPUS encoding.

For further details about encoding in OPUS format refer to the EncodeOPUS class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.PAF property (RO)

EncodeFormats.PAF property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property PAF As EncodePAF

[C#]

public EncodePAF PAF {get;}

[C++]

public: __property EncodePAF* get_PAF ();

This property is Read-only

Remarks

The object that gives access to Ensoniq PARIS encoding.

This property encapsulates the functionality of the EncodePAF class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.PVF property (RO)

EncodeFormats.PVF property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property PVF As EncodePVF

[C#]

public EncodePVF PVF {get;}

[C++]

public: __property EncodePVF* get_PVF ();

This property is Read-only

Remarks

The object that gives access to Portable Voice Format encoding.

This property encapsulates the functionality of the EncodePVF class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.RAW property (RO)

EncodeFormats.RAW property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property RAW As EncodeRAW

[C#]

public EncodeRAW RAW {get;}

[C++]

public: __property EncodeRAW* get_RAW ();

This property is Read-only

Remarks

The object that gives access to RAW encoding.

This property encapsulates the functionality of the EncodeRAW class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.SVX property (RO)

EncodeFormats.SVX property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property SVX As EncodeSVX

[C#]

public EncodeSVX SVX {get;}

[C++]

public: __property EncodeSVX* get_SVX ();

This property is Read-only

Remarks

The object that gives access to Commodore Amiga IFF / SVX encoding.

This property encapsulates the functionality of the EncodeSVX class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.VOC property (RO)

EncodeFormats.VOC property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property VOC As EncodeVOC

[C#]

public EncodeVOC VOC {get;}

[C++]

public: __property EncodeVOC* get_VOC ();

This property is Read-only

Remarks

The object that gives access to Creative VOC encoding.

This property encapsulates the functionality of the EncodeVOC class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.W64 property (RO)

EncodeFormats.W64 property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property W64 As EncodeW64

[C#]

public EncodeW64 W64 {get;}

[C++]

public: __property EncodeW64* get_W64 ();

This property is Read-only

Remarks

The object that gives access to Sonic Foundry's 64 bit RIFF/WAV encoding.

This property encapsulates the functionality of the EncodeW64 class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.WAV property (RO)

EncodeFormats.WAV property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property WAV As EncodeWAV

[C#]

public EncodeWAV WAV {get;}

[C++]

public: __property EncodeWAV* get_WAV ();

This property is Read-only

Remarks

The object that gives access to WAV encoding.

This property encapsulates the functionality of the EncodeWAV class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.WMA property (RO)

EncodeFormats.WMA property (RO)

Return to chapter overview

Type

[Visual Basic]

Public Property WMA As EncodeWMA

[C#]

public EncodeWMA WMA {get;}

[C++]

public: __property EncodeWMA* get_WMA ();

This property is Read-only

Remarks

The object that gives access to WMA encoding.

This property encapsulates the functionality of the EncodeWMA class.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.ResampleNativeFormatGetDesc method

EncodeFormats.ResampleNativeFormatGetDesc method

Remarks

Retrieves the friendly description for a given recording format (e.g. "44100 Hz, Stereo, 16-bit").

The number of available recording formats can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding and resampling options refer to the EncodeFormatsMan class section.

Syntax

[Visual Basic]

Public Function ResampleNativeFormatGetDesc (

nInputDevice as Int16,

nFormatIndex as Int16

) as string

[C#]

public string ResampleNativeFormatGetDesc (

Int16 nInputDevice,

Int16 nFormatIndex

);

[C++]

public: string ResampleNativeFormatGetDesc (

Int16 nInputDevice,

Int16 nFormatIndex

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device. Use the value returned by the GetInputDevicesCount method in order to know how many input devices are currently installed on the system and the GetInputDeviceDesc method in order to retrieve the friendly name of each input device.
nFormatIndex | Number representing the zero-based index of the recording format

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 friendly description of the requested recording format.


EncodeFormats.ResampleNativeFormatsGetCount method

EncodeFormats.ResampleNativeFormatsGetCount method

Remarks

Retrieves the number of supported recording formats.

The friendly description of each recording format can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding and resampling options refer to the EncodeFormatsMan class section.

Syntax

[Visual Basic]

Public Function ResampleNativeFormatsGetCount (

nInputDevice as Int16

) as Int16

[C#]

public Int16 ResampleNativeFormatsGetCount (

Int16 nInputDevice

);

[C++]

public: Int16 ResampleNativeFormatsGetCount (

Int16 nInputDevice

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device. Use the value returned by the GetInputDevicesCount method in order to know how many input devices are currently installed on the system and the GetInputDeviceDesc method in order to retrieve the friendly name of each input device.

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 supported formats.


EncodeIRCAM class

EncodeIRCAM class

The EncodeIRCAM class, accessible through the control's EncodeFormats.IRCAM property, contains methods needed to take advantage of encoding in various Berkeley/IRCAM/CARL formats.

The EncodeIRCAM class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.IRCAM.EncodeMode property

EncodeFormats.IRCAM.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumIRCAMEncodeModes

[C#]

public enumIRCAMEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumIRCAMEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumIRCAMEncodeModes);

Remarks

The Berkeley/IRCAM/CARL encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
IRCAM_ENCODE_PCM_S16 | 0 | IRCAM PCM 16 bits Signed
IRCAM_ENCODE_PCM_S24 | 1 | Unsupported, when used will generate a IRCAM PCM 16 bits Signed
IRCAM_ENCODE_PCM_S32 | 2 | IRCAM PCM 32 bits Signed
IRCAM_ENCODE_FLOAT32 | 3 | IRCAM 32 bits floating point
IRCAM_ENCODE_G711_ULAW | 4 | IRCAM G711 U-LAW
IRCAM_ENCODE_G711_ALAW | 5 | IRCAM G711 A-LAW

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_IRCAM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_IRCAM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_IRCAM (for further details see the How to export a recorded sound section).

For further details about using the Berkeley/IRCAM/CARL format refer to the EncodeIRCAM class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.IRCAM.GetEncodeModeDesc method

EncodeFormats.IRCAM.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Berkeley/IRCAM/CARL format.

The number of available encoding modes can be obtained using the EncodeFormats.IRCAM.GetEncodeModesCount method.

For further details about encoding in Berkeley/IRCAM/CARL format refer to the EncodeIRCAM class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.IRCAM.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.IRCAM.GetEncodeModesCount method

EncodeFormats.IRCAM.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Berkeley/IRCAM/CARL format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.IRCAM.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.IRCAM.EncodeMode property.

For further details about encoding in Berkeley/IRCAM/CARL format refer to the EncodeIRCAM class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeMP2 class

EncodeMP2 class

The EncodeMP2 class, accessible through the control's EncodeFormats.MP2 property, contains methods and properties needed to take advantage of encoding in MP2 format.

The EncodeMP3 class is implemented through the following properties and methods:

Properties

EncodeMode

CBR

CustomString

Downmix

Methods

GetEncodeModesCount

GetEncodeModeDesc

GetTwoLameEncodingBitratesCount

GetTwoLameEncodingBitrate

GetTwoLameEncodingBitratesCountEx

GetTwoLameEncodingBitrateEx

For further information about available encoding formats see the EncodeFormatsMan class.

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

- SimpleRecorder


EncodeFormats.MP2.CBR property

EncodeFormats.MP2.CBR property

Type

[Visual Basic]

Public Property CBR As Int32

[C#]

public Int32 CBR {get; set;}

[C++]

public: __property Int32 CBR();

public: __property void CBR(Int32);

Remarks

The Constant Bitrate (CBR), expressed in bits per second (bps), used for MP2 format during recording or CD ripping sessions.

This is the default encoding mode and the bitrate will be the same for the whole file. It means that each part of your mp2 file will be using the same number of bits. The musical passage being a difficult one to encode or an easy one, the encoder will use the same bitrate, so the quality of your mp2 is variable. Complex parts will be of a lower quality than the easiest ones. The main advantage is that the final files size won't change and can be accurately predicted.

Note that, depending upon the chosen input format (fixed to 44100 Hz, 16 bits, Stereo for CD ripping sessions), not all of the bitrate values are supported by TwoLame.

The full list of Constant Bitrates, supported by a certain native input format, can be obtained using the EncodeFormats.MP2.GetTwoLameEncodingBitratesCount and EncodeFormats.MP2.GetTwoLameEncodingBitrate methods.

The full list of Constant Bitrates, supported by a certain frequency, can be obtained using the EncodeFormats.MP2.GetTwoLameEncodingBitratesCountEx and EncodeFormats.MP2.GetTwoLameEncodingBitrateEx methods.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP2 and the EncodeFormats.MP2.EncodeMode property is set to MP2_ENCODE_CBR (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP2 and the EncodeFormats.MP2.EncodeMode property is set to MP2_ENCODE_CBR (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP2 and the EncodeFormats.MP2.EncodeMode property is set to MP2_ENCODE_CBR (for further details see the How to export a recorded sound section).

This property is the same as entering the -b <kbps> setting inside the Appendix D - TwoLame command line.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP2.CustomString property

EncodeFormats.MP2.CustomString property

Type

[Visual Basic]

Public Property CustomString As string

[C#]

public string CustomString {get; set;}

[C++]

public: __property string get_CustomString();

public: __property void set_CustomString(string);

Remarks

String containing custom MP2 options to send to the TwoLame encoder.

For advanced users, this string allows applying all of the possible MP2 encoding options available with TwoLame. See Appendix D - TwoLame command line for the complete set of available options.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP2 and the EncodeFormats.MP2.EncodeMode property is set to MP2_ENCODE_CUSTOM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP2 and the EncodeFormats.MP2.EncodeMode property is set to MP2_ENCODE_CUSTOM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP2 and the EncodeFormats.MP2.EncodeMode property is set to MP2_ENCODE_CUSTOM (for further details see the How to export a recorded sound section).

IMPORTANT NOTE: As you may know, the TwoLame command line is as follows:

usage: twolame [options] <infile> [outfile]

Contents of the EncodeFormats.MP2.CustomString property are related to the [options] field only so you must omit entering the word twoame and omit to specify the <infile> and [outfile] settings also. You should also omit the -r option which is already applied internally and the --x option which is not compatible with the control.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP2.Downmix property

EncodeFormats.MP2.Downmix property

Type

[Visual Basic]

Public Property Downmix As bool

[C#]

public bool Downmix {get; set;}

[C++]

public: __property bool get_Downmix();

public: __property void set_Downmix(bool);

Remarks

Downmixes from stereo to mono file for mono encoding in MP2 format.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP2 (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP2 (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP2 (for further details see the How to export a recorded sound section).

This property is the same as entering the -a setting inside the Appendix D - TwoLame command line.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP2.EncodeMode property

EncodeFormats.MP2.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumMp2EncodeModes

[C#]

public enumMp2EncodeModes EncodeMode {get; set;}

[C++]

public: __property enumMp2EncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumMp2EncodeModes);

Remarks

The encoding mode used for MP2 format during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
MP2_ENCODE_CBR | 0 | Encode using the Constant Bitrate (CBR) specified inside the EncodeFormats.MP2.CBR property. In this mode, the bitrate will be the same for the whole file. It means that each part of your mp2 file will be using the same number of bits. The musical passage being a difficult one to encode or an easy one, the encoder will use the same bitrate, so the quality of your mp2 is variable. Complex parts will be of a lower quality than the easiest ones. The main advantage is that the final files size won't change and can be accurately predicted.
MP2_ENCODE_CUSTOM | 1 | Encode using the custom string defined inside the EncodeFormats.MP2.CustomString property.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP2 (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP2 (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP2 (for further details see the How to export a recorded sound section).

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP2.GetEncodeModeDesc method

EncodeFormats.MP2.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the MP2 format.

The number of available encoding modes can be obtained using the EncodeFormats.MP2.GetEncodeModesCount method.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.MP2.EncodeMode property.

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 friendly description of the requested encode mode.


EncodeFormats.MP2.GetEncodeModesCount method

EncodeFormats.MP2.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the MP2 format

The friendly description of each encoding mode can be obtained using the EncodeFormats.MP2.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.MP2.EncodeMode property.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeFormats.MP2.GetTwoLameEncodingBitrate method

EncodeFormats.MP2.GetTwoLameEncodingBitrate method

Remarks

Retrieves a specific encoding bitrate (Constant Bitrate or CBR) supported by TwoLame for a given recording format.

The number of available bitrates can be obtained using the EncodeFormats.MP2.GetTwoLameEncodingBitratesCount method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetTwoLameEncodingBitrate (

nInputDevice as Int16,

nFormatIndex as Int16,

nBitrateIndex as Int16

) as Int32

[C#]

public Int32 GetTwoLameEncodingBitrate (

Int16 nInputDevice,

Int16 nFormatIndex,

Int16 nBitrateIndex

);

[C++]

public: Int32 GetTwoLameEncodingBitrate (

Int16 nInputDevice,

Int16 nFormatIndex,

Int16 nBitrateIndex

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nFormatIndex | Number representing the zero-based index of the native resampling format. The number of native resampling formats supported by the given input device can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.
nBitrateIndex | Number representing the zero-based index of the bitrate

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The requested encoding costant bitrate


EncodeFormats.MP2.GetTwoLameEncodingBitrateEx method

EncodeFormats.MP2.GetTwoLameEncodingBitrateEx method

Remarks

Retrieves a specific encoding bitrate (for Constant Bitrate or CBR) supported by TwoLame for a given frequency.

The number of available bitrates can be obtained using the EncodeFormats.MP2.GetTwoLameEncodingBitratesCountEx method.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetTwoLameEncodingBitrateEx (

nFrequency as Int32,

nBitrateIndex as Int16

) as Int32

[C#]

public Int32 GetTwoLameEncodingBitrateEx (

Int32 nFrequency,

Int16 nBitrateIndex

);

[C++]

public: Int32 GetTwoLameEncodingBitrateEx (

Int32 nFrequency,

Int16 nBitrateIndex

);

Parameter | Description
nFrequency | Frequency expressed in Hertz (e.g. 44100)
nBitrateIndex | Number representing the zero-based index of the bitrate

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The requested encoding costant bitrate


EncodeFormats.MP2.GetTwoLameEncodingBitratesCount method

EncodeFormats.MP2.GetTwoLameEncodingBitratesCount method

Remarks

Retrieves the number of encoding bitrates (Constant Bitrate or CBR) supported by TwoLame for a given native resampling format.

Each of the supported bitrates can be obtained at a later time using the EncodeFormats.MP2.GetTwoLameEncodingBitrate method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetTwoLameEncodingBitratesCount (

nInputDevice as Int16,

nFormatIndex as Int16

) as Int16

[C#]

public Int16 GetTwoLameEncodingBitratesCount (

Int16 nInputDevice,

Int16 nFormatIndex

);

[C++]

public: Int16 GetTwoLameEncodingBitratesCount (

Int16 nInputDevice,

Int16 nFormatIndex

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nFormatIndex | Number representing the zero-based index of the native resampling format. The number of native resampling formats supported by the given input device can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The number of supported encoding constant bitrates (CBR)


EncodeFormats.MP2.GetTwoLameEncodingBitratesCountEx method

EncodeFormats.MP2.GetTwoLameEncodingBitratesCountEx method

Remarks

Retrieves the number of encoding bitrates (Constant Bitrate or CBR) supported by TwoLame for a given frequency.

Each of the supported bitrates can be obtained at a later time using the EncodeFormats.MP2.GetTwoLameEncodingBitrateEx method.

For further details about encoding in MP2 format refer to the EncodeMP2 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetTwoLameEncodingBitratesCountEx (

nFrequency as Int32

) as Int16

[C#]

public Int16 GetTwoLameEncodingBitratesCountEx (

Int32 nFrequency

);

[C++]

public: Int16 GetTwoLameEncodingBitratesCountEx (

Int32 nFrequency

);

Parameter | Description
nFrequency | Frequency expressed in Hertz (e.g. 44100)

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The number of supported encoding constant bitrates (CBR)


EncodeMP3 class

EncodeMP3 class

The EncodeMP3 class, accessible through the control's EncodeFormats.MP3 property, contains methods and properties needed to take advantage of encoding in MP3 format.

The EncodeMP3 class is implemented through the following properties and methods:

Properties

EncodeMode

Preset

CBR

ABR

CustomString

Downmix

Methods

GetEncodeModesCount

GetEncodeModeDesc

GetLameEncodingBitratesCount

GetLameEncodingBitrate

GetLameEncodingBitratesCountEx

GetLameEncodingBitrateEx

For further information about available encoding formats see the EncodeFormatsMan class.

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

- CdRipper

- RecordedSoundEditor

- SimpleRecorder

- SimpleMp3Rec

- UploadSoundToFTP


EncodeFormats.MP3.ABR property

EncodeFormats.MP3.ABR property

Type

[Visual Basic]

Public Property ABR As Int32

[C#]

public Int32 ABR {get; set;}

[C++]

public: __property Int32 get_ABR();

public: __property void set_ABR(Int32);

Remarks

The Average Bitrate (ABR), expressed in bits per second (bps), used for MP3 format during recording or CD ripping sessions.

Using this preset will usually give you good quality at a specified bitrate. Depending on the bitrate entered, this preset will determine the optimal settings for that particular situation. While this approach works, it is not nearly as flexible as VBR, and usually will not reach the same quality level as VBR at higher bitrates.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_ABR (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_ABR (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_ABR (for further details see the How to export a recorded sound section).

This property is the same as entering the --abr <kbps> setting inside the Appendix A - Lame command line.

For further details about encoding in MP3 format refer to the EncodeMP3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP3.CBR property

EncodeFormats.MP3.CBR property

Type

[Visual Basic]

Public Property CBR As Int32

[C#]

public Int32 CBR {get; set;}

[C++]

public: __property Int32 CBR();

public: __property void CBR(Int32);

Remarks

The Constant Bitrate (CBR), expressed in bits per second (bps), used for MP3 format during recording or CD ripping sessions.

This is the default encoding mode, and also the most basic. In this mode, the bitrate will be the same for the whole file. It means that each part of your mp3 file will be using the same number of bits. The musical passage being a difficult one to encode or an easy one, the encoder will use the same bitrate, so the quality of your mp3 is variable. Complex parts will be of a lower quality than the easiest ones. The main advantage is that the final files size won't change and can be accurately predicted.

Note that, depending upon the chosen input format (fixed to 44100 Hz, 16 bits, Stereo for CD ripping sessions), not all of the bitrate values are supported by Lame.

The full list of Constant Bitrates, supported by a certain native input format, can be obtained using the EncodeFormats.MP3.GetLameEncodingBitratesCount and EncodeFormats.MP3.GetLameEncodingBitrate methods.

The full list of Constant Bitrates, supported by a certain frequency, can be obtained using the EncodeFormats.MP3.GetLameEncodingBitratesCountEx and EncodeFormats.MP3.GetLameEncodingBitrateEx methods.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_CBR (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_CBR (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_CBR (for further details see the How to export a recorded sound section).

This property is the same as entering the -b <kbps> --cbr setting inside the Appendix A - Lame command line.

For further details about encoding in MP3 format refer to the EncodeMP3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP3.CustomString property

EncodeFormats.MP3.CustomString property

Type

[Visual Basic]

Public Property CustomString As string

[C#]

public string CustomString {get; set;}

[C++]

public: __property string get_CustomString();

public: __property void set_CustomString(string);

Remarks

String containing custom MP3 options to send to the Lame encoder.

For advanced users, this string allows applying all of the possible MP3 encoding options available with Lame. See Appendix A - Lame command line for the complete set of available options.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_CUSTOM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_CUSTOM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_CUSTOM (for further details see the How to export a recorded sound section).

IMPORTANT NOTE: As you may know, the Lame command line is as follows:

usage: lame [options] <infile> [outfile]

Contents of the EncodeFormats.MP3.CustomString property are related to the [options] field only so you must omit entering the word lame and omit to specify the <infile> and [outfile] settings also. You should also omit the -r and -x options which are already applied internally and the --big-endian option which is not compatible with the control.

For further details about encoding in MP3 format refer to the EncodeMP3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP3.Downmix property

EncodeFormats.MP3.Downmix property

Type

[Visual Basic]

Public Property Downmix As bool

[C#]

public bool Downmix {get; set;}

[C++]

public: __property bool get_Downmix();

public: __property void set_Downmix(bool);

Remarks

Downmixes from stereo to mono file for mono encoding in MP3 format.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP3 (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP3 (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP3 (for further details see the How to export a recorded sound section).

This property is the same as entering the -a setting inside the Appendix A - Lame command line.

For further details about encoding in MP3 format refer to the EncodeMP3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP3.EncodeMode property

EncodeFormats.MP3.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumMp3EncodeModes

[C#]

public enumMp3EncodeModes EncodeMode {get; set;}

[C++]

public: __property enumMp3EncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumMp3EncodeModes);

Remarks

The encoding mode used for MP3 format during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
MP3_ENCODE_PRESETS | 0 | Encode using the Lame's built-in preset specified inside the EncodeFormats.MP3.Preset property. Those presets are designed to provide the highest possible quality at both Variable Bitrates (VBR) and Constant Bitrate (CBR).
MP3_ENCODE_CBR | 1 | Encode using the Constant Bitrate (CBR) specified inside the EncodeFormats.MP3.CBR property. In this mode, the bitrate will be the same for the whole file. It means that each part of your mp3 file will be using the same number of bits. The musical passage being a difficult one to encode or an easy one, the encoder will use the same bitrate, so the quality of your mp3 is variable. Complex parts will be of a lower quality than the easiest ones. The main advantage is that the final files size won't change and can be accurately predicted.
MP3_ENCODE_ABR | 2 | Encode using the Average Bitrate (ABR) specified inside the EncodeFormats.MP3.ABR property. Using this preset will usually give you good quality at a specified bitrate. Depending on the bitrate entered, this preset will determine the optimal settings for that particular situation. While this approach works, it is not nearly as flexible as VBR, and usually will not reach the same quality level as VBR at higher bitrates.
MP3_ENCODE_CUSTOM | 3 | Encode using the custom string defined inside the EncodeFormats.MP3.CustomString property.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP3 (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP3 (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP3 (for further details see the How to export a recorded sound section).

For further details about encoding in MP3 format refer to the EncodeMP3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP3.Preset property

EncodeFormats.MP3.Preset property

Type

[Visual Basic]

Public Property Preset As enumMp3EncodePresets

[C#]

public enumMp3EncodePresets Preset {get; set;}

[C++]

public: __property enumMp3EncodePresets get_Preset();

public: __property void set_Preset(enumMp3EncodePresets);

Remarks

The Lame's built-in preset used for MP3 encoding. Lame's presets are designed to provide the highest possible quality at both Variable Bitrates (VBR) and Constant Bitrate (CBR).

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
MP3_PRESET_MEDIUM | 0 | This VBR preset should provide near transparency to most people on most music. The resulting bitrate should be in the 150-180kbps range, according to music complexity.
MP3_PRESET_STANDARD | 1 | This VBR preset should generally be transparent to most people on most music and is already quite high in quality. The resulting bitrate should be in the 170-210kbps range, according to music complexity.
MP3_PRESET_EXTREME | 2 | This VBR preset will provide slightly higher quality than the "standard" mode .The resulting bitrate should be in the 200-240kbps range, according to music complexity.
MP3_PRESET_INSANE | 3 | This CBR preset (320 kbps) will usually be overkill for most people and most situations, but if you must have the absolute highest quality with no regard to file size, this is the way to go. This preset is the highest preset quality available.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_PRESETS (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_PRESETS (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_MP3 and the EncodeFormats.MP3.EncodeMode property is set to MP3_ENCODE_PRESETS (for further details see the How to export a recorded sound section).

For further details about encoding in MP3 format refer to the EncodeMP3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.MP3.GetEncodeModeDesc method

EncodeFormats.MP3.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the MP3 format.

The number of available encoding modes can be obtained using the EncodeFormats.MP3.GetEncodeModesCount method.

For further details about encoding and resampling options refer to the EncodeMp3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.MP3.EncodeMode property.

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 friendly description of the requested encode mode.


EncodeFormats.MP3.GetEncodeModesCount method

EncodeFormats.MP3.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the MP3 format

The friendly description of each encoding mode can be obtained using the EncodeFormats.MP3.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.MP3.EncodeMode property.

For further details about encoding in MP3 format refer to the EncodeMP3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeFormats.MP3.GetLameEncodingBitrate method

EncodeFormats.MP3.GetLameEncodingBitrate method

Remarks

Retrieves a specific encoding bitrate (Constant Bitrate or CBR) supported by Lame for a given recording format.

The number of available bitrates can be obtained using the EncodeFormats.MP3.GetLameEncodingBitratesCount method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding and resampling options refer to the EncodeMp3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetLameEncodingBitrate (

nInputDevice as Int16,

nFormatIndex as Int16,

nBitrateIndex as Int16

) as Int32

[C#]

public Int32 GetLameEncodingBitrate (

Int16 nInputDevice,

Int16 nFormatIndex,

Int16 nBitrateIndex

);

[C++]

public: Int32 GetLameEncodingBitrate (

Int16 nInputDevice,

Int16 nFormatIndex,

Int16 nBitrateIndex

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nFormatIndex | Number representing the zero-based index of the native resampling format. The number of native resampling formats supported by the given input device can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.
nBitrateIndex | Number representing the zero-based index of the bitrate

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The requested encoding costant bitrate


EncodeFormats.MP3.GetLameEncodingBitrateEx method

EncodeFormats.MP3.GetLameEncodingBitrateEx method

Remarks

Retrieves a specific encoding bitrate (for Constant Bitrate or CBR) supported by Lame for a given frequency.

The number of available bitrates can be obtained using the EncodeFormats.MP3.GetLameEncodingBitratesCountEx method.

For further details about encoding and resampling options refer to the EncodeMp3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetLameEncodingBitrateEx (

nFrequency as Int32,

nBitrateIndex as Int16

) as Int32

[C#]

public Int32 GetLameEncodingBitrateEx (

Int32 nFrequency,

Int16 nBitrateIndex

);

[C++]

public: Int32 GetLameEncodingBitrateEx (

Int32 nFrequency,

Int16 nBitrateIndex

);

Parameter | Description
nFrequency | Frequency expressed in Hertz (e.g. 44100)
nBitrateIndex | Number representing the zero-based index of the bitrate

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The requested encoding costant bitrate


EncodeFormats.MP3.GetLameEncodingBitratesCount method

EncodeFormats.MP3.GetLameEncodingBitratesCount method

Remarks

Retrieves the number of encoding bitrates (Constant Bitrate or CBR) supported by Lame for a given native resampling format.

Each of the supported bitrates can be obtained at a later time using the EncodeFormats.MP3.GetLameEncodingBitrate method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding and resampling options refer to the EncodeMp3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetLameEncodingBitratesCount (

nInputDevice as Int16,

nFormatIndex as Int16

) as Int16

[C#]

public Int16 GetLameEncodingBitratesCount (

Int16 nInputDevice,

Int16 nFormatIndex

);

[C++]

public: Int16 GetLameEncodingBitratesCount (

Int16 nInputDevice,

Int16 nFormatIndex

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nFormatIndex | Number representing the zero-based index of the native resampling format. The number of native resampling formats supported by the given input device can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The number of supported encoding constant bitrates (CBR)


EncodeFormats.MP3.GetLameEncodingBitratesCountEx method

EncodeFormats.MP3.GetLameEncodingBitratesCountEx method

Remarks

Retrieves the number of encoding bitrates (Constant Bitrate or CBR) supported by Lame for a given frequency.

Each of the supported bitrates can be obtained at a later time using the EncodeFormats.MP3.GetLameEncodingBitrateEx method.

For further details about encoding and resampling options refer to the EncodeMp3 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetLameEncodingBitratesCountEx (

nFrequency as Int32

) as Int16

[C#]

public Int16 GetLameEncodingBitratesCountEx (

Int32 nFrequency

);

[C++]

public: Int16 GetLameEncodingBitratesCountEx (

Int32 nFrequency

);

Parameter | Description
nFrequency | Frequency expressed in Hertz (e.g. 44100)

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The number of supported encoding constant bitrates (CBR)


EncodeNIST class

EncodeNIST class

The EncodeNIST class, accessible through the control's EncodeFormats.NIST property, contains methods needed to take advantage of encoding in various Sphere NIST formats.

The EncodeNIST class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.NIST.EncodeMode property

EncodeFormats.NIST.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumNISTEncodeModes

[C#]

public enumNISTEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumNISTEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumNISTEncodeModes);

Remarks

The Sphere NIST encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
NIST_ENCODE_PCM_S8 | 0 | NIST PCM 8 bits Signed
NIST_ENCODE_PCM_S16 | 1 | NIST PCM 16 bits Signed
NIST_ENCODE_PCM_S24 | 2 | NIST PCM 24 bits Signed
NIST_ENCODE_PCM_S32 | 3 | NIST PCM 32 bits Signed
NIST_ENCODE_G711_ULAW | 4 | NIST G711 U-LAW
NIST_ENCODE_G711_ALAW | 5 | NIST G711 A-LAW

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_NIST (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_NIST (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_NIST (for further details see the How to export a recorded sound section).

For further details about using the Sphere NIST format refer to the EncodeNIST class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.NIST.GetEncodeModeDesc method

EncodeFormats.NIST.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Sphere NIST format.

The number of available encoding modes can be obtained using the EncodeFormats.NIST.GetEncodeModesCount method.

For further details about encoding in Sphere NIST format refer to the EncodeNIST class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.NIST.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.NIST.GetEncodeModesCount method

EncodeFormats.NIST.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Sphere NIST format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.NIST.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.NIST.EncodeMode property.

For further details about encoding in Sphere NIST format refer to the EncodeNIST class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeOGG class

EncodeOGG class

The EncodeOGG class, accessible through the control's EncodeFormats.OGG property, contains methods and properties needed to take advantage of encoding in OGG Vorbis format.

The EncodeOGG class is implemented through the following properties and methods:

Properties

EncodeMode

Bitrate

Quality

CustomString

Downmix

ResampleFrequency

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder

- SimpleOggRec


EncodeFormats.OGG.Bitrate property

EncodeFormats.OGG.Bitrate property

Type

[Visual Basic]

Public Property Bitrate As Int32

[C#]

public Int32 Bitrate {get; set;}

[C++]

public: __property Int32 get_Bitrate();

public: __property void set_Bitrate(Int32);

Remarks

Chooses a nominal bitrate (expressed in bps) to encode at in OGG Vorbis format. Attempts to encode at a bitrate averaging this. Takes an argument in kbps. This uses the bitrate management engine, and is not recommended for most users. A better alternative is setting the EncodeFormats.OGG.EncodeMode property to OGG_ENCODE_QUALITY and using the EncodeFormats.OGG.Quality property.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_BITRATE (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_BITRATE (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_BITRATE (for further details see the How to export a recorded sound section).

This property is the same as entering either the -b <kbps> or --bitrate <kbps> setting inside the Appendix B - OggEnc command line.

For further details about encoding in OGG Vorbis format refer to the EncodeOGG class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OGG.CustomString property

EncodeFormats.OGG.CustomString property

Type

[Visual Basic]

Public Property CustomString As string

[C#]

public string CustomString {get; set;}

[C++]

public: __property string get_CustomString();

public: __property void set_CustomString(string);

Remarks

String containing custom OGG Vorbis options to send to the OggEnc encoder.

For advanced users, this string allows applying all of the possible OGG Vorbis encoding options available with OggEnc. See Appendix B - OggEnc command line for the complete set of available options.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_CUSTOM (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_CUSTOM (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_CUSTOM (for further details see the How to export a recorded sound section).

IMPORTANT NOTE: As you may know, the OggEnc command line is as follows:

Usage: oggenc [options] input.wav [...]

Contents of the CustomString property are related to the [options] field only so you must omit entering the word oggenc and omit to specify the input.wav file and [...] settings also. You should also omit the -r option which is already applied internally.

For further details about encoding in OGG Vorbis format refer to the EncodeOGG class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OGG.Downmix property

EncodeFormats.OGG.Downmix property

Type

[Visual Basic]

Public Property Downmix As bool

[C#]

public bool Downmix {get; set;}

[C++]

public: __property bool get_Downmix();

public: __property void set_Downmix(bool);

Remarks

Downmixes from stereo to mono file for mono encoding in OGG Vorbis format.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OGG (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OGG (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OGG (for further details see the How to export a recorded sound section).

This property is the same as entering the --downmix setting inside the Appendix B - OggEnc command line.

For further details about encoding in OGG Vorbis format refer to the EncodeOGG class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OGG.EncodeMode property

EncodeFormats.OGG.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumOggEncodeModes

[C#]

public enumOggEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumOggEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumOggEncodeModes);

Remarks

The encoding mode used for OGG Vorbis format during recording or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Value | Meaning
OGG_ENCODE_QUALITY | 0 | Encode with the OggEnc encoder using the quality specified inside the EncodeFormats.OGG.Quality property.
OGG_ENCODE_BITRATE | 1 | Encode with the OggEnc encoder using the Constant Bitrate (CBR) specified inside the EncodeFormats.OGG.Bitrate property.
OGG_ENCODE_CUSTOM | 2 | Encode with the OggEnc encoder using the custom string defined inside the EncodeFormats.OGG.CustomString property.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OGG (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OGG (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OGG (for further details see the How to export a recorded sound section).

For further details about encoding in OGG Vorbis format refer to the EncodeOGG class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OGG.ResampleFrequency property

EncodeFormats.OGG.ResampleFrequency property

Type

[Visual Basic]

Public Property ResampleFrequency As Int32

[C#]

public Int32 ResampleFrequency {get; set;}

[C++]

public: __property Int32 get_ResampleFrequency();

public: __property void set_ResampleFrequency(Int32);

Remarks

Resamples input to the given sample rate (in Hz) before encoding in OGG Vorbis format during recording or CD ripping sessions. Primarily useful for down-sampling for lower-bitrate encoding.

Below is some example of the limits of encoding bitrates (which can be set using the EncodeFormats.OGG.Bitrate property) associated to a certain input frequency:

- with 44100 Hz you can reach a minimal bitrate of 64000 kbps

- with 22050 Hz you can reach a minimal bitrate of 32000 kbps

- with 11025 Hz you can reach a minimal bitrate of 16000 kbps

- with 8000 Hz you can reach a minimal bitrate of 12000 kbps

Regarding compatibility, to ensure your listeners don't have pitch-shifting (like a slow record or tape) use resample rates from the following list only: 8000 11025 16000 22050 32000 44100 48000

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OGG (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OGG (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OGG (for further details see the How to export a recorded sound section).

This property is the same as entering the --resample n setting inside the Appendix B - OggEnc command line.

For further details about encoding in OGG Vorbis format refer to the EncodeOGG class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OGG.Quality property

EncodeFormats.OGG.Quality property

Type

[Visual Basic]

Public Property Quality As float

[C#]

public float Quality {get; set;}

[C++]

public: __property float get_Quality();

public: __property void set_Quality(float);

Remarks

Sets encoding quality used for OGG Vorbis format during recording or CD ripping sessions.

Normal quality range is 0 - 10. Quality -1 is also possible, but for most users may not be of acceptable quality. Fractional quality levels such as 2.5 are permitted.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_QUALITY (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_QUALITY (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OGG and the EncodeFormats.OGG.EncodeMode property is set to OGG_ENCODE_QUALITY (for further details see the How to export a recorded sound section).

This property is the same as entering either the -q <quality> or --quality <quality> setting inside the Appendix B - OggEnc command line.

For further details about encoding in OGG Vorbis format refer to the EncodeOGG class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OGG.GetEncodeModeDesc method

EncodeFormats.OGG.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the OGG format.

The number of available encoding modes can be obtained using the EncodeFormats.OGG.GetEncodeModesCount method.

For further details about encoding in OGG Vorbis format refer to the EncodeOGG class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.OGG.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.OGG.GetEncodeModesCount method

EncodeFormats.OGG.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the OGG Vorbis format

The friendly description of each encoding mode can be obtained using the EncodeFormats.OGG.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.OGG.EncodeMode property.

For further details about encoding in OGG Vorbis format refer to the EncodeOGG class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeOPUS class

EncodeOPUS class

The EncodeOPUS class, accessible through the control's EncodeFormats.OPUS property, contains methods and properties needed to take advantage of encoding in OGG Vorbis format.

The EncodeOPUS class is implemented through the following properties and methods:

Properties

EncodeMode

Bitrate

CustomString

DownmixMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OPUS.Bitrate property

EncodeFormats.OPUS.Bitrate property

Type

[Visual Basic]

Public Property Bitrate As Int32

[C#]

public Int32 Bitrate {get; set;}

[C++]

public: __property Int32 get_Bitrate();

public: __property void set_Bitrate(Int32);

Remarks

Chooses the bitrate (expressed in bps) to encode at in OPUS format.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

This property is the same as entering either the --bitrate <kbps> setting inside the Appendix E - OpusEnc command line.

For further details about encoding in OPUS format refer to the EncodeOPUS class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OPUS.CustomString property

EncodeFormats.OPUS.CustomString property

Type

[Visual Basic]

Public Property CustomString As string

[C#]

public string CustomString {get; set;}

[C++]

public: __property string get_CustomString();

public: __property void set_CustomString(string);

Remarks

String containing custom OPUS options to send to the OpusEnc encoder.

For advanced users, this string allows applying all of the possible OPUS encoding options available with OpusEnc. See Appendix E - OpusEnc command line for the complete set of available options.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

IMPORTANT NOTE: As you may know, the OpusEnc command line is as follows:

Usage: opusenc [options] input_file output_file.opus

Contents of the CustomString property are related to the [options] field only so you must omit entering the word opusenc and omit to specify the input_file. You should also omit the --raw option and any other options related to the raw input format which are already applied internally .

For further details about encoding in OPUS format refer to the EncodeOPUS class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OPUS.DownmixMode property

EncodeFormats.OPUS.DownmixMode property

Type

[Visual Basic]

Public Property DownmixMode As enumOpusDownmixModes

[C#]

public enumOpusDownmixModes DownmixMode {get; set;}

[C++]

public: __property enumOpusDownmixModes get_DownmixMode();

public: __property void set_DownmixMode(enumOpusDownmixModes);

Remarks

Sets the way used to eventually downmix the number of channels of the input file for mono/stereo encoding in OPUS format.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
OPUS_DOWNMIX_NONE | 0 | No downmix is applied.
OPUS_DOWNMIX_MONO | 1 | Downmix to mono. This property is the same as entering the --downmix-mono setting inside the Appendix E - OpusEnc command line.
OPUS_DOWNMIX_STEREO | 2 | Downmix to stereo. This property is the same as entering the --downmix-stereo setting inside the Appendix E - OpusEnc command line.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

For further details about encoding in OPUS format refer to the EncodeOPUS class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OPUS.EncodeMode property

EncodeFormats.OPUS.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumOpusEncodeModes

[C#]

public enumOpusEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumOpusEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumOpusEncodeModes);

Remarks

The encoding mode used for OPUS format during exporting sessions.

Supported values are the following:

Mnemonic Value

Numeric value

Meaning

OPUS_ENCODE_VBR

0

Encode with the OpusEnc encoder using the Variable Bitrate (VBR) specified inside the EncodeFormats.OPUS.Bitrate property.

This property is the same as entering either the --vbr setting inside the Appendix E - OpusEnc command line.

OPUS_ENCODE_CONSTR_VBR

1

Encode with the OpusEnc encoder using the Constrained Variable Bitrate (CVBR) specified inside the EncodeFormats.OPUS.Bitrate property.

This property is the same as entering either the --cvbr setting inside the Appendix E - OpusEnc command line.

OPUS_ENCODE_HARD_CBR

2

Encode with the OpusEnc encoder using the Hard Constant Bitrate (Hard-CBR) specified inside the EncodeFormats.OPUS.Bitrate property.

This property is the same as entering either the --hard-cbr setting inside the Appendix E - OpusEnc command line.

OPUS_ENCODE_CUSTOM

3

Encode with the OpusEnc encoder using the custom string defined inside the EncodeFormats.OPUS.CustomString property.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_OPUS and the EncodeFormats.OPUS.EncodeMode property is set to a value different from OPUS_ENCODE_CUSTOM.

For further details about encoding in OPUS format refer to the EncodeOPUS class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.OPUS.GetEncodeModeDesc method

EncodeFormats.OPUS.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the OPUS format.

The number of available encoding modes can be obtained using the EncodeFormats.OPUS.GetEncodeModesCount method.

For further details about encoding in OPUS format refer to the EncodeOPUS class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.OPUS.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.OPUS.GetEncodeModesCount method

EncodeFormats.OPUS.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the OPUS format

The friendly description of each encoding mode can be obtained using the EncodeFormats.OPUS.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.OPUS.EncodeMode property.

For further details about encoding in OPUS format refer to the EncodeOPUS class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodePAF class

EncodePAF class

The EncodePAF class, accessible through the control's EncodeFormats.PAF property, contains methods needed to take advantage of encoding in various Ensoniq PARIS formats.

The EncodePAF class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.PAF.EncodeMode property

EncodeFormats.PAF.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumPAFEncodeModes

[C#]

public enumPAFEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumPAFEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumPAFEncodeModes);

Remarks

The Ensoniq PARIS encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
PAF_ENCODE_PCM_S8 | 0 | PAF PCM 8 bits Signed
PAF_ENCODE_PCM_S16 | 1 | PAF PCM 16 bits Signed
PAF_ENCODE_PCM_S24 | 2 | PAF PCM 24 bits Signed

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_PAF (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_PAF (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_PAF (for further details see the How to export a recorded sound section).

For further details about using the Ensoniq PARIS format refer to the EncodePAF class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.PAF.GetEncodeModeDesc method

EncodeFormats.PAF.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Ensoniq PARIS format.

The number of available encoding modes can be obtained using the EncodeFormats.PAF.GetEncodeModesCount method.

For further details about encoding in Ensoniq PARIS format refer to the EncodePAF class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.PAF.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.PAF.GetEncodeModesCount method

EncodeFormats.PAF.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Ensoniq PARIS format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.PAF.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.PAF.EncodeMode property.

For further details about encoding in Ensoniq PARIS format refer to the EncodePAF class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodePVF class

EncodePVF class

The EncodePVF class, accessible through the control's EncodeFormats.PVF property, contains methods needed to take advantage of encoding in various Portable Voice Format formats.

The EncodePVF class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.PVF.EncodeMode property

EncodeFormats.PVF.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumPVFEncodeModes

[C#]

public enumPVFEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumPVFEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumPVFEncodeModes);

Remarks

The Portable Voice Format encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
PVF_ENCODE_PCM_S8 | 0 | PVF PCM 8 bits Signed
PVF_ENCODE_PCM_S16 | 1 | PVF PCM 16 bits Signed
PVF_ENCODE_PCM_S32 | 2 | PVF PCM 32 bits Signed

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_PVF (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_PVF (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_PVF (for further details see the How to export a recorded sound section).

For further details about using the Portable Voice Format refer to the EncodePVF class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.PVF.GetEncodeModeDesc method

EncodeFormats.PVF.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Portable Voice Format.

The number of available encoding modes can be obtained using the EncodeFormats.PVF.GetEncodeModesCount method.

For further details about encoding in Portable Voice Format refer to the EncodePVF class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.PVF.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.PVF.GetEncodeModesCount method

EncodeFormats.PVF.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Portable Voice Format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.PVF.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.PVF.EncodeMode property.

For further details about encoding in Portable Voice Format refer to the EncodePVF class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeRAW class

EncodeRAW class

The EncodeRAW class, accessible through the control's EncodeFormats.RAW property, contains methods needed to take advantage of encoding in various RAW formats.

The EncodeRAW class is implemented through the following properties and methods:

Properties

EncodeMode

UseBigEndian

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.RAW.EncodeMode property

EncodeFormats.RAW.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumRAWEncodeModes

[C#]

public enumRAWEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumRAWEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumRAWEncodeModes);

Remarks

The RAW encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Value | Meaning
RAW_ENCODE_PCM_S8 | 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

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_RAW (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_RAW (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_RAW (for further details see the How to export a recorded sound section).

For further details about using RAW formats refer to the EncodeRAW class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.RAW.UseBigEndian property

EncodeFormats.RAW.UseBigEndian property

Type

[Visual Basic]

Public Property UseBigEndian As bool

[C#]

public bool UseBigEndian {get; set;}

[C++]

public: __property bool get_UseBigEndian();

public: __property void set_UseBigEndian(bool);

Remarks

Uses "Big-endian" convention during the encoding in RAW format..

Supported values are the following:

Mnemonic Value | Meaning
false (default) | Use "Little-endian" convention
true | Use "Big-endian" convention

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_RAW (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_RAW (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_RAW (for further details see the How to export a recorded sound section).

For further details about using RAW formats refer to the EncodeRAW class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.RAW.GetEncodeModeDesc method

EncodeFormats.RAW.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the RAW format.

The number of available encoding modes can be obtained using the EncodeFormats.RAW.GetEncodeModesCount method.

For further details about encoding in RAW format refer to the EncodeRAW class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.RAW.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.RAW.GetEncodeModesCount method

EncodeFormats.RAW.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the RAW format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.RAW.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.RAW.EncodeMode property.

For further details about encoding in RAW format refer to the EncodeRAW class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeSVX class

EncodeSVX class

The EncodeSVX class, accessible through the control's EncodeFormats.SVX property, contains methods needed to take advantage of encoding in various Commodore Amiga IFF / SVX formats.

The EncodeSVX class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.SVX.EncodeMode property

EncodeFormats.SVX.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumSVXEncodeModes

[C#]

public enumSVXEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumSVXEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumSVXEncodeModes);

Remarks

The Commodore Amiga IFF / SVX encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
SVX_ENCODE_PCM_S8 | 0 | SVX PCM 8 bits Signed
SVX_ENCODE_PCM_S16 | 1 | SVX PCM 16 bits Signed

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_SVX (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_SVX (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_SVX (for further details see the How to export a recorded sound section).

For further details about using the Commodore Amiga IFF / SVX format refer to the EncodeSVX class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.SVX.GetEncodeModeDesc method

EncodeFormats.SVX.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Commodore Amiga IFF / SVX format.

The number of available encoding modes can be obtained using the EncodeFormats.SVX.GetEncodeModesCount method.

For further details about encoding in Commodore Amiga IFF / SVX format refer to the EncodeSVX class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.SVX.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.SVX.GetEncodeModesCount method

EncodeFormats.SVX.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Commodore Amiga IFF / SVX format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.SVX.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.SVX.EncodeMode property.

For further details about encoding in Commodore Amiga IFF / SVX format refer to the EncodeSVX class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeVOC class

EncodeVOC class

The EncodeVOC class, accessible through the control's EncodeFormats.VOC property, contains methods needed to take advantage of encoding in various Creative VOC formats.

The EncodeVOC class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.VOC.EncodeMode property

EncodeFormats.VOC.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumVOCEncodeModes

[C#]

public enumVOCEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumVOCEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumVOCEncodeModes);

Remarks

The Creative VOC encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
VOC_ENCODE_PCM_U8 | 0 | VOC PCM 8 bits Unsigned
VOC_ENCODE_PCM_S16 | 1 | VOC PCM 16 bits Signed
VOC_ENCODE_G711_ULAW | 2 | VOC G711 U-LAW
VOC_ENCODE_G711_ALAW | 3 | VOC G711 A-LAW

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_VOC (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_VOC (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_VOC (for further details see the How to export a recorded sound section).

For further details about using the Creative VOC format refer to the EncodeVOC class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.VOC.GetEncodeModeDesc method

EncodeFormats.VOC.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Creative VOC format.

The number of available encoding modes can be obtained using the EncodeFormats.VOC.GetEncodeModesCount method.

For further details about encoding in Creative VOC format refer to the EncodeVOC class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.VOC.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.VOC.GetEncodeModesCount method

EncodeFormats.VOC.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Creative VOC format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.VOC.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.VOC.EncodeMode property.

For further details about encoding in Creative VOC format refer to the EncodeVOC class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeW64 class

EncodeW64 class

The EncodeW64 class, accessible through the control's EncodeFormats.W64 property, contains methods needed to take advantage of encoding in various Sonic Foundry's 64 bit RIFF/WAV formats.

The EncodeW64 class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder


EncodeFormats.W64.EncodeMode property

EncodeFormats.W64.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumW64EncodeModes

[C#]

public enumW64EncodeModes EncodeMode {get; set;}

[C++]

public: __property enumW64EncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumW64EncodeModes);

Remarks

The Sonic Foundry's 64 bit RIFF/WAV encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
W64_ENCODE_PCM_U8 | 0 | W64 PCM 8 bits Unsigned
W64_ENCODE_PCM_S16 | 1 | W64 PCM 16 bits Signed
W64_ENCODE_PCM_S24 | 2 | W64 PCM 24 bits Signed
W64_ENCODE_PCM_S32 | 3 | W64 PCM 32 bits Signed
W64_ENCODE_FLOAT32 | 4 | W64 32 bits floating point
W64_ENCODE_G711_ULAW | 5 | W64 G711 U-LAW
W64_ENCODE_G711_ALAW | 6 | W64 G711 A-LAW
W64_ENCODE_GSM_610 | 7 | W64 GSM 6.10
W64_ENCODE_IMA_ADPCM | 8 | W64 IMA ADPCM
W64_ENCODE_MS_ADPCM | 9 | W64 MS ADPCM

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_W64 (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_W64 (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_W64 (for further details see the How to export a recorded sound section).

For further details about using the W64 format refer to the EncodeW64 class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.W64.GetEncodeModeDesc method

EncodeFormats.W64.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the Sonic Foundry's 64 bit RIFF/WAV format.

The number of available encoding modes can be obtained using the EncodeFormats.W64.GetEncodeModesCount method.

For further details about encoding in W64 format refer to the EncodeW64 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.W64.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.W64.GetEncodeModesCount method

EncodeFormats.W64.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the Sonic Foundry's 64 bit RIFF/WAV format.

The friendly description of each encoding mode can be obtained using the EncodeFormats.W64.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.W64.EncodeMode property.

For further details about encoding in W64 format refer to the EncodeW64 class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeWAV class

EncodeWAV class

The EncodeWAV class, accessible through the control's EncodeFormats.WAV property, contains methods and properties needed to take advantage of encoding in various WAV formats.

The EncodeWAV class is implemented through the following properties and methods:

Properties

EncodeMode

Methods

GetEncodeModesCount

GetEncodeModeDesc

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder

- SimpleWavRec

- SoundActivationSystem


EncodeFormats.WAV.EncodeMode property

EncodeFormats.WAV.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumWavEncodeModes

[C#]

public enumWavEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumWavEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumWavEncodeModes);

Remarks

The WAV encoding mode used during recording, exporting or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
WAV_ENCODE_PCM_U8 | 0 | WAV PCM 8 bits Unsigned
WAV_ENCODE_PCM_S16 | 1 | WAV PCM 16 bits Signed
WAV_ENCODE_PCM_S24 | 2 | WAV PCM 24 bits Signed
WAV_ENCODE_PCM_S32 | 3 | WAV PCM 32 bits Signed
WAV_ENCODE_FLOAT32 | 4 | WAV 32 bits floating point, also known as WAVE_FORMAT_IEEE_FLOAT
WAV_ENCODE_G711_ULAW | 5 | WAV G711 U-LAW
WAV_ENCODE_G711_ALAW | 6 | WAV G711 A-LAW
WAV_ENCODE_IMA_ADPCM | 7 | WAV IMA ADPCM
WAV_ENCODE_MS_ADPCM | 8 | WAV Microsoft ADPCM
WAV_ENCODE_GSM_610 | 9 | WAV GSM 6.10
WAV_ENCODE_G721_ADPCM_32 | 10 | WAV G721 ADPCM 32 kbps

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WAV (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_WAV (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_WAV (for further details see the How to export a recorded sound section).

For further details about using the WAV format refer to the EncodeWAV class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.WAV.GetEncodeModeDesc method

EncodeFormats.WAV.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the WAV format.

The number of available encoding modes can be obtained using the EncodeFormats.WAV.GetEncodeModesCount method.

For further details about encoding and resampling options refer to the EncodeWav class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.WAV.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.WAV.GetEncodeModesCount method

EncodeFormats.WAV.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the WAV format

The friendly description of each encoding mode can be obtained using the EncodeFormats.WAV.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.WAV.EncodeMode property.

For further details about encoding in WAV format refer to the EncodeWAV class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeWMA class

EncodeWMA class

The EncodeWMA class, accessible through the control's EncodeFormats.WMA property, contains methods and properties needed to take advantage of encoding in WMA format.

The EncodeWMA class is implemented through the following properties and methods:

Properties

EncodeMode

CBR

Profile

Quality

Methods

GetEncodeModesCount

GetEncodeModeDesc

GetEncodingBitratesCount

GetEncodingBitrate

GetEncodingCBRCount

GetEncodingCBR

GetEncodingProfileCount

GetEncodingProfileInfo

GetEncodingProfileProCount

GetEncodingProfileProInfo

GetEncodingVBRQualitiesCount

GetEncodingVBRQuality

GetEncodingVBRQualitiesCountEx

GetEncodingVBRQualityEx

For further information about available encoding formats see the EncodeFormatsMan class.

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

- RecordedSoundEditor

- SimpleRecorder

- SimpleWmaRec

- RecorderWmaProfiles


EncodeFormats.WMA.CBR property

EncodeFormats.WMA.CBR property

Type

[Visual Basic]

Public Property CBR As Int32

[C#]

public Int32 CBR {get; set;}

[C++]

public: __property Int32 get_CBR();

public: __property void set_CBR(Int32);

Remarks

The Constant Bitrate (CBR), expressed in bits per second (bps), used for WMA (Windows Media Audio) format during recording or CD ripping sessions.

Note that, depending upon the chosen input format (fixed to 44100 Hz, 16 bits, Stereo for CD ripping sessions), not all of the bitrate values are supported.

The full list of Constant Bitrates, supported by a certain native input format, can be obtained using the EncodeFormats.WMA.GetEncodingBitratesCount and EncodeFormats.WMA.GetEncodingBitrate methods.

The full list of Constant Bitrates, supported by a certain frequency and number of channels, can be obtained using the EncodeFormats.WMA.GetEncodingCBRCount and EncodeFormats.WMA.GetEncodingCBR methods.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_CBR_STD_16, WMA_ENCODE_CBR_PRO_16 or WMA_ENCODE_CBR_PRO_24 (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_CBR_STD_16, WMA_ENCODE_CBR_PRO_16 or WMA_ENCODE_CBR_PRO_24 (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_CBR_STD_16, WMA_ENCODE_CBR_PRO_16 or WMA_ENCODE_CBR_PRO_24 (for further details see the How to export a recorded sound section).

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.WMA.EncodeMode property

EncodeFormats.WMA.EncodeMode property

Type

[Visual Basic]

Public Property EncodeMode As enumWmaEncodeModes

[C#]

public enumWmaEncodeModes EncodeMode {get; set;}

[C++]

public: __property enumWmaEncodeModes get_EncodeMode();

public: __property void set_EncodeMode(enumWmaEncodeModes);

Remarks

The encoding mode used for WMA (Windows Media Audio) format during recording or CD ripping sessions.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
WMA_ENCODE_VBR_QUALITY | 0 | Encode using the Variable Bitrate (VBR) quality specified inside the EncodeFormats.WMA.Quality property. Encoding will be performed using the WMA Standard format at 16 bits per sample.
WMA_ENCODE_CBR_STD_16 | 1 | Encode using the Constant Bitrate (CBR) specified inside the EncodeFormats.WMA.CBR property. Encoding will be performed using the WMA Standard format at 16 bits per sample.
WMA_ENCODE_PROFILE_STD | 2 | Encode using the Profile specified inside the EncodeFormats.WMA.Profile property. Encoding will be performed using the WMA Standard format at 16 bits per sample.
WMA_ENCODE_CBR_PRO_16 | 3 | Encode using the Constant Bitrate (CBR) specified inside the EncodeFormats.WMA.CBR property. Encoding will be performed using the WMA Professional format at 16 bits per sample.
WMA_ENCODE_CBR_PRO_24 | 4 | Encode using the Constant Bitrate (CBR) specified inside the EncodeFormats.WMA.CBR property. Encoding will be performed using the WMA Professional format at 24 bits per sample.
WMA_ENCODE_PROFILE_PRO | 5 | Encode using the Profile specified inside the EncodeFormats.WMA.Profile property. Encoding will be performed using the WMA Professional format at 16 or 24 bits per sample depending upon the chosen profile.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_WMA (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_WMA (for further details see the How to export a recorded sound section).

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.WMA.Profile property

EncodeFormats.WMA.Profile property

Type

[Visual Basic]

Public Property Profile As Int32

[C#]

public Int32 Profile {get; set;}

[C++]

public: __property Int32 get_Profile();

public: __property void set_Profile(Int32);

Remarks

The profile used for WMA (Windows Media Audio) format during recording or CD ripping sessions.

The full list of supported profiles for the WMA Standard format can be obtained using the EncodeFormats.WMA.GetEncodingProfileCount and EncodeFormats.WMA.GetEncodingProfileInfo methods.

The full list of supported profiles for the WMA Professional format can be obtained using the EncodeFormats.WMA.GetEncodingProfileProCount and EncodeFormats.WMA.GetEncodingProfileProInfo methods.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE_STD or WMA_ENCODE_PROFILE_PRO (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE_STD or WMA_ENCODE_PROFILE_PRO (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE_STD or WMA_ENCODE_PROFILE_PRO (for further details see the How to export a recorded sound section).

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.WMA.Quality property

EncodeFormats.WMA.Quality property

Type

[Visual Basic]

Public Property Quality As Int32

[C#]

public Int32 Quality {get; set;}

[C++]

public: __property Int32 get_Quality();

public: __property void set_Quality(Int32);

Remarks

The Variable Bitrate (VBR) quality used for WMA (Windows Media Audio) format during recording or CD ripping sessions.

Supported values are in the range from 0 (low quality) to 100 (high quality): note that, depending upon the chosen input format (fixed to 44100 Hz, 16 bits, Stereo for CD ripping sessions), not all of the values inside this range are supported.

The full list of VBR qualities, supported by a certain native resampling format, can be obtained using the EncodeFormats.WMA.GetEncodingVBRQualitiesCount and EncodeFormats.WMA.GetEncodingVBRQuality methods.

The full list of VBR qualities, supported by a certain frequency and number of channels, can be obtained using the EncodeFormats.WMA.GetEncodingVBRQualitiesCountEx and EncodeFormats.WMA.GetEncodingVBRQualityEx methods.

This property is used only in the following situations:

During a recording session if the EncodeFormats.ForRecording property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_VBR_QUALITY (for further details see the How to perform a recording session section).

During a CD ripping session if the EncodeFormats.ForCdRipping property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_VBR_QUALITY (for further details see the How to perform a CD ripping session section).

During an exporting session if the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_VBR_QUALITY (for further details see the How to export a recorded sound section).

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.


EncodeFormats.WMA.GetEncodeModeDesc method

EncodeFormats.WMA.GetEncodeModeDesc method

Remarks

Retrieves the friendly description of the requested encoding mode available for the WMA format.

The number of available encoding modes can be obtained using the EncodeFormats.WMA.GetEncodeModesCount method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModeDesc (

nEncodeModeIndex as Int16

) as string

[C#]

public string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

[C++]

public: string GetEncodeModeDesc (

Int16 nEncodeModeIndex

);

Parameter | Description
nEncodeModeIndex | Number representing the zero-based index of the encoding mode. Supported encoding modes are described inside the EncodeFormats.WMA.EncodeMode property.

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 friendly description of the requested recording format.


EncodeFormats.WMA.GetEncodeModesCount method

EncodeFormats.WMA.GetEncodeModesCount method

Remarks

Retrieves the number of encoding modes available for the WMA format

The friendly description of each encoding mode can be obtained using the EncodeFormats.WMA.GetEncodeModeDesc method.

Supported encoding modes are described inside the EncodeFormats.WMA.EncodeMode property.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodeModesCount (

) as Int16

[C#]

public Int16 GetEncodeModesCount (

);

[C++]

public: Int16 GetEncodeModesCount (

);

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 supported formats.


EncodeFormats.WMA.GetEncodingBitrate method

EncodeFormats.WMA.GetEncodingBitrate method

Remarks

Retrieves a specific encoding constant bitrate (CBR) for a given native resampling format.

The number of available bitrates can be obtained using the EncodeFormats.WMA.GetEncodingBitratesCount method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingBitrate (

nInputDevice as Int16,

nFormatIndex as Int16

nBitrateIndex as Int16,

) as Int32

[C#]

public Int32 GetEncodingBitrate (

Int16 nInputDevice,

Int16 nFormatIndex

Int16 nBitrateIndex,

);

[C++]

public: Int32 GetEncodingBitrate (

Int16 nInputDevice,

Int16 nFormatIndex

Int16 nBitrateIndex,

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nFormatIndex | Number representing the zero-based index of the native resampling format. The number of native resampling formats supported by the given input device can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.
nBitrateIndex | Number representing the zero-based index of the bitrate

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The requested encoding constant bitrate


EncodeFormats.WMA.GetEncodingBitratesCount method

EncodeFormats.WMA.GetEncodingBitratesCount method

Remarks

Retrieves the number of supported encoding constant bitrates (CBR) for a given native resampling format.

Each of the supported bitrates can be obtained at a later time using the EncodeFormats.WMA.GetEncodingBitrate method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingBitratesCount (

nInputDevice as Int16,

nFormatIndex as Int16

) as Int16

[C#]

public Int16 GetEncodingBitratesCount (

Int16 nInputDevice,

Int16 nFormatIndex

);

[C++]

public: Int16 GetEncodingBitratesCount (

Int16 nInputDevice,

Int16 nFormatIndex

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nFormatIndex | Number representing the zero-based index of the native resampling format. The number of native resampling formats supported by the given input device can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The number of supported encoding constant bitrates (CBR)


EncodeFormats.WMA.GetEncodingCBR method

EncodeFormats.WMA.GetEncodingCBR method

Remarks

Retrieves a specific encoding bitrate (for Constant Bitrate or CBR) supported by Windows Media components for a given frequency and number of channels.

The number of available bitrates can be obtained using the EncodeFormats.WMA.GetEncodingCBRCount method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingCBR (

nFrequency as Int32,

nChannels as Int16,

nEncodeMode as enumWmaEncodeModes,

nBitrateIndex as Int16

) as Int32

[C#]

public Int32 GetEncodingCBR (

Int32 nFrequency,

Int16 nChannels,

enumWmaEncodeModes nEncodeMode,

Int16 nBitrateIndex

);

[C++]

public: Int32 GetEncodingCBR (

Int32 nFrequency,

Int16 nChannels,

enumWmaEncodeModes nEncodeMode,

Int16 nBitrateIndex

);

Parameter

Description

nFrequency

Frequency expressed in Hertz (e.g. 44100)

nChannels

Number of channels: 1 for Mono, 2 for Stereo

nEncodeMode

The encoding mode used for WMA (Windows Media Audio) format recording/encoding.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
WMA_ENCODE_CBR_STD_16 | 1 | WMA Standard format at 16 bits per sample.
WMA_ENCODE_CBR_PRO_16 | 3 | WMA Professional format at 16 bits per sample.
WMA_ENCODE_CBR_PRO_24 | 4 | WMA Professional format at 24 bits per sample.

nBitrateIndex

Number representing the zero-based index of the bitrate

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The requested encoding constant bitrate


EncodeFormats.WMA.GetEncodingCBRCount method

EncodeFormats.WMA.GetEncodingCBRCount method

Remarks

Retrieves the number of encoding bitrates (Constant Bitrate or CBR) supported by Windows Media components for a given frequency, number of channels and encoding format.

Each of the supported bitrates can be obtained at a later time using the EncodeFormats.WMA.GetEncodingCBR method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingCBRCount (

nFrequency as Int32,

nChannels as Int16,

nEncodeMode as enumWmaEncodeModes

) as Int16

[C#]

public Int16 GetEncodingCBRCount (

Int32 nFrequency,

Int16 nChannels,

enumWmaEncodeModes nEncodeMode

);

[C++]

public: Int16 GetEncodingCBRCount (

Int32 nFrequency,

Int16 nChannels,

enumWmaEncodeModes nEncodeMode

);

Parameter

Description

nFrequency

Frequency expressed in Hertz (e.g. 44100)

nChannels

Number of channels: 1 for Mono, 2 for Stereo

nEncodeMode

The encoding mode used for WMA (Windows Media Audio) format recording/encoding.

Supported values are the following:

Mnemonic Value | Numeric value | Meaning
WMA_ENCODE_CBR_STD_16 | 1 | WMA Standard format at 16 bits per sample.
WMA_ENCODE_CBR_PRO_16 | 3 | WMA Professional format at 16 bits per sample.
WMA_ENCODE_CBR_PRO_24 | 4 | WMA Professional format at 24 bits per sample.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The number of supported encoding constant bitrates (CBR)


EncodeFormats.WMA.GetEncodingProfileCount method

EncodeFormats.WMA.GetEncodingProfileCount method

Remarks

Retrieves the number of supported WMA Standard profiles.

Each of the supported profiles can be obtained at a later time using the EncodeFormats.WMA.GetEncodingProfileInfo method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingProfileCount (

) as Int16

[C#]

public Int16 GetEncodingProfileCount (

);

[C++]

public: Int16 GetEncodingProfileCount (

);

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 supported WMA profiles.


EncodeFormats.WMA.GetEncodingProfileInfo method

EncodeFormats.WMA.GetEncodingProfileInfo method

Remarks

Retrieves a specific WMA Standard profile.

The number of available WMA Standard profiles can be obtained using the EncodeFormats.WMA.GetEncodingProfileCount method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingProfileInfo (

nIndexProfile as Int16,

ByRef nFrequency as Int32,

ByRef nChannels as Int16,

ByRef nInfo as Int32,

ByRef nEncodeMode as enumWmaEncodeModes

) as string

[C#]

public string GetEncodingProfileInfo (

Int16 nIndexProfile,

ref Int32 nFrequency,

ref Int16 nChannels,

ref Int32 nInfo,

ref enumWmaEncodeModes nEncodeMode

);

[C++]

public: string GetEncodingProfileInfo (

Int16 nIndexProfile,

Int32 __gc *nFrequency,

Int16 __gc *nChannels,

Int32 __gc *nInfo,

enumWmaEncodeModes __gc *nEncodeMode

);

Parameter

Description

nIndexProfile

Zero-based index of the WMA profile

nFrequency

Reference that, after returning from the method call, will contain the frequency, expressed in Hertz, of the WMA profile

nChannels

Reference that, after returning from the method call, will contain the number of channels of the WMA profile

nInfo

Reference that, after returning from the method call, will contain the value of the profile which, depending upon the value returned into the nEncodeMode parameter, may be a bitrate for CBR profiles or a quality for VBR profiles

nEncodeMode

Reference that, after returning from the method call, will contain the WMA encode mode which indicates if the WMA profile is based upon CBR or VBR.

Supported values are the following:

Mnemonic Value | Value | Meaning
WMA_ENCODE_VBR_QUALITY | 0 | The nInfo parameter contains a Variable Bitrate (VBR) quality value.
WMA_ENCODE_CBR_STD_16 | 1 | The nInfo parameter contains a Constant Bitrate (CBR) value.

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 friendly description of the requested WMA profile like in the examples below:

8,000 Hz; Stereo; CBR 12 kbps

44,100 Hz; Mono; CBR 20 kbps

48,000 Hz; Stereo; VBR Quality 90

etc.

The thousands separator used for the frequency value may vary depending upon the locale of the PC running the component.


EncodeFormats.WMA.GetEncodingProfileProCount method

EncodeFormats.WMA.GetEncodingProfileProCount method

Remarks

Retrieves the number of supported profiles for the WMA Professional format.

Each of the supported profiles can be obtained at a later time using the EncodeFormats.WMA.GetEncodingProfileProInfo method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingProfileProCount (

) as Int16

[C#]

public Int16 GetEncodingProfileProCount (

);

[C++]

public: Int16 GetEncodingProfileProCount (

);

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 supported WMA profiles.


EncodeFormats.WMA.GetEncodingProfileProInfo method

EncodeFormats.WMA.GetEncodingProfileProInfo method

Remarks

Retrieves a specific profile for the WMA Professional format.

The number of available WMA profiles can be obtained using the EncodeFormats.WMA.GetEncodingProfileProCount method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingProfileProInfo (

nIndexProfile as Int16,

ByRef nFrequency as Int32,

ByRef nChannels as Int16,

ByRef nBitsPerSample as Int16,

ByRef nInfo as Int32,

ByRef nEncodeMode as enumWmaEncodeModes

) as string

[C#]

public string GetEncodingProfileProInfo (

Int16 nIndexProfile,

ref Int32 nFrequency,

ref Int16 nChannels,

ref Int16 nBitsPerSample,

ref Int32 nInfo,

ref enumWmaEncodeModes nEncodeMode

);

[C++]

public: string GetEncodingProfileProInfo (

Int16 nIndexProfile,

Int32 __gc *nFrequency,

Int16 __gc *nChannels,

Int16 __gc *nBitsPerSample,

Int32 __gc *nInfo,

enumWmaEncodeModes __gc *nEncodeMode

);

Parameter

Description

nIndexProfile

Zero-based index of the WMA profile

nFrequency

Reference that, after returning from the method call, will contain the frequency, expressed in Hertz, of the WMA profile

nChannels

Reference that, after returning from the method call, will contain the number of channels of the WMA profile

nBitsPerSample

Reference that, after returning from the method call, will contain the number of bits per sample used for encoding.

WMA Professional supports both 16 and 24 bits per sample.

nInfo

Reference that, after returning from the method call, will contain the value of the profile which, depending upon the value returned into the nEncodeMode parameter, may be a bitrate for CBR profiles or a quality for VBR profiles

nEncodeMode

Reference that, after returning from the method call, will contain the WMA encode mode which indicates the WMA Professional encode mode.

Supported values are the following:

Mnemonic Value | Value | Meaning
WMA_ENCODE_CBR_PRO_16 | 3 | WMA Professional format at 16 bits per sample.
WMA_ENCODE_CBR_PRO_24 | 4 | WMA Professional format at 24 bits per sample.

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 friendly description of the requested WMA profile like in the examples below:

32,000 Hz; Stereo; 16 bits; CBR 32 kbps

44,100 Hz; Stereo; 24 bits; CBR 440 kbps

44,100 Hz; Stereo; 24 bits; CBR 384 kbps

etc.

The thousands separator used for the frequency value may vary depending upon the locale of the PC running the component.


EncodeFormats.WMA.GetEncodingVBRQualitiesCount method

EncodeFormats.WMA.GetEncodingVBRQualitiesCount method

Remarks

Retrieves the number of supported encoding qualities (for Variable Bit Rate support) for a given native resampling format.

Each of the supported qualities can be obtained at a later time using the EncodeFormats.WMA.GetEncodingVBRQuality method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingVBRQualitiesCount (

nInputDevice as Int16,

nFormatIndex as Int16

) as Int16

[C#]

public Int16 GetEncodingVBRQualitiesCount (

Int16 nInputDevice,

Int16 nFormatIndex

);

[C++]

public: Int16 GetEncodingVBRQualitiesCount (

Int16 nInputDevice,

Int16 nFormatIndex

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nFormatIndex | Number representing the zero-based index of the native resampling format. The number of native resampling formats supported by the given input device can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The number of supported encoding Variable Bit Rate qualities.


EncodeFormats.WMA.GetEncodingVBRQualitiesCountEx method

EncodeFormats.WMA.GetEncodingVBRQualitiesCountEx method

Remarks

Retrieves the number of encoding qualities (for Variable Bit Rate support) supported by Windows Media components for a given frequency and number of channels.

Each of the supported qualities can be obtained at a later time using the EncodeFormats.WMA.GetEncodingVBRQualityEx method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingVBRQualitiesCountEx (

nFrequency as Int32,

nChannels as Int16

) as Int16

[C#]

public Int16 GetEncodingVBRQualitiesCountEx (

Int32 nFrequency,

Int16 nChannels

);

[C++]

public: Int16 GetEncodingVBRQualitiesCountEx (

Int32 nFrequency,

Int16 nChannels

);

Parameter | Description
nFrequency | Frequency expressed in Hertz (e.g. 44100)
nChannels | Number of channels: 1 for Mono, 2 for Stereo

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The number of supported encoding Variable Bit Rate qualities.


EncodeFormats.WMA.GetEncodingVBRQuality method

EncodeFormats.WMA.GetEncodingVBRQuality method

Remarks

Retrieves a specific encoding quality (for Variable Bit Rate support) for a given native resampling format.

The number of available bitrates can be obtained using the EncodeFormats.WMA.GetEncodingVBRQualitiesCount method.

This method can be called only when the Status property is different from RECORD_STATUS_NOT_READY.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingVBRQuality (

nInputDevice as Int16,

nFormatIndex as Int16,

nQualityIndex as Int16

) as Int32

[C#]

public Int32 GetEncodingVBRQuality (

Int16 nInputDevice,

Int16 nFormatIndex,

Int16 nQualityIndex

);

[C++]

public: Int32 GetEncodingVBRQuality (

Int16 nInputDevice,

Int16 nFormatIndex,

Int16 nQualityIndex

);

Parameter | Description
nInputDevice | Number representing the zero-based index of the input device
nFormatIndex | Number representing the zero-based index of the native resampling format. The number of native resampling formats supported by the given input device can be obtained using the EncodeFormats.ResampleNativeFormatsGetCount method and their friendly description can be obtained using the EncodeFormats.ResampleNativeFormatGetDesc method.
nQualityIndex | Number representing the zero-based index of the bitrate quality

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The requested encoding Variable Bit Rate quality: the range of supported values is from 0 to 100.


EncodeFormats.WMA.GetEncodingVBRQualityEx method

EncodeFormats.WMA.GetEncodingVBRQualityEx method

Remarks

Retrieves a specific encoding quality (for Variable Bit Rate support) supported by Windows Media components for a given frequency and number of channels.

The number of available bitrates can be obtained using the EncodeFormats.WMA.GetEncodingVBRQualitiesCountEx method.

For further details about encoding in WMA format refer to the EncodeWMA class section.

For further information about available encoding formats see the EncodeFormatsMan class.

Syntax

[Visual Basic]

Public Function GetEncodingVBRQualityEx (

nFrequency as Int32,

nChannels as Int16,

nQualityIndex as Int16

) as Int32

[C#]

public Int32 GetEncodingVBRQualityEx (

Int32 nFrequency,

Int16 nChannels,

Int16 nQualityIndex

);

[C++]

public: Int32 GetEncodingVBRQualityEx (

Int32 nFrequency,

Int16 nChannels,

Int16 nQualityIndex

);

Parameter | Description
nFrequency | Frequency expressed in Hertz (e.g. 44100)
nChannels | Number of channels: 1 for Mono, 2 for Stereo
nQualityIndex | Number representing the zero-based index of the bitrate quality

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The requested encoding Variable Bit Rate quality: the range of supported values is from 0 to 100.


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

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

- RecordedSoundEditor

- SimpleMp3Recorder


GraphicBarsManager.Create method

GraphicBarsManager.Create method

Remarks

Creates a new instance of the GraphicBarsMan class on the given parent window.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class section.

Syntax

[Visual Basic]

Public Function Create (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
0 | An error occurred, check the LastError property value in order to get the error code
Other values | Handle (HWND) of the new graphic bar


GraphicBarsManager.Destroy method

GraphicBarsManager.Destroy method

Remarks

Destroys an existing graphic bar control.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_NOERROR (0) | The method call was successful.


GraphicBarsManager.GetGraphicalSettings method

GraphicBarsManager.GetGraphicalSettings method

Remarks

Retrieves the current graphical settings for the given graphic bar. Settings can be modified through the GraphicBarsManager.SetGraphicalSettings method.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_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 details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_NOERROR (0) | The method call was successful.


GraphicBarsManager.GetValue method

GraphicBarsManager.GetValue method

Remarks

Obtains the current value set into the graphic bar. The current value can be modified through the GraphicBarsManager.SetValue method.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_NOERROR (0) | The method call was successful.


GraphicBarsManager.Move method

GraphicBarsManager.Move method

Remarks

Moves or resizes an existing graphic bar control..

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_NOERROR (0) | The method call was successful.


GraphicBarsManager.Refresh method

GraphicBarsManager.Refresh method

Remarks

Refreshes an existing graphic bar control.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_NOERROR (0) | The method call was successful.


GraphicBarsManager.SetFlatBorder method

GraphicBarsManager.SetFlatBorder method

Remarks

Sets parameters for the flat border surrounding the graphic bar. This method is ignored if the border of the graphic bar has been set to 3D mode by setting the bAppearance3d parameter of the GRAPHIC_BAR_SETTINGS structure to "True".

In the graphics below you can see the flat border having a width set to two pixels and the color set to green.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_NOERROR (0) | The method call was successful.


GraphicBarsManager.SetGraphicalSettings method

GraphicBarsManager.SetGraphicalSettings method

Remarks

Modifies the graphical settings for the given graphic bar. Current settings can be obtained through the GraphicBarsManager.GetGraphicalSettings method.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_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 details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_NOERROR (0) | The method call was successful.


GraphicBarsManager.SetValue method

GraphicBarsManager.SetValue method

Remarks

Sets a new value into the graphic bar. The current value can be obtained through the GraphicBarsManager.GetValue method.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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.ERR_NOERROR (0) | The method call was successful.


GraphicBarsManager.Show method

GraphicBarsManager.Show method

Remarks

Shows/hides an existing graphic bar control.

For details about the use of the Graphic Bars Manager refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Graphic Bars Manager refer to the GraphicBarsMan class 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 Waveform Analyzer window
true | Shows the Waveform Analyzer window

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.


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 details about the use of graphic bars refer to the How to perform custom feedbacks rendering using graphic bars section.

For further details about methods of the Waveform Analyzer refer to the GraphicBarsMan class 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 | 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 | 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:


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


Oscilloscope.ColorBackground property

Oscilloscope.ColorBackground property

Type

[Visual Basic]

Public Property ColorBackground As Color

[C#]

public Color ColorBackground {get; set;}

[C++]

public: __property Color get_ColorBackground();

public: __property void set_ColorBackground(Color);

Remarks

Determines the color of the Oscilloscope background.

See also

Oscilloscope class.

DisplayOscilloscope property

How to use embedded Visual Feedbacks section.


Oscilloscope.ColorLine property

Oscilloscope.ColorLine property

Type

[Visual Basic]

Public Property ColorLine As Color

[C#]

public Color ColorLine {get; set;}

[C++]

public: __property Color get_ColorLine();

public: __property void set_ColorLine(Color);

Remarks

Determines the color of the Oscilloscope line.

See also

Oscilloscope class.

DisplayOscilloscope property

How to use embedded Visual Feedbacks section.


Oscilloscope.LineWidth property

Oscilloscope.LineWidth property

Type

[Visual Basic]

Public Property LineWidth As Int16

[C#]

public Int16 LineWidth {get; set;}

[C++]

public: __property Int16 get_LineWidth();

public: __property void set_LineWidth(Int16);

Remarks

Determines the width in pixels of the Oscilloscope line.

See also

Oscilloscope class.

DisplayOscilloscope property

How to use embedded Visual Feedbacks section.


Oscilloscope.Type property

Oscilloscope.Type property

Type

[Visual Basic]

Public Property Type As enumOscillType

[C#]

public enumOscillType Type {get; set;}

[C++]

public: __property enumOscillType get_Type();

public: __property void set_Type(enumOscillType);

Remarks

Determines the type of drawing performed for the embedded Oscilloscope visual feedback.

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 embedded Visual Feedbacks section.


Oscilloscope.ZoomPerc property

Oscilloscope.ZoomPerc property

Type

[Visual Basic]

Public Property ZoomPerc As Int16

[C#]

public int16 ZoomPerc {get; set;}

[C++]

public: __property Int16 get_ZoomPerc();

public: __property void set_ZoomPerc(Int16);

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%

See also

Oscilloscope class.

DisplayOscilloscope property

How to use embedded Visual Feedbacks section.


Oscilloscope.Create method

Oscilloscope.Create method

Remarks

Creates an instance of the Oscilloscope class: 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.

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 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 Oscilloscope graphics.

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.


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 Oscilloscope is still not visible: you must make a call to the Oscilloscope.Show method in order to display it.

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 CreateNew (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


Oscilloscope.Resize method

Oscilloscope.Resize method

Remarks

Resizes the embedded Oscilloscope, useful when a resize of the hosting window occurs. This method has no effect without a previous call to the Oscilloscope.Create method.

For further details about using the embedded Oscilloscope refer to the Oscilloscope class section.

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

Syntax

[Visual Basic]

Public Function Resize (

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Resize (

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Resize (

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
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.ERR_NOERROR (0) | The method call was successful.


Oscilloscope.SetBackPictureFromFile method

Oscilloscope.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the embedded Oscilloscope refer to the Oscilloscope class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks 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.ERR_NOERROR (0) | The method call was successful.


Oscilloscope.SetBackPictureFromHandle method

Oscilloscope.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle.

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 (

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

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

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.


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 embedded Visual Feedbacks 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 Oscilloscope graphics.

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.


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 embedded Visual Feedbacks 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 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.ERR_NOERROR (0) | The method call was successful.


RecordedSound class

RecordedSound class

The RecordedSound class, accessible through the control's RecordedSound property, contains methods that allow processing the current recorded sound contents.

The RecordedSound class is implemented through the following methods:

Methods

AddToZip

CancelExportToFile

CancelUploadToFTP

CopyRangeToClipboard

FilterApply

FreeMemory

GetDuration64

GetFormattedDuration

GetFormattedPlaybackPosition

GetMemoryPtr

GetMemorySize

GetPlaybackPosition

Pause

Play

PlayRange

PlaybackRateGet

PlaybackRateSet

PlaybackRateRatioGet

PlaybackTempoGet

PlaybackTempoSet

RequestDeleteRange

RequestExportToFile

RequestInsertSilence

RequestReduceToRange

RequestUploadToFTP

Resume

SaveToFile

SeekPlayPosition

SoundDirectionEnable

SoundDirectionGet

SoundDirectionIsEnabled

SoundDirectionSet

Stop

TrimSilence

TrimSilenceEnhanced

As you can see on the list above, some method's name begins with the "Request" prefix: all of these methods will start a lengthy operation that, if not executed inside a separate thread, would certainly block the user interface of the container application: for this reason, these methods will start the related task inside a worker thread and then will immediately return control to the container application which will be kept informed about the advancement and success of the launched task through dedicated events.

Samples of use of the RecordedSound object in Visual C#.NET and Visual Basic.NET can be found inside all of the samples installed with the product's setup package.


RecordedSound.AddToZip method

RecordedSound.AddToZip method

Remarks

Adds the recorded sound 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.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to export a recorded sound section.

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 AddToZip (

strEntryName as String,

bAddExtraPath as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes AddToZip (

string strEntryName,

bool bAddExtraPath

);

[C++]

public: enumErrorCodes AddToZip (

string strEntryName,

bool bAddExtraPath

);

Parameter

Description

strEntryName

String representing the name of the entry to add.

If sound data resulting from a recording session has been stored on a file, you may use the full pathname of the destination file.

In case the ZIP session should already contain an entry with the same name, this would be removed and replaced by the new one: you may use the ZIP.EntryUncompressedSizeGet method in order to understand if an entry with a specific name already exists.

bAddExtraPath

This parameter is ignored if sound data resulting from a recording session has been stored on a memory buffer

If sound data resulting from a recording session has been stored on a file, this value represents a boolean flag determining if the relative path of the recorded sound file should be added to the destination path inside the ZIP file session.

Supported values are the following:

Value | Meaning
false | The relative path of the recorded sound file is not added. If for example the strEntryName parameter should be "c:\first_dir\second_dir\myFile.mp3" the final name of the entry would be "myFile.mp3"
true | The relative path of the recorded sound file is added. If for example the strEntryName parameter should be "c:\first_dir\second_dir\myFile.mp3" the final name of the entry would be "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.


RecordedSound.CancelExportToFile method

RecordedSound.CancelExportToFile method

Remarks

Stops an existing exporting session started through a call to the RecordedSound.RequestExportToFile method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to export a recorded sound section.

Syntax

[Visual Basic]

Public Function CancelExportToFile (

) as enumErrorCodes

[C#]

public enumErrorCodes CancelExportToFile (

);

[C++]

public: enumErrorCodes CancelExportToFile (

);

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.


RecordedSound.CancelUploadToFTP method

RecordedSound.CancelUploadToFTP method

Remarks

Stops an existing FTP session started through a call to the RecordedSound.RequestUploadToFTP or RequestUploadFileToFTP methods.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

An example of use of this method can be found inside the UploadSoundToFTP sample.

Syntax

[Visual Basic]

Public Function CancelUploadToFTP (

) as enumErrorCodes

[C#]

public enumErrorCodes CancelUploadToFTP (

);

[C++]

public: enumErrorCodes CancelUploadToFTP (

);

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.


RecordedSound.CopyRangeToClipboard method

RecordedSound.CopyRangeToClipboard method

Remarks

Copies the given sound range into the system clipboard.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function CopyRangeToClipboard (

nStartPosition as Int32,

nEndPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes CopyRangeToClipboard (

Int32 nStartPosition,

Int32 nEndPosition

);

[C++]

public: enumErrorCodes CopyRangeToClipboard (

Int32 nStartPosition,

Int32 nEndPosition

);

Parameter | Description
nStartPosition | Start position, expressed in milliseconds, of the sound range to copy to clipboard
nEndPosition | End position, expressed in milliseconds, of the sound range to copy to clipboard. If set to -1 the end position will be set to the end of the sound.

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.


RecordedSound.DurationStringGet method

RecordedSound.DurationStringGet method

Remarks

Retrieves a string containing the formatted duration of the last recorded sound 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 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 RecordedSound.GetDuration64 method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function DurationStringGet (

bShowHour as Boolean,

bShowMs as Boolean,

strHourSeparator as String,

strMsSeparator as String,

nNumberOfMsDigits as Int32

) as String

[C#]

public string DurationStringGet (

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits

);

[C++]

public: string DurationStringGet (

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits

);

Parameter

Description

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 sound duration


RecordedSound.FilterApply method

RecordedSound.FilterApply method

Remarks

Applies an embedded filter effect to the given portion of the recorded sound.

For further information about the use of embedded filters refer to the How to apply embedded filters section.

Syntax

[Visual Basic]

Public Function FilterApply (

nStartPosition as Int32,

nEndPosition as Int32,

nFilterName as enumFilterNames,

nFilterType as enumFilterTypes,

fFrequency1 as Single,

fFrequency2 as Single,

fGain as Single,

fTransitionTime as Single

) as enumErrorCodes

[C#]

public enumErrorCodes FilterApply (

Int32 nStartPosition,

Int32 nEndPosition,

enumFilterNames nFilterName,

enumFilterTypes nFilterType,

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

[C++]

public: enumErrorCodes FilterApply (

Int32 nStartPosition,

Int32 nEndPosition,

enumFilterNames nFilterName,

enumFilterTypes nFilterType,

float fFrequency1,

float fFrequency2,

float fGain,

float fTransitionTime

);

Parameter

Description

nStartPosition

Start position, expressed in milliseconds, of the affected sound range.

nEndPosition

End position, expressed in milliseconds, of the affected sound range.. If set to -1 the end position will be set to the end of the sound.

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 recording which can be determined in two ways:

· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_CUSTOM_FORMAT, through the EncodeFormats.ResampleCustomFrequency property
· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_NATIVE_FORMAT, through the frequency established by the value set into the EncodeFormats.ResampleNativeFormat property

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 under editing; the frequency of the recording which can be determined in two ways:

· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_CUSTOM_FORMAT, through the EncodeFormats.ResampleCustomFrequency property
· if the EncodeFormats.ResampleMode property is set to RESAMPLE_MODE_NATIVE_FORMAT, through the frequency established by the value set into the EncodeFormats.ResampleNativeFormat property

fGain

Gain applied to the filter, expressed in percentage: typically this parameter should be set to 100 which leaves the original sound level unchanged during filtering; values under 100 reduce the sound level while values above 100 amplify the sound level.

This parameter is ignored by IIR filters like Bessel and Butterworth.

fTransitionTime

Transition time, expressed in milliseconds, describes how quickly a filter transitions from a pass band to a stop band, or vice versa.

The minimum accepted value is 201 milliseconds.

This parameter is ignored by IIR filters like Bessel and Butterworth.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


RecordedSound.FreeMemory method

RecordedSound.FreeMemory method

Remarks

If sound data resulting from a recording session has been stored in memory, this method frees the memory buffer. For file-based recording sessions, the original output file won't be deleted but the control will no more consider it as belonging to the latest recording session.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function FreeMemory (

) as enumErrorCodes

[C#]

public enumErrorCodes FreeMemory (

);

[C++]

public: enumErrorCodes FreeMemory (

);

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.


RecordedSound.GetDuration method

RecordedSound.GetDuration64 method

Remarks

Gets the duration, expressed in milliseconds, of the last recorded sound.

A formatted string of the sound duration can be retrieved using the RecordedSound.GetFormattedDuration method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function GetDuration64 (

) as Int64

[C#]

public Int64 GetDuration64 (

);

[C++]

public: Int64 GetDuration64 (

);

Return value

Value | Meaning
Value > 0 | The sound duration expressed in milliseconds
Negative value | An error occurred (see the LastError property for further error details)


RecordedSound.GetMemoryPtr method

RecordedSound.GetMemoryPtr method

Remarks

If sound data resulting from a recording session has been stored in memory, this method will return the memory address (pointer) of the buffer containing sound data.

The actual size of the memory buffer can be retrieved using the RecordedSound.GetMemorySize method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function GetMemoryPtr (

) as Int32

[C#]

public Int32 GetMemoryPtr (

);

[C++]

public: Int32 GetMemoryPtr (

);

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The buffer's memory address


RecordedSound.GetMemorySize method

RecordedSound.GetMemorySize method

Remarks

If sound data resulting from a recording session has been stored in memory, this method will return the size in bytes of the buffer. Note that, during the recording session, you can obtain the growing buffer's size in real time through theCallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_SIZE.

The buffer's address in memory can be retrieved through the RecordedSound.GetMemoryPtr method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function GetMemorySize (

) as Int32

[C#]

public Int32 GetMemorySize (

);

[C++]

public: Int32 GetMemorySize (

);

Return value

Value | Meaning
Negative value | An error occurred. Check the LastError property value in order to see the last error.
> 0 | The buffer's size in bytes


RecordedSound.GetPlaybackPosition method

RecordedSound.GetPlaybackPosition method

Remarks

Gets the current position, expressed in milliseconds, of the current playback session.

A formatted string of the current position can be retrieved using the RecordedSound.GetFormattedPlaybackPosition method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function GetPlaybackPosition (

) as Int32

[C#]

public Int32 GetPlaybackPosition (

);

[C++]

public: Int32 GetPlaybackPosition (

);

Return value

Value | Meaning
Value > 0 | The playback position in milliseconds
Negative value | An error occurred (see the LastError property for further error details)


RecordedSound.Pause method

RecordedSound.Pause method

Remarks

Pauses a playback session started through the RecordedSound.Play or RecordedSound.PlayRange methods.

A paused session can be resumed through a call to the RecordedSound.Resume method.

A successful call to this method causes the CallbackSoundPlaybackStatusChanged delegate to be invoked with the nStatus parameter set to PLAYBACK_PAUSED.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function Pause (

) as enumErrorCodes

[C#]

public enumErrorCodes Pause (

);

[C++]

public: enumErrorCodes Pause (

);

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.


RecordedSound.Play method

RecordedSound.Play method

Remarks

Plays the last recorded sound: if sound data resulting from a recording session has been stored in memory, this method will start a playback session using recorded sound data in memory; if sound data have been stored into a disk file, this method will load and will automatically play the file.

A playback session can be paused through the RecordedSound.Pause method and stopped through the RecordedSound.Stop method.

A successful call to this method causes the CallbackSoundPlaybackStatusChanged delegate to be invoked with the nStatus parameter set to PLAYBACK_PLAYING. Once the playback session has been performed completely, the CallbackSoundPlaybackDone delegate is invoked.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function Play (

) as enumErrorCodes

[C#]

public enumErrorCodes Play (

);

[C++]

public: enumErrorCodes Play (

);

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.


RecordedSound.PlayRange method

RecordedSound.PlayRange method

Remarks

Plays the given range inside the last recorded sound: if sound data resulting from a recording session has been stored in memory, this method will start a playback session using recorded sound data in memory; if sound data have been stored into a disk file, this method will load and will automatically play the file.

A playback session can be paused through the RecordedSound.Pause method and stopped through the RecordedSound.Stop method.

A successful call to this method causes the CallbackSoundPlaybackStatusChanged delegate to be invoked with the nStatus parameter set to PLAYBACK_PLAYING. Once the playback session has been performed completely, the CallbackSoundPlaybackDone delegate is invoked.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function PlayRange (

nStartPosition as Int32,

nEndPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlayRange (

Int32 nStartPosition,

Int32 nEndPosition

);

[C++]

public: enumErrorCodes PlayRange (

Int32 nStartPosition,

Int32 nEndPosition

);

Parameter | Description
nStartPosition | Start position, expressed in milliseconds, of the sound range to play.
nEndPosition | End position, expressed in milliseconds, of the sound range to play. If this parameter is set to -1, the playback session will continue until reaching the sound's end.

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.


RecordedSound.PlaybackRateGet method

RecordedSound.PlaybackRateGet method

Remarks

Obtains the current rate percentage of the playback stream. The playback rate percentage can be modified calling the RecordedSound.PlaybackRateSet method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function PlaybackRateGet (

ByRef fRatePerc as Single

) as Single

[C#]

public float PlaybackRateGet (

ref float fRatePerc

);

[C++]

public: enumErrorCodes PlaybackRateGet (

float __gc *fRatePerc

);

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


RecordedSound.PlaybackRateSet method

RecordedSound.PlaybackRateSet method

Remarks

Changes both the sound tempo and pitch of the playback stream, 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 RecordedSound.PlaybackTempoSet method. The current rate percentage can be obtained through the RecordedSound.PlaybackRateGet method. The current effective playback rate ratio, that may be also affected by the RecordedSounds.PlaybackTempoSet method, can be obtained through the RecordedSound.PlaybackRateRatioGet method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function PlaybackRateSet (

fRatePerc As Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackRateSet (

float fRatePerc

);

[C++]

public: enumErrorCodes PlaybackRateSet (

float fRatePerc

);

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


RecordedSound.PlaybackRateRatioGet method

RecordedSound.PlaybackRateRatioGet method

Remarks

Obtains the current ratio for playback rate.

When playback is performed at normal speed, its ratio is 1.0; after changing the playback speed through the RecordedSound.PlaybackTempSet or RecordedSound.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.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function PlaybackRateRatioGet (

ByRef fRatio as Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackRateRatioGet (

ref float fRatio

);

[C++]

public: enumErrorCodes PlaybackRateRatioGet (

float __gc *fRatio

);

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


RecordedSound.PlaybackTempoGet method

RecordedSound.PlaybackTempoGet method

Remarks

Retrieves the current Tempo percentage for the playback stream. The Tempo percentage can be modified calling the RecordedSound.PlaybackTempoSet method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function PlaybackTempoGet (

ByRef fTempoPerc as Single

) as Single

[C#]

public float PlaybackTempoGet (

ref float fTempoPerc

);

[C++]

public: float PlaybackTempoGet (

float __gc *fTempoPerc

);

Parameter | Description
fTempoPerc | Reference that, on return from the method call, will contain the Tempo variation expressed in percentage; supported values are from -90 to 90.


RecordedSound.PlaybackTempoSet method

RecordedSound.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 RecordedSound.PlaybackTempoGet method. The current effective playback rate ratio, that may be also affected by the RecordedSound.PlaybackRateSet method, can be obtained through the RecordedSound.PlaybackRateRatioGet method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function PlaybackTempoSet (

fTempoPerc As Single

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackTempoSet (

float fTempoPerc

);

[C++]

public: enumErrorCodes PlaybackTempoSet (

float fTempoPerc

);

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


RecordedSound.PositionStringGet method

RecordedSound.PositionStringGet method

Remarks

Retrieves a formatted string representing the current time position during a playback session. The string is formatted as 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 that the playing sound has performed, till now, for 4 minutes, 34 seconds and 200 milliseconds.

The playback position in milliseconds can be obtained using the RecordedSound.GetPlaybackPosition method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function PositionStringGet (

bShowHour as Boolean,

bShowMs as Boolean,

strHourSeparator as String,

strMsSeparator as String,

nNumberOfMsDigits as Int32

) as String

[C#]

public string PositionStringGet (

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits

);

[C++]

public: string PositionStringGet (

bool bShowHour,

bool bShowMs,

string strHourSeparator,

string strMsSeparator,

Int32 nNumberOfMsDigits

);

Parameter

Description

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 playback position


RecordedSound.RequestDeleteRange method

RecordedSound.RequestDeleteRange method

Remarks

Requests to edit the recorded sound deleting the given sound range.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function RequestDeleteRange (

nStartPosition as Int32,

nEndPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes RequestDeleteRange (

Int32 nStartPosition,

Int32 nEndPosition

);

[C++]

public: enumErrorCodes RequestDeleteRange (

Int32 nStartPosition,

Int32 nEndPosition

);

Parameter | Description
nStartPosition | Start position, expressed in milliseconds, of the sound range to delete
nEndPosition | End position, expressed in milliseconds, of the sound range to delete. If set to -1 the end position will be set to the end of the sound.

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.


RecordedSound.RequestExportToFile method

RecordedSound.RequestExportToFile method

Remarks

Requests to resample and export the given sound range into a file.

The exporting session can be cancelled through the RecordedSound.CancelExportToFile method.

During the export session, the container application will be notified about the exporting advancement through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_SOUND_EXPORT_PERC.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to export a recorded sound section.

Syntax

[Visual Basic]

Public Function RequestExportToFile (

nFrequency as Int32,

nChannels as Int32,

nBitsPerSample as Int32,

nStartPosition as Int32,

nEndPosition as Int32,

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes RequestExportToFile (

Int32 nFrequency,

Int32 nChannels,

Int32 nBitsPerSample,

Int32 nStartPosition,

Int32 nEndPosition,

string strPathname

);

[C++]

public: enumErrorCodes RequestExportToFile (

Int32 nFrequency,

Int32 nChannels,

Int32 nBitsPerSample,

Int32 nStartPosition,

Int32 nEndPosition,

string strPathname

);

Parameter | Description
nFrequency | Frequency used to resample the sound to export (44100, 22050, etc.). This parameter is ignored when the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE.
nChannels | Number of channels used to resample the sound to export (1 for Mono or 2 for Stereo). This parameter is ignored when the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE.
nBitsPerSample | Number of bits per sample used to resample the sound to export (8 or 16). This parameter is ignored when the EncodeFormats.ForExporting property is set to ENCODING_FORMAT_WMA and the EncodeFormats.WMA.EncodeMode property is set to WMA_ENCODE_PROFILE.
nStartPosition | Start position, expressed in milliseconds, of the sound range to export
nEndPosition | End position, expressed in milliseconds, of the sound range to export. If set to -1 the end position will be set to the end of the sound.
strPathname | String containing the absolute pathname of the destination file. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


RecordedSound.RequestInsertSilence method

RecordedSound.RequestInsertSilence method

Remarks

Requests to insert a portion of silence inside the recorded sound.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function RequestInsertSilence (

nStartPosition as Int32,

nSilenceLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes RequestInsertSilence (

Int32 nStartPosition,

Int32 nSilenceLength

);

[C++]

public: enumErrorCodes RequestInsertSilence (

Int32 nStartPosition,

Int32 nSilenceLength

);

Parameter | Description
nStartPosition | Start position, expressed in milliseconds, where the portion of silence will be inserted
nSilenceLength | Silence length, expressed in milliseconds

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.


RecordedSound.RequestReduceToRange method

RecordedSound.RequestReduceToRange method

Remarks

Requests to reduce the recorded sound removing portions of sound before and after the given range.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function RequestReduceToRange (

nStartPosition as Int32,

nEndPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes RequestReduceToRange (

Int32 nStartPosition,

Int32 nEndPosition

);

[C++]

public: enumErrorCodes RequestReduceToRange (

Int32 nStartPosition,

Int32 nEndPosition

);

Parameter | Description
nStartPosition | Start position, expressed in milliseconds, of the sound range to keep
nEndPosition | End position, expressed in milliseconds, of the sound range to keep. If set to -1 the end position will be set to the end of the sound.

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.


RecordedSound.RequestUploadToFTP method

RecordedSound.RequestUploadToFTP method

Remarks

Requests to start an uploading session of the recorded sound to a FTP server.

In case you should need to upload a file stored inside the local hard disk you could use the RequestUploadFileToFTP method.

An uploading session can be terminated before completion through a call to the RecordedSound.CancelUploadToFTP method.

During uploading session the container application is notified about the advancement percentage through the CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_SOUND_UPLOAD_PERC.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

An example of use of this method can be found inside the UploadSoundToFTP sample.

Syntax

[Visual Basic]

Public Function RequestUploadToFTP (

strHost as String,

strUsername as String,

strPassword as String,

nPort as Int32,

bPassiveMode as Boolean,

strDirectory as String,

strFilename as String,

) as enumErrorCodes

[C#]

public enumErrorCodes RequestUploadToFTP (

string strHost,

string strUsername,

string strPassword,

Int32 nPort,

bool bPassiveMode,

string strDirectory,

string strFilename

);

[C++]

public: enumErrorCodes RequestUploadToFTP (

string strHost,

string strUsername,

string strPassword,

Int32 nPort,

bool bPassiveMode,

string strDirectory,

string strFilename

);

Parameter

Description

strHost

String representing the FTP host address, without the protocol prefix (for example "ftp.multimediasoft.com" instead of "ftp://ftp.multimediasoft.com")

strUsername

String representing the FTP account username

strPassword

String representing the FTP account password

nPort

FTP port number (for example 21)

bPassiveMode

Boolean value for FTP "passive mode" flag.

Supported values are the following:

Mnemonic Value | Meaning
false | Don't use passive mode
true | Use passive mode

strDirectory

String representing the destination directory on FTP server

strFilename

String representing the destination filename

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.


RecordedSound.Resume method

RecordedSound.Resume method

Remarks

Resumes a playback session paused through the RecordedSound.Pause method.

A successful call to this method causes the CallbackSoundPlaybackStatusChanged delegate to be invoked with the nStatus parameter set to PLAYBACK_PLAYING. Once the playback session has been performed completely, the CallbackSoundPlaybackDone delegate is invoked.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function Resume (

) as enumErrorCodes

[C#]

public enumErrorCodes Resume (

);

[C++]

public: enumErrorCodes Resume (

);

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.


RecordedSound.RewindWavRecPosition method

RecordedSound.RewindWavRecPosition method

Remarks

Supported only by recording sessions in WAV format, moves back the recording position truncating the existing recorded sound beyond the given position.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function RewindWavRecPosition (

nFinalPosition as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes RewindWavRecPosition (

Int32 nFinalPosition,

);

[C++]

public: enumErrorCodes RewindWavRecPosition (

Int32 nFinalPosition

);

Parameter | Description
nFinalPosition | Rewind position expressed in milliseconds

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.


RecordedSound.SaveToFile method

RecordedSound.SaveToFile method

Remarks

If sound data resulting from a recording session has been stored in memory, this method will save the buffer's contents into a file on disk.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SaveToFile (

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes SaveToFile (

string strPathname

);

[C++]

public: enumErrorCodes SaveToFile (

string strPathname

);

Parameter | Description
strPathname | Absolute pathname of the destination file. If this pathname should contain invalid characters, they would be automatically changed into an underscore '_' character.

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.


RecordedSound.SeekPlayPosition method

RecordedSound.SeekPlayPosition method

Remarks

Seeks the current playback session to the specified position.

This method will only work with a playing or paused playback session: if you need to start the playback session from a certain position, use the RecordedSound.PlayRange method instead of the RecordedSound.Play method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SeekPlayPosition (

nPosition as Int32,

nScaleUnits as enumScaleUnits

) as enumErrorCodes

[C#]

public enumErrorCodes SeekPlayPosition (

Int32 nPosition,

enumScaleUnits nScaleUnits

);

[C++]

public: enumErrorCodes SeekPlayPosition (

Int32 nPosition,

enumScaleUnits nScaleUnits

);

Parameter

Description

nPosition

Number representing the position to reach; it's value depends upon the value of the nScaleUnits parameter

nScaleUnits

The unit used to define the nPosition parameter.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_MILLISECONDS | 0 | Milliseconds
SCALE_SECONDS | 1 | Seconds
SCALE_MINUTES | 2 | Minutes
SCALE_HOURS | 3 | Hours
SCALE_PERCENTAGE | 4 | Percentage (expressed with values from 0 to 100)

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.


RecordedSound.SetRewindOnEndOfPlayback method

RecordedSound.SetRewindOnEndOfPlayback method

Remarks

Causes the control to automatically rewind the playback position when reaching the end of the recording session's playback.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SetRewindOnEndOfPlayback (

bRewind as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SetRewindOnEndOfPlayback (

bool bRewind

);

[C++]

public: enumErrorCodes SetRewindOnEndOfPlayback (

bool bRewind

);

Parameter

Description

bRewind

Boolean value that specifies if the control must automatically rewind the playback position when the end of the recording session is reached.

Supported values are the following:

Value | Meaning
false | Don't rewind the playback position when the end is reached.
true (default) | Rewind the playback position when the end is reached.

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.


RecordedSound.SoundDirectionEnable method

RecordedSound.SoundDirectionEnable method

Remarks

Enables/disables the possibility to play the recorded sounds in reverse through future calls to the RecordedSound.SoundDirectionSet method.

Invoking this method is not needed when the waveform scroller is set, through the WaveformScroller.PlaybackOnScrollEnable method, to work in playback mode during manual scrolling.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SoundDirectionEnable (

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SoundDirectionEnable (

bool bEnable

);

[C++]

public: enumErrorCodes SoundDirectionEnable (

bool bEnable

);

Parameter

Description

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.


RecordedSound.SoundDirectionGet method

RecordedSound.SoundDirectionGet method

Remarks

Obtains the current sound's playback direction. The playback direction can be modified through the RecordedSound.SoundDirectionSet method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SoundDirectionGet (

ByRef nDirection as enumSoundDirections

) as enumSoundDirections

[C#]

public enumSoundDirections SoundDirectionGet (

ref enumSoundDirections nDirection

);

[C++]

public: enumSoundDirections SoundDirectionGet (

enumSoundDirections __gc *nDirection

);

Parameter

Description

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.


RecordedSound.SoundDirectionIsEnabled method

RecordedSound.SoundDirectionIsEnabled method

Remarks

Verifies if the possibility to play the loaded song in reverse has been enabled on the given player through the RecordedSound.SoundDirectionEnable method.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SoundDirectionIsEnabled (

ByRef bEnabled as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes SoundDirectionIsEnabled (

ref bool bEnabled

);

[C++]

public: enumErrorCodes SoundDirectionIsEnabled (

bool __gc *bEnabled

);

Parameter

Description

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.


RecordedSound.SoundDirectionSet method

RecordedSound.SoundDirectionSet method

Remarks

Sets the recorded 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 RecordedSound.SoundDirectionEnable method.

The current playback direction can be obtained through the RecordedSound.SoundDirectionGet method.

It's important to note that calling the RecordedSound.Stop method will force the forward direction of the playing sound.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function SoundDirectionSet (

nDirection as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SoundDirectionSet (

Int16 nDirection

);

[C++]

public: enumErrorCodes SoundDirectionSet (

Int16 nDirection

);

Parameter

Description

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.


RecordedSound.Stop method

RecordedSound.Stop method

Remarks

Stops a playback session started through a previous call to the RecordedSound.Play or RecordedSound.PlayRange methods.

A successful call to this method causes the CallbackSoundPlaybackStatusChanged delegate to be invoked with the nStatus parameter set to PLAYBACK_STOPPED.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function Stop (

) as enumErrorCodes

[C#]

public enumErrorCodes Stop (

);

[C++]

public: enumErrorCodes Stop (

);

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.


RecordedSound.TrimSilence method

RecordedSound.TrimSilence method

Remarks

Requests to edit the recorded sound deleting the given sound range.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function TrimSilence (

nSilenceThreshold as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes TrimSilence (

Int16 nSilenceThreshold

);

[C++]

public: enumErrorCodes TrimSilence (

Int16 nSilenceThreshold

);

Parameter

Description

nSilenceThreshold

Number representing the silence threshold referred to the volume level. Supported values are expressed with a linear volume in the range from 0 to 32767. 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);

In case you should need to define different thresholds for the initial and final portions of the recorded sound, use the RecordedSound.TrimSilenceEnhanced 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.


RecordedSound.TrimSilenceEnhanced method

RecordedSound.TrimSilenceEnhanced method

Remarks

Requests to edit the recorded sound deleting the given sound range.

For further details about recorded sound methods refer to the RecordedSound class section.

For further details see the How to perform a recording session section.

Syntax

[Visual Basic]

Public Function TrimSilenceEnhanced (

nSilenceThresholdInitial as Int16,

nSilenceThresholdFinal as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes TrimSilenceEnhanced (

Int16 nSilenceThresholdInitial,

Int16 nSilenceThresholdFinal

);

[C++]

public: enumErrorCodes TrimSilenceEnhanced (

Int16 nSilenceThresholdInitial,

Int16 nSilenceThresholdFinal

);

Parameter

Description

nSilenceThresholdInitial

Number representing the silence threshold referred to the volume level for the initial portion of the recorded sound. Supported values are expressed with a linear volume in the range from 0 to 32767. 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);

nSilenceThresholdFinal

Number representing the silence threshold referred to the volume level for the final portion of the recorded sound.

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


Spectrum.BandsWidth property

Spectrum.BandsWidth property

Type

[Visual Basic]

Public Property BandsWidth As Int16

[C#]

public Int16 BandsWidth {get; set;}

[C++]

public: __property Int16 get_BandsWidth();

public: __property void set_BandsWidth(Int16);

Remarks

Gets/sets the width in pixel of each single band composing the Spectrum visual feedback.

See also

Spectrum class.

DisplaySpectrum property

How to use embedded Visual Feedbacks section.


Spectrum.ColorBackground property

Spectrum.ColorBackground property

Type

[Visual Basic]

Public Property ColorBackground As Color

[C#]

public Color ColorBackground {get; set;}

[C++]

public: __property Color get_ColorBackground();

public: __property void set_ColorBackground(Color);

Remarks

Determines the color of the Spectrum background.

See also

Spectrum class.

DisplaySpectrum property

How to use embedded Visual Feedbacks section.


Spectrum.ColorBands property

Spectrum.ColorBands property

Type

[Visual Basic]

Public Property ColorBands As Color

[C#]

public Color ColorBands {get; set;}

[C++]

public: __property Color get_ColorBands();

public: __property void set_ColorBands(Color);

Remarks

Determines the spectrum "bands" color.

See also

Spectrum class.

DisplaySpectrum property

How to use embedded Visual Feedbacks section.


Spectrum.ColorPeaks property

Spectrum.ColorPeaks property

Type

[Visual Basic]

Public Property ColorPeaks As Color

[C#]

public Color ColorPeaks {get; set;}

[C++]

public: __property Color get_ColorPeaks();

public: __property void set_ColorPeaks(Color);

Remarks

Determines the Spectrum "peaks" color.

See also

Spectrum class.

DisplaySpectrum property

How to use embedded Visual Feedbacks section.


Spectrum.HasPeaks property

Spectrum.HasPeaks property

Type

[Visual Basic]

Public Property HasPeaks As Boolean

[C#]

public bool HasPeaks {get; set;}

[C++]

public: __property bool get_HasPeaks();

public: __property void set_HasPeaks(bool);

Remarks

Determines if the embedded Spectrum visual feedback will display graphic "peaks" over the "bands".

Supported values are the following:

Mnemonic value | Meaning
false | No peaks
true (default) | Visible peaks

See also

Spectrum class.

DisplaySpectrum property

How to use embedded Visual Feedbacks section.


Spectrum.UseLogarithmic property

Spectrum.UseLogarithmic property

Type

[Visual Basic]

Public Property UseLogarithmic As Boolean

[C#]

public bool UseLogarithmic {get; set;}

[C++]

public: __property bool get_UseLogarithmic();

public: __property void set_UseLogarithmic(bool);

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.

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 embedded Visual Feedbacks section.


Spectrum.ZoomPerc property

Spectrum.ZoomPerc property

Type

[Visual Basic]

Public Property ZoomPerc As Int16

[C#]

public int16 ZoomPerc {get; set;}

[C++]

public: __property Int16 get_ZoomPerc();

public: __property void set_ZoomPerc(Int16);

Remarks

Determines the height zoom percentage of bands drawn. By default set to 100%, can assume values in the range from 5% to 500%

See also

Spectrum class.

DisplaySpectrum property

How to use embedded Visual Feedbacks section.


Spectrum.Create method

Spectrum.Create method

Remarks

Creates an instance of the Spectrum class: 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 Sprectrum.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.

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 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 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 CallbackVuMeterValueChange delegate, allowing to render also 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.ERR_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.

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 (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


Spectrum.GetTable method

Spectrum.GetTable method

Remarks

Obtains the table of values related to each band of the spectrum.

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

Syntax

[Visual Basic]

Public Function GetTable (

tableValues() as Int16,

nTableLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetTable (

Int16 [] tableValues,

Int32 nTableLength

);

[C++]

public: enumErrorCodes GetTable (

unsigned Int16 __gc[] tableValues,

Int32 nTableLength

);

Parameter | Description
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 embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function Resize (

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Resize (

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Resize (

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
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.ERR_NOERROR (0) | The method call was successful.


Spectrum.SetBackPictureFromFile method

Spectrum.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the embedded Spectrum refer to the Spectrum class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks 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.ERR_NOERROR (0) | The method call was successful.


Spectrum.SetBackPictureFromHandle method

Spectrum.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle.

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 (

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

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

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.


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 embedded Visual Feedbacks 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 Spectrum graphics.

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.


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 embedded Visual Feedbacks section.

Syntax

[Visual Basic]

Public Function SetNumberOfBands (

nBands as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes SetNumberOfBands (

Int16 nBands

);

[C++]

public: enumErrorCodes SetNumberOfBands (

Int16 nBands

);

Parameter | Description
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.ERR_NOERROR (0) | The method call was successful.


Spectrum.Show method

Spectrum.Show method

Remarks

Shows/hides the embedded Spectrum. This method has no effect without a previous call to the Spectrum.Create method.

For further details about using the embedded Spectrum refer to the Spectrum class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks 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 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.ERR_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: 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 (

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

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
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.

Syntax

[Visual Basic]

Public Function Move (

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Move (

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Move (

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

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

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.


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 (

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.


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 (

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

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

ByRef settings as SPECTR_ENH_GENERAL_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsGeneralGet (

ref SPECTR_ENH_GENERAL_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsGeneralGet (

SPECTR_ENH_GENERAL_SETTINGS __gc *settings

);

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

settings as SPECTR_ENH_GENERAL_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsGeneralSet (

SPECTR_ENH_GENERAL_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsGeneralSet (

SPECTR_ENH_GENERAL_SETTINGS settings

);

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

ByRef settings as SPECTR_ENH_RULERS_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsRulersGet (

ref SPECTR_ENH_RULERS_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsRulersGet (

SPECTR_ENH_RULERS_SETTINGS __gc *settings

);

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

settings as SPECTR_ENH_RULERS_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsRulersSet (

SPECTR_ENH_RULERS_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsRulersSet (

SPECTR_ENH_RULERS_SETTINGS settings

);

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

ByRef settings as SPECTR_ENH_WAVE_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsWaveGet (

ref SPECTR_ENH_WAVE_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsWaveGet (

SPECTR_ENH_WAVE_SETTINGS __gc *settings

);

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

settings as SPECTR_ENH_WAVE_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsWaveSet (

SPECTR_ENH_WAVE_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsWaveSet (

SPECTR_ENH_WAVE_SETTINGS settings

);

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


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 embedded Visual Feedbacks section

The VUMeter class is implemented through the following methods and properties:

Methods

Create

CreateNew

Resize

Show

SetHwnd

SetBackPictureFromFile

SetBackPictureFromHandle

Properties

BandType

HasPeaks

ColorBands

ColorPeaks

ColorBackground

ZoomPerc


VUMeter.BandType property

VUMeter.BandType property

Type

[Visual Basic]

Public Property BandType As enumVuBandsMode

[C#]

public enumVuBandsMode BandType {get; set;}

[C++]

public: __property enumVuBandsMode get_BandType();

public: __property void set_BandType(enumVuBandsMode);

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

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 embedded Visual Feedbacks section.


VUMeter.ColorBackground property

VUMeter.ColorBackground property

Type

[Visual Basic]

Public Property ColorBackground As Color

[C#]

public Color ColorBackground {get; set;}

[C++]

public: __property Color get_ColorBackground();

public: __property void set_ColorBackground(Color);

Remarks

Determines the color of the VU-Meter background.

See also

VUMeter class.

DisplayVUMeter property

How to use embedded Visual Feedbacks section.


VUMeter.ColorBands property

VUMeter.ColorBands property

Type

[Visual Basic]

Public Property ColorBands As Color

[C#]

public Color ColorBands {get; set;}

[C++]

public: __property Color get_ColorBands();

public: __property void set_ColorBands(Color);

Remarks

Determines the VU-Meter "bands" color.

See also

VUMeter class.

DisplayVUMeter property

How to use embedded Visual Feedbacks section.


VUMeter.ColorPeaks property

VUMeter.ColorPeaks property

Type

[Visual Basic]

Public Property ColorPeaks As Color

[C#]

public Color ColorPeaks {get; set;}

[C++]

public: __property Color get_ColorPeaks();

public: __property void set_ColorPeaks(Color);

Remarks

Determines the VU-Meter "peaks" color.

See also

VUMeter class.

DisplayVUMeter property

How to use embedded Visual Feedbacks section.


VUMeter.HasPeaks property

VUMeter.HasPeaks property

Type

[Visual Basic]

Public Property HasPeaks As Boolean

[C#]

public bool HasPeaks {get; set;}

[C++]

public: __property bool get_HasPeaks();

public: __property void set_HasPeaks(bool);

Remarks

Determines if the embedded VU-Meter visual feedback will display graphic "peaks" over the "bands".

Supported values are the following:

Mnemonic value | Meaning
false | No peaks
true (default) | Visible peaks

See also

VUMeter class.

DisplayVUMeter property

How to use embedded Visual Feedbacks section.


VUMeter.ZoomPerc property

VUMeter.ZoomPerc property

Type

[Visual Basic]

Public Property ZoomPerc As Int16

[C#]

public int16 ZoomPerc {get; set;}

[C++]

public: __property Int16 get_ZoomPerc();

public: __property void set_ZoomPerc(Int16);

Remarks

Determines the height zoom percentage of bands drawn. By default set to 100%, can assume values in the range from 5% to 500%

See also

VUMeter class.

DisplayVUMeter property

How to use embedded Visual Feedbacks section.


VUMeter.Create method

VUMeter.Create method

Remarks

Creates an instance of the VUMeter class: 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.

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 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 VU-Meter 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 VU-Meter values change through the CallbackVuMeterValueChange delegate, allowing to create a custom graphical rendering.

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.


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.

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 (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


VUMeter.Resize method

VUMeter.Resize method

Remarks

Resizes the embedded VU-Meter, useful when a resize of the hosting window occurs. This method has no effect without a previous call to the VUMeter.Create method.

For further details about using the embedded VU-Meter refer to the VUMeter class section.

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

Syntax

[Visual Basic]

Public Function Resize (

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Resize (

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Resize (

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
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.ERR_NOERROR (0) | The method call was successful.


VUMeter.SetBackPictureFromFile method

VUMeter.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the embedded VU-Meter refer to the VUMeter class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks 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.ERR_NOERROR (0) | The method call was successful.


VUMeter.SetBackPictureFromHandle method

VUMeter.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle.

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 (

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

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

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.


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 embedded Visual Feedbacks 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 VU-Meter graphics.

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.


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 embedded Visual Feedbacks 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 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.ERR_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:

DeviceChannelsGet

DeviceCoreAudioIndexGet

DeviceGetCount

DeviceGetDesc

DeviceIsFormatSupported

DeviceIsStarted

DeviceLatencyGet

DeviceMuteGet

DeviceMuteSet

DeviceSharedFormatGet

DeviceStartExcusive

DeviceStartShared

DeviceStop

DeviceVolumeGet

DeviceVolumeSet

ListenInputDeviceStart

ListenInputDeviceStop

MixerInputDeviceAttach

MixerInputDeviceAttachedCountGet

MixerInputDeviceAttachedInfoGet

MixerInputDeviceDetach

MixerInputDeviceIsAttached

MixerInputDevicePeakLevelsGet

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:

- WasapiRecorder


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


WASAPI.DeviceCoreAudioIndexGet method

WASAPI.DeviceCoreAudioIndexGet method

Remarks

Obtains the zero-based index inside the list of CoreAudio devices of a given WASAPI device.

While the list of CoreAudio devices, depending upon the value of the nStateMask parameter of the CoreAudioDevices.Enum method, may not contain 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.DeviceGetCount method

WASAPI.DeviceGetCount method

Remarks

Retrieves the number of WASAPI devices currently installed inside the system.

The friendly name of each WASAPI device can be obtained using the WASAPI.DeviceGetDesc method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.DeviceGetDesc method

WASAPI.DeviceGetDesc method

Remarks

Retrieves the friendly description of the requested WASAPI device. This method is useful when you have to fill a combo box with the friendly names of available WASAPI devices.

The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the 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 been 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.DeviceMuteGet method

WASAPI.DeviceMuteGet method

Remarks

Obtains the muting state of the audio stream that enters or leaves the given WASAPI device for the current process. The current muting state can be modified through the WASAPI.DeviceMuteSet method.

If you need to obtain the master mute for the given WASAPI device, shared by all running processes, use the CoreAudioDevices.MuteGet method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.DeviceMuteSet method

WASAPI.DeviceMuteSet method

Remarks

Sets the muting state of the audio stream that enters or leaves the given WASAPI device for the current process. The current muting state can be obtained through the WASAPI.DeviceMuteGet method.

If you need to modify the master mute for the given WASAPI device, shared by all running processes, use the CoreAudioDevices.MuteSet method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.DeviceSharedFormatGet method

WASAPI.DeviceSharedFormatGet method

Remarks

Obtains the audio format for shared mode currently selected inside the Windows control panel for the given WASAPI device.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.DeviceStartExclusive method

WASAPI.DeviceStartExclusive method

Remarks

Starts a WASAPI device in exclusive mode. In order to start the device in shared mode you can use the WASAPI.DeviceStartShared method. You can know if a WASAPI device is already started through the WASAPI .DeviceIsStarted method.

Loopback devices cannot be started in exclusive mode.

This method is only effective if the InitDriversType method has been invoked with the nDriverType parameter set to DRIVER_TYPE_WASAPI and must be always called at a later stage respect to the call to the InitRecordingSystem 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 DJ Studio API for .NET and/or Audio Sound Editor API for .NET components, these ones would be affected too.

If you should be using this API in conjunction with Audio DJ Studio 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.

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


WASAPI.DeviceStartShared method

WASAPI.DeviceStartShared method

Remarks

Starts a WASAPI device in shared mode. In order to start the device in exclusive mode you can use the WASAPI.DeviceStartExcusive method. You can know if a WASAPI device is already started through the WASAPI .DeviceIsStarted method.

This method is only effective if the InitDriversType method has been invoked with the nDriverType parameter set to DRIVER_TYPE_WASAPI and must be always called at a later stage respect to the call to the InitRecordingSystem 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 DJ Studio API for .NET and/or Audio Sound Editor API for .NET components, these ones would be affected too..

If you should be using this API in conjunction with Audio DJ Studio 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.

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 multichannel mode.
WASAPI_CHANNEL_MODE_STEREO | 1 | Enables stereo mode.

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


WASAPI.DeviceStop method

WASAPI.DeviceStop method

Remarks

Stops a WASAPI device previously started through the WASAPI.DeviceStartExcusive or WASAPI.DeviceStartShared methods. You can know if a WASAPI device is already started through the WASAPI .DeviceIsStarted method.

This method will affect any other instance of the control inside the application. If the control should be used in conjunction with the Audio DJ Studio API component, this one would be affected too.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.DeviceVolumeGet method

WASAPI.DeviceVolumeGet method

Remarks

Obtains the volume of the given WASAPI device for the current process. The current volume can be modified through the WASAPI.DeviceVolumeSet method.

If you need to obtain the master volume for the given WASAPI device, shared by all running processes, use the CoreAudioDevices.MasterVolumeGet method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.DeviceVolumeSet method

WASAPI.DeviceVolumeSet method

Remarks

Sets the volume of the given WASAPI device for the current process. The current volume can be obtained through the WASAPI.DeviceVolumeGet method.

If you need to modify the master volume for the given WASAPI device, shared by all running processes, use the CoreAudioDevices.MasterVolumeSet method.

This method is only intended for usage with Windows Vista and later versions.

For further details about the use of WASAPI see the 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.ERR_NOERROR (0) | The method call was successful.


WASAPI.ListenInputDeviceStart method

WASAPI.ListenInputDeviceStart method

Remarks

Attaches a given WASAPI capture device to a specific render device, allowing to emulate the "Listen to this device" option available inside the Windows control panel.

The effect of this method can be canceled through a call to the WASAPI.ListenInputDeviceStop method.

Both the given capture and render devices must have been previously started through one between the WASAPI.DeviceStartShared and WASAPI.DeviceStartExcusive 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 ListenInputDeviceStart (

nInputDeviceIndex as Int32,

nRenderDeviceIndex as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ListenInputDeviceStart (

Int32 nInputDeviceIndex,

Int32 nRenderDeviceIndex

);

[C++]

public: enumErrorCodes ListenInputDeviceStart (

Int32 nInputDeviceIndex,

Int32 nRenderDeviceIndex

);

Parameter | Description
nInputDeviceIndex | Number representing the zero-based index of the WASAPI capture device of interest. The total number of available WASAPI capture devices can be obtained using the WASAPI.DeviceGetCount method with the nDeviceType parameter set to WASAPI_DEVICE_TYPE_CAPTURE.
nRenderDeviceIndex | Number representing the zero-based index of the WASAPI render device of interest. The total number of available WASAPI render devices can be obtained using the WASAPI.DeviceGetCount method with the nDeviceType parameter set to WASAPI_DEVICE_TYPE_RENDER.

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.


WASAPI.ListenInputDeviceStop method

WASAPI.ListenInputDeviceStop method

Remarks

Stops the effect of a previous call to the WASAPI.ListenInputDeviceStart 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 ListenInputDeviceStop (

nInputDeviceIndex as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes ListenInputDeviceStop (

Int32 nInputDeviceIndex

);

[C++]

public: enumErrorCodes ListenInputDeviceStop (

Int32 nInputDeviceIndex

);

Parameter | Description
nInputDeviceIndex | Number representing the zero-based index of the WASAPI capture device of interest.

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.


WASAPI.MixerInputDeviceAttach method

WASAPI.MixerInputDeviceAttach method

Remarks

Attaches a WASAPI input device to the internal WASAPI input mixer before starting a new recording session through the StartFromWasapiMixer method. The call to this method will fail if the recording session is already started.

An attached input device can be detached at any time through the WASAPI.MixerInputDeviceDetach method. You can verify if an input device is already attached through the WASAPI.MixerInputDeviceIsAttached method.

The device to attach must have been previously started through one between the WASAPI.DeviceStartShared and WASAPI.DeviceStartExcusive 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 MixerInputDeviceAttach (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes

) as enumErrorCodes

[C#]

public enumErrorCodes MixerInputDeviceAttach (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

[C++]

public: enumErrorCodes MixerInputDeviceAttach (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI input device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of input device.

Supported values are the following:

Mnemonic Value | Value | Meaning
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.ERR_NOERROR (0) | The method call was successful.


WASAPI.MixerInputDeviceAttachedCountGet method

WASAPI.MixerInputDeviceAttachedCountGet method

Remarks

Obtains the number of input devices previously attached to the WASAPI mixer through the WASAPI.MixerInputDeviceAttach method.

Information about a specific input device attached to the WASAPI mixer can be obtained through the WASAPI.MixerInputDeviceAttachedInfoGet 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 MixerInputDeviceAttachedCountGet (

ByRef nCount as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes MixerInputDeviceAttachedCountGet (

ref Int32 nCount

);

[C++]

public: enumErrorCodes MixerInputDeviceAttachedCountGet (

Int32 __gc *nCount

);

Parameter | Description
nCount | Reference that, on return from the method call, will contain the number of attached input devices.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


WASAPI.MixerInputDeviceAttachedInfoGet method

WASAPI.MixerInputDeviceAttachedInfoGet method

Remarks

Obtains information about a single input device previously attached to the WASAPI mixer through the WASAPI.MixerInputDeviceAttach 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 MixerInputDeviceAttachedInfoGet (

nListIndex as Int32,

ByRef nDeviceIndex as Int32,

ByRef nDeviceType as enumWasapiDeviceTypes

) as enumErrorCodes

[C#]

public enumErrorCodes MixerInputDeviceAttachedInfoGet (

Int32 nListIndex,

ref Int32 nDeviceIndex,

ref enumWasapiDeviceTypes nDeviceType

);

[C++]

public: enumErrorCodes MixerInputDeviceAttachedInfoGet (

Int32 nListIndex,

Int32 __gc *nDeviceIndex,

enumWasapiDeviceTypes __gc *nDeviceType

);

Parameter

Description

nListIndex

Zero-based index of the input device within the list of input devices attached to the WASAPI mixer; the number of of input devices attached to the WASAPI mixer can be obtained through the WASAPI.MixerInputDeviceAttachedCountGet method.

nDeviceIndex

Reference that, on return from the method call, will contain the the zero-based index of the input device within the list of capture or loopback devices installed inside the system. The total number of available WASAPI capture or loopback devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

Reference that, on return from the method call, will contain the type of input device.

Supported values are the following:

Mnemonic Value | Value | Meaning
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.ERR_NOERROR (0) | The method call was successful.


WASAPI.MixerInputDeviceDetach method

WASAPI.MixerInputDeviceDetach method

Remarks

Detaches a WASAPI input device, previously attached through the WASAPI.MixerInputDeviceAttach method, from the internal WASAPI mixer.

You can verify if an input device is attached to the WASAPI input mixer through the WASAPI.MixerInputDeviceIsAttached 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 MixerInputDeviceDetach (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes

) as enumErrorCodes

[C#]

public enumErrorCodes MixerInputDeviceDetach (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

[C++]

public: enumErrorCodes MixerInputDeviceDetach (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI input device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of input device.

Supported values are the following:

Mnemonic Value | Value | Meaning
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.ERR_NOERROR (0) | The method call was successful.


WASAPI.MixerInputDeviceIsAttached method

WASAPI.MixerInputDeviceIsAttached method

Remarks

Checks if the given WASAPI input device has been previously attached to the WASAPI input mixer through a call to the WASAPI.MixerInputDeviceAttach 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 MixerInputDeviceIsAttached (

nDeviceIndex as Int32,

nDeviceType as enumWasapiDeviceTypes,

ByRef bIsAttached as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MixerInputDeviceIsAttached (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

ref bool bIsAttached

);

[C++]

public: enumErrorCodes MixerInputDeviceIsAttached (

Int32 nDeviceIndex,

enumWasapiDeviceTypes nDeviceType,

bool __gc *bIsAttached

);

Parameter

Description

nDeviceIndex

Number representing the zero-based index of the WASAPI input device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

The type of input device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

bIsAttached

Reference that, on return from the method call, will contain the attached state.

Supported values are the following:

Mnemonic constant | Meaning
false | The input device is not attached or has already been detached
true | The input device is attached

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.


WASAPI.MixerInputDevicePeakLevelsGet method

MixerInputDevicePeakLevelsGet method

Remarks

Retrieves peak levels on one of the input devices attached to the stream mixer using the specified scale.

The CallbackVuMeterValueChange delegate is used for the purpose of retrieving peak levels of the audio stream during recording/playback: this method can be used as an integration of the existing CallbackVuMeterValueChange delegate in order to obtain peak or RMS (Root-Mean-Square) levels for a specific input devices attached to the stream mixer: a good place to invoke this method is indeed inside the handler function of the CallbackVuMeterValueChange

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 MixerInputDevicePeakLevelsGet (

tPeakLevels() as Single,

nLengthInMs as Int32,

bRms as Boolean,

bStereo as Boolean,

nScaleType as enumVolumeScales

) as enumErrorCodes

[C#]

public enumErrorCodes MixerInputDevicePeakLevelsGet (

float[] tPeakLevels,

Int32 nLengthInMs,

bool bRms,

bool bStereo,

enumVolumeScales nScaleType

);

[C++]

public: enumErrorCodes MixerInputDevicePeakLevelsGet (

float[] tPeakLevels,

Int32 nLengthInMs,

bool bRms,

bool bStereo,

enumVolumeScales nScaleType

);

Parameter

Description

nListIndex

Zero-based index of the input device within the list of input devices attached to the WASAPI mixer; the number of of input devices attached to the WASAPI mixer can be obtained through the WASAPI.MixerInputDeviceAttachedCountGet method.

nDeviceIndex

Reference that, on return from the method call, will contain the number representing the zero-based index of the WASAPI input device of interest. The total number of available WASAPI devices can be obtained using the WASAPI.DeviceGetCount method.

nDeviceType

Reference that, on return from the method call, will contain type of input device.

Supported values are the following:

Mnemonic Value | Value | Meaning
WASAPI_DEVICE_TYPE_CAPTURE | 1 | Audio capture device.
WASAPI_DEVICE_TYPE_LOOPBACK | 2 | Audio loopback device.

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.


Waveform class

Waveform class

The Waveform class, accessible through the control's DisplayWaveform property, contains information needed to render the embedded Waveform visual feedback.

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 embedded Visual Feedbacks section.

The Waveform class is implemented through the following methods and properties:

Methods

Create

CreateNew

Resize

Show

SetHwnd

SetBackPictureFromFile

SetBackPictureFromHandle

Properties

Resolution

ColorLine

ColorBackground

ZoomPerc


Waveform.ColorBackground property

Waveform.ColorBackground property

Type

[Visual Basic]

Public Property ColorBackground As Color

[C#]

public Color ColorBackground {get; set;}

[C++]

public: __property Color get_ColorBackground();

public: __property void set_ColorBackground(Color);

Remarks

Determines the color of the Waveform background.

See also

Waveform class.

DisplayWaveform property

How to use embedded Visual Feedbacks section.


Waveform.ColorLine property

Waveform.ColorLine property

Type

[Visual Basic]

Public Property ColorLine As Color

[C#]

public Color ColorLine {get; set;}

[C++]

public: __property Color get_ColorLine();

public: __property void set_ColorLine(Color);

Remarks

Determines the color of the Waveform line.

See also

Waveform class.

DisplayWaveform property

How to use embedded Visual Feedbacks section.


Waveform.Resolution property

Waveform.Resolution property

Type

[Visual Basic]

Public Property Resolution As enumWaveformRes

[C#]

public enumWaveformRes Resolution {get; set;}

[C++]

public: __property enumWaveformRes get_Resolution();

public: __property void set_Resolution(enumWaveformRes);

Remarks

Determines how frequently vertical lines are drawn on the screen (by default every 30 milliseconds).

Supported values are the following:

Mnemonic constant | Value | Meaning
WAVE_RES_LOW | 0 | Low resolution: the Waveform is updated every 60 milliseconds
WAVE_RES_MEDIUM (default) | 1 | Medium resolution: the Waveform is updated every 30 milliseconds
WAVE_RES_HIGH | 2 | High resolution: the Waveform is updated every 15 milliseconds

See also

Waveform class.

DisplayWaveform property

How to use embedded Visual Feedbacks section.


Waveform.ZoomPerc property

Waveform.ZoomPerc property

Type

[Visual Basic]

Public Property ZoomPerc As Int16

[C#]

public int16 ZoomPerc {get; set;}

[C++]

public: __property Int16 get_ZoomPerc();

public: __property void set_ZoomPerc(Int16);

Remarks

Determines the height zoom percentage of waveform's lines. By default set to 100%, can assume values in the range from 5% to 500%

See also

Waveform class.

DisplayWaveform property

How to use embedded Visual Feedbacks section.


Waveform.Create method

Waveform.Create method

Remarks

Creates an instance of the Waveform class: once created, the Waveform will stay active until the termination of the container application: being a graphical object, the Waveform needs to be associated to an existing window that will be used as a surface for the graphic rendering: this window can be changed at a later time through the Waveform.SetHwnd method. 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 is still not visible: you must make a call to the Waveform.Show method in order to display it.

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 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 Waveform graphics

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.


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.

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 (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr CreateNew (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


Waveform.Resize method

Waveform.Resize method

Remarks

Resizes the embedded Waveform, useful when a resize of the hosting window occurs. This method has no effect without a previous call to the Waveform.Create method.

For further details about using the embedded Waveform refer to the Waveform class section.

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

Syntax

[Visual Basic]

Public Function Resize (

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Resize (

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Resize (

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
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.ERR_NOERROR (0) | The method call was successful.


Waveform.SetBackPictureFromFile method

Waveform.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about using the embedded Waveform refer to the Waveform class section.

For details about using Visual Feedbacks refer to the How to use embedded Visual Feedbacks 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.ERR_NOERROR (0) | The method call was successful.


Waveform.SetBackPictureFromHandle method

Waveform.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle.

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 (

hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap

);

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

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.


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 embedded Visual Feedbacks 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 Waveform graphics

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.


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 embedded Visual Feedbacks 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 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.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer class

WaveformAnalyzer class

The WaveformAnalyzer class, accessible through the control's DisplayWaveformAnalyzer property, contains methods needed to analyze the recorded sound and display its waveform representation on the screen or inside a bitmap file. For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

The WaveformAnalyzer class is implemented through the following methods:

Methods

Create

AnalyzeFullSound

AnalyzeAbort

AutoZoomEnable

Destroy

EnableScrollbarsDuringPlayback

FreeMemory

GetDisplayRange

GetDisplayWidth

GetMinMaxPeakLevelsForRange

GetRectangle

GetSelection

GraphicItemBuddyPictureGet

GraphicItemBuddyPictureParamsGet

GraphicItemBuddyPictureParamsSet

GraphicItemBuddyPictureSetFromFile

GraphicItemBuddyPictureSetFromHandle

GraphicItemBuddyPictureSetFromMemory

GraphicItemBuddyTextGet

GraphicItemBuddyTextParamsGet

GraphicItemBuddyTextParamsSet

GraphicItemBuddyTextSet

GraphicItemDescriptionGet

GraphicItemDescriptionSet

GraphicItemHorizontalLineAdd

GraphicItemHorizontalLineParamsGet

GraphicItemHorizontalLineParamsSet

GraphicItemNameGet

GraphicItemNameSet

GraphicItemHorzPositionGet

GraphicItemHorzPositionSet

GraphicItemRemove

GraphicItemShow

GraphicItemTypeGet

GraphicItemUniqueIdGet

GraphicItemVerticalLineAdd

GraphicItemVerticalLineParamsGet

GraphicItemVerticalLineParamsSet

GraphicItemVertPositionGet

GraphicItemVertPositionSet

GraphicItemWaveRangeAdd

GraphicItemWaveRangeParamsGet

GraphicItemWaveRangeParamsSet

GraphicItemsCountGet

GraphicItemsLoad

GraphicItemsLoadFromMemory

GraphicItemsMouseMoveEnable

GraphicItemsSave

GraphicItemsTypeCountGet

GraphicItemsTypeRemove

GraphicItemsTypeShow

MouseSelectionEnable

Move

PeaksBufferGet

PeaksBufferLengthGet

PeaksLoad

PeaksSave

PlaybackLineWidthSet

PositionLineWidthSet

Refresh

Scroll

SetBackPictureFromFile

SetBackPictureFromHandle

SetDisplayRange

SettingsGeneralGet

SettingsGeneralSet

SettingsRulersGet

SettingsRulersSet

SettingsRulersTimeFormatSet

SettingsScrollbarsGet

SettingsScrollbarsSet

SettingsWaveGet

SettingsWaveSet

SettingsLoad

SettingsLoadFromMemory

SettingsSave

SetSelection

SetTrackerCursors

Show

SnapshotViewDrawToHdc

SnapshotViewGetWidth

SnapshotViewGraphicItemsMaskSet

SnapshotViewSaveToFile

SnapshotViewSaveToMemory

ViewModeGet

ViewModeSet

ZoomIn

ZoomOut

ZoomToFullSound

ZoomToSelection

Internal data structures

WANALYZER_GENERAL_SETTINGS

WANALYZER_RULERS_SETTINGS

WANALYZER_SCROLLBARS_SETTINGS

WANALYZER_WAVEFORM_SETTINGS

WANALYZER_VERTICAL_LINE

WANALYZER_HORIZONTAL_LINE

WANALYZER_WAVE_RANGE

WANALYZER_BUDDY_PICTURE

WANALYZER_BUDDY_TEXT

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

- RecordedSoundEditor

- WaveformAnalyzer

- WaveformAnalyzerConfig


WaveformAnalyzer.AnalyzeAbort method

WaveformAnalyzer.AnalyzeAbort method

Remarks

Aborts a running analysis of the recorded sound.

For details about generating a waveform bitmap of the recorded sound and about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function AnalyzeAbort (

) as enumErrorCodes

[C#]

public enumErrorCodes AnalyzeAbort (

);

[C++]

public: enumErrorCodes AnalyzeAbort (

);

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.


WaveformAnalyzer.AnalyzeFullSound method

WaveformAnalyzer.AnalyzeFullSound method

Remarks

Starts the analysis of the recorded sound 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 CallbackForRecordersEvents delegate which is invoked with the nEvent parameter set to EV_REC_WAVE_ANALYSIS_PERC, after the method is completed it will be possible calculating the width in pixels of a bitmap view through the WaveformAnalyzer.SnapshotViewGetWidthForWaveform method and creating bitmaps of the waveform through the WaveformAnalyzer.SnapshotViewSaveToFile and WaveformAnalyzer.SnapshotViewSaveToMemory methods.

Data resulting from an analysis session can be discarded from memory using the WaveformAnalyzer.FreeMemory method.

This method doesn't require a previous call to the WaveformAnalyzer.Create method because it doesn't need displaying the Waveform Analyzer user interface.

For details about generating a waveform bitmap of the recorded sound and about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function AnalyzeFullSound (

) as enumErrorCodes

[C#]

public enumErrorCodes AnalyzeFullSound (

);

[C++]

public: enumErrorCodes AnalyzeFullSound (

);

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.


WaveformAnalyzer.AutoZoomEnable method

WaveformAnalyzer.AutoZoomEnable method

Remarks

Enables/disable automatic vertical zoom on waveforms with low volume level.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function AutoZoomEnable (

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes AutoZoomEnable (

bool bEnable

);

[C++]

public: enumErrorCodes AutoZoomEnable (

bool bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if auto-zoom is enabled or disabled.

Supported values are the following:

Value | Meaning
false (default) | Auto-zoom is disabled
true | Auto-zoom is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.Create method

WaveformAnalyzer.Create method

Remarks

Creates a new instance of the WaveformAnalyzer class on the given parent window in order to display the user interface of the Waveform Analyzer.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function Create (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
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.


WaveformAnalyzer.Destroy method

WaveformAnalyzer.Destroy method

Remarks

Destroys the Waveform Analyzer window.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function Destroy (

) as enumErrorCodes

[C#]

public enumErrorCodes Destroy (

);

[C++]

public: enumErrorCodes Destroy (

);

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.


WaveformAnalyzer.EnableScrollbarsDuringPlayback method

WaveformAnalyzer.EnableScrollbarsDuringPlayback method

Remarks

Enables/disables the usage of scrollbars during playback.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function EnableScrollbarsDuringPlayback (

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes EnableScrollbarsDuringPlayback (

bool bEnable

);

[C++]

public: enumErrorCodes EnableScrollbarsDuringPlayback (

bool bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if scrollbars are enabled or disabled during playback.

Supported values are the following:

Value | Meaning
false (default) | Scrollbars are disabled during playback
true | Scrollbars are enabled during playback

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.


WaveformAnalyzer.FreeMemory method

WaveformAnalyzer.FreeMemory method

Remarks

Frees memory allocated by the Waveform Analyzer after a call to the WaveformAnalyzer.AnalyzeFullSound method and clears its window contents.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function FreeMemory (

) as enumErrorCodes

[C#]

public enumErrorCodes FreeMemory (

);

[C++]

public: enumErrorCodes FreeMemory (

);

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.


WaveformAnalyzer.GetAnalysisInfo method

WaveformAnalyzer.GetAnalysisInfo method

Remarks

Obtains relevant information about the latest waveform analysis.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GetAnalysisInfo (

ByRef nTotalPeaksDetected As Int32,

ByRef fPeakDurationInMs as Single,

ByRef nMaxPeakLeft As Int32,

ByRef nMaxPeakRight As Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetAnalysisInfo (

ref Int32 nTotalPeaksDetected,

ref float fPeakDurationInMs,

ref Int32 nMaxPeakLeft,

ref Int32 nMaxPeakRight

);

[C++]

public: enumErrorCodes GetAnalysisInfo (

Int32 __gc *nTotalPeaksDetected,

float __gc *fPeakDurationInMs,

Int32 __gc *nMaxPeakLeft,

Int32 __gc *nMaxPeakRight

);

Parameter | Description
nTotalPeaksDetected | Reference that, after returning from the method call, will contain the amount of peaks detected during the sound's analysis.
fPeakDurationInMs | Reference that, after returning from the method call, will contain the duration in milliseconds of each detected peak.
nMaxPeakLeft | Reference that, after returning from the method call, will contain the level of the highest peak detected on the left channel; the peak value can be in the range from 0 to 32767.
nMaxPeakRight | Reference that, after returning from the method call, will contain the level of the highest peak detected on the right channel; the peak value can be in the range from 0 to 32767.

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


WaveformAnalyzer.GetDisplayRange method

WaveformAnalyzer.GetDisplayRange method

Remarks

Retrieves the waveform range currently displayed on the analyzer window. The current range can be modified calling the WaveformAnalyzer.SetDisplayRange method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GetDisplayRange (

ByRef nBeginPosInMs as Int32,

ByRef nEndPosInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetDisplayRange (

ref Int32 nBeginPosInMs,

ref Int32 nEndPosInMs

);

[C++]

public: enumErrorCodes GetDisplayRange (

Int32 __gc *nBeginPosInMs,

Int32 __gc *nEndPosInMs

);

Parameter | Description
nBeginPosInMs | Reference to the displayed range start position, expressed in milliseconds
nEndPosInMs | Reference to the displayed range end position, expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformAnalyzer.GetDisplayWidth method

WaveformAnalyzer.GetDisplayWidth method

Remarks

Retrieves the actual size, expressed in both milliseconds and pixels, of the display surface used to render the waveform.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GetDisplayWidth (

ByRef nWidthInMs as Int32,

ByRef nWidthInPixels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetDisplayWidth (

ref Int32 nWidthInMs,

ref Int32 nWidthInPixels

);

[C++]

public: enumErrorCodes GetDisplayWidth (

Int32 __gc *nWidthInMs,

Int32 __gc *nWidthInPixels

);

Parameter | Description
nWidthInMs | Reference that, after returning from the method call, will contain the width of the display surface, expressed in milliseconds, used for rendering the waveform
nWidthInPixels | Reference that, after returning from the method call, will contain the width of the display surface, expressed in pixels, used for rendering the waveform

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


WaveformAnalyzer.GetMinMaxPeakLevelsForRange method

WaveformAnalyzer.GetMinMaxPeakLevelsForRange method

Remarks

Obtains the minimum and maximum peak levels inside a range of the recorded sound.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GetMinMaxPeakLevelsForRange (

nBeginPosInMs as Int32,

nEndPosInMs as Int32,

ByRef fPeakMin as Single,

ByRef fPeakMax as Single,

nWaveformType as enumWaveformTypes

) as enumErrorCodes

[C#]

public enumErrorCodes GetMinMaxPeakLevelsForRange (

Int32 nBeginPosInMs,

Int32 nEndPosInMs,

ref float fPeakMin,

ref float fPeakMax,

enumWaveformTypes nWaveformType

);

[C++]

public: enumErrorCodes GetMinMaxPeakLevelsForRange (

Int32 nBeginPosInMs,

Int32 nEndPosInMs,

float __gc *fPeakMin,

float __gc *fPeakMax,

enumWaveformTypes nWaveformType

);

Parameter

Description

nBeginPosInMs

Range start position, expressed in milliseconds

nEndPosInMs

Range end position, expressed in milliseconds

fPeakMin

Reference that, after returning from the method call, will contain the minimum peak level, expressed in percentage

fPeakMax

Reference that, after returning from the method call, will contain the maximum peak level, expressed in percentage

nWaveformType

The type of waveform, related to the sound's channels.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVEFORM_TYPE_LEFT | 0 | Peaks are detected inside the left channel
WAVEFORM_TYPE_RIGHT | 1 | Peaks are detected inside the right channel
WAVEFORM_TYPE_MIXED | 2 | Peaks are detected inside both left and right mixed channels

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformAnalyzer.GetRectangle method

WaveformAnalyzer.GetRectangle method

Remarks

Obtains the rectangle where a specific graphic element is positioned inside the Waveform Analyzer.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GetRectangle (

nIdRectangle as enumWaveAnalyzerRectangles,

nIdSecondary as Int16,

ByRef nLeft as Int32,

ByRef nTop as Int32,

ByRef nWidth as Int32,

ByRef nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetRectangle (

enumWaveAnalyzerRectangles nIdRectangle,

Int16 nIdSecondary,

ref Int32 nLeft,

ref Int32 nTop,

ref Int32 nWidth,

ref Int32 nHeight

);

[C++]

public: enumErrorCodes GetRectangle (

enumWaveAnalyzerRectangles nIdRectangle,

Int16 nIdSecondary,

Int32 __gc *nLeft,

Int32 __gc *nTop,

Int32 __gc *nWidth,

Int32 __gc *nHeight

);

Parameter

Description

nIdRectangle

Mnemonic Identifier of the graphic element

Supported values are the following:

Mnemonic value | Value | Meaning
WAVEANALYZER_RECT_TOTAL | 0 | Total rectangle
WAVEANALYZER_RECT_WAVEFORM | 1 | Waveform rectangle
WAVEANALYZER_RECT_WAVEFORM_LEFT_CH | 2 | Waveform rectangle for left channel
WAVEANALYZER_RECT_WAVEFORM_RIGHT_CH | 3 | Waveform rectangle for right channel
WAVEANALYZER_RECT_SB_TOP | 4 | Top scrollbar rectangle
WAVEANALYZER_RECT_SB_BOTTOM | 5 | Bottom scrollbar rectangle
WAVEANALYZER_RECT_RULER_LEFT | 6 | Left ruler rectangle
WAVEANALYZER_RECT_RULER_RIGHT | 7 | Right ruler rectangle
WAVEANALYZER_RECT_RULER_TOP | 8 | Top ruler rectangle
WAVEANALYZER_RECT_RULER_BOTTOM | 9 | Bottom ruler rectangle
WAVEANALYZER_RECT_SELECTION | 10 | Selected rectangle
WAVEANALYZER_RECT_PLAYBACK_LINE | 11 | Playback line rectangle
WAVEANALYZER_RECT_CUSTOM_LINE | 12 | Custom vertical line rectangle. If nWidth and nHeight dimensions of the rectangle are both set to 0, this means that the line is not on the visible area of the waveform
WAVEANALYZER_RECT_HORZ_LINE_LEFT | 13 | Horizontal line on left channel rectangle. If nWidth and nHeight dimensions of the rectangle are both set to 0, this means that the line is not on the visible area of the waveform
WAVEANALYZER_RECT_HORZ_LINE_RIGHT | 14 | Horizontal line on right channel rectangle. If nWidth and nHeight dimensions of the rectangle are both set to 0, this means that the line is not on the visible area of the waveform
WAVEANALYZER_RECT_WAVE_RANGE | 15 | Wave range rectangle. If nWidth and nHeight dimensions of the rectangle are both set to 0, this means that the wave range is not on the visible area of the waveform

nIdSecondary

Unique identifier of a specific graphic item added to the analyzer through a call to one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

Leave this parameter to 0 if the value of the nIdRectangle parameter is different from WAVEANALYZER_RECT_CUSTOM_LINE, WAVEANALYZER_RECT_HORZ_LINE_LEFT, WAVEANALYZER_RECT_HORZ_LINE_RIGHT or WAVEANALYZER_RECT_WAVE_RANGE.

nLeft

Reference that, after returning from the method call, will contain the left coordinate, expressed in pixels, of the requested rectangle respect to the client area of the Waveform Analyzer.

nTop

Reference that, after returning from the method call, will contain the top coordinate, expressed in pixels, of the requested rectangle respect to the client area of the Waveform Analyzer.

nWidth

Reference that, after returning from the method call, will contain the width, expressed in pixels, of the requested rectangle.

nHeight

Reference that, after returning from the method call, will contain the height, expressed in pixels, of the requested rectangle

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


WaveformAnalyzer.GetSelection method

WaveformAnalyzer.GetSelection method

Remarks

Retrieves the portion of waveform currently selected through the tracker. The current selection can be removed/modified calling the WaveformAnalyzer.SetSelection method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GetSelection (

ByRef bSelectionAvailable as Boolean,

ByRef nBeginPosInMs as Int32,

ByRef nEndPosInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GetSelection (

ref bool bSelectionAvailable,

ref Int32 nBeginPosInMs,

ref Int32 nEndPosInMs

);

[C++]

public: enumErrorCodes GetSelection (

bool __gc *bSelectionAvailable,

Int32 __gc *nBeginPosInMs,

Int32 __gc *nEndPosInMs

);

Parameter

Description

bSelectionAvailable

Reference that, after returning from the method call, will contain the flag for selection availability.

Supported values are the following:

Value | Meaning
false | No selection is currently available
true | A selection is currently available and its limits are stored inside nBeginPosInMs and nEndPosInMs parameters

nBeginPosInMs

Reference that, after returning from the method call, will contain the selection's start position, expressed in milliseconds

nEndPosInMs

Reference that, after returning from the method call, will contain the selection's end position, expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformAnalyzer.GraphicItemBuddyPictureGet method

WaveformAnalyzer.GraphicItemBuddyPictureGet method

Remarks

Obtains the HBITMAP of the eventually existing buddy picture for the given graphic item.

On the screenshot below you can see a set of vertical lines displayed over the waveform, each with its buddy picture aligned on the bottom right of the vertical line:

An existing buddy picture can be removed at a later time by calling this method again with the HBITMAP parameter set to IntPtr.Zero.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyPictureGet (

nUniqueId as Int32,

ByRef hBitmap as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyPictureGet (

Int32 nUniqueId,

ref IntPtr hBitmap

);

[C++]

public: enumErrorCodes GraphicItemBuddyPictureGet (

Int32 nUniqueId,

IntPtr __gc *hBitmap

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

hBitmap

Reference that, on return from the method call, will contain the HBITMAP of the picture.

In order to avoid leaks of system resource, when the HBITMAP is no more needed the container application should free it by calling the DeleteObject function of the Windows API.

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.


WaveformAnalyzer.GraphicItemBuddyPictureParamsGet method

WaveformAnalyzer.GraphicItemBuddyPictureParamsGet method

Remarks

Obtains parameters of a buddy picture associated to a graphic item over the waveform's graphics. These parameters can be modified through the WaveformAnalyzer.GraphicItemBuddyPictureParamsSet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyPictureParamsGet (

nUniqueId as Int32,

ByRef settings as WANALYZER_BUDDY_PICTURE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyPictureParamsGet (

Int32 nUniqueId,

ref WANALYZER_BUDDY_PICTURE settings

);

[C++]

public: enumErrorCodes GraphicItemBuddyPictureParamsGet (

Int32 nUniqueId,

WANALYZER_BUDDY_PICTURE __gc *settings

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

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


WaveformAnalyzer.GraphicItemBuddyPictureParamsSet method

WaveformAnalyzer.GraphicItemBuddyPictureParamsSet method

Remarks

Obtains parameters of a buddy picture associated to a graphic item over the waveform's graphics. Current parameters can be obtained through the WaveformAnalyzer.GraphicItemBuddyPictureParamsGet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyPictureParamsSet (

nUniqueId as Int32,

settings as WANALYZER_BUDDY_PICTURE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyPictureParamsSet (

Int32 nUniqueId,

WANALYZER_BUDDY_PICTURE settings

);

[C++]

public: enumErrorCodes GraphicItemBuddyPictureParamsSet (

Int32 nUniqueId,

WANALYZER_BUDDY_PICTURE settings

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

settings

The new 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.


WaveformAnalyzer.GraphicItemBuddyPictureSetFromFile method

WaveformAnalyzer.GraphicItemBuddyPictureSetFromFile method

Remarks

Sets a picture taken from a file that will be displayed as a buddy picture of a graphic item over the waveform's graphics. The HBITMAP of the current buddy picture can be obtained through the WaveformAnalyzer.GraphicItemBuddyPictureGet method.

Settings of the buddy picture can be obtained and modified through the WaveformAnalyzer.GraphicItemBuddyPictureParamsGet and WaveformAnalyzer.GraphicItemBuddyPictureParamsSet methods.

On the screenshot below you can see a set of vertical lines displayed over the waveform, each with its buddy picture aligned on the bottom right of the vertical line:

In this case vertical lines are set to be rendered over time rulers, allowing buddy pictures to be rendered outside of the waveform area.

An existing buddy picture can be removed at a later time by calling this method again and by specifying an empty pathname.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyPictureSetFromFile (

nUniqueId as Int32,

strPathname as String,

settings as WANALYZER_BUDDY_PICTURE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyPictureSetFromFile (

Int32 nUniqueId,

string strPathname,

WANALYZER_BUDDY_PICTURE settings

);

[C++]

public: enumErrorCodes GraphicItemBuddyPictureSetFromFile (

Int32 nUniqueId,

string strPathname,

WANALYZER_BUDDY_PICTURE settings

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

strPathname

Absolute pathname of the picture file.

Supported graphic formats are BMP, ICO, GIF, JPG, TIF and PNG.

An empty string will remove an eventually existing buddy picture.

settings

Settings for the buddy picture.

These settings can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemBuddyPictureParamsSet and WaveformAnalyzer.GraphicItemBuddyPictureParamsGet methods.

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.


WaveformAnalyzer.GraphicItemBuddyPictureSetFromHandle method

WaveformAnalyzer.GraphicItemBuddyPictureSetFromHandle method

Remarks

Sets a picture taken from a HBITMAP that will be displayed as a buddy picture of a graphic item over the waveform's graphics. The HBITMAP of the current buddy picture can be obtained through the WaveformAnalyzer.GraphicItemBuddyPictureGet method.

Settings of the buddy picture can be obtained and modified through the WaveformAnalyzer.GraphicItemBuddyPictureParamsGet and WaveformAnalyzer.GraphicItemBuddyPictureParamsSet methods.

On the screenshot below you can see a set of vertical lines displayed over the waveform, each with its buddy picture aligned on the bottom right of the vertical line:

In this case vertical lines are set to be rendered over time rulers, allowing buddy pictures to be rendered outside of the waveform area.

An existing buddy picture can be removed at a later time by calling this method again with the HBITMAP parameter set to IntPtr.Zero.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyPictureSetFromHandle (

nUniqueId as Int32,

hBitmap as IntPtr,

settings as WANALYZER_BUDDY_PICTURE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyPictureSetFromHandle (

Int32 nUniqueId,

IntPtr hBitmap,

WANALYZER_BUDDY_PICTURE settings

);

[C++]

public: enumErrorCodes GraphicItemBuddyPictureSetFromHandle (

Int32 nUniqueId,

IntPtr hBitmap,

WANALYZER_BUDDY_PICTURE settings

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

hBitmap

HBITMAP of the picture. If this parameter is set to IntPtr.Zero an eventually existing buddy picture will be removed.

settings

Settings for the buddy picture.

These settings can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemBuddyPictureParamsSet and WaveformAnalyzer.GraphicItemBuddyPictureParamsGet methods.

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.


WaveformAnalyzer.GraphicItemBuddyPictureSetFromMemoryStream method

WaveformAnalyzer.GraphicItemBuddyPictureSetFromMemoryStream method

Return to chapter overview

Remarks

Sets a picture taken from a memory stream that will be displayed as a buddy picture of a graphic item over the waveform's graphics. The HBITMAP of the current buddy picture can be obtained through the WaveformAnalyzer.GraphicItemBuddyPictureGet method.

Settings of the buddy picture can be obtained and modified through the WaveformAnalyzer.GraphicItemBuddyPictureParamsGet and WaveformAnalyzer.GraphicItemBuddyPictureParamsSet methods.

This method is not available through COM interoperability.

On the screenshot below you can see a set of vertical lines displayed over the waveform, each with its buddy picture aligned on the bottom right of the vertical line:

In this case vertical lines are set to be rendered over time rulers, allowing buddy pictures to be rendered outside of the waveform area.

An existing buddy picture can be removed at a later time by calling the WaveformAnalyzer.GraphicItemBuddyPictureSetFromFile method with an empty pathname.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyPictureSetFromMemoryStream (

nUniqueId as Int32,

ms as MemoryStream,

settings as WANALYZER_BUDDY_PICTURE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyPictureSetFromMemoryStream (

Int32 nUniqueId,

MemoryStream ms,

WANALYZER_BUDDY_PICTURE settings

);

[C++]

public: enumErrorCodes GraphicItemBuddyPictureSetFromMemory (

Int32 nUniqueId,

MemoryStream ms,

WANALYZER_BUDDY_PICTURE settings

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

ms

Memory stream containing the buddy picture.

Supported graphic formats are BMP, ICO, GIF, JPG, TIF and PNG.

settings

Settings for the buddy picture.

These settings can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemBuddyPictureParamsSet and WaveformAnalyzer.GraphicItemBuddyPictureParamsGet methods.

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.


WaveformAnalyzer.GraphicItemBuddyTextGet method

WaveformAnalyzer.GraphicItemBuddyTextGet method

Remarks

Obtains the buddy text of a graphic item over the waveform's graphics.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyTextGet (

nUniqueId as Int32,

ByRef strText as String,

ByRef fontText as Font

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyTextGet (

Int32 nUniqueId,

ref string strText,

ref Font fontText

);

[C++]

public: enumErrorCodes GraphicItemBuddyTextGet (

Int32 nUniqueId,

string __gc *strText,

Font __gc *fontText

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

strText

Reference that, on return from the method call, will contain the string of the buddy text.

An empty string will remove an eventually existing buddy text.

fontText

Reference that, on return from the method call, will contain the font used for rendering the text.

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.


WaveformAnalyzer.GraphicItemBuddyTextSet method

WaveformAnalyzer.GraphicItemBuddyTextSet method

Remarks

Sets a buddy text of a graphic item over the waveform's graphics. The current buddy text can be obtained through the WaveformAnalyzer.GraphicItemBuddyTextGet method.

Settings of the buddy text can be obtained and modified through the WaveformAnalyzer.GraphicItemBuddyTextParamsGet and WaveformAnalyzer.GraphicItemBuddyTextParamsSet methods.

On the screenshot below you can see a set of vertical lines displayed over the waveform, each with its buddy text aligned on the top right of the vertical line:

An existing buddy text can be removed at a later time by calling this method again and by specifying an empty text string.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyTextSet (

nUniqueId as Int32,

strText as String,

settings as WANALYZER_BUDDY_TEXT,

ByRef fontText as Font

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyTextSet (

Int32 nUniqueId,

string strText,

WANALYZER_BUDDY_TEXT settings,

ref Font fontText

);

[C++]

public: enumErrorCodes GraphicItemBuddyTextSet (

Int32 nUniqueId,

string strText,

WANALYZER_BUDDY_TEXT settings,

Font __gc *fontText

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

strText

String of the buddy text.

An empty string will remove an eventually existing buddy text.

settings

Settings for the buddy text.

These settings can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemBuddyTextParamsSet and WaveformAnalyzer.GraphicItemBuddyTextParamsGet methods.

fontText

Reference to the font used for rendering the text.

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.


WaveformAnalyzer.GraphicItemBuddyTextParamsGet method

WaveformAnalyzer.GraphicItemBuddyTextParamsGet method

Remarks

Modifies parameters of a buddy text associated to a graphic item over the waveform's graphics. Settings for the buddy text can be modified through the WaveformAnalyzer.GraphicItemBuddyTextParamsSet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyTextParamsGet (

nUniqueId as Int32,

ByRef settings as WANALYZER_BUDDY_TEXT

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyTextParamsGet (

Int32 nUniqueId,

ref WANALYZER_BUDDY_TEXT settings

);

[C++]

public: enumErrorCodes GraphicItemBuddyTextParamsGet (

Int32 nUniqueId,

WANALYZER_BUDDY_TEXT __gc *settings

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

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


WaveformAnalyzer.GraphicItemBuddyTextParamsSet method

WaveformAnalyzer.GraphicItemBuddyTextParamsSet method

Remarks

Modifies parameters of a buddy text associated to a graphic item over the waveform's graphics. The current settings for the buddy text can be obtained through the WaveformAnalyzer.GraphicItemBuddyTextParamsGet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemBuddyTextParamsSet (

nUniqueId as Int32,

settings as WANALYZER_BUDDY_TEXT

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemBuddyTextParamsSet (

Int32 nUniqueId,

WANALYZER_BUDDY_TEXT settings

);

[C++]

public: enumErrorCodes GraphicItemBuddyTextParamsSet (

Int32 nUniqueId,

WANALYZER_BUDDY_TEXT settings

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

settings

Settings for the buddy text.

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.


WaveformAnalyzer.GraphicItemDescriptionGet

WaveformAnalyzer.GraphicItemDescriptionGet method

Remarks

Obtains the description of the given graphic item.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemDescriptionGet (

nUniqueId as Int32

) as string

[C#]

public string GraphicItemDescriptionGet (

Int32 nUniqueId

);

[C++]

public: string GraphicItemDescriptionGet (

Int32 nUniqueId

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

Return value

Value | Meaning
Empty string | Information not available or an error occurred (see the LastError property for further error details)
Valid string | The description of the graphic item


WaveformAnalyzer.GraphicItemDescriptionSet method

WaveformAnalyzer.GraphicItemDescriptionSet method

Remarks

Sets the description of the given graphic item.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemDescriptionSet (

nUniqueId as Int16,

strDescription as String

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemDescriptionSet (

Int16 nUniqueId,

string strDescription

);

[C++]

public: enumErrorCodes GraphicItemDescriptionSet (

Int16 nUniqueId,

string strDescription

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

strDescription

String containing the description to assign to the graphic item

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.


WaveformAnalyzer.GraphicItemHorizontalLineAdd method

WaveformAnalyzer.GraphicItemHorizontalLineAdd method

Remarks

Adds a new horizontal line that will be displayed over the waveform's graphics.

On the screenshot below you can see a set of horizontal lines displayed over the waveform, each with its own set of properties, positions and buddy text:

This line can be manually moved on the screen in one of the following ways:

· horizontally through code using the WaveformAnalyzer.GraphicItemHorzPositionSet method
· vertically through code using the WaveformAnalyzer.GraphicItemVertPositionSet method or through the WaveformAnalyzer.GraphicItemHorizontalLineParamsSet method.
· horizontally and vertically through the mouse, causing the CallbackWaveformAnalyzerHorzLineMoved delegate to be invoked.

During playback of the loaded sound, the CallbackWaveformAnalyzerHorzLineReached delegate is invoked when playback position reaches the start position of the horizontal line and the CallbackWaveformAnalyzerHorzLineLeaved delegate is invoked when playback position leaves the end position of the horizontal line.

This method fails if no sound is currently loaded into the editor.

The horizontal line is automatically destroyed, as all of the other existing graphic items, when the loaded sound is discarded from memory through the RecordedSound.FreeMemory method.

A horizontal line can be removed through the WaveformAnalyzer.GraphicItemRemove method and hidden or shown through the WaveformAnalyzer.GraphicItemShow method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemHorizontalLineAdd (

strFriendlyName as String,

strDescription as String,

nStartPosInMs as Int32,

nEndPosInMs as Int32,

settings as WANALYZER_HORIZONTAL_LINE

) as Int16

[C#]

public Int16 GraphicItemHorizontalLineAdd (

string strFriendlyName,

string strDescription,

Int32 nStartPosInMs,

Int32 nEndPosInMs,

WANALYZER_HORIZONTAL_LINE settings

);

[C++]

public: Int16 GraphicItemHorizontalLineAdd (

string strFriendlyName,

string strDescription,

Int32 nStartPosInMs,

Int32 nEndPosInMs,

WANALYZER_HORIZONTAL_LINE settings

);

Parameter | Description
strFriendlyName | Friendly name of the line. This friendly name can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemNameGet and WaveformAnalyzer.GraphicItemNameSet methods.
strDescription | Description of the line. This description can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemDescriptionGet and WaveformAnalyzer.GraphicItemDescriptionSet methods.
nStartPosInMs | Start position expressed in milliseconds This position can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemHorzPositionGet and WaveformAnalyzer.GraphicItemHorzPositionSet methods.
nEndPosInMs | End position expressed in milliseconds This position can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemHorzPositionGet and WaveformAnalyzer.GraphicItemHorzPositionSet methods.
settings | Settings for the new line. These settings can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemHorizontalLineParamsSet and WaveformAnalyzer.GraphicItemHorizontalLineParamsGet methods.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Value > 0 | Unique identification number assigned to this new line.


WaveformAnalyzer.GraphicItemHorizontalLineParamsGet method

WaveformAnalyzer.GraphicItemHorizontalLineParamsGet method

Remarks

Obtains parameters of an existing horizontal line displayed over the waveform's graphics. These parameters can be modified through the WaveformAnalyzer.GraphicItemHorizontalLineParamsSet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemHorizontalLineParamsGet (

nUniqueId as Int16,

ByRef settings as WANALYZER_HORIZONTAL_LINE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemHorizontalLineParamsGet (

Int16 nUniqueId,

ref WANALYZER_HORIZONTAL_LINE settings

);

[C++]

public: enumErrorCodes GraphicItemHorizontalLineParamsGet (

Int16 nUniqueId,

WANALYZER_HORIZONTAL_LINE __gc *settings

);

Parameter | Description
nUniqueId | Unique identification number assigned to the line by a previous call to the WaveformAnalyzer.GraphicItemHorizontalLineAdd 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.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.GraphicItemHorizontalLineParamsSet method

WaveformAnalyzer.GraphicItemHorizontalLineParamsSet method

Remarks

Modifies parameters of an existing horizontal line displayed over the waveform's graphics. Current parameters can be obtained through the WaveformAnalyzer.GraphicItemHorizontalLineParamsGet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemHorizontalLineParamsSet (

nUniqueId as Int16,

settings as WANALYZER_HORIZONTAL_LINE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemHorizontalLineParamsSet (

Int16 nUniqueId,

WANALYZER_HORIZONTAL_LINE settings

);

[C++]

public: enumErrorCodes GraphicItemHorizontalLineParamsSet (

Int16 nUniqueId,

WANALYZER_HORIZONTAL_LINE settings

);

Parameter | Description
nUniqueId | Unique identification number assigned to the line by a previous call to the WaveformAnalyzer.GraphicItemHorizontalLineAdd method.
settings | New 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.


WaveformAnalyzer.GraphicItemNameGet

WaveformAnalyzer.GraphicItemNameGet method

Remarks

Obtains the friendly name of the given graphic item.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemNameGet (

nUniqueId as Int32

) as string

[C#]

public string GraphicItemNameGet (

Int32 nUniqueId

);

[C++]

public: string GraphicItemNameGet (

Int32 nUniqueId

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

Return value

Value | Meaning
Empty string | Information not available or an error occurred (see the LastError property for further error details)
Valid string | The friendly name of the graphic item


WaveformAnalyzer.GraphicItemNameSet method

WaveformAnalyzer.GraphicItemNameSet method

Remarks

Sets the friendly name of the given graphic item.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemNameSet (

nUniqueId as Int16,

strFriendlyName as String

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemNameSet (

Int16 nUniqueId,

string strFriendlyName

);

[C++]

public: enumErrorCodes GraphicItemNameSet (

Int16 nUniqueId,

string strFriendlyName

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

strFriendlyName

String containing the friendly name to assign to the graphic item

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.


WaveformAnalyzer.GraphicItemHorzPositionGet method

WaveformAnalyzer.GraphicItemHorzPositionGet method

Remarks

Obtains the current horizontal position of the given graphic item. The horizontal position can be modified through the WaveformAnalyzer.GraphicItemHorzPositionSet method or through the mouse.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemHorzPositionGet (

nUniqueId as Int16,

ByRef nStartPosInMs as Int32,

ByRef nEndPosInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemHorzPositionGet (

Int16 nUniqueId,

ref Int32 nStartPosInMs,

ref Int32 nEndPosInMs

);

[C++]

public: enumErrorCodes GraphicItemHorzPositionGet (

Int16 nUniqueId,

Int32 __gc *nStartPosInMs,

Int32 __gc *nEndPosInMs

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

nStartPosInMs

Reference that, on return from the method call, will contain the start position of the item expressed in milliseconds

nEndPosInMs

Reference that, on return from the method call, will contain the end position of the item expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.GraphicItemHorzPositionSet method

WaveformAnalyzer.GraphicItemHorzPositionSet method

Remarks

Sets the new horizontal position of the given graphic item. The current horizontal position can be obtained through the WaveformAnalyzer.GraphicItemHorzPositionGet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemHorzPositionSet (

nUniqueId as Int16,

nStartPosInMs as Int32,

nEndPosInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemHorzPositionSet (

Int16 nUniqueId,

Int32 nStartPosInMs,

Int32 nEndPosInMs

);

[C++]

public: enumErrorCodes GraphicItemHorzPositionSet (

Int16 nUniqueId,

Int32 nStartPosInMs,

Int32 nEndPosInMs

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

nStartPosInMs

The new start position of the item expressed in milliseconds.

The call to this method fails if the specified position is less than 0 or higher than the total duration of the sound currently loaded into the editor

nEndPosInMs

The new end position of the item expressed in milliseconds (parameter ignored for vertical lines)

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.


WaveformAnalyzer.GraphicItemRemove method

WaveformAnalyzer.GraphicItemRemove method

Remarks

Removes the given graphic item.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemRemove (

nUniqueId as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemRemove (

Int16 nUniqueId

);

[C++]

public: enumErrorCodes GraphicItemRemove (

Int16 nUniqueId

);

Parameter

Description

nUniqueId

Unique identification number of the graphic item to remove.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

Set this parameter to -1 in order to remove all of the available graphic items.

In order to remove all of the graphic items of a given type, use the WaveformAnalyzer.GraphicItemsTypeRemove 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.


WaveformAnalyzer.GraphicItemShow method

WaveformAnalyzer.GraphicItemShow method

Remarks

Shows/hides the given graphic item.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemShow (

nUniqueId as Int16,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemShow (

Int16 nUniqueId,

bool bShow

);

[C++]

public: enumErrorCodes GraphicItemShow (

Int16 nUniqueId,

bool bShow

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

bShow

Boolean value that specifies if the graphic item must be shown or hidden.

Supported values are the following:

Value | Meaning
false | Hides the graphic item
true | Shows the graphic item

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.


WaveformAnalyzer.GraphicItemTypeGet method

WaveformAnalyzer.GraphicItemTypeGet method

Remarks

Given the unique identification number, obtains the type of graphic item.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemTypeGet (

nUniqueId as Int16,

ByRef nType as enumGraphicItemType

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemTypeGet (

Int16 nUniqueId,

ref enumGraphicItemType nType

);

[C++]

public: enumErrorCodes GraphicItemTypeGet (

Int16 nUniqueId,

enumGraphicItemType __gc *nType

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines
· WaveformAnalyzer.GraphicItemVerticalLineAdd for vertical lines
· WaveformAnalyzer.GraphicItemWaveRangeAdd for wave ranges

nType

Reference that, on return from the method call, will contain the type of graphic item.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical line
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal line
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave range

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.


WaveformAnalyzer.GraphicItemUniqueIdGet method

WaveformAnalyzer.GraphicItemUniqueIdGet method

Remarks

Obtains the unique identification number of a specific graphic item of a given type.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemUniqueIdGet (

nType as enumGraphicItemType,

nIndex as Int16,

ByRef nUniqueId as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemUniqueIdGet (

enumGraphicItemType nType,

Int16 nIndex,

ref Int16 nUniqueId

);

[C++]

public: enumErrorCodes GraphicItemUniqueIdGet (

enumGraphicItemType nType,

Int16 nIndex,

Int16 __gc *nUniqueId

);

Parameter

Description

nType

The type of graphic item.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical lines
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal lines
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave ranges

nIndex

Zero-based index of the graphic item. The total number of available graphic items can be obtained through the WaveformAnalyzer.GraphicItemsTypeCountGet method.

It's important to note that, after eventually removing graphic items through the WaveformAnalyzer.GraphicItemRemove method, you will have to perform a new call to the WaveformAnalyzer.GraphicItemsTypeCountGet in order to have an update enumeration of graphic items and in order to avoid misalignments of the zero-based index.

nUniqueId

Reference that, on return from the method call, will contain the unique identification number of the given graphic item.

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.


WaveformAnalyzer.GraphicItemVerticalLineAdd method

WaveformAnalyzer.GraphicItemVerticalLineAdd method

Remarks

Adds a new vertical line that will be displayed over the waveform's graphics.

On the screenshot below you can see a set of vertical lines displayed over the waveform, each with its own set of properties, positions and buddy text:

This line can be manually moved on the screen in one of the following ways:

· through code using the WaveformAnalyzer.GraphicItemHorzPositionSet method
· through the mouse, causing the CallbackWaveformAnalyzerLineMoved delegate to be invoked.

During playback of the loaded sound, the CallbackWaveformAnalyzerLineReached delegate is invoked when playback position reaches the position of the vertical line.

This method fails if no sound is currently loaded into the editor.

The vertical line is automatically destroyed, as all of the other existing graphic items, when the loaded sound is discarded from memory through the RecordedSound.FreeMemory method.

A vertical line can be removed through the WaveformAnalyzer.GraphicItemRemove method and hidden or shown through the WaveformAnalyzer.GraphicItemShow method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemVerticalLineAdd (

strFriendlyName as String,

strDescription as String,

nPositionInMs as Int32,

settings as WANALYZER_VERTICAL_LINE

) as Int16

[C#]

public Int16 GraphicItemVerticalLineAdd (

string strFriendlyName,

string strDescription,

Int32 nPositionInMs,

WANALYZER_VERTICAL_LINE settings

);

[C++]

public: Int16 GraphicItemVerticalLineAdd (

string strFriendlyName,

string strDescription,

Int32 nPositionInMs,

WANALYZER_VERTICAL_LINE settings

);

Parameter | Description
strFriendlyName | Friendly name of the line. This friendly name can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemNameGet and WaveformAnalyzer.GraphicItemNameSet methods.
strDescription | Description of the line. This description can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemDescriptionGet and WaveformAnalyzer.GraphicItemDescriptionSet methods.
nPositionInMs | Position of the line expressed in milliseconds. This position can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemHorzPositionGet and WaveformAnalyzer.GraphicItemHorzPositionSet methods.
settings | Settings for the new line. These settings can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemVerticalLineParamsGet and WaveformAnalyzer.GraphicItemVerticalLineParamsSet methods.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Value > 0 | Unique identification number assigned to this new line.


WaveformAnalyzer.GraphicItemVerticalLineParamsGet method

WaveformAnalyzer.GraphicItemVerticalLineParamsGet method

Remarks

Obtains parameters of an existing vertical line displayed over the waveform's graphics. These parameters can be modified through the WaveformAnalyzer.GraphicItemVerticalLineParamsSet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemVerticalLineParamsGet (

nUniqueId as Int16,

ByRef settings as WANALYZER_VERTICAL_LINE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemVerticalLineParamsGet (

Int16 nUniqueId,

ref WANALYZER_VERTICAL_LINE settings

);

[C++]

public: enumErrorCodes GraphicItemVerticalLineParamsGet (

Int16 nUniqueId,

WANALYZER_VERTICAL_LINE __gc *settings

);

Parameter | Description
nUniqueId | Unique identification number assigned to the line by a previous call to the WaveformAnalyzer.GraphicItemVerticalLineAdd 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.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.GraphicItemVerticalLineParamsSet method

WaveformAnalyzer.GraphicItemVerticalLineParamsSet method

Remarks

Modifies parameters of an existing vertical line displayed over the waveform's graphics. Current parameters can be obtained through the WaveformAnalyzer.GraphicItemVerticalLineParamsGet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemVerticalLineParamsSet (

nUniqueId as Int16,

settings as WANALYZER_VERTICAL_LINE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemVerticalLineParamsSet (

Int16 nUniqueId,

WANALYZER_VERTICAL_LINE settings

);

[C++]

public: enumErrorCodes GraphicItemVerticalLineParamsSet (

Int16 nUniqueId,

WANALYZER_VERTICAL_LINE settings

);

Parameter | Description
nUniqueId | Unique identification number assigned to the line by a previous call to the WaveformAnalyzer.GraphicItemVerticalLineAdd method.
settings | New 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.


WaveformAnalyzer.GraphicItemVertPositionGet method

WaveformAnalyzer.GraphicItemVertPositionGet method

Remarks

Obtains the current vertical position of the given graphic item. The vertical position can be modified through the WaveformAnalyzer.GraphicItemVertPositionSet method or through the mouse.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemVertPositionGet (

nUniqueId as Int16,

ByRef nPosInPerc as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemVertPositionGet (

Int16 nUniqueId,

ref Int32 nPosInPerc

);

[C++]

public: enumErrorCodes GraphicItemVertPositionGet (

Int16 nUniqueId,

Int32 __gc *nPosInPerc

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines

nPosInPerc

Reference that, on return from the method call, will contain the position of the item expressed in percentage of wave amplitude.

May assume values from -100 to 100: a negative value indicates that the line should be drawn over negative waveform peaks.

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.


WaveformAnalyzer.GraphicItemVertPositionSet method

WaveformAnalyzer.GraphicItemVertPositionSet method

Remarks

Sets the new vertical position of the given graphic item. The current vertical position can be obtained through the WaveformAnalyzer.GraphicItemVertPositionGet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemVertPositionSet (

nUniqueId as Int16,

nPosInPerc as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemVertPositionSet (

Int16 nUniqueId,

Int32 nPosInPerc

);

[C++]

public: enumErrorCodes GraphicItemVertPositionSet (

Int16 nUniqueId,

Int32 nPosInPerc

);

Parameter

Description

nUniqueId

Unique identification number assigned to the graphic item.

The unique identification number of a graphic item is generated using one of the following methods:

· WaveformAnalyzer.GraphicItemHorizontalLineAdd for horizontal lines

nPosInPerc

The new vertical position of the line expressed in percentage of wave amplitude.

May assume values from -100 to 100: a negative value indicates that the line should be drawn over negative waveform peaks.

In case you should be willing the set the line position based upon a logarithmic scale, you could convert your value in dB to a value in percentage using the following formula:

ValueInPerc = 100 * pow (10, ValueInDB/20);

On the screenshot below you can see 3 lines, 2 on positive waveform peaks, respectively at 70% and 25% of the waveform amplitude, and one on negative waveform peaks at -80% of the waveform amplitude.

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.


WaveformAnalyzer.GraphicItemWaveRangeAdd method

WaveformAnalyzer.GraphicItemWaveRangeAdd method

Remarks

Adds a new wave range that will be displayed over the waveform's graphics.

Inside the screenshot below you can see 2 examples of wave ranges, each with its own set of colors. Please note that "wave ranges" are a different concept respect to "waveform selection": you can only have one single "waveform selection", whose positioning can be managed through code or through mouse movement, but you can have multiple "wave ranges" managed through code without any mouse management for changing the positioning.

When the WaveformAnalyzer.ViewModeSet method has been invoked with the nMode parameter set to WANALYZER_VIEW_MODE_SPECTRAL, wave ranges are not fully displayed because their presence would cause a loss of colors of the spectral view so they will be only rendered on the top and of the bottom of the waveform area as senn on the screenshot below:

Wave ranges can be moved through code using the WaveformAnalyzer.GraphicItemHorzPositionSet method.

During playback of the loaded sound, the CallbackWaveformAnalyzerWaveRangeReached delegate is invoked when playback position reaches the start position of the wave range and the CallbackWaveformAnalyzerWaveRangeLeaved delegate is invoked when playback position leaves the end position of the wave range.

This method fails if no sound is currently loaded into the editor

The wave range is automatically destroyed, as all of the other existing graphic items, when the loaded sound is discarded from memory through the the RecordedSound.FreeMemory method.

A wave range can be removed through the WaveformAnalyzer.GraphicItemRemove method and hidden or shown through the WaveformAnalyzer.GraphicItemShow method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemWaveRangeAdd (

strFriendlyName as String,

strDescription as String,

nStartPosInMs as Int32,

nEndPosInMs as Int32,

settings as WANALYZER_WAVE_RANGE

) as Int16

[C#]

public Int16 GraphicItemWaveRangeAdd (

string strFriendlyName,

string strDescription,

Int32 nStartPosInMs,

Int32 nEndPosInMs,

WANALYZER_WAVE_RANGE settings

);

[C++]

public: Int16 GraphicItemWaveRangeAdd (

string strFriendlyName,

string strDescription,

Int32 nStartPosInMs,

Int32 nEndPosInMs,

WANALYZER_WAVE_RANGE settings

);

Parameter | Description
strFriendlyName | Friendly name of the wave range. This friendly name can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemNameGet and WaveformAnalyzer.GraphicItemNameSet methods.
strDescription | Description of the wave range. This description can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemDescriptionGet and WaveformAnalyzer.GraphicItemDescriptionSet methods.
nStartPosInMs | Start position expressed in milliseconds. This position can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemHorzPositionGet and WaveformAnalyzer.GraphicItemHorzPositionSet methods.
nEndPosInMs | End position expressed in milliseconds. This position can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemHorzPositionGet and WaveformAnalyzer.GraphicItemHorzPositionSet methods.
settings | Settings for the new wave range. These settings can be modified or retrieved at a later time through the WaveformAnalyzer.GraphicItemWaveRangeParamsSet and WaveformAnalyzer.GraphicItemWaveRangeParamsGet methods.

Return value

Value | Meaning
0 | An error occurred (see the LastError property for further error details)
Value > 0 | Unique identification number assigned to this new line.


WaveformAnalyzer.GraphicItemWaveRangeParamsGet method

WaveformAnalyzer.GraphicItemWaveRangeParamsGet method

Remarks

Obtains settings of an existing wave range displayed over the waveform's graphics. These settings can be modified through the WaveformAnalyzer.GraphicItemWaveRangeParamsSet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemWaveRangeParamsGet (

nUniqueId as Int16,

ByRef settings as WANALYZER_WAVE_RANGE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemWaveRangeParamsGet (

Int16 nUniqueId,

ref WANALYZER_WAVE_RANGE settings

);

[C++]

public: enumErrorCodes GraphicItemWaveRangeParamsGet (

Int16 nUniqueId,

WANALYZER_WAVE_RANGE __gc *settings

);

Parameter | Description
nUniqueId | Unique identification number assigned to the wave range by a previous call to the WaveformAnalyzer.GraphicItemWaveRangeAdd 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.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.GraphicItemWaveRangeParamsSet method

WaveformAnalyzer.GraphicItemWaveRangeParamsSet method

Remarks

Modifies settings of an existing wave range displayed over the waveform's graphics. The current settings can be retrieved through the WaveformAnalyzer.GraphicItemWaveRangeParamsGet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemWaveRangeParamsSet (

nUniqueId as Int16,

settings as WANALYZER_WAVE_RANGE

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemWaveRangeParamsSet (

Int16 nUniqueId,

WANALYZER_WAVE_RANGE settings

);

[C++]

public: enumErrorCodes GraphicItemWaveRangeParamsSet (

Int16 nUniqueId,

WANALYZER_WAVE_RANGE settings

);

Parameter | Description
nUniqueId | Unique identification number assigned to the wave range by a previous call to the WaveformAnalyzer.GraphicItemWaveRangeAdd method.
settings | New settings for the new wave range.

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.


WaveformAnalyzer.GraphicItemsLoad method

WaveformAnalyzer.GraphicItemsLoad method

Remarks

Loads and adds to the waveform analyzer graphic items contained inside the given XML file. In case the XML file should be contained inside a memory stream, you could use the WaveformAnalyzer.GraphicItemsLoadFromMemory method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemsLoad (

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemsLoad (

string strPathname

);

[C++]

public: enumErrorCodes GraphicItemsLoad (

string strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the source file.

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.


WaveformAnalyzer.GraphicItemsLoadFromMemory method

WaveformAnalyzer.GraphicItemsLoadFromMemory method

Remarks

Loads graphic items from a XML memory stream and add them to the waveform analyzer.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemsLoadFromMemory (

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemsLoadFromMemory (

MemoryStream ms

);

[C++]

public: enumErrorCodes GraphicItemsLoadFromMemory (

MemoryStream ms

);

Parameter | Description
ms | Memory stream containing the graphic items in XML format.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.GraphicItemsMouseMoveEnable method

WaveformAnalyzer.GraphicItemsMouseMoveEnable method

Remarks

Enables/disables the possibility to move graphic items through the mouse.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemsMouseMoveEnable (

nGraphicItemsMask as enumGraphicItemMaskValues,

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemsMouseMoveEnable (

enumGraphicItemMaskValues nGraphicItemsMask,

bool bEnable

);

[C++]

public: enumErrorCodes GraphicItemsMouseMoveEnable (

enumGraphicItemMaskValues nGraphicItemsMask,

bool bEnable

);

Parameter

Description

nGraphicItemsMask

Combination of values determining the mask of graphic items whose movement through mouse we want enable or disable.

Can be a combination of the following values:

Mnemonic value | Value | Meaning
MASK_GRAPHIC_ITEM_VERTICAL_LINES | 1 | The setting is applied to vertical lines
MASK_GRAPHIC_ITEM_HORIZONTAL_LINES | 2 | The setting is applied to horizontal lines

bEnable

Boolean value that specifies if mouse movement of the the graphic item must be enabled or disabled.

Supported values are the following:

Value | Meaning
false | Moving of given graphic items through the mouse is disabled
true (default) | Moving of given graphic items through the mouse is enabled

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.GraphicItemsSave method

WaveformAnalyzer.GraphicItemsSave method

Remarks

Saves into the given XML file all of the graphic items already added to the waveform analyzer.

The XML file is normally saved in ANSI format: in case one or more of the saved strings should contain UNICODE characters, the file would be automatically saved in UTF-8 format.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemsSave (

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemsSave (

string strPathname

);

[C++]

public: enumErrorCodes GraphicItemsSave (

string strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the destination file.

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.


WaveformAnalyzer.GraphicItemsTypeCountGet method

WaveformAnalyzer.GraphicItemsTypeCountGet method

Remarks

Obtains the total number of graphic items of a given type added to the waveform analyzer.

It's important to note that, after eventually removing graphic items through the WaveformAnalyzer.GraphicItemRemove method, you will have to perform a new call to the WaveformAnalyzer.GraphicItemsCountGet in order to have an update enumeration of graphic items and in order to avoid misalignments of the zero-based index when accessing the unique identification number of the graphic item through the WaveformAnalyzer.GraphicItemUniqueIdGet method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemsTypeCountGet (

nType as enumGraphicItemType,

ByRef nCount as Int16

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemsTypeCountGet (

enumGraphicItemType nType,

ref Int16 nCount

);

[C++]

public: enumErrorCodes GraphicItemsTypeCountGet (

enumGraphicItemType nType,

Int16 __gc *nCount

);

Parameter

Description

nType

The type of graphic items.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical lines
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal lines
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave ranges

nCount

Reference that, on return from the method call, will contain the total number of graphic items of the given type

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.


WaveformAnalyzer.GraphicItemsTypeRemove method

WaveformAnalyzer.GraphicItemsTypeRemove method

Remarks

Removes all of the graphic items of a given type. In order to remove all types of graphic items at once, use the WaveformAnalyzer.GraphicItemRemove method with parameter -1.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemsTypeRemove (

nType as enumGraphicItemType

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemsTypeRemove (

enumGraphicItemType nType

);

[C++]

public: enumErrorCodes GraphicItemsTypeRemove (

enumGraphicItemType nType

);

Parameter

Description

nType

The type of graphic items.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical line
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal line
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave range

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.


WaveformAnalyzer.GraphicItemsTypeShow method

WaveformAnalyzer.GraphicItemsTypeShow method

Remarks

Shows/hides all of the graphic items of a given type.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function GraphicItemsTypeShow (

nType as enumGraphicItemType,

bShow as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes GraphicItemsTypeShow (

enumGraphicItemType nType,

bool bShow

);

[C++]

public: enumErrorCodes GraphicItemsTypeShow (

enumGraphicItemType nType,

bool bShow

);

Parameter

Description

nType

The type of graphic items.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
GRAPHIC_ITEM_VERTICAL_LINE | 0 | Vertical line
GRAPHIC_ITEM_HORIZONTAL_LINE | 1 | Horizontal line
GRAPHIC_ITEM_WAVE_RANGE | 2 | Wave range

bShow

Boolean value that specifies if the graphic items of the given type must be shown or hidden.

Supported values are the following:

Value | Meaning
false | Hides the graphic items
true | Shows the graphic items

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.


WaveformAnalyzer.MouseSelectionEnable method

WaveformAnalyzer.MouseSelectionEnable method

Remarks

Enables/disables selecting a waveform's range through the mouse.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function MouseSelectionEnable (

bEnable as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes MouseSelectionEnable (

bool bEnable

);

[C++]

public: enumErrorCodes MouseSelectionEnable (

bool bEnable

);

Parameter

Description

bEnable

Boolean value that specifies if Boolean value that specifies if mouse-based selections are enabled or disabled

Supported values are the following:

Value | Meaning
false | Disable mouse-based selections
true (default) | Enable mouse-based selections

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.


WaveformAnalyzer.Move method

WaveformAnalyzer.Move method

Remarks

Moves or resizes an existing instance of the WaveformAnalyzer.

In case of a resize operation, the CallbackWaveformAnalyzerWidth delegate is invoked.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function Move (

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Move (

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: enumErrorCodes Move (

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
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.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.PeaksBufferGet method

WaveformAnalyzer.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 WaveformAnalyzer.PeaksBufferLengthGet method.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the WaveformAnalyzer.AnalyzeFullSound method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function PeaksBufferGet (

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

Int32 nStartPos,

Int32 nEndPos,

bool bValueInPerc,

Int16[] pBufferMin,

Int16[] pBufferMax,

Int32 nBufferLength

);

[C++]

public: enumErrorCodes PeaksBufferGet (

Int16 nChannel,

Int32 nStartPos,

Int32 nEndPos,

bool bValueInPerc,

Int16 __gc[] pBufferMin,

Int16 __gc[] pBufferMax,

Int32 nBufferLength

);

Parameter

Description

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

 m_recorder.DisplayWaveformAnalyzer.PeaksBufferLengthGet (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

m_recorder.DisplayWaveformAnalyzer.PeaksBufferGet (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;

 m_recorder.DisplayWaveformAnalyzer.PeaksBufferLengthGet (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

 m_recorder.DisplayWaveformAnalyzer.PeaksBufferGet (0, nStartPosInMs, nEndPosInMs, true, m_bufferMin, m_bufferMax, nBufferLength);

}


WaveformAnalyzer.PeaksBufferLengthGet method

WaveformAnalyzer.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 WaveformAnalyzer.PeaksBufferGet method.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the WaveformAnalyzer.AnalyzeFullSound method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function PeaksBufferLengthGet (

nStartPos as Int32,

nEndPos as Int32,

ByRef nBufferLength as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PeaksBufferLengthGet (

Int32 nStartPos,

Int32 nEndPos,

ref Int32 nBufferLength

);

[C++]

public: enumErrorCodes PeaksBufferLengthGet (

Int32 nStartPos,

Int32 nEndPos,

Int32 __gc[] *nBufferLength

);

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


WaveformAnalyzer.PeaksLoad method

WaveformAnalyzer.PeaksLoad method

Remarks

Loads waveform's peaks from a source file previously saved through the WaveformAnalyzer.PeaksSave method.

This method allows a fast retrieval of waveform's peaks without the need to perform a new sound analysis through the WaveformAnalyzer.AnalyzeFullSound method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function PeaksLoad (

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes PeaksLoad (

string strPathname

);

[C++]

public: enumErrorCodes PeaksLoad (

string strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the source file.

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.


WaveformAnalyzer.PeaksSave method

WaveformAnalyzer.PeaksSave method

Remarks

Saves waveform's peaks into a destination file.

This file can be retrieved at a later time through the WaveformAnalyzer.PeaksLoad method, allowing a fast retrieval of waveform's peaks without the need to perform a new sound analysis through the WaveformAnalyzer.AnalyzeFullSound method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function PeaksSave (

strPathname as String

) as enumErrorCodes

[C#]

public enumErrorCodes PeaksSave (

string strPathname

);

[C++]

public: enumErrorCodes PeaksSave (

string strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the destination file.

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.


WaveformAnalyzer.PlaybackLineWidthSet method

WaveformAnalyzer.PlaybackLineWidthSet method

Remarks

Sets the width of the line indicating the playback position on the waveform.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function PlaybackLineWidthSet (

nWidthInPixels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PlaybackLineWidthSet (

Int32 nWidthInPixels

);

[C++]

public: enumErrorCodes PlaybackLineWidthSet (

Int32 nWidthInPixels

);

Parameter | Description
nWidthInPixels | Width of the line expressed in pixels

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.


WaveformAnalyzer.PositionLineWidthSet method

WaveformAnalyzer.PositionLineWidthSet method

Remarks

Sets the width of the line indicating the selected position on the waveform.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function PositionLineWidthSet (

nWidthInPixels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes PositionLineWidthSet (

Int32 nWidthInPixels

);

[C++]

public: enumErrorCodes PositionLineWidthSet (

Int32 nWidthInPixels

);

Parameter | Description
nWidthInPixels | Width of the line expressed in pixels

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.


WaveformAnalyzer.Refresh method

WaveformAnalyzer.Refresh method

Remarks

Refreshes the Waveform Analyzer window.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function Refresh (

) as enumErrorCodes

[C#]

public enumErrorCodes Refresh (

);

[C++]

public: enumErrorCodes Refresh (

);

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.


WaveformAnalyzer.Scroll method

WaveformAnalyzer.Scroll method

Remarks

Scrolls the waveform horizontally of a given amount of pixels.

After a call to this method the CallbackWaveformAnalyzerRange delegate is invoked.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function Scroll (

nPixels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Scroll (

Int32 nPixels

);

[C++]

public: enumErrorCodes Scroll (

Int32 nPixels

);

Parameter

Description

nPixels

Amount of pixels to scroll.

Value | Meaning
Negative value | Scroll the waveform to the left of the given amount of pixels
Positive value | Scroll the waveform to the right of the given amount of pixels

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


WaveformAnalyzer.SetBackPictureFromFile method

WaveformAnalyzer.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromFile (

strPathname as String,

nMode as enumBitmapModes

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromFile (

string strPathname,

enumBitmapModes nMode

);

[C++]

public: enumErrorCodes SetBackPictureFromFile (

string strPathname,

enumBitmapModes nMode

);

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.

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


WaveformAnalyzer.SetBackPictureFromHandle method

WaveformAnalyzer.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SetBackPictureFromHandle (

hBitmap as IntPtr,

nMode as enumBitmapModes

) as enumErrorCodes

[C#]

public enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap,

enumBitmapModes nMode

);

[C++]

public: enumErrorCodes SetBackPictureFromHandle (

IntPtr hBitmap,

enumBitmapModes nMode

);

Parameter

Description

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


WaveformAnalyzer.SetDisplayRange method

WaveformAnalyzer.SetDisplayRange method

Remarks

Changes the waveform range currently displayed on the analyzer window. The current range can be obtained calling the WaveformAnalyzer.GetDisplayRange method.

After a call to this method the CallbackWaveformAnalyzerRange delegate is invoked.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SetDisplayRange (

nBeginPosInMs as Int32,

nEndPosInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetDisplayRange (

Int32 nBeginPosInMs,

Int32 nEndPosInMs

);

[C++]

public: enumErrorCodes SetDisplayRange (

Int32 nBeginPosInMs,

Int32 nEndPosInMs

);

Parameter | Description
nBeginPosInMs | Number representing the displayed range start position, expressed in milliseconds
nEndPosInMs | Number representing the displayed range end position, expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformAnalyzer.SetEmptySettings method

WaveformAnalyzer.SetEmptySettings method

Remarks

Applies settings used to render the waveform analyzer while no sound is loaded and no waveform is displayed.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SetEmptySettings (

nDurationMs as Int32,

nChannels as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetEmptySettings (

Int32 nDurationMs,

Int32 nChannels

);

[C++]

public: enumErrorCodes SetEmptySettings (

Int32 nDurationMs,

Int32 nChannels

);

Parameter

Description

nDurationMs

Number representing the displayed duration expressed in milliseconds.

This value in taken into consideration until the instance of the recorder component is empty or after closing the recorded sound through a call to the RecordedSound.FreeMemory method; if for example this value should be set to 20000 (20 seconds) and a sound file having a duration of 5 seconds should be loaded, the waveform analyzer would display these 5 seconds only.

nChannels

Number representing the number of displayed channels.

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


WaveformAnalyzer.SettingsLoad method

WaveformAnalyzer.SettingsLoad method

Remarks

Loads graphic settings of the waveform analyzer from a XML file previously saved through the WaveformAnalyzer.SettingsSave method.

The XML file contains all settings stored inside the various waveform analyzer data structures: WANALYZER_GENERAL_SETTINGS, WANALYZER_RULERS_SETTINGS, WANALYZER_SCROLLBARS_SETTINGS and WANALYZER_WAVEFORM_SETTINGS.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsLoad (

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsLoad (

string strPathname

);

[C++]

public: enumErrorCodes SettingsLoad (

string strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the source file.

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


WaveformAnalyzer.SettingsLoadFromMemory method

WaveformAnalyzer.SettingsLoadFromMemory method

Remarks

Loads graphic settings of the waveform analyzer from a memory stream containing a XML file previously saved through the WaveformAnalyzer.SettingsSave method.

The XML file contains all settings stored inside the various waveform analyzer data structures: WANALYZER_GENERAL_SETTINGS, WANALYZER_RULERS_SETTINGS, WANALYZER_SCROLLBARS_SETTINGS and WANALYZER_WAVEFORM_SETTINGS.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsLoadFromMemory (

ms as MemoryStream

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsLoadFromMemory (

MemoryStream ms

);

[C++]

public: enumErrorCodes SettingsLoadFromMemory (

MemoryStream ms

);

Parameter | Description
ms | Memory stream containing the waveform analyzer settings in XML format.

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful.


WaveformAnalyzer.SettingsSave method

WaveformAnalyzer.SettingsSave method

Remarks

Saves graphic settings of the waveform analyzer into a XML file. The saved XML file can be retrieved at a later time through the WaveformAnalyzer.SettingsLoad method.

The XML file will contain all settings stored inside the various waveform analyzer data structures: WANALYZER_GENERAL_SETTINGS, WANALYZER_RULERS_SETTINGS, WANALYZER_SCROLLBARS_SETTINGS and WANALYZER_WAVEFORM_SETTINGS.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsSave (

strPathname as string

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsSave (

string strPathname

);

[C++]

public: enumErrorCodes SettingsSave (

string strPathname

);

Parameter | Description
strPathname | String containing the absolute pathname of the destination file.

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


WaveformAnalyzer.SettingsGeneralGet method

WaveformAnalyzer.SettingsGeneralGet method

Remarks

Retrieves the current general settings for the waveform analyzer. Settings can be modified through the WaveformAnalyzer.SettingsGeneralSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsGeneralGet (

ByRef settings as WANALYZER_GENERAL_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsGeneralGet (

ref WANALYZER_GENERAL_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsGeneralGet (

WANALYZER_GENERAL_SETTINGS __gc *settings

);

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


WaveformAnalyzer.SettingsGeneralSet method

WaveformAnalyzer.SettingsGeneralSet method

Remarks

Sets new general settings for the waveform analyzer. Current settings can be obtained through the WaveformAnalyzer.SettingsGeneralGet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsGeneralSet (

settings as WANALYZER_GENERAL_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsGeneralSet (

WANALYZER_GENERAL_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsGeneralSet (

WANALYZER_GENERAL_SETTINGS settings

);

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


WaveformAnalyzer.SettingsRulersGet method

WaveformAnalyzer.SettingsRulersGet method

Remarks

Retrieves the rulers current settings for the waveform analyzer. Settings can be modified through the WaveformAnalyzer.SettingsRulersSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsRulersGet (

ByRef settings as WANALYZER_RULERS_SETTINGS,

ByRef fontText as Font

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsRulersGet (

ref WANALYZER_RULERS_SETTINGS settings,

ref Font fontText

);

[C++]

public: enumErrorCodes SettingsRulersGet (

WANALYZER_RULERS_SETTINGS __gc *settings,

Font __gc *fontText

);

Parameter

Description

settings

Reference that, on return from the method call, will contain the rulers current settings.

fontText

Reference that, on return from the method call, will contain a copy of the font used for rendering the text of ruler's ticks.

In order to avoid leaks of system resource, when the font is no more needed the container application should free it by calling the DeleteObject function of the Windows API.

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.


WaveformAnalyzer.SettingsRulersSet method

WaveformAnalyzer.SettingsRulersSet method

Remarks

Sets rulers new settings for the waveform analyzer. Current settings can be obtained through the WaveformAnalyzer.SettingsRulersGet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsRulersSet (

settings as WANALYZER_RULERS_SETTINGS,

fontText as Font

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsRulersSet (

WANALYZER_RULERS_SETTINGS settings,

Font fontText

);

[C++]

public: enumErrorCodes SettingsRulersSet (

WANALYZER_RULERS_SETTINGS settings,

Font fontText

);

Parameter | Description
settings | The rulers new settings.
fontText | The font that needs to be used for rendering the text of ruler's ticks. The component will make a copy of this font so, when the method's call returns to the caller, you can remove this font from system resources by calling the DeleteObject function of the Windows API.

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.


WaveformAnalyzer.SettingsRulersTimeFormatSet method

WaveformAnalyzer.SettingsRulersTimeFormatSet method

Remarks

Sets the format for displaying strings of time position on time rulers of the waveform analyzer.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsRulersTimeFormatSet (

bShowHour as Boolean,

nNumberOfMsDigits as Int16,

strHourSeparator as String,

strMsSeparator as String,

bRemoveZeroes as Boolean

) as String

[C#]

public string SettingsRulersTimeFormatSet (

bool bShowHour,

Int16 nNumberOfMsDigits,

string strHourSeparator,

string strMsSeparator,

bool bRemoveZeroes

);

[C++]

public: string SettingsRulersTimeFormatSet (

bool bShowHour,

Int16 nNumberOfMsDigits,

string strHourSeparator,

string strMsSeparator,

bool bRemoveZeroes

);

Parameter

Description

bShowHour

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

Supported values are the following:

Mnemonic constant | Value | Meaning
false | 0 | Doesn't show hour value
true (default) | 1 | Shows hour value

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.

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

bRemoveZeroes

Boolean value that specifies to remove zeroes at the beginning and end of the string.

Supported values are the following:

Mnemonic constant | Value | Meaning
false (default) | 0 | Doesn't remove zeroes
true | 1 | Removes zeroes

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.


WaveformAnalyzer.SettingsScrollbarsGet method

WaveformAnalyzer.SettingsScrollbarsGet method

Remarks

Retrieves the scrollbars current settings for the waveform analyzer. Settings can be modified through the WaveformAnalyzer.SettingsScrollbarsSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsScrollbarsGet (

ByRef settings as WANALYZER_SCROLLBARS_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsScrollbarsGet (

ref WANALYZER_SCROLLBARS_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsScrollbarsGet (

WANALYZER_SCROLLBARS_SETTINGS __gc *settings

);

Parameter | Description
settings | Reference that, on return from the method call, will contain the scrollbars current 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.


WaveformAnalyzer.SettingsScrollbarsSet method

WaveformAnalyzer.SettingsScrollbarsSet method

Remarks

Sets scrollbars new settings for the waveform analyzer. Current settings can be obtained through the WaveformAnalyzer.SettingsScrollbarsGet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsScrollbarsSet (

settings as WANALYZER_SCROLLBARS_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsScrollbarsSet (

WANALYZER_SCROLLBARS_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsScrollbarsSet (

WANALYZER_SCROLLBARS_SETTINGS settings

);

Parameter | Description
settings | The new 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.


WaveformAnalyzer.SettingsWaveGet method

WaveformAnalyzer.SettingsWaveGet method

Remarks

Retrieves the current waveform rendering settings for the waveform analyzer. Settings can be modified through the WaveformAnalyzer.SettingsWaveSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsWaveGet (

ByRef settings as WANALYZER_WAVEFORM_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsWaveGet (

ref WANALYZER_WAVEFORM_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsWaveGet (

WANALYZER_WAVEFORM_SETTINGS __gc *settings

);

Parameter | Description
settings | Reference that, on return from the method call, will contain the current waveform rendering 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.


WaveformAnalyzer.SettingsWaveSet method

WaveformAnalyzer.SettingsWaveSet method

Remarks

Sets waveform rendering new settings for the waveform analyzer. Current settings can be obtained through the WaveformAnalyzer.SettingsWaveGet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SettingsWaveSet (

settings as WANALYZER_WAVEFORM_SETTINGS

) as enumErrorCodes

[C#]

public enumErrorCodes SettingsWaveSet (

WANALYZER_WAVEFORM_SETTINGS settings

);

[C++]

public: enumErrorCodes SettingsWaveSet (

WANALYZER_WAVEFORM_SETTINGS settings

);

Parameter | Description
settings | The new 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.


WaveformAnalyzer.SetSelection method

WaveformAnalyzer.SetSelection method

Remarks

Changes the portion of waveform currently selected through the tracker. The current selection, if any, can be retrieved calling the WaveformAnalyzer.GetSelection method.

After a call to this method the CallbackWaveformAnalyzerSelection delegate is invoked.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SetSelection (

bSelectionAvailable as Boolean,

nBeginPosInMs as Int32,

nEndPosInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SetSelection (

bool bSelectionAvailable,

Int32 nBeginPosInMs,

Int32 nEndPosInMs

);

[C++]

public: enumErrorCodes SetSelection (

bool bSelectionAvailable,

Int32 nBeginPosInMs,

Int32 nEndPosInMs

);

Parameter

Description

bSelectionAvailable

Flag for selection availability.

Supported values are the following:

Value | Meaning
false | Remove the current selection, if any. In this case values passed through nBeginPosInMs and nEndPosInMs parameters are ignored.
true | Perform a new selection using values stored inside nBeginPosInMs and nEndPosInMs parameters

nBeginPosInMs

The selection's start position, expressed in milliseconds

nEndPosInMs

The selection's end position, expressed in milliseconds

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful


WaveformAnalyzer.SetTrackerCursors method

WaveformAnalyzer.SetTrackerCursors method

Remarks

Sets the cursors used by the trackers for resizing and panning operations.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SetTrackerCursors (

nCursorMode as enumTrackerCursorModes,

hCursorResize as IntPtr,

hCursorPan as IntPtr

) as enumErrorCodes

[C#]

public enumErrorCodes SetTrackerCursors (

enumTrackerCursorModes nCursorMode,

IntPtr hCursorResize,

IntPtr hCursorPan

);

[C++]

public: enumErrorCodes SetTrackerCursors (

enumTrackerCursorModes nCursorMode,

IntPtr hCursorResize,

IntPtr hCursorPan

);

Parameter

Description

nCursorMode

The cursor mode.

Supported values are the following:

Mnemonic Value | Value | Meaning
TRACKER_CURSOR_MODE_ARROWS (default) | 0 | Arrow based cursors. For resizing operations: For panning operations:
TRACKER_CURSOR_MODE_HANDS | 1 | Hand based cursors. For resizing operations: For panning operations:
TRACKER_CURSOR_MODE_CUSTOM | 2 | Custom cursors defined by the handles passed through the hCursorResize and hCursorPan parameters.

hCursorResize

If the cursor mode is set to TRACKER_CURSOR_MODE_CUSTOM, represents the handle to the cursor used for tracker's resizing operations, otherwise is ignored

hCursorPan

If the cursor mode is set to TRACKER_CURSOR_MODE_CUSTOM, represents the handle to the cursor used for tracker's panning operations, otherwise is ignored

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


WaveformAnalyzer.Show method

WaveformAnalyzer.Show method

Remarks

Shows/hides the Waveform Analyzer window.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class 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 if it must show/hide the Waveform Analyzer window.

Supported values are the following:

Value | Meaning
false | Hides the Waveform Analyzer window
true | Shows the Waveform Analyzer window

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.


WaveformAnalyzer.SnapshotViewDrawToHdc method

WaveformAnalyzer.SnapshotViewDrawToHdc method

Remarks

Creates a graphic file containing the bitmap view of the analysed sound waveform: the view can represent the full sound's waveform or portions of it.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the WaveformAnalyzer.AnalyzeFullSound method.

For details about generating a waveform bitmap of the recorded sound and about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SnapshotViewDrawToHdc (

nMode as enumWaveSnapshotViewMode,

hDC as IntPtr,

nPosLeft as Int32,

nPosTop as Int32,

nWidth as Int32,

nHeight as Int32,

nChannel as enumWaveformChannels,

bShowMaskedGraphicItems as Boolean,

nStartPos as Int32,

nEndPos as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SnapshotViewDrawToHdc (

enumWaveSnapshotViewMode nMode,

IntPtr hDC,

Int32 nPosLeft,

Int32 nPosTop,

Int32 nWidth,

Int32 nHeight,

enumWaveformChannels nChannel

bool bShowMaskedGraphicItems,

Int32 nStartPos,

Int32 nEndPos

);

[C++]

public: enumErrorCodes SnapshotViewDrawToHdc (

enumWaveSnapshotViewMode nMode,

IntPtr hDC,

Int32 nPosLeft,

Int32 nPosTop,

Int32 nWidth,

Int32 nHeight,

enumWaveformChannels nChannel

bool bShowMaskedGraphicItems,

Int32 nStartPos,

Int32 nEndPos

);

Parameter

Description

nMode

Snapshot view mode.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVE_SNAPSHOT_MODE_WAVEFORM | 0 | Snapshot of the waveform
WAVE_SNAPSHOT_MODE_SPECTRAL | 1 | Snapshot of the spectral view

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

nChannel

Audio channel to render.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVEFORM_CHAN_ALL | -2 | The snapshot contains sound data for all channels separated
WAVEFORM_CHAN_MIXED | -1 | The snapshot contains sound data for all channels mixed together
WAVEFORM_CHAN_0 | 0 | The snapshot contains sound data for channel 0 or left channel for stereo
WAVEFORM_CHAN_1 | 1 | The snapshot contains sound data for channel 1 or right channel for stereo
WAVEFORM_CHAN_2 | 2 | The snapshot contains sound data for channel 2
WAVEFORM_CHAN_3 | 3 | The snapshot contains sound data for channel 3
WAVEFORM_CHAN_4 | 4 | The snapshot contains sound data for channel 4
WAVEFORM_CHAN_5 | 5 | The snapshot contains sound data for channel 5
WAVEFORM_CHAN_6 | 6 | The snapshot contains sound data for channel 6
WAVEFORM_CHAN_7 | 7 | The snapshot contains sound data for channel 7

bShowMaskedGraphicItems

Boolean flag that determines if eventual graphic items, enabled/disabled through the WaveformAnalyzer.SnapshotViewGraphicItemsMaskSet method, should be rendered over the waveform.

Supported values are the following:

Mnemonic constant | Meaning
false | Doesn't render graphic items
true | Renders graphic items. See the How to add graphic items to the Waveform analyzer tutorial for details about graphic items management on the waveform analyzer.

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


WaveformAnalyzer.SnapshotViewGetWidthForWaveform method

WaveformAnalyzer.SnapshotViewGetWidthForWaveform method

Remarks

Given a range in milliseconds, calculates the number of pixels required for displaying the waveform's view in horizontal.

The returned value can be assigned to the nBitmapWidth parameter of the WaveformAnalyzer.BitmapViewSaveToFile and WaveformAnalyzer.BitmapViewSaveToMemory methods.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the WaveformAnalyzer.AnalyzeFullSound method.

For details about generating a waveform bitmap of the recorded sound and about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SnapshotViewGetWidthForWaveform (

nStartPos as Int32,

nEndPos as Int32,

ByRef nWidth as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes SnapshotViewGetWidthForWaveform (

Int32 nStartPos,

Int32 nEndPos,

ref Int32 nWidth

);

[C++]

public: enumErrorCodes SnapshotViewGetWidthForWaveform (

Int32 nStartPos,

Int32 nEndPos,

Int32 __gc *nWidth

);

Parameter | Description
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.
nWidth | Reference that, after returning from the method call, will contain the width expressed in pixels

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.


WaveformAnalyzer.SnapshotViewGraphicItemsMaskSet method

WaveformAnalyzer.SnapshotViewGraphicItemsMaskSet method

Remarks

Sets the mask for determining which graphic items will be rendered over the waveform through the WaveformAnalyzer.SnapshotViewDrawToHdc method.

For details about graphic items management on the waveform analyzer refer to the How to add graphic items to the Waveform analyzer section.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SnapshotViewGraphicItemsMaskSet (

nGraphicItemsMask as enumGraphicItemMaskValues

) as enumErrorCodes

[C#]

public enumErrorCodes SnapshotViewGraphicItemsMaskSet (

enumGraphicItemMaskValues nGraphicItemsMask

);

[C++]

public: enumErrorCodes SnapshotViewGraphicItemsMaskSet (

enumGraphicItemMaskValues nGraphicItemsMask

);

Parameter

Description

nGraphicItemsMask

Combination of values determining the mask of graphic items that must be drawn. By default all graphic items are enabled for being drawn.

Supported values are the following:

Mnemonic constant | Value | Meaning
MASK_GRAPHIC_ITEM_NONE | 0 | No graphic item is drawn
MASK_GRAPHIC_ITEM_VERTICAL_LINE | 1 | Draws vertical lines
MASK_GRAPHIC_ITEM_HORIZONTAL_LINE | 2 | Draws horizontal lines
MASK_GRAPHIC_ITEM_WAVE_RANGE | 4 | Draw wave ranges

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.


WaveformAnalyzer.SnapshotViewSaveToFile method

WaveformAnalyzer.SnapshotViewSaveToFile method

Remarks

Creates a graphic file containing a snapshot of the bitmap view of the analysed sound waveform: the view can represent the full sound's waveform or portions of it.

Before calling this method it's mandatory performing a previous sound's analysis through a call to the WaveformAnalyzer.AnalyzeFullSound method.

For details about generating a waveform bitmap of the recorded sound and about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SnapshotViewSaveToFile (

nMode as enumWaveSnapshotViewMode,

nStartPos as Int32,

nEndPos as Int32,

nBitmapWidth as Int32,

nBitmapHeight as Int32,

nChannel as enumWaveformChannels,

strPathname as string,

nFormat as enumGraphicFormats,

nFormatParameter as Long

) as enumErrorCodes

[C#]

public enumErrorCodes SnapshotViewSaveToFile (

enumWaveSnapshotViewMode nMode,

Int32 nStartPos,

Int32 nEndPos,

Int32 nBitmapWidth,

Int32 nBitmapHeight,

enumWaveformChannels nChannel

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

[C++]

public: enumErrorCodes SnapshotViewSaveToFile (

enumWaveSnapshotViewMode nMode,

Int32 nStartPos,

Int32 nEndPos,

Int32 nBitmapWidth,

Int32 nBitmapHeight,

enumWaveformChannels nChannel

string strPathname,

enumGraphicFormats nFormat,

Int32 nFormatParameter

);

Parameter

Description

nMode

Snapshot view mode.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVE_SNAPSHOT_MODE_WAVEFORM | 0 | Snapshot of the waveform
WAVE_SNAPSHOT_MODE_SPECTRAL | 1 | Snapshot of the spectral view
WAVE_SNAPSHOT_MODE_WAVEFORM_ABS | 2 | Snapshot of the waveform with absolute values

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.

nChannel

Audio channel to render.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVEFORM_CHAN_ALL | -2 | The snapshot contains sound data for all channels separated
WAVEFORM_CHAN_MIXED | -1 | The snapshot contains sound data for all channels mixed together
WAVEFORM_CHAN_0 | 0 | The snapshot contains sound data for channel 0 or left channel for stereo
WAVEFORM_CHAN_1 | 1 | The snapshot contains sound data for channel 1 or right channel for stereo
WAVEFORM_CHAN_2 | 2 | The snapshot contains sound data for channel 2
WAVEFORM_CHAN_3 | 3 | The snapshot contains sound data for channel 3
WAVEFORM_CHAN_4 | 4 | The snapshot contains sound data for channel 4
WAVEFORM_CHAN_5 | 5 | The snapshot contains sound data for channel 5
WAVEFORM_CHAN_6 | 6 | The snapshot contains sound data for channel 6
WAVEFORM_CHAN_7 | 7 | The snapshot contains sound data for channel 7

strPathname

String containing the absolute pathname of the file where the waveform will be saved.

nFormat

Graphic format used to save the bitmap.

Supported values are the following:

Mnemonic value | Value | Meaning
GRAPHIC_FORMAT_BMP | 0 | BMP format
GRAPHIC_FORMAT_JPEG | 1 | JPEG format
GRAPHIC_FORMAT_PNG | 2 | PNG format
GRAPHIC_FORMAT_GIF | 3 | GIF format
GRAPHIC_FORMAT_TIFF | 4 | TIFF format

nFormatParameter

Eventual parameters required by the chosen graphic format.

When the nFormat parameter is set to GRAPHIC_FORMAT_JPEG, this parameter defines the JPEG compression factor whose range can be in the range from 0 (Maximum compression, Lower Quality) to 100 (Minimum compression, Higher Quality).

Return value

Value | Meaning
Negative value | An error occurred (see the LastError property for further error details)
enumErrorCodes.ERR_NOERROR (0) | The method call was successful and the waveform's bitmap was saved inside the BMP file indicated by the strPathname parameter.


WaveformAnalyzer.SnapshotViewSaveToMemory method

WaveformAnalyzer.SnapshotViewSaveToMemory method

Remarks

Creates a view (in form of memory bitmap referenced by a HBITMAP) of the waveform for the recorded sound: 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 WaveformAnalyzer.AnalyzeFullSound method.

For details about generating a waveform bitmap of the recorded sound and about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function SnapshotViewSaveToMemory (

nMode as enumWaveSnapshotViewMode,

nStartPos as Int32,

nEndPos as Int32,

nBitmapWidth as Int32,

nBitmapHeight as Int32,

nChannel as enumWaveformChannels

) as IntPtr

[C#]

public IntPtr SnapshotViewSaveToMemory (

enumWaveSnapshotViewMode nMode,

Int32 nStartPos,

Int32 nEndPos,

Int32 nBitmapWidth,

Int32 nBitmapHeight,

enumWaveformChannels nChannel

);

[C++]

public: IntPtr SnapshotViewSaveToMemory (

enumWaveSnapshotViewMode nMode,

Int32 nStartPos,

Int32 nEndPos,

Int32 nBitmapWidth,

Int32 nBitmapHeight,

enumWaveformChannels nChannel

);

Parameter

Description

nMode

Snapshot view mode.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVE_SNAPSHOT_MODE_WAVEFORM | 0 | Snapshot of the waveform
WAVE_SNAPSHOT_MODE_SPECTRAL | 1 | Snapshot of the spectral view
WAVE_SNAPSHOT_MODE_WAVEFORM_ABS | 2 | Snapshot of the waveform with absolute values

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.

nChannel

Audio channel to render.

Supported values are the following:

Mnemonic value | Value | Meaning
WAVEFORM_CHAN_ALL | -2 | The snapshot contains sound data for all channels separated
WAVEFORM_CHAN_MIXED | -1 | The snapshot contains sound data for all channels mixed together
WAVEFORM_CHAN_0 | 0 | The snapshot contains sound data for channel 0 or left channel for stereo
WAVEFORM_CHAN_1 | 1 | The snapshot contains sound data for channel 1 or right channel for stereo
WAVEFORM_CHAN_2 | 2 | The snapshot contains sound data for channel 2
WAVEFORM_CHAN_3 | 3 | The snapshot contains sound data for channel 3
WAVEFORM_CHAN_4 | 4 | The snapshot contains sound data for channel 4
WAVEFORM_CHAN_5 | 5 | The snapshot contains sound data for channel 5
WAVEFORM_CHAN_6 | 6 | The snapshot contains sound data for channel 6
WAVEFORM_CHAN_7 | 7 | The snapshot contains sound data for channel 7

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


WaveformAnalyzer.ViewModeGet method

WaveformAnalyzer.ViewModeGet method

Remarks

Obtains the current visualization mode on the waveform analyzer. The visualization mode can be modified through the WaveformAnalyzer.ViewModeSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function ViewModeGet (

ByRef nMode as enumWaveAnalyzerViewModes

) as enumErrorCodes

[C#]

public enumErrorCodes ViewModeGet (

ref enumWaveAnalyzerViewModes nMode

);

[C++]

public: enumErrorCodes ViewModeGet (

enumWaveAnalyzerViewModes __gc *nMode

);

Parameter

Description

nMode

Reference that, after returning from the method call, will contain the visualization mode.

Supported values are the following:

Mnemonic constant | Value | Meaning
WANALYZER_VIEW_MODE_WAVEFORM | 0 | Waveform view
WANALYZER_VIEW_MODE_SPECTRAL | 1 | Spectral view

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


WaveformAnalyzer.ViewModeSet method

WaveformAnalyzer.ViewModeSet method

Remarks

Sets the visualization mode on the waveform analyzer. The current visualization mode can be obtained through the WaveformAnalyzer.ViewModeGet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function ViewModeSet (

nMode as enumWaveAnalyzerViewModes

) as enumErrorCodes

[C#]

public enumErrorCodes ViewModeSet (

enumWaveAnalyzerViewModes nMode

);

[C++]

public: enumErrorCodes ViewModeSet (

enumWaveAnalyzerViewModes nMode

);

Parameter

Description

nMode

Visualization mode.

Supported values are the following:

Mnemonic constant | Value | Meaning
WANALYZER_VIEW_MODE_WAVEFORM | 0 | Waveform view
WANALYZER_VIEW_MODE_SPECTRAL | 1 | Spectral view
WANALYZER_VIEW_MODE_WAVEFORM_ABS | 2 | Waveform view with absolute values

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


WaveformAnalyzer.ZoomIn method

WaveformAnalyzer.ZoomIn method

Remarks

Zooms in the waveform.

After a call to this method the CallbackWaveformAnalyzerRange delegate is invoked.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function ZoomIn (

) as enumErrorCodes

[C#]

public enumErrorCodes ZoomIn (

);

[C++]

public: enumErrorCodes ZoomIn (

);

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


WaveformAnalyzer.ZoomOut method

WaveformAnalyzer.ZoomOut method

Remarks

Zooms out the waveform.

After a call to this method the CallbackWaveformAnalyzerRange delegate is invoked.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function ZoomOut (

) as enumErrorCodes

[C#]

public enumErrorCodes ZoomOut (

);

[C++]

public: enumErrorCodes ZoomOut (

);

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


WaveformAnalyzer.ZoomToFullSound method

WaveformAnalyzer.ZoomToFullSound method

Remarks

Zooms out and display the whole waveform.

After a call to this method the CallbackWaveformAnalyzerRange delegate is invoked.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function ZoomToFullSound (

) as enumErrorCodes

[C#]

public enumErrorCodes ZoomToFullSound (

);

[C++]

public: enumErrorCodes ZoomToFullSound (

);

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


WaveformAnalyzer.ZoomToSelection method

WaveformAnalyzer.ZoomToSelection method

Remarks

If a waveform's selection is available, zooms its contents.

After a call to this method the CallbackWaveformAnalyzerRange delegate is invoked.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

Syntax

[Visual Basic]

Public Function ZoomToSelection (

bRemoveSelectionAfterZoom as Boolean

) as enumErrorCodes

[C#]

public enumErrorCodes ZoomToSelection (

bool bRemoveSelectionAfterZoom

);

[C++]

public: enumErrorCodes ZoomToSelection (

bool bRemoveSelectionAfterZoom

);

Parameter

Description

bRemoveSelectionAfterZoom

Tells to remove the actual selection, if any, after the zoom operation.

Supported values are the following:

Value | Meaning
false | Leaves the current selection after zooming.
true | Removes the current selection after zooming.

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


WANALYZER_BUDDY_PICTURE structure

WANALYZER_BUDDY_PICTURE structure

The WANALYZER_BUDDY_PICTURE structure (defined as WANALYZER_BUDDY_PICTURE_DLL when used for COM interoperability) describes settings applied to a "buddy" picture assigned to a graphic item, available on the Waveform Analyzer, through one between the WaveformAnalyzer.GraphicItemBuddyPictureSetFromFile,WaveformAnalyzer.GraphicItemBuddyPictureSetFromMemory or WaveformAnalyzer.GraphicItemBuddyPictureSetFromHandle methods. The current settings of the "buddy" picture can be retrieved through the WaveformAnalyzer.GraphicItemBuddyPictureParamsGet method and modified through the WaveformAnalyzer.GraphicItemBuddyPictureParamsSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_BUDDY_PICTURE

{

     public Color colorTransp;

     public Int16 nTranspFactor;

     public enumBuddyAlignment nAlignment;

     public Int32 nResizeWidth;

     public Int32 nResizeHeight;

     public bool bKeepVisible;

}

Definition for COM Interoperability

public struct WANALYZER_BUDDY_PICTURE_DLL

{

     public Int32 colorTransp;

     public Int16 nTranspFactor;

     public Int32 nAlignment;

     public Int32 nResizeWidth;

     public Int32 nResizeHeight;

     public Int16 bKeepVisible;

}

Member

Description

colorTransp

Color of the picture rendered as transparent.

nTranspFactor

Transparent factor. 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.

nAlignment

Alignment respect to the graphic item.

Supported values are the following:

Mnemonic constant | Value | Meaning
BUDDY_ALIGN_LEFT_TOP | 0 | Buddy element is left-top aligned
BUDDY_ALIGN_CENTER_TOP | 1 | Buddy element is center-top aligned
BUDDY_ALIGN_RIGHT_TOP | 2 | Buddy element is right-top aligned
BUDDY_ALIGN_LEFT_MIDDLE | 3 | Buddy element is left-middle aligned
BUDDY_ALIGN_CENTER_MIDDLE | 4 | Buddy element is center-middle aligned
BUDDY_ALIGN_RIGHT_MIDDLE | 5 | Buddy element is right-center aligned
BUDDY_ALIGN_LEFT_BOTTOM | 6 | Buddy element is left-bottom aligned
BUDDY_ALIGN_CENTER_BOTTOM | 7 | Buddy element is center-bottom aligned
BUDDY_ALIGN_RIGHT_BOTTOM | 8 | Buddy element is right-bottom aligned

nResizeWidth

Resize width in pixels (0 use original width).

nResizeHeight

Resize height in pixels (0 use original height).

bKeepVisible

Boolean value that specifies if the picture is kept visible when reaching the limits of the waveform visible range.

Supported values are the following:

Mnemonic constant | Meaning
False | The picture is not kept visible
True | The picture is kept visible


WANALYZER_BUDDY_TEXT structure

WANALYZER_BUDDY_TEXT structure

The WANALYZER_BUDDY_TEXT structure (defined as WANALYZER_BUDDY_TEXT_DLL when used for COM interoperability) describes settings applied to a "buddy" text assigned to a graphic item, available on the Waveform Analyzer, through the WaveformAnalyzer.GraphicItemBuddyTextSet method. The current settings of the "buddy" text can be retrieved through the WaveformAnalyzer.GraphicItemBuddyTextParamsGet method and modified through the WaveformAnalyzer.GraphicItemBuddyTextParamsSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_BUDDY_TEXT

{

     public Color colorText;

     public Color colorTextOutline;

     public Int16 nOutlineWidth;

     public Int16 nTranspFactor;

     public enumBuddyAlignment nAlignment;

     public bool bKeepVisible;

}

Definition for COM Interoperability

public struct WANALYZER_BUDDY_TEXT_DLL

{

     public Int32 colorText;

     public Int32 colorTextOutline;

     public Int16 nOutlineWidth;

     public Int16 nTranspFactor;

     public Int32 nAlignment;

     public Int16 bKeepVisible;

}

Member

Description

colorText

Text color

colorTextOutline

Text outline color. If this color is set to a value identical to the colorText field, no outline is rendered.

nOutlineWidth

Text outline width in pixels. If this field is set to 0, no outline is rendered.

nTranspFactor

Transparent factor. 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.

nAlignment

Alignment respect to the graphic item.

Supported values are the following:

Mnemonic constant | Value | Meaning
BUDDY_ALIGN_LEFT_TOP | 0 | Buddy element is left-top aligned
BUDDY_ALIGN_CENTER_TOP | 1 | Buddy element is center-top aligned
BUDDY_ALIGN_RIGHT_TOP | 2 | Buddy element is right-top aligned
BUDDY_ALIGN_LEFT_MIDDLE | 3 | Buddy element is left-middle aligned
BUDDY_ALIGN_CENTER_MIDDLE | 4 | Buddy element is center-middle aligned
BUDDY_ALIGN_RIGHT_MIDDLE | 5 | Buddy element is right-center aligned
BUDDY_ALIGN_LEFT_BOTTOM | 6 | Buddy element is left-bottom aligned
BUDDY_ALIGN_CENTER_BOTTOM | 7 | Buddy element is center-bottom aligned
BUDDY_ALIGN_RIGHT_BOTTOM | 8 | Buddy element is right-bottom aligned

bKeepVisible

Boolean value that specifies if the buddy text is kept visible when reaching the limits of the waveform visible range.

Supported values are the following:

Mnemonic constant | Meaning
False | The buddy text is not kept visible
True | The buddy text is kept visible


WANALYZER_HORIZONTAL_LINE structure

WANALYZER_HORIZONTAL_LINE structure

The WANALYZER_HORIZONTAL_LINE structure (defined as WANALYZER_HORIZONTAL_LINE_DLL when used for COM interoperability) describes settings applied to a horizontal line added to the Waveform Analyzer through the WaveformAnalyzer.GraphicItemHorizontalLineAdd. The current settings can be retrieved through the WaveformAnalyzer.GraphicItemHorizontalLineParamsGet method and modified through the WaveformAnalyzer.GraphicItemHorizontalLineParamsSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_HORIZONTAL_LINE

{

     public Color color;

     public enumHorizontalLineChannel nChannel;

     public enumWaveformLineDashStyles nDashStyle;

     public Int16 nHeightInPix;

     public Int16 nTranspFactor;

     public Int16 nVertPosInPerc;

     public enumLineCaps nLeftCap;

     public enumLineCaps nRightCap;

     public enumLineDashCaps nDashCap;

}

Definition for COM Interoperability

public struct WANALYZER_HORIZONTAL_LINE_DLL

{

     public Int32 color;

     public Int32 nChannel;

     public Int32 nDashStyle;

     public Int16 nHeightInPix;

     public Int16 nTranspFactor;

     public Int16 nVertPosInPerc;

     public Int32 nLeftCap;

     public Int32 nRightCap;

     public Int32 nDashCap;

}

Member

Description

color

Color used for rendering the line.

nChannel

Audio channel on which the horizontal line is drawn.

Supported values are the following:

Mnemonic constant | Numeric value | Meaning
HORZ_LINE_CHANNEL_ALL | 0 | The horizontal line is drawn on all channels
HORZ_LINE_CHANNEL_LEFT | 1 | The horizontal line is drawn on the left channel only
HORZ_LINE_CHANNEL_RIGHT | 2 | The horizontal line is drawn on the right channel only

nDashStyle

Line dash style.

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.

On the screenshot below you can see the different types of horizontal lines with the corresponding value displayed on the buddy text:

nHeightInPix

Height of the line expressed in pixels.

nTranspFactor

Transparent factor. 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.

nVertPosInPerc

Vertical position of the line expressed in percentage of wave amplitude.

May assume values from -100 to 100: a negative value indicates that the line should be drawn over negative waveform peaks.

In case you should be willing the set the line position based upon a logarithmic scale, you could convert your value in dB to a value in percentage using the following formula:

ValueInPerc = 100 * pow (10, ValueInDB/20);

On the screenshot below you can see 3 horizontal lines, 2 on positive peaks, respectively at 70% and 25% of the waveform amplitude, and one on negative peaks at -80% of the waveform amplitude.

nLeftCap

Type of cap for the left end of the 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.

On the screenshot below you can see the different types of line caps with the corresponding value displayed on the buddy text:

nRightCap

Type of cap for the right end of the line.

Supported values are the same as seen for the nLeftCap field above.

nDashCap

Type of dash/dot cap for the 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.

On the screenshot below you can see the different types of line dash caps with the corresponding value displayed on the buddy text:


WANALYZER_VERTICAL_LINE structure

WANALYZER_VERTICAL_LINE structure

The WANALYZER_VERTICAL_LINE structure (defined as WANALYZER_VERTICAL_LINE_DLL when used for COM interoperability) describes settings applied to a vertical line added to the Waveform Analyzer through the WaveformAnalyzer.GraphicItemVerticalLineAdd method. The current settings can be retrieved through the WaveformAnalyzer.GraphicItemVerticalLineParamsGet method and modified through the WaveformAnalyzer.GraphicItemVerticalLineParamsSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_VERTICAL_LINE

{

     public Color color;

     public enumWaveformLineDashStyles nDashStyle;

     public Int16 nWidth;

     public Int16 nTranspFactor;

     public enumLineCaps nHighCap;

     public enumLineCaps nLowCap;

     public enumLineDashCaps nDashCap;

}

Definition for COM Interoperability

public struct WANALYZER_VERTICAL_LINE_DLL

{

     public Int32 color;

     public Int32 nDashStyle;

     public Int16 nWidth;

     public Int16 nTranspFactor;

     public Int32 nHighCap;

     public Int32 nLowCap;

     public Int32 nDashCap;

}

Member

Description

color

Color used for rendering the line.

nDashStyle

Line dash style.

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.

On the screenshot below you can see the different types of vertical lines with the corresponding value displayed on the buddy text:

nWidth

Line width in pixels.

nTranspFactor

Transparent factor. 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.

nHighCap

Type of cap for the high end of the 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.

On the screenshot below you can see the different types of line caps with the corresponding value displayed on the buddy text:

nLowCap

Type of cap for the low end of the line.

Supported values are the same as seen for the nHighCap field above.

nDashCap

Type of dash/dot cap for the 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.

On the screenshot below you can see the different types of line dash caps with the corresponding value displayed on the buddy text:


WANALYZER_WAVE_RANGE structure

WANALYZER_WAVE_RANGE structure

The WANALYZER_WAVE_RANGE structure (defined as WANALYZER_WAVE_RANGE_DLL when used for COM interoperability) describes settings applied to a waveform range added to the Waveform Analyzer through the WaveformAnalyzer.GraphicItemWaveRangeAdd method. The current settings can be retrieved through the WaveformAnalyzer.GraphicItemWaveRangeParamsGet method and modified through the WaveformAnalyzer.GraphicItemWaveRangeParamsSet t method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_WAVE_RANGE

{

     public Color colorBack;

     public Color colorWaveLinePeak;

     public Color colorWaveLineCenter;

}

Definition for COM Interoperability

public struct WANALYZER_WAVE_RANGE_DLL

{

     public Int32 colorBack;

     public Int32 colorWaveLinePeak;

     public Int32 colorWaveLineCenter;

}

Inside the screenshot below you can see 2 examples of wave ranges, each with its own set of colors. Please note that "wave ranges" are a different concept respect to "waveform selection": you can only have one single "waveform selection", whose positioning can be managed through code or through mouse movement, but you can have multiple "wave ranges" managed through code without any mouse management for changing the positioning.

Member | Description
colorBack | Color used for rendering the waveform background.
colorWaveLinePeak | Color used for rendering the peak of the waveform line
colorWaveLineCenter | Color used for rendering the center of the waveform line

NOTE: If values of the colorWaveLineCenter e colorWaveLinePeak fields should be identical, the rendering would keep count of the bUseHalfColorsForPeaks field of the WANALYZER_WAVEFORM_SETTINGS data structure.


WANALYZER_GENERAL_SETTINGS structure

WANALYZER_GENERAL_SETTINGS structure

The WANALYZER_GENERAL_SETTINGS structure (defined as WANALYZER_GENERAL_SETTINGS_DLL when used for COM interoperability) describes the general settings applied to the Waveform Analyzer. The current settings can be retrieved through the WaveformAnalyzer.SettingsGeneralGet method and modified through the WaveformAnalyzer.SettingsGeneralSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_GENERAL_SETTINGS

{

     public bool bAppearance3d;

     public enumAnalyzerResolutions nResolution;

     public float fHorizontalZoomFactor;

     public float fVerticalZoomFactor;

     public Int16 nPositionLineWidth;

     public enumWaveformLineDashStyles nPositionLineDashStyle;

     public Color colorPositionLine;

     public bool bPlaybackLineVisible;

     public Int16 nPlaybackLineWidth;

     public enumWaveformLineDashStyles nPlaybackLineDashStyle;

     public Color colorPlaybackLine;

     public enumLineCaps nPositionLineHighCap;

     public enumLineCaps nPositionLineLowCap;

     public enumLineDashCaps nPositionLineDashCap;

     public Int16 nPositionLineTranspFactor;

     public enumLineCaps nPlaybackLineHighCap;

     public enumLineCaps nPlaybackLineLowCap;

     public enumLineDashCaps nPlaybackLineDashCap;

     public Int16 nPlaybackLineTranspFactor;

     public bool bVerticalLinesOnTimeRuler;

     public bool bAutoRefresh;

}

Definition for COM Interoperability

public struct WANALYZER_GENERAL_SETTINGS_DLL

{

     public Int16 bAppearance3d;

     public Int32 nResolution;

     public float fHorizontalZoomFactor;

     public float fVerticalZoomFactor;

     public Int16 nPositionLineWidth;

     public Int32 nPositionLineDashStyle;

     public Int32 colorPositionLine;

     public Int16 bPlaybackLineVisible;

     public Int16 nPlaybackLineWidth;

     public Int32 nPlaybackLineDashStyle;

     public Int32 colorPlaybackLine;

     public Int32 nPositionLineHighCap;

     public Int32 nPositionLineLowCap;

     public Int32 nPositionLineDashCap;

     public Int16 nPositionLineTranspFactor;

     public Int32 nPlaybackLineHighCap;

     public Int32 nPlaybackLineLowCap;

     public Int32 nPlaybackLineDashCap;

     public Int16 nPlaybackLineTranspFactor;

     public Int16 bVerticalLinesOnTimeRuler;

     public Int16 bAutoRefresh;

}

Member

Description

bAppearance3d

Boolean value that specifies if the Waveform Analyzer is displayed with 3D borders.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display 3D borders
True | Displays 3D borders

nResolution

Resolution used for waveform's analysis.

Supported values are the following:

Mnemonic constant | Value | Meaning
WAVEANALYZER_RES_MINIMUM | 100 | Minimum resolution, faster calculation time. Each line on the analyzer is the average for 256 PCM samples.
WAVEANALYZER_RES_VERY_LOW | 101 | Very low resolution. Each line on the analyzer is the average for 128 PCM samples.
WAVEANALYZER_RES_LOW | 102 | Low resolution. Each line on the analyzer is the average for 64 PCM samples.
WAVEANALYZER_RES_MIDDLE | 103 | Middle resolution. Each line on the analyzer is the average for 32 PCM samples.
WAVEANALYZER_RES_HIGH | 104 | High resolution. Each line on the analyzer is the average for 16 PCM samples.
WAVEANALYZER_RES_VERY_HIGH | 105 | Very high resolution. Each line on the analyzer is the average for 8 PCM samples.
WAVEANALYZER_RES_MAXIMUM | 106 | Maximum resolution, slower calculation time. Each line on the analyzer is the average for 4 PCM samples.

fHorizontalZoomFactor

Floating point value indicating the factor applied to zooming operations: by default the zoom factor is 2.0.

The value of this field cannot be lower than 1.01. Smaller values will be automatically capped to 1.01.

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.

- Values smaller than 1 will vertically zoom-out the waveform, reducing its vertical size

- Value 1 will display the waveform without zooming (default)

- Values higher than 1 will vertically zoom-in the waveform, increasing its vertical size

nPositionLineWidth

Width in pixels of the line that indicates a selected position on the waveform

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.

On the screenshot below you can see the different dash styles with the corresponding value displayed:

colorPositionLine

Color used for rendering the line that indicates a selected position on the waveform.

bPlaybackLineVisible

Boolean value that specifies if the line that indicates the playback position is visible during a playback session.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display the position line during playback
True | Displays the position line during playback

nPlaybackLineWidth

Width in pixels of the playback line

nPlaybackLineDashStyle

Dash style of the line that indicates the playback position on the waveform during a playback session.

Supported values are the same as seen for the nPositionLineDashStyle field above.

colorPlaybackLine

Color used for rendering the line that indicates the playback position on the waveform during a playback session.

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.

On the screenshot below you can see the different types of line caps with the corresponding value displayed:

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.

On the screenshot below you can see the different types of line dash caps with the corresponding value displayed:

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.

nPlaybackLineHighCap

Type of cap for the high end of the playback line.

Supported values are the same as seen for the nPositionLineHighCap field above.

nPlaybackLineLowCap

Type of cap for the low end of the playback line.

Supported values are the same as seen for the nPositionLineHighCap field above.

nPlaybackLineDashCap

Type of dash/dot cap for the playback line.

Supported values are the same as seen for the nPositionLineDashCap field above.

nPlaybackLineTranspFactor

Transparent factor applied to the playback 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.

bVerticalLinesOnTimeRuler

Boolean value that specifies if caps of vertical lines must be rendered over time rulers.

Supported values are the following:

Mnemonic constant | Meaning
False (default) | Caps of vertical lines must be rendered over time rulers.
True | Caps of vertical lines must be rendered over the waveform are without exceeding over time rulers..

bAutoRefresh

Boolean value that specifies if the waveform is refreshed automatically during the analysis phase.

Supported values are the following:

Mnemonic constant | Meaning
False (default) | Auto-refresh is disabled.
True | Auto-refresh is enabled. This setting doesn't apply when the WaveformAnalyzer.ViewModeSet method has been invoked with the nMode parameter set to WANALYZER_VIEW_MODE_SPECTRAL.


WANALYZER_RULERS_SETTINGS structure

WANALYZER_RULERS_SETTINGS structure

The WANALYZER_RULERS_SETTINGS structure (defined as WANALYZER_RULERS_SETTINGS_DLL when used for COM interoperability) describes settings applied while rendering the time and amplitude rulers on the Waveform Analyzer. The current settings can be retrieved through the WaveformAnalyzer.SettingsRulersGet method and modified through the WaveformAnalyzer.SettingsRulersSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_RULERS_SETTINGS

{

     public enumVolumeScales nAmplitudeScale;

     public bool bVisibleLeft;

     public bool bTicksLeft;

     public bool bVisibleRight;

     public bool bTicksRight;

     public bool bVisibleTop;

     public bool bTicksTop;

     public bool bVisibleBottom;

     public bool bTicksBottom;

     public Color colorBackground;

     public Color colorTicks;

     public Color colorText;

     public Int16 nTopRulerHeightInPix;

     public Int16 nBottomRulerHeightInPix;

     public Int16 nVertRulerWidthInPix;

     public float fTimeTicksFrequencyInPix;

}

Definition for COM Interoperability

public struct WANALYZER_RULERS_SETTINGS_DLL

{

     public Int32 nAmplitudeScale;

     public Int16 bVisibleLeft;

     public Int16 bTicksLeft;

     public Int16 bVisibleRight;

     public Int16 bTicksRight;

     public Int16 bVisibleTop;

     public Int16 bTicksTop;

     public Int16 bVisibleBottom;

     public Int16 bTicksBottom;

     public Int32 colorBackground;

     public Int32 colorTicks;

     public Int32 colorText;

     public Int16 nTopRulerHeightInPix;

     public Int16 nBottomRulerHeightInPix;

     public Int16 nVertRulerWidthInPix;

     public float fTimeTicksFrequencyInPix;

}

Member

Description

nAmplitudeScale

Scale used for vertical rulers indicating waveform amplitude.

Supported values are the following:

Mnemonic constant | Value | Meaning
SCALE_LINEAR (default) | 0 | Linear mode
SCALE_LOG | 1 | Logarithmic mode

bVisibleLeft

Boolean value that specifies if the left amplitude ruler is visible.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display left amplitude ruler
True (default) | Displays left amplitude ruler

bTicksLeft

Boolean value that specifies if the left amplitude ruler has ticks.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display ticks for the left amplitude ruler
True (default) | Displays ticks for the left amplitude ruler

bVisibleRight

Boolean value that specifies if the right amplitude ruler is visible.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display right amplitude ruler
True (default) | Displays right amplitude ruler

bTicksRight

Boolean value that specifies if the right amplitude ruler has ticks.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display ticks for the right amplitude ruler
True (default) | Displays ticks for the right amplitude ruler

bVisibleTop

Boolean value that specifies if the top time ruler is visible.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display top time ruler
True (default) | Displays top time ruler

bTicksTop

Boolean value that specifies if the top time ruler has ticks.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display ticks for the top time ruler
True (default) | Displays ticks for the top time ruler

bVisibleBottom

Boolean value that specifies if the bottom time ruler is visible.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display bottom time ruler
True (default) | Displays bottom time ruler

bTicksBottom

Boolean value that specifies if the bottom time ruler has ticks.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display ticks for the bottom time ruler
True (default) | Displays ticks for the bottom time ruler

colorBackground

Color used for rendering the rulers background.

colorTicks

Color used for rendering rulers ticks.

colorText

Color used for rendering rulers texts.

nTopRulerHeightInPix

Height of the top time ruler in pixels.

The default value is 16 pixels.

nBottomRulerHeightInPix

Height of the bottom time ruler in pixels.

The default value is 16 pixels.

nVertRulerWidthInPix

Width of vertical amplitude rulers in pixels.

The default value is 41 pixels.

fTimeTicksFrequencyInPix

Frequency of the time ticks in pixels.

The default value is 40 pixels.


WANALYZER_SCROLLBARS_SETTINGS structure

WANALYZER_SCROLLBARS_SETTINGS structure

The WANALYZER_SCROLLBARS_SETTINGS structure (defined as WANALYZER_SCROLLBARS_SETTINGS_DLL when used for COM interoperability) describes settings applied while rendering the scrollbars on the Waveform Analyzer. The current settings can be retrieved through the WaveformAnalyzer.SettingsScrollbarsGet method and modified through the WaveformAnalyzer.SettingsScrollbarsSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_SCROLLBARS_SETTINGS

{

     public Int16 nHeightInPixels;

     public enumWaveScrollbarType nType;

     public enumGraphicItemMaskValues nGraphicItemsMask;

     public bool bVisibleTop;

     public bool bVisibleBottom;

     public Color colorBackground;

     public Color colorThumb;

     public Color colorVisibleRange;

     public enumScrollbarWaveVisibleRangeType nVisibleRangeType;

     public Int16 nVisibleRangeTranspGlassFactor;

     public Int16 nVisibleRangeLinesWidth;

     public bool bEnabledDuringPlayback;

     public enumTranspGlassType nTransparentGlassType;

     public Int16 nTransparentGlassPos3D;

     public bool bTransparentGlassInvert3D;

}

Definition for COM Interoperability

public struct WANALYZER_SCROLLBARS_SETTINGS_DLL

{

     public Int16 nHeightInPixels;

     public Int32 nType;

     public Int32 nGraphicItemsMask;

     public Int16 bVisibleTop;

     public Int16 bVisibleBottom;

     public Int32 colorBackground;

     public Int32 colorThumb;

     public Int32 colorVisibleRange;

     public Int32 nVisibleRangeType;

     public Int16 nVisibleRangeTranspGlassFactor;

     public Int16 nVisibleRangeLinesWidth;

     public Int16 bEnabledDuringPlayback;

     public Int32 nTransparentGlassType;

     public Int16 nTransparentGlassPos3D;

     public Int16 bTransparentGlassInvert3D;

}

Member

Description

nHeightInPixels

Height of the scrollbars in pixels.

By default this value is set to 12.

If the nType field below is set to WSCROLLBAR_TYPE_RECT, this field cannot be set to a value smaller than 6.

If the nType field below is set to WSCROLLBAR_TYPE_WAVEFORM, this field cannot be set to a value smaller than 12.

Eventual smaller values will be automatically capped to the nearest valid value.

nType

Determines how the scrollbar is visualized.

Supported values are the following:

Mnemonic constant | Value | Meaning
WSCROLLBAR_TYPE_RECT (default) | 0 | Scrollbars are rendered as a 3D rectangle
WSCROLLBAR_TYPE_WAVEFORM | 1 | Scrollbars display a small sized representation of the full waveform
WSCROLLBAR_TYPE_WAVEFORM_ABS | 2 | Scrollbars display a small sized representation of the full waveform with absolute values.

On the screenshots below you can see that two different types of scrollbar; in all cases you can resize the visible range by dragging the provided handles with the left mouse button:

nGraphicItemsMask

Combination of values determining the mask of graphic items that must be drawn on the waveform scrollbar.

By default this

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
MASK_GRAPHIC_ITEM_HORIZONTAL_LINE | 2 | Draws horizontal lines
MASK_GRAPHIC_ITEM_WAVE_RANGE | 4 | Draw wave ranges

bVisibleTop

Boolean value that specifies if the top scrollbar is visible.

Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display top scrollbar
True (default) | Displays top scrollbar

bVisibleBottom

Boolean value that specifies if the bottom scrollbar is visible.Supported values are the following:

Mnemonic constant | Meaning
False | Doesn't display bottom scrollbar
True (default) | Displays bottom scrollbar

colorBackground

Color used for rendering the scrollbars background.

colorThumb

Color used for rendering the scrollbars thumb.

colorVisibleRange

Color used for rendering inside the scrollbars the waveform background for visible range.

This setting is ignored when the nType field above is set to a value different from WSCROLLBAR_TYPE_WAVEFORM.

nVisibleRangeType

Determines how the visible range of the waveform is displayed.

This setting is ignored when the nType field above is set to a value different from WSCROLLBAR_TYPE_WAVEFORM

Supported values are the following:

Mnemonic constant | Value | Meaning
SCROLL_WAVE_VISIBLE_LINES (default) | 0 | Displays two lines on top and bottom
SCROLL_WAVE_VISIBLE_LINE_TOP | 1 | Displays one line on top
SCROLL_WAVE_VISIBLE_LINE_BOTTOM | 2 | Displays one line on bottom
SCROLL_WAVE_VISIBLE_TRANSP_GLASS_INNER | 3 | Displays a transparent glass over the portion of waveform representing the visible range
SCROLL_WAVE_VISIBLE_TRANSP_GLASS_OUTER | 4 | Displays a transparent glass over portions of waveform representing ranges of the waveform outside of the visible area.

nVisibleRangeTranspGlassFactor

Transparent factor applied to the transparent glass.

This value can range from 0 (total opacity) to 255 (total transparency) with a default value of 128. Values outside of this range will be automatically capped to the nearest valid value.

This setting is ignored when the nType field above is set to a value different from WSCROLLBAR_TYPE_WAVEFORM.

This setting is ignored when the nVisibleRangeType field above is set to a value different from SCROLL_WAVE_VISIBLE_TRANSP_GLASS_INNER or SCROLL_WAVE_VISIBLE_TRANSP_GLASS_OUTER.

nVisibleRangeLinesWidth

Width of lines in pixels.

Cannot assume values smaller than 1. The default value is 2.

This setting is ignored when the nType field above is set to a value different from WSCROLLBAR_TYPE_WAVEFORM.

This setting is ignored when the nVisibleRangeType field above is set to SCROLL_WAVE_VISIBLE_TRANSP_GLASS_INNER or SCROLL_WAVE_VISIBLE_TRANSP_GLASS_OUTER.

bEnabledDuringPlayback

Boolean value that specifies if scrollbars are enabled during playback.

Supported values are the following:

Mnemonic constant | Meaning
False (default) | Scrollbars are disabled during playback
True | Scrollbars are enabled during playback

nTransparentGlassType

Type of transparent glass.

Supported values are the following:

Mnemonic constant | Value | Meaning
TRANSP_GLASS_TYPE_FLAT | 0 | Flat glass.
TRANSP_GLASS_TYPE_3D_VERT (default) | 1 | 3D vertical glass.
TRANSP_GLASS_TYPE_3D_HORZ | 2 | 3D horizontal glass.

This setting is ignored when the nType field above is set to a value different from WSCROLLBAR_TYPE_WAVEFORM.

This setting is ignored when the nVisibleRangeType field above is set to a value different from SCROLL_WAVE_VISIBLE_TRANSP_GLASS_INNER or SCROLL_WAVE_VISIBLE_TRANSP_GLASS_OUTER.

nTransparentGlassPos3D

Position of the 3D effect for the transparent glass.

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.

This setting is ignored when the nType field above is set to a value different from WSCROLLBAR_TYPE_WAVEFORM.

This setting is ignored when the nVisibleRangeType field above is set to a value different from SCROLL_WAVE_VISIBLE_TRANSP_GLASS_INNER or SCROLL_WAVE_VISIBLE_TRANSP_GLASS_OUTER.

nTransparentGlassInvert3D

Boolean value that specifies if the transparency of the 3D effect is inverted.

Supported values are the following:

Mnemonic constant | Meaning
False (default) | Doesn't invert 3D effect
True | Inverts 3D effect

This setting is ignored when the nType field above is set to a value different from WSCROLLBAR_TYPE_WAVEFORM.

This setting is ignored when the nVisibleRangeType field above is set to a value different from SCROLL_WAVE_VISIBLE_TRANSP_GLASS_INNER or SCROLL_WAVE_VISIBLE_TRANSP_GLASS_OUTER.


WANALYZER_WAVEFORM_SETTINGS structure

WANALYZER_WAVEFORM_SETTINGS structure

The WANALYZER_WAVEFORM_SETTINGS structure (defined as WANALYZER_WAVEFORM_SETTINGS_DLL when used for COM interoperability) describes settings applied while rendering the waveform on the Waveform Analyzer. The current settings can be retrieved through the WaveformAnalyzer.SettingsWaveGet method and modified through the WaveformAnalyzer.SettingsWaveSet method.

For details about the use of the Waveform Analyzer refer to the How to use the Waveform Analyzer section.

For further details about methods of the Waveform Analyzer refer to the WaveformAnalyzer class section.

C# definition

public struct WANALYZER_WAVEFORM_SETTINGS

{

     public enumWaveformStereoModes nStereoVisualizationMode;

     public Color colorWaveLinePeak;

     public Color colorWaveLineCenter;

     public Int16 nWaveLineIntensityFactor;

     public Color colorWaveBackground;

     public bool bUseHalfColorsForPeaks;

     public enumWaveformSelectionMode nSelectionMode;

     public Color colorWaveLineSelPeak;

     public Color colorWaveLineSelCenter;

     public Color colorWaveSelBackground;

     public Color colorTransparentGlass;

     public Int16 nTransparentGlassFactor;

     public Color colorVolumeLevelLine;

     public Color colorTimeLine;

     public enumTranspGlassType nTransparentGlassType;

     public Int16 nTransparentGlassPos3D;

     public bool bTransparentGlassInvert3D;

     public bool bDrawLinesOverWave;

}

Definition for COM Interoperability

public struct WANALYZER_WAVEFORM_SETTINGS_DLL

{

     public Int32 nStereoVisualizationMode;

     public Int32 colorWaveLinePeak;

     public Int32 colorWaveLineCenter;

     public Int16 nWaveLineIntensityFactor;

     public Int32 colorWaveBackground;

     public Int16 bUseHalfColorsForPeaks;

     public Int32 nSelectionMode;

     public Int32 colorWaveLineSelPeak;

     public Int32 colorWaveLineSelCenter;

     public Int32 colorWaveSelBackground;

     public Int32 colorTransparentGlass;

     public Int16 nTransparentGlassFactor;

     public Int32 colorVolumeLevelLine;

     public Int32 colorTimeLine;

     public Int32 nTransparentGlassType;

     public Int16 nTransparentGlassPos3D;

     public Int16 bTransparentGlassInvert3D;

     public Int16 bDrawLinesOverWave;

}

On the screenshot A below you can see the various involved colors: the portion with blue background represents a selection:

Screenshot A

On the screenshot B below you can see the default colors with a selection rendered as a transparent glass.:

Screenshot B

Member

Description

nStereoVisualizationMode

Visualization mode used for displaying stereo sounds

Supported values are the following:

Mnemonic constant | Value | Meaning
STEREO_MODE_CHANNELS_BOTH (default) | 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

colorWaveLinePeak

Color used for rendering peaks of the waveform line. See screenshot A above.

colorWaveLineCenter

Color used for rendering the center of the waveform line. See screenshot A 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

Color used for rendering the waveform background. See screenshot A 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:

Mnemonic constant | Meaning
False | Doesn't use half color for peaks
True (default) | Uses half color for peaks

nSelectionMode

Specifies how waveform selection is rendered. See screenshots A and B above.

Supported values are the following:

Mnemonic constant | Value | Meaning
WAVE_SEL_INVERT_COLORS (default) | 0 | Render selection by inverting waveform colors.
WAVE_SEL_TRANSPARENT_GLASS | 1 | Render selection simulating a transparent glass. See screenshot B above.
WAVE_SEL_CUSTOM_COLORS | 2 | Render selection by using custom colors. See screenshot A above.

colorWaveLineSelPeak

Color used for rendering gradient of peaks of the waveform line when selected. See screenshot A above.

This setting is ignored when the nSelectionMode field above is set to a value different from WAVE_SEL_CUSTOM_COLORS.

colorWaveLineSelCenter

Color used for rendering gradient of center of the waveform line when selected. See screenshot A above.

This setting is ignored when the nSelectionMode field above is set to a value different from WAVE_SEL_CUSTOM_COLORS.

colorWaveSelBackground

Color used for rendering the waveform background when selected. See screenshot A above.

This setting is ignored when the nSelectionMode field above is set to a value different from WAVE_SEL_CUSTOM_COLORS.

colorTransparentGlass

Color used for rendering the transparent glass selection. See screenshot B above.

This setting is ignored when the nSelectionMode field above is set to a value different from WAVE_SEL_TRANSPARENT_GLASS.

nTransparentGlassFactor

Transparent factor for rendering the transparent glass selection.

This value can range from 0 (total opacity) to 255 (total transparency) with a default value of 128. Values outside of this range will be automatically capped to the nearest valid value.

This setting is ignored when the nSelectionMode field above is set to a value different from WAVE_SEL_TRANSPARENT_GLASS.

colorVolumeLevelLine

Color used for rendering horizontal lines related to the volume level. See screenshot A above.

You can set this field to -1 in order to hide volume level lines.

colorTimeLine

Color used for rendering vertical lines related to time. See screenshot A above.

You can set this field to -1 in order to hide time lines.

nTransparentGlassType

Type of transparent glass.

Supported values are the following:

Mnemonic constant | Value | Meaning
TRANSP_GLASS_TYPE_FLAT | 0 | Flat glass.
TRANSP_GLASS_TYPE_3D_VERT (default) | 1 | 3D vertical glass.
TRANSP_GLASS_TYPE_3D_HORZ | 2 | 3D horizontal glass.

This setting is ignored when the nSelectionMode field above is set to a value different from WAVE_SEL_TRANSPARENT_GLASS.

On the screenshot below you can appreciate the difference between the available settings:

nTransparentGlassPos3D

Position of the 3D effect for the transparent glass.

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.

This setting is ignored when the nSelectionMode field above is set to a value different from WAVE_SEL_TRANSPARENT_GLASS.

bTransparentGlassInvert3D

Boolean value that specifies if the transparency of the 3D effect is inverted.

Supported values are the following:

Mnemonic constant | Meaning
False (default) | Doesn't invert 3D effect
True | Inverts 3D effect

This setting is ignored when the nSelectionMode field above is set to a value different from WAVE_SEL_TRANSPARENT_GLASS.

On the screenshot below you can appreciate the difference between the available settings (inverted 3D effect on the left):

bDrawLinesOverWave

Boolean value that specifies if time and volume lines must be drawn over the waveform.

Supported values are the following:

Mnemonic constant | Meaning
False (default) | Time and volume lines are drawn under the waveform.
True | Time and volume lines are drawn over the waveform.


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

Refresh

SetBackPictureFromFile

SetBackPictureFromHandle

SetCursor

SettingsGet

SettingsSet

SetViewLength

Show

Data structures

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:

- WaveformAnalyzerConfig


WaveformScroller.Create method

WaveformScroller.Create method

Remarks

Creates a new instance of the WaveformScroller class 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 (

hWndParent as IntPtr,

nLeft as Int32,

nTop as Int32,

nWidth as Int32,

nHeight as Int32

) as IntPtr

[C#]

public IntPtr Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

[C++]

public: IntPtr Create (

IntPtr hWndParent,

Int32 nLeft,

Int32 nTop,

Int32 nWidth,

Int32 nHeight

);

Parameter | Description
hWndParent | Handle of the parent window, usually the container form.
nLeft | Left position of the window, expressed in client coordinates (pixels) of hWndParent
nTop | Top position of the window, expressed in client coordinates (pixels) of hWndParent
nWidth | Width of the window, expressed in pixels
nHeight | Height of the window, expressed in pixels

Return value

Value | Meaning
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.ERR_NOERROR (0) | The method call was successful.


WaveformScroller.GetViewLength method

WaveformScroller.GetViewLength method

Remarks

Obtains the current length of the waveform scroller's view in terms of displayed milliseconds. The view length can be modified through the WaveformScroller.SetViewLength method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

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


WaveformScroller.PlaybackOnScrollEnable method

WaveformScroller.PlaybackOnScrollEnable method

Remarks

Enables/disables playback of audio data during the manual scroll of the waveform through the mouse.

Current settings can be obtained through the WaveformScroller.PlaybackOnScrollInfoGet method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

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


WaveformScroller.SetBackPictureFromFile method

WaveformScroller.SetBackPictureFromFile method

Remarks

Sets a background picture from a graphic file.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

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


WaveformScroller.SetBackPictureFromHandle method

WaveformScroller.SetBackPictureFromHandle method

Remarks

Sets a background picture from an existing bitmap handle.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

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


WaveformScroller.SetCursor method

WaveformScroller.SetCursor method

Remarks

Sets the cursor to display, from an existing cursor handle (HCURSOR), when the mouse hovers the control's area.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

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.ERR_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.ERR_NOERROR (0) | The method call was successful.


WaveformScroller.SettingsGet method

WaveformScroller.SettingsGet method

Remarks

Retrieves the current graphical settings for the given waveform scroller. Settings can be modified through the WaveformScroller.SettingsSet method.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

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.ERR_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 Move (

hWndWaveformScroller as IntPtr,

nLengthInMs as Int32

) as enumErrorCodes

[C#]

public enumErrorCodes Move (

IntPtr hWndWaveformScroller,

Int32 nLengthInMs

);

[C++]

public: enumErrorCodes Move (

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


WaveformScroller.Show method

WaveformScroller.Show method

Remarks

Shows/hides an existing waveform scroller control.

For further details about methods of the Waveform scroller refer to the WaveformScroller object.

For a tutorial about the use of Waveform scrollers refer to the How to scroll the sound's waveform during playback tutorial.

Syntax

[Visual Basic]

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.ERR_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 | 0 | No graphic item is drawn
MASK_GRAPHIC_ITEM_VERTICAL_LINE (default) | 1 | Draws vertical lines
MASK_GRAPHIC_ITEM_HORIZONTAL_LINE | 2 | Draws horizontal lines
MASK_GRAPHIC_ITEM_WAVE_RANGE | 4 | Draw wave ranges

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:

- RecorderWmaProfiles

- SimpleMp3Rec

- RecordedSoundEditor


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 - Lame encoder command line

Appendix A - Lame encoder command line

Lame encoder, used during the development of this product, is available for download from the following link.

Lame encoder latest build, with full source code, is available for download from its owner's website

Below you can find the full list of command line's options for Lame version 3.96.1:

LAME version 3.96.1 (http://lame.sourceforge.net/)

usage: lame [options] <infile> [outfile]

 <infile> and/or <outfile> can be "-", which means stdin/stdout.

RECOMMENDED:

 lame -h input.wav output.mp3

OPTIONS:

Input options:

 -r              input is raw pcm

 -x              force byte-swapping of input

 -s sfreq        sampling frequency of input file (kHz) - default 44.1 kHz

 --bitwidth w    input bit width is w (default 16)

 --mp1input      input file is a MPEG Layer I   file

 --mp2input      input file is a MPEG Layer II  file

 --mp3input      input file is a MPEG Layer III file

 --nogap <file1> <file2> <...>

                 gapless encoding for a set of contiguous files

 --nogapout <dir>

                 output dir for gapless encoding (must precede --nogap)

 --nogaptags     allow the use of VBR tags in gapless encoding

Operational options:

 -m <mode>       (s)tereo, (j)oint, (f)orce, (m)ono

                 default is (s) or (j) depending on bitrate

                 force = force ms_stereo on all frames.

 -a              downmix from stereo to mono file for mono encoding

 --freeformat    produce a free format bitstream

 --decode        input=mp3 file, output=wav

 -t              disable writing wav header when using --decode

 --comp  <arg>   choose bitrate to achive a compression ratio of <arg>

 --scale <arg>   scale input (multiply PCM data) by <arg>

 --scale-l <arg> scale channel 0 (left) input (multiply PCM data) by <arg>

 --scale-r <arg> scale channel 1 (right) input (multiply PCM data) by <arg>

 --replaygain-fast   compute RG fast but slightly inaccurately (default)

 --replaygain-accurate   compute RG more accurately and find the peak sample

 --noreplaygain  disable ReplayGain analysis

 --clipdetect    enable --replaygain-accurate and print a message whether

                 clipping occurs and how far the waveform is from full scale

 --preset type   type must be "medium", "standard", "extreme", "insane",

                 or a value for an average desired bitrate and depending

                 on the value specified, appropriate quality settings will

                 be used.

                 "--preset help" gives more info on these

Verbosity:

 --disptime <arg>print progress report every arg seconds

 -S              don't print progress report, VBR histograms

 --nohist        disable VBR histogram display

 --silent        don't print anything on screen

 --quiet         don't print anything on screen

 --brief         print more useful information

 --verbose       print a lot of useful information

Noise shaping & psycho acoustic algorithms:

 -q <arg>        <arg> = 0...9.  Default  -q 5

                 -q 0:  Highest quality, very slow

                 -q 9:  Poor quality, but fast

 -h              Same as -q 2.   Recommended.

 -f              Same as -q 7.   Fast, ok quality

CBR (constant bitrate, the default) options:

 -b <bitrate>    set the bitrate in kbps, default 128 kbps

 --cbr           enforce use of constant bitrate

ABR options:

 --abr <bitrate> specify average bitrate desired (instead of quality)

VBR options:

 -v              use variable bitrate (VBR) (--vbr-old)

 --vbr-old       use old variable bitrate (VBR) routine

 --vbr-new       use new variable bitrate (VBR) routine

 -V n            quality setting for VBR.  default n=4

                 0=high quality,bigger files. 9=smaller files

 -b <bitrate>    specify minimum allowed bitrate, default  32 kbps

 -B <bitrate>    specify maximum allowed bitrate, default 320 kbps

 -F              strictly enforce the -b option, for use with players that

                 do not support low bitrate mp3

 -t              disable writing LAME Tag

 -T              enable and force writing LAME Tag

ATH related:

 --noath         turns ATH down to a flat noise floor

 --athshort      ignore GPSYCHO for short blocks, use ATH only

 --athonly       ignore GPSYCHO completely, use ATH only

 --athtype n     selects between different ATH types [0-4]

 --athlower x    lowers ATH by x dB

 --athaa-type n  ATH auto adjust types 1-3, else no adjustment

 --athaa-loudapprox n   n=1 total energy or n=2 equal loudness curve

 --athaa-sensitivity x  activation offset in -/+ dB for ATH auto-adjustment

PSY related:

 --short         use short blocks when appropriate

 --noshort       do not use short blocks

 --allshort      use only short blocks

 --cwlimit <freq>  compute tonality up to freq (in kHz) default 8.8717

 --notemp        disable temporal masking effect

 --nssafejoint   M/S switching criterion

 --nsmsfix <arg> M/S switching tuning [effective 0-3.5]

 --interch x     adjust inter-channel masking ratio

 --ns-bass x     adjust masking for sfbs  0 -  6 (long)  0 -  5 (short)

 --ns-alto x     adjust masking for sfbs  7 - 13 (long)  6 - 10 (short)

 --ns-treble x   adjust masking for sfbs 14 - 21 (long) 11 - 12 (short)

 --ns-sfb21 x    change ns-treble by x dB for sfb21

 --shortthreshold x,y  short block switching threshold, x for L/R/M channel, y for S channel

Noise Shaping related:

 --substep n     use pseudo substep noise shaping method types 0-2

experimental switches:

 -X n[,m]        selects between different noise measurements

                 n for long block, m for short. if m is omitted, m = n

 -Y              lets LAME ignore noise in sfb21, like in CBR

 -Z [n]          toggles the scalefac-scale and subblock gain feature on

                 if n is set and minus, only scalefac-scale is enabled

MP3 header/stream options:

 -e <emp>        de-emphasis n/5/c  (obsolete)

 -c              mark as copyright

 -o              mark as non-original

 -p              error protection.  adds 16 bit checksum to every frame

                 (the checksum is computed correctly)

 --nores         disable the bit reservoir

 --strictly-enforce-ISO   comply as much as possible to ISO MPEG spec

Filter options:

 -k              keep ALL frequencies (disables all filters),

                 Can cause ringing and twinkling

--lowpass <freq>        frequency(kHz), lowpass filter cutoff above freq

--lowpass-width <freq>  frequency(kHz) - default 15% of lowpass freq

--highpass <freq>       frequency(kHz), highpass filter cutoff below freq

--highpass-width <freq> frequency(kHz) - default 15% of highpass freq

--resample <sfreq>  sampling frequency of output file(kHz)- default=automatic

ID3 tag options:

 --tt <title>    audio/song title (max 30 chars for version 1 tag)

 --ta <artist>   audio/song artist (max 30 chars for version 1 tag)

 --tl <album>    audio/song album (max 30 chars for version 1 tag)

 --ty <year>     audio/song year of issue (1 to 9999)

 --tc <comment>  user-defined text (max 30 chars for v1 tag, 28 for v1.1)

 --tn <track>    audio/song track number (1 to 255, creates v1.1 tag)

 --tg <genre>    audio/song genre (name or number in list)

 --add-id3v2     force addition of version 2 tag

 --id3v1-only    add only a version 1 tag

 --id3v2-only    add only a version 2 tag

 --space-id3v1   pad version 1 tag with spaces instead of nulls

 --pad-id3v2     pad version 2 tag with extra 128 bytes

 --genre-list    print alphabetically sorted ID3 genre list and exit

 --ignore-tag-errors  ignore errors in values passed for tags

 Note: A version 2 tag will NOT be added unless one of the input fields

 won't fit in a version 1 tag (e.g. the title string is longer than 30

 characters), or the '--add-id3v2' or '--id3v2-only' options are used,

 or output is redirected to stdout.

MS-Windows-specific options:

 --priority <type>     sets the process priority:

                            0,1 = Low priority (IDLE_PRIORITY_CLASS)

                            2 = normal priority (NORMAL_PRIORITY_CLASS, default)

                            3,4 = High priority (HIGH_PRIORITY_CLASS))

 Note: Calling '--priority' without a parameter will select priority 0.

MPEG-1   layer III sample frequencies (kHz):  32  48  44.1

bitrates (kbps): 32 40 48 56 64 80 96 112 128 160 192 224 256 320

MPEG-2   layer III sample frequencies (kHz):  16  24  22.05

bitrates (kbps):  8 16 24 32 40 48 56 64 80 96 112 128 144 160

MPEG-2.5 layer III sample frequencies (kHz):   8  12  11.025

bitrates (kbps):  8 16 24 32 40 48 56 64 80 96 112 128 144 160


Appendix B - OggEnc encoder command line

Appendix B - OggEnc encoder command line

OggEnc encoder, used during the development of this product, is available for download from the following link.

OggEnc encoder is part of the Vorbis-tools package whose full source code can be downloaded from the Xiph.org website.

Below you can find the full list of command line's options for OggEnc version 1.0

OggEnc v1.0 (libvorbis 1.0)

(c) 2000-2002 Michael Smith <msmith@labyrinth.net.au>

Usage: oggenc [options] input.wav [...]

OPTIONS:

General:

-Q, --quiet Produce no output to stderr

-h, --help Print this help text

-r, --raw Raw mode. Input files are read directly as PCM data

-B, --raw-bits=n Set bits/sample for raw input. Default is 16

-C, --raw-chan=n Set number of channels for raw input. Default is 2

-R, --raw-rate=n Set samples/sec for raw input. Default is 44100

--raw-endianness 1 for bigendian, 0 for little (defaults to 0)

-b, --bitrate Choose a nominal bitrate to encode at. Attempt

to encode at a bitrate averaging this. Takes an

argument in kbps. This uses the bitrate management

engine, and is not recommended for most users.

See -q, --quality for a better alternative.

-m, --min-bitrate Specify a minimum bitrate (in kbps). Useful for

encoding for a fixed-size channel.

-M, --max-bitrate Specify a maximum bitrate in kbps. Useful for

streaming applications.

-q, --quality Specify quality between 0 (low) and 10 (high),

instead of specifying a particular bitrate.

This is the normal mode of operation.

Fractional qualities (e.g. 2.75) are permitted

Quality -1 is also possible, but may not be of

acceptable quality.

--resample n Resample input data to sampling rate n (Hz)

--downmix Downmix stereo to mono. Only allowed on stereo

input.

-s, --serial Specify a serial number for the stream. If encoding

multiple files, this will be incremented for each

stream after the first.

Naming:

-o, --output=fn Write file to fn (only valid in single-file mode)

-n, --names=string Produce filenames as this string, with %a, %t, %l,

%n, %d replaced by artist, title, album, track number,

and date, respectively (see below for specifying these).

%% gives a literal %.

-X, --name-remove=s Remove the specified characters from parameters to the

-n format string. Useful to ensure legal filenames.

-P, --name-replace=s Replace characters removed by --name-remove with the

characters specified. If this string is shorter than the

--name-remove list or is not specified, the extra

characters are just removed.

Default settings for the above two arguments are platform

specific.

-c, --comment=c Add the given string as an extra comment. This may be

used multiple times.

-d, --date Date for track (usually date of performance)

-N, --tracknum Track number for this track

-t, --title Title for this track

-l, --album Name of album

-a, --artist Name of artist

-G, --genre Genre of track

If multiple input files are given, then multiple

instances of the previous five arguments will be used,

in the order they are given. If fewer titles are

specified than files, OggEnc will print a warning, and

reuse the final one for the remaining files. If fewer

track numbers are given, the remaining files will be

unnumbered. For the others, the final tag will be reused

for all others without warning (so you can specify a date

once, for example, and have it used for all the files)

INPUT FILES:

OggEnc input files must currently be 16 or 8 bit PCM WAV, AIFF, or AIFF/C

files, or 32 bit IEEE floating point WAV. Files may be mono or stereo

(or more channels) and any sample rate.

Alternatively, the --raw option may be used to use a raw PCM data file, which

must be 16bit stereo little-endian PCM ('headerless wav'), unless additional

parameters for raw mode are specified.

You can specify taking the file from stdin by using - as the input filename.

In this mode, output is to stdout unless an outfile filename is specified

with -o


Appendix C - Faac encoder command line

Appendix C - Faac encoder command line

Faac encoder, used during the development of this product, is available for download from the following link.

Below you can find the full list of command line's options for Faac version 1.24.1

Freeware Advanced Audio Coder

FAAC 1.24.1 (May 17 2005) UNSTABLE

Usage: faac [options] infiles ...

Quality-related options:

-q <quality>  Set default variable bitrate (VBR) quantizer quality in percent.

             (default: 100, averages at approx. 120 kbps VBR for a normal

             stereo input file with 16 bit and 44.1 kHz sample rate; max.

             value 500, min. 10).

-b <bitrate>  Set average bitrate (ABR) to approximately <bitrate> kbps.

             (max. value 152 kbps/stereo with a 16 kHz cutoff, can be raised

             with a higher -c setting).

-c <freq>     Set the bandwidth in Hz (default: automatic, i.e. adapts

             maximum value to input sample rate).

Input/output options:

-             <stdin/stdout>: If you simply use a hyphen/minus sign instead

             of an input file name, FAAC can encode directly from stdin,

             thus enabling piping from other applications and utilities. The

             same works for stdout as well, so FAAC can pipe its output to

             other apps such as a server.

-o X          Set output file to X (only for one input file)

             only for one input file; you can use *.aac, *.mp4, *.m4a or

             *.m4b as file extension, and the file format will be set

             automatically to ADTS or MP4).

-P            Raw PCM input mode (default: off, i.e. expecting a WAV header;

             necessary for input files or bitstreams without a header; using

             only -P assumes the default values for -R, -B and -C in the

             input file).

-R            Raw PCM input sample rate in Hz (default: 44100 Hz, max. 96 kHz)

-B            Raw PCM input sample size (default: 16, also possible 8, 24, 32

             bit fixed or float input).

-C            Raw PCM input channels (default: 2, max. 33 + 1 LFE).

-X            Raw PCM swap input bytes (default: bigendian).

-I <C[,LFE]>  Input multichannel configuration (default: 3,4 which means

             Center is third and LFE is fourth like in 5.1 WAV, so you only

             have to specify a different position of these two mono channels

             in your multichannel input files if they haven't been reordered

             already).

MP4 specific options:

-w            Wrap AAC data in MP4 container. (default for *.mp4, *.m4a and

             *.m4b)

--artist X    Set artist to X

--writer X    Set writer/composer to X

--title X     Set title/track name to X

--genre X     Set genre to X

--album X     Set album/performer to X

--compilation Mark as compilation

--track X     Set track to X (number/total)

--disc X      Set disc to X (number/total)

--year X      Set year to X

--cover-art X Read cover art from file X

             Supported image formats are GIF, JPEG, and PNG.

--comment X   Set comment to X

Expert options, only for testing purposes:

--tns         Enable coding of TNS, temporal noise shaping.

--no-midside  Don't use mid/side coding.

--mpeg-vers X Force AAC MPEG version, X can be 2 or 4

--obj-type X  AAC object type. (LC (Low Complexity, default), Main or LTP

             (Long Term Prediction)

--shortctl X  Enforce block type (0 = both (default); 1 = no short; 2 = no

             long).

-r            Generate raw AAC bitstream (i.e. without any headers).

             Not advised!!!, RAW AAC files are practically useless!!!

Documentation:

--license     Show the FAAC license.

--help        Show this abbreviated help.

--long-help   Show complete help.

More tips can be found in the audiocoding.com Knowledge Base at

<http://www.audiocoding.com/wiki/>


Appendix D - TwoLame encoder command line

Appendix D - TwoLame encoder command line

TwoLame encoder, used during the development of this product, is available for download from the following link.

TwoLame encoder latest build, with full source code, is available for download from its owner's website

Below you can find the full list of command line's options for TwoLame version 0.3.12b:

TwoLAME version TwoLame 0.3.12b (http://www.twolame.org)

MPEG Audio Layer II (MP2) encoder

Usage:

twolame [options] <infile> [outfile]

Both input and output filenames can be set to - to use stdin/stdout.

 <infile>       input sound file (any format supported by libsndfile)

 <outfile>      output bit stream of encoded audio

Input Options

-r, --raw-input          input is raw signed PCM audio

-x, --byte-swap          force byte-swapping of input

-s, --samplerate srate   sampling frequency of raw input (Hz)

   --samplesize bits    size of raw input samples in bits (default 16-bit)

   --samplefloat        32-bit float raw input

-N, --channels nch       number of channels in raw input

-g, --swap-channels      swap channels of input file

   --scale value        scale input (multiply PCM data)

   --scale-l value      scale channel 0 (left) input

   --scale-r value      scale channel 1 (right) input

Output Options

-m, --mode mode          (s)tereo, (j)oint, (d)ual, (m)ono or (a)uto

-a, --downmix            downmix from stereo to mono file for mono encoding

-b, --bitrate br         total bitrate in kbps (default 192 for 44.1kHz)

-P, --psyc-mode psyc     psychoacoustic model -1 to 4 (default 3)

-v, --vbr                enable VBR mode

-V, --vbr-level lev      enable VBR and set VBR level -50 to 50 (default 5)

-B, --max-bitrate rate   set the upper bitrate when in VBR mode

-l, --ath lev            ATH level (default 0.0)

-q, --quick num          only calculate psy model every num frames

-S, --single-frame       only encode a single frame of MPEG Audio

Miscellaneous Options

-c, --copyright          mark as copyright

-o, --non-original       mark as non-original

   --original           mark as original (default)

-p, --protect            enable CRC error protection

-d, --padding            force padding bit/frame on

-R, --reserve-bits num   set number of reserved bits in each frame

-e, --deemphasis emp     de-emphasis n/5/c (default: (n)one)

-E, --energy             turn on energy level extensions

Verbosity Options

-t, --talkativity num    talkativity 0-10 (default is 2)

   --quiet              same as --talkativity=0

   --brief              same as --talkativity=1

   --verbose            same as --talkativity=4

Allowable bitrates for 32, 44.1 and 48kHz sample input (MPEG-1)

 32,  48,  56,  64,  80,  96, 112, 128, 160, 192, 224, 256, 320, 384

Allowable bitrates for 16, 22.05 and 24kHz sample input (MPEG-2)

  8,  16,  24,  32,  40,  48,  56,  64,  80,  96, 112, 128, 144, 160


Appendix E - OpusEnc encoder command line

Appendix E - OpusEnc encoder command line

OpusEnc encoder, used during the development of this product, is available for download from the following link.

OpusEnc encoder latest build, with full source code, is available for download from its owner's website

Below you can find the full list of command line's options for OpusEnc version 0.1.9:

Usage: opusenc [options] input_file output_file.opus

Encodes input_file using Opus.

It can read the WAV, AIFF, FLAC, Ogg/FLAC, or raw files.

General options:

-h, --help         This help

-V, --version      Version information

--quiet            Quiet mode

input_file can be:

 filename.wav      file

 -                 stdin

output_file can be:

 filename.opus     compressed file

 -                 stdout

Encoding options:

--bitrate n.nnn    Target bitrate in kbit/sec (6-256/channel)

--vbr              Use variable bitrate encoding (default)

--cvbr             Use constrained variable bitrate encoding

--hard-cbr         Use hard constant bitrate encoding

--comp n           Encoding complexity (0-10, default: 10 (slowest))

--framesize n      Maximum frame size in milliseconds

                     (2.5, 5, 10, 20, 40, 60, default: 20)

--expect-loss      Percentage packet loss to expect (default: 0)

--downmix-mono     Downmix to mono

--downmix-stereo   Downmix to stereo (if >2 channels)

--max-delay n      Maximum container delay in milliseconds

                     (0-1000, default: 1000)

Diagnostic options:

--serial n         Forces a specific stream serial number

--save-range file  Saves check values for every frame to a file

--set-ctl-int x=y  Pass the encoder control x with value y (advanced)

                     Preface with s: to direct the ctl to multistream s

                     This may be used multiple times

Metadata options:

--comment          Add the given string as an extra comment

                     This may be used multiple times

--artist           Author of this track

--title            Title for this track

--album            Album or collection this track belongs to

--date             Date for this track

--genre            Genre for this track

--picture          Album art for this track

                     More than one --picture option can be specified.

                     Either a FILENAME for the picture file or a more

                     complete SPECIFICATION form can be used. The

                     SPECIFICATION is a string whose parts are

                     separated by | (pipe) characters. Some parts may

                     be left empty to invoke default values. A

                     FILENAME is just shorthand for "||||FILENAME".

                     The format of SPECIFICATION is

                     [TYPE]|[MIME-TYPE]|[DESCRIPTION]|[WIDTHxHEIGHT

                     xDEPTH[/COLORS]]|FILENAME

                     TYPE is an optional number from one of:

                     0: Other

                     1: 32x32 pixel 'file icon' (PNG only)

                     2: Other file icon

                     3: Cover (front)

                     4: Cover (back)

                     5: Leaflet page

                     6: Media (e.g., label side of a CD)

                     7: Lead artist/lead performer/soloist

                     8: Artist/performer

                     9: Conductor

                     10: Band/Orchestra

                     11: Composer

                     12: Lyricist/text writer

                     13: Recording location

                     14: During recording

                     15: During performance

                     16: Movie/video screen capture

                     17: A bright colored fish

                     18: Illustration

                     19: Band/artist logotype

                     20: Publisher/studio logotype

                     The default is 3 (front cover). There may only be

                     one picture each of type 1 and 2 in a file.

                     MIME-TYPE is optional. If left blank, it will be

                     detected from the file. For best compatibility

                     with players, use pictures with a MIME-TYPE of

                     image/jpeg or image/png. The MIME-TYPE can also

                     be --> to mean that FILENAME is actually a URL to

                     an image, though this use is discouraged. The

                     file at the URL will not be fetched. The URL

                     itself is stored in the metadata.

                     DESCRIPTION is optional. The default is an empty

                     string.

                     The next part specifies the resolution and color

                     information. If the MIME-TYPE is image/jpeg,

                     image/png, or image/gif, you can usually leave

                     this empty and they can be detected from the

                     file. Otherwise, you must specify the width in

                     pixels, height in pixels, and color depth in

                     bits-per-pixel. If the image has indexed colors

                     you should also specify the number of colors

                     used. If possible, these are checked against the

                     file for accuracy.

                     FILENAME is the path to the picture file to be

                     imported, or the URL if the MIME-TYPE is -->.

--padding n        Extra bytes to reserve for metadata (default: 512)

--discard-comments Don't keep metadata when transcoding

--discard-pictures Don't keep pictures when transcoding

Input options:

--raw              Raw input

--raw-bits n       Set bits/sample for raw input (default: 16)

--raw-rate n       Set sampling rate for raw input (default: 48000)

--raw-chan n       Set number of channels for raw input (default: 2)

--raw-endianness n 1 for bigendian, 0 for little (defaults to 0)

--ignorelength     Always ignore the datalength in Wave headers


Appendix F - FdkAac encoder command line

Appendix F - FdkAac encoder command line

FdkAac encoder, used during the development of this product, is available for download from the following link.

Below you can find the full list of command line's options for FdkAac version 0.6.2:

Usage: fdkaac [options] input_file

Options:

-h, --help                    Print this help message

-p, --profile <n>             Profile (audio object type)

                                2: MPEG-4 AAC LC (default)

                                5: MPEG-4 HE-AAC (SBR)

                               29: MPEG-4 HE-AAC v2 (SBR+PS)

                               23: MPEG-4 AAC LD

                               39: MPEG-4 AAC ELD

                              129: MPEG-2 AAC LC

                              132: MPEG-2 HE-AAC (SBR)

                              156: MPEG-2 HE-AAC v2 (SBR+PS)

-b, --bitrate <n>             Bitrate in bits per seconds (for CBR)

-m, --bitrate-mode <n>        Bitrate configuration

                                0: CBR (default)

                                1-5: VBR

                              (VBR mode is not officially supported, and

                               works only on a certain combination of

                               parameter settings, sample rate, and

                               channel configuration)

-w, --bandwidth <n>           Frequency bandwidth in Hz (AAC LC only)

-a, --afterburner <n>         Afterburner

                                0: Off

                                1: On(default)

-L, --lowdelay-sbr <-1|0|1>   Configure SBR activity on AAC ELD

                               -1: Use ELD SBR auto configurator

                                0: Disable SBR on ELD (default)

                                1: Enable SBR on ELD

-s, --sbr-ratio <0|1|2>       Controls activation of downsampled SBR

                                0: Use lib default (default)

                                1: downsampled SBR (default for ELD+SBR)

                                2: dual-rate SBR (default for HE-AAC)

-f, --transport-format <n>    Transport format

                                0: RAW (default, muxed into M4A)

                                1: ADIF

                                2: ADTS

                                6: LATM MCP=1

                                7: LATM MCP=0

                               10: LOAS/LATM (LATM within LOAS)

-C, --adts-crc-check          Add CRC protection on ADTS header

-h, --header-period <n>       StreamMuxConfig/PCE repetition period in

                              transport layer

-o <filename>                 Output filename

-G, --gapless-mode <n>        Encoder delay signaling for gapless playback

                                0: iTunSMPB (default)

                                1: ISO standard (edts + sgpd)

                                2: Both

--include-sbr-delay           Count SBR decoder delay in encoder delay

                              This is not iTunes compatible, but is default

                              behavior of FDK library.

-I, --ignorelength            Ignore length of WAV header

-S, --silent                  Don't print progress messages

--moov-before-mdat            Place moov box before mdat box on m4a output

Options for raw (headerless) input:

-R, --raw                     Treat input as raw (by default WAV is

                              assumed)

--raw-channels <n>            Number of channels (default: 2)

--raw-rate     <n>            Sample rate (default: 44100)

--raw-format   <spec>         Sample format, default is "S16L".

                              Spec is as follows:

                               1st char: S(igned)|U(nsigned)|F(loat)

                               2nd part: bits per channel

                               Last char: L(ittle)|B(ig)

                              Last char can be omitted, in which case L is

                              assumed. Spec is case insensitive, therefore

                              "u16b" is same as "U16B".

Tagging options:

--title <string>

--artist <string>

--album <string>

--genre <string>

--date <string>

--composer <string>

--grouping <string>

--comment <string>

--album-artist <string>

--track <number[/total]>

--disk <number[/total]>

--tempo <n>

--tag <fcc>:<value>          Set iTunes predefined tag with four char code.

--tag-from-file <fcc>:<filename>

                             Same as above, but value is read from file.

--long-tag <name>:<value>    Set arbitrary tag as iTunes custom metadata.

--tag-from-json <filename[?dot_notation]>

                             Read tags from JSON. By default, tags are

                             assumed to be direct children of the root

                             object(dictionary).

                             Optionally, position of the dictionary

                             that contains tags can be specified with

                             dotted notation.

                             Example:

                               --tag-from-json /path/to/json?format.tags


Asrecnet-0000ce

Copyright © 2006-2018 MultiMedia Soft

Asrecnet-0000ce

 Return to chapter overview


Senza titolo 50

Copyright © 2006-2018 MultiMedia Soft

Senza titolo 50

Return to chapter overview


Senza titolo 129

Copyright © 2006-2018 MultiMedia Soft

Senza titolo 129

Return to chapter overview


Senza titolo 311

Copyright © 2006-2018 MultiMedia Soft

Senza titolo 311

Return to chapter overview


Senza titolo 78

Copyright © 2006-2018 MultiMedia Soft

Senza titolo 78

Return to chapter overview


Footer

Copyright © 2006-2018 MultiMedia Soft

Footer

Return to chapter overview

Copyright © 2006 - 2010 MultiMedia Soft

Return to Table of contents


Table of contents

Copyright © 2006-2018 MultiMedia Soft

Table of contents

Return to chapter overview


Asrecnet_000007

Copyright © 2006-2018 MultiMedia Soft

Asrecnet_000007

 Return to chapter overview


Empty page

Copyright © 2006-2018 MultiMedia Soft

Empty page

Return to chapter overview


Asrecnet_000050

Copyright © 2006-2018 MultiMedia Soft

Asrecnet_000050

 Return to chapter overview


Header

Copyright © 2006-2018 MultiMedia Soft

Header

Return to chapter overview

Copyright © 2006 - 2010 MultiMedia Soft

Return to Table of contents


Asrecnet_000062

Copyright © 2006-2018 MultiMedia Soft

Asrecnet_000062

 Return to chapter overview


Asrecnet_000092

Copyright © 2006-2018 MultiMedia Soft

Asrecnet_000092

 Return to chapter overview


Pagina vuota

Copyright © 2006-2018 MultiMedia Soft

Pagina vuota

Return to chapter overview