npWave plugin

About this plugin

With this plugin you can treat with WAVE files from your publications. For example, you can play and record WAVE files in an easy way, taking all controll of the proccess, and get notifying for all player and recorder events.

You can play WAVE files to all of availables system output devices, and also you can record WAVE files from all availables system input devices, not only from a microphone, for example you can record WAVE files from the computer sound cards.

Also this plugin allow you to create various instances of player and recorder objects, so you can deal with differents player and recorder separatelly: every object have their own properties and events. Last but not least, the plugin have various general WAVE related actions.

Thirparty

This plugin are imposible without the aid of this people:

Thanks a lot!

Plugin actions index

npWavePlayerCreate

This action creates a new instance of an Wave object. The result variable store the ID of the new Wave object. You can use this ID with other plugin actions.

↑↑

npWavePlayerDestroy

This action destruct a previously created WAVE player object instance. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. This action The [LastError] variable contain information about the error.

↑↑

npWavePlayerDestroyAll

This action destruct all previously created WAVE player object instances.

↑↑

npWaveOutputDevices

Get all availables system output devices. This action retrieves all availables system output devices, to use it later with the appropiate plugin actions. If fact you dont need to call this action before you start playing a WAVE file: if you dont provide one output device the plugin play the WAVE file with the default one. Please, see the plugin samples for more information.

This action retrieves the output devices into the specified Array variable, and the total plugin count in the specified count variable. So is easy to iterate on the output devices Array variable in order to store the output devices in a ListBox object, for example. If no one output devices are found in the system (very rarely) the specified Array variable are empty and the count variable is zero.

↑↑

npWavePlayerStart

Play a WAVE file. Specified the WAVE file path to be played, and, optionally, the output device to play in it. If you dont provide a output device ID the plugin play the WAVE file using the default system output device. This action store in the result variable "True" if everything is OK, or "False" if not. In this last case the [LastError] variable contain information about the error.

↑↑

npWavePlayerStop

Stop a currently playing WAVE file. The action store in the result variable "True" if player can be stopped, or "False" if not, for example, because no one active player are found. See npWavePlayerIsActive.

↑↑

npWavePlayerPause

Pause a currently playing WAVE file. The action store in the result variable "True" if player can be paused, or "False" if not, for example, because no one active player are found or an active player are already paused. See npWavePlayerIsPaused.

↑↑

npWavePlayerResume

Recume a currently playing pause WAVE file. The action store in the result variable "True" if player can be resumed, or "False" if not, for example, because no one active player are found or an active player is not paused. See npWavePlayerIsPaused.

↑↑

npWavePlayerPosition

Set the position of the current active WAVE file. The action store in the result variable "True" if player can be positioned, or "False" if not, for example, because no one active player are found.

↑↑

npWavePlayerIsActive

Find if the output device is playing a WAVE file. Note that if one WAVE file is paused, also is considerer active. The action store in the result variable "True" if the WAVE file player is active, or "False" if not.

↑↑

npWavePlayerIsPaused

Find if the output device is playing a WAVE file and its currently paused. The action store in the result variable "True" if the WAVE file player is active, or "False" if not.

↑↑

npOnPlayerError

This action allow you to set a subroutine to be executed when a player error is detected. The instance ID variable contain the ID of the Wave object that fire the event. The specified error variable contain on this case information about the detected player error.

↑↑

npOnPlayerLevel

This action allow you to set a subroutine to be executed to inform you about the currently playing percentage level. The instance ID variable contain the ID of the Wave object that fire the event. The action store in the specified level variable the level percent value. See the plugin samples for more information.

↑↑

npOnPlayerPause

Set a subroutine to be executed when a player is paused. The instance ID variable contain the ID of the Wave object that fire the event. The action store in the output device variable the output device used to play the WAVE file.

↑↑

npOnPlayerResume

Set a subroutine to be executed when a player is resumed. The instance ID variable contain the ID of the Wave object that fire the event. The action store in the output device variable the output device used to play the WAVE file.

↑↑

npOnPlayerPosition

Set a subroutine to be execute to inform you of the position of the current playing WAVE file. The instance ID variable contain the ID of the Wave object that fire the event. The position is stored in the specified variable and contain the currently WAVE file position milliseconds. See npOnPlayerActivate.

↑↑

npOnPlayerActivate

Set a subroutine to be executed to inform you that a output device player is activate, in other words begin to play a WAVE file. The instance ID variable contain the ID of the Wave object that fire the event. The action store in the device output variable the currently used output device. Also store in the WAVE length variable the total (in milliseconds) of the WAVE file. See npOnPlayerPosition.

↑↑

npOnPlayerDeactivate

Set a subroutine to be executed when a WAVE file playing terminates. The instance ID variable contain the ID of the Wave object that fire the event. The output device variable store the output device that is deactivate.

↑↑

npWaveRecordCreate

This action creates a new instance of an WAVE recorder object. The result variable contain a number mayor than zero, if everything is OK, or -1 if not. The [LastError] variable contain information about the error. You can use the result variable value as the ID of the WAVE recorder object with other plugin actions.

↑↑

npWaveRecordDestroy

This action destruct a previously created WAVE recorder object instance. The result variable store "True" if every is OK, or "False" if not, for example, because no instance is found with the provided ID. This action The [LastError] variable contain information about the error.

↑↑

npWaveRecordDestroyAll

This action destruct all previously created WAVE recorder object instances.

↑↑

npWaveInputDevices

Get all system availables recording input devices. You can use this action in order to allow your publication users to choose the recording input device to use when recording WAVE files. The action store in the specified Array variable all the input available devices, and in the specified count variable the total input devices, so is easy iterate the Array variable to store the output input devices in a ListBox for example.

Is not mandatory to use this action in order to record WAVE files: if you dont provide a input device when can be, the plugin record the WAVE file using the Windows default input device. For more information I remite you to the plugin recording samples.

↑↑

npWavePCMFormats

This action retrieve all PCM formats support the specified output recording device. If you dont provide a output device this action find the PCM formats supported by the system default output device. The action stores in the specified Array variable all the supported PCM formats, and in the specified count variable the total of PCM formats, so is easy to iterate the Array variable in order to add the PCM formats to a Listbox object, for example. See the recording plugin samples for more information.

↑↑

npWaveRecordStart

Start the recording of a WAVE file. The WAVE file is saved in the specified WAVE file path. Optionally you can specifiy the output device and the PCM format to use, in other case the plugin uses the default ones. The result variable store "True" if everything is OK, or "False" if not. In this last case you can found more information about the error in the [LastError].

↑↑

npWaveRecordStop

Stop a currently WAVE file recording. The specified result variable store "True" if the recording can be stopped, or "False" if not, for example, because no one recording is currently active.

↑↑

npWaveRecordPause

Pause a currently recording WAVE file. The action store in the result variable "True" if recording can be paused, or "False" if not, for example, because no one active recorder are found or an active recorder are already paused. See npWaveRecordIsPaused.

↑↑

npWaveRecordResume

Recume a currently recording pause WAVE file. The action store in the result variable "True" if recording can be resumed, or "False" if not, for example, because no one active recorder are found or an active recorder is not paused. See npWaveRecordIsPaused.

↑↑

npWaveRecordIsActive

Find if the input device is recording a WAVE file. Note that if one recording WAVE file is paused, also is considerer active. The action store in the result variable "True" if the WAVE file recorder is active, or "False" if not.

↑↑

npWaveRecordIsPaused

Find if the input device is recording a WAVE file and its currently paused. The action store in the result variable "True" if the WAVE file recorder is active, or "False" if not.

↑↑

npOnRecordError

This action allow you to set a subroutine to be executed when a record error is detected. The instance ID variable contain the ID of the Record object that fire the event. The specified error variable contain on this case information about the detected record error.

↑↑

npOnRecordLevel

This action allow you to set a subroutine to be executed to inform you about the currently recording percentage level. The instance ID variable contain the ID of the Record object that fire the event. The action store in the specified level variable the level percent value. See the plugin samples for more information.

↑↑

npOnRecordPause

Set a subroutine to be executed when a record is paused. The instance ID variable contain the ID of the Record object that fire the event. The action store in the input device variable the input device used to recording the WAVE file.

↑↑

npOnRecordResume

Set a subroutine to be executed when a record is resumed. The instance ID variable contain the ID of the Record object that fire the event. The action store in the input device variable the input device used to recording the WAVE file.

↑↑

npOnRecordPosition

Set a subroutine to be execute to inform you of the position of the current recording WAVE file. The instance ID variable contain the ID of the Record object that fire the event. The position is stored in the specified variable and contain the currently WAVE file position milliseconds.

↑↑

npOnRecordActivate

Set a subroutine to be executed to inform you that a input device record is activate, in other words begin to recording a WAVE file. The instance ID variable contain the ID of the Record object that fire the event. The action store in the device input variable the currently used input device.

↑↑

npOnRecordDeactivate

Set a subroutine to be executed when a WAVE file recording terminates. The instance ID variable contain the ID of the Record object that fire the event. The input device variable store the input device that is deactivate.

↑↑

npWaveSub

Substract a portion of the audio of a WAVE file, starting by the specified position to the specified length all in milliseconds. The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

npWaveInfo

Retrieve a lot of information from a WAVE file. This action store in the result variable "False" if any error ocurred, and set the [LastError] variable with the error message. But, if everything is OK, the result variable contain an Array with lot of WAVE file information. In fact the result variable contain an Array with this five elements and their appropiate values:

↑↑

npWaveConcat

Concatenates two WAVE files with the same audio format to generate a single wave WAVE file. The action inserts a silence between WAVES, which its amount is specified by the Gap variable in milliseconds. If the Gap variable is not zero, the source waves should be PCM format only. The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

npWaveInvert

Inverts the audio of a WAVE file (PCM format only). The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

npWaveDelete

Delete a portion of the audio of a WAVE file, starting by the specified position to the specified length all in milliseconds. The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

npWaveTrimStart

Delete a portion of the audio of a WAVE file from the start to the specified length. The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

npWaveTrimEnd

Delete a portion of the audio of a WAVE file from the end to the specified length. The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

npWaveChangeVolume

Increases or decreases the volume of the audio of a WAVE file (PCM format only). The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

npWaveInsertSilence

Insert a silence in the audio of a WAVE file (PCM format only) from the specified position to the specified length. The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

npWaveConvertToPCM

Convert the provided source WAVE file to the specified PCM format and save it to the target WAVE file.

Here is the list of available PCM formats:

The result variable stores "True" if everthing is OK, or "False" if not.

↑↑

Action errors subroutine

All the NeoPlugins deal with errors in the same way that NeoBook does: when the plugin found an action error the [LastError] variable store information about the error, so you can take care about this variable when execute an action.

But all the NeoPlugins also incorporate an advanced way to deal with possible action errors. You can define a subroutine named OnNeoPluginActionError in order to be executed when some action error are found and you can use this variables inside:

Note that this error handling subroutine are shared for all the NeoPlugins, so you no need to specify a subroutine for every plugin you use in your publication because the same subroutine are recognized and automagically used by every NeoPlugin. Below you can view a sample of this subroutine code:

:OnNeoPluginActionError
  AlertBox "NeoPlugin Error" "Error [LastError] in plugin: [PluginName]"
Return

Also note that the use of this NeoPlugins error handling subroutine is completelly optional. You can continue using the [LastError] variable as usual and even use the both methods at the same time.

↑↑