PrimoBurner(tm) for C++  4.6
CD, DVD and Blu-ray Software Development Kit
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Pages
AudioInput Class Referenceabstract

Defines an audio input for Audio CD writing. More...

#include <PrimoBurnerAPI.h>

Inherits Reference.

Public Member Functions

virtual AudioInputclone () const =0
 Creates a copy of the AudioInput object. More...
 
virtual int32_t endFrame () const =0
 Gets the value set with SetEndFrame. More...
 
virtual const char_t * filePath () const =0
 Gets the path set with setFilePath. More...
 
virtual bool_t forceMinTrackLength () const =0
 Gets the value specifying whether to artificially expand an audio input to at least 4 seconds in length. More...
 
virtual PcmAudioFormatformat () const =0
 Gets the PCM format set by setFormat. More...
 
virtual int32_t fullLength () const =0
 Gets the full length of the audio input. More...
 
virtual void setEndFrame (int32_t frame)=0
 Sets the last frame of audio that will be written to the disc. More...
 
virtual void setFilePath (const char_t *path)=0
 Sets the full path to the file from which AudioCD should read data during audio CD burning. More...
 
virtual void setForceMinTrackLength (bool_t force)=0
 The standard audio CD track should be at least 4 seconds in length. More...
 
virtual void setFormat (PcmAudioFormat *format)=0
 Specifies the PCM audio format of the audio source. More...
 
virtual void setFullLength (int32_t frames)=0
 Sets the full length of the audio input. More...
 
virtual void setStartFrame (int32_t frame)=0
 Sets the first frame of audio that will be written to the disc. More...
 
virtual void setStorageType (AudioStorage::Enum storage)=0
 Sets the audio storage type. More...
 
virtual void setStream (primo::Stream *stream)=0
 Set the input stream that should be used for reading audio data during audio track creation. More...
 
virtual int32_t startFrame () const =0
 Gets the value set with setStartFrame. More...
 
virtual AudioStorage::Enum storageType () const =0
 Gets the audio storage type. More...
 
virtual primo::Streamstream () const =0
 Gets the audio stream set with setStream. More...
 
- Public Member Functions inherited from Reference
virtual int32_t release () const =0
 Releases the instance. More...
 
virtual int32_t retain () const =0
 Retains the instance. More...
 
virtual int32_t retainCount () const =0
 Returns the current reference count. More...
 

Detailed Description

Defines an audio input for Audio CD writing.

Member Function Documentation

virtual AudioInput* clone ( ) const
pure virtual

Creates a copy of the AudioInput object.

Returns
A copy of the AudioInput. The new object should be released when it's not needed anymore.

see Object Management

virtual int32_t endFrame ( ) const
pure virtual

Gets the value set with SetEndFrame.

Returns
end frame address
virtual const char_t* filePath ( ) const
pure virtual

Gets the path set with setFilePath.

Returns
A null-terminated string or NULL if no file path is set.
virtual bool_t forceMinTrackLength ( ) const
pure virtual

Gets the value specifying whether to artificially expand an audio input to at least 4 seconds in length.

NOTE: If the setForceMinTrackLength method has not been called this method returns TRUE.

Returns
TRUE. Audio input will be artificially expanded to 4 seconds if its original length is less than 4 seconds.
FALSE. Audio input will be used as is; no digital silence will be added after it once it is written on the CD, even if its length is less than 4 seconds.
See Also
AudioInput::setForceMinTrackLength
AudioCD::inputLength
virtual PcmAudioFormat* format ( ) const
pure virtual

Gets the PCM format set by setFormat.

Returns
A pointer to PcmAudioFormat.
virtual int32_t fullLength ( ) const
pure virtual

Gets the full length of the audio input.

Returns
Audio length in CDDA frames (1 CDDA frame = 2352 bytes).
See Also
AudioInput::setFullLength
virtual void setEndFrame ( int32_t  frame)
pure virtual

Sets the last frame of audio that will be written to the disc.

This is used in case you do not want to read the audio all the way to the end of the file.

This method does not validate its parameters against the start frame and the length of the file.

Parameters
frame[in] End frame. It can be >= 0 or -1. When set to -1 it means audio data should be read until reaching the end of file.

The length of the audio will be (endFrame - startFrame + 1) in case frame is a positive number and (audio source length in frames - startFrame) in case frame is -1.

NOTE: The length of the audio should be at least 300 frames, because the standard mandates that audio CD track is at least 4 seconds long, and 1 sec = 75 frames. Therefore 4 sec x 75 frames/sec = 300 frames.

If the length of the audio is less than 4 sec it will be padded with silence to 4 sec during the burning.

The start/end frame validation is done by the AudioCD::writeToCD method before the burning starts.

virtual void setFilePath ( const char_t *  path)
pure virtual

Sets the full path to the file from which AudioCD should read data during audio CD burning.

Parameters
pathThe full path to the audio input file.

The file extension implicitly specifies the input type regardless of the storage type.

NOTE: Even when the storage type is AudioStorage::Stream the file path must be set to the file extension, in order to specify the Stream type.

For example, if the stream represents a wav input, the file path should be set to ".wav".

virtual void setForceMinTrackLength ( bool_t  force)
pure virtual

The standard audio CD track should be at least 4 seconds in length.

This method allows the user to specify whether to artificially expand an audio input in case it is less than 4 seconds.

Parameters
force[in] Set this parameter to TRUE to allow artificial expanding of the audio input otherwise set to FALSE. By default the audio input will be expanded.

NOTE: Calling this method affects only inputs that are less than 4 seconds in length. If this method is called with TRUE as input parameter for such an audio input, then when written on a CD, digital silence will be added after its end (on the CD) to complete it to 4 seconds in length. If several audio inputs are to be used to create a single audio track then it may be better to call this method with FALSE as input parameter for each of these inputs.

See Also
AudioCD::inputLength
virtual void setFormat ( PcmAudioFormat format)
pure virtual

Specifies the PCM audio format of the audio source.

This is used as a hint for the audio plugin that will be used to decode the audio data.

A plugin can use this format if the audio source is raw PCM data and therefore has no meta information describing the PCM format. A plugin can also ignore the format hint if it can be determined by the meta information in the audio source.

Parameters
format[in] a pointer to a structure that describes the PCM format of the audio source.
virtual void setFullLength ( int32_t  frames)
pure virtual

Sets the full length of the audio input.

Parameters
framesAudio length in CDDA frames (1 CDDA frame = 2352 bytes). The audio length must be either a non-negative value or -1. The special value of -1 is the default one and means that the full length of the audio input is unknown. In this case AudioCD parses the audio input and determines its full length. Any other negative value except -1 is ignored.
Remarks
Usually it's not needed to set explicitly the full length of the audio input. This method can be useful when the audio input storage (file/stream) is changed after the audio input has been added to AudioCD. In this case resetting the full length to -1 will make AudioCD parse the audio input once again when it needs to determine its full length. Otherwise AudioCD will use the existing full length (if it's a non-negative value).
virtual void setStartFrame ( int32_t  frame)
pure virtual

Sets the first frame of audio that will be written to the disc.

This is used in case you do not want to read the audio from the beginning of the file.

This method does not validate its parameters against the end frame and the length of the file.

Parameters
frameStart frame. It must be >= 0. Negative values are ignored.
virtual void setStorageType ( AudioStorage::Enum  storage)
pure virtual

Sets the audio storage type.

Parameters
storageA constant from the AudioStorage enumeration.

If you do not set an audio storage type, the default value of AudioStorage::File will be used.

If the audio input is in a CD Audio format (raw PCM, 44100 Hz, 16-bit, stereo) it is used directly and no plug-in is needed to 'decode' the audio source. In addition such audio source is never decoded in a temp file. The CD Audio format can be specified with the special extension (.cd-audio).

See Also
AudioStorage::Enum
AudioInput::setStream
AudioInput::setFilePath
virtual void setStream ( primo::Stream stream)
pure virtual

Set the input stream that should be used for reading audio data during audio track creation.

In order for this method to work AudioStorage::Stream should be set as an audio storage using the setStorageType method.

Parameters
stream[in] a pointer to an object that implements primo::Stream.

NOTE: AudioInput::filePath must be set to the file extension, in order to specify the Stream type.

For example, if the stream represents a wav input, the file path should be set to ".wav".

If the audio input is in a CD Audio format (raw PCM, 44100 Hz, 16-bit, stereo) it is used directly and no plug-in is needed to 'decode' the audio source. In addition such audio source is never decoded in a temp file. The CD Audio format can be specified with the special extension (.cd-audio).

See Also
AudioInput::setFilePath
AudioInput::setStorageType
virtual int32_t startFrame ( ) const
pure virtual

Gets the value set with setStartFrame.

Returns
start frame address
virtual AudioStorage::Enum storageType ( ) const
pure virtual

Gets the audio storage type.

Returns
A constant from the AudioStorage enumeration.
See Also
AudioStorage::Enum
AudioInput::stream
AudioInput::filePath
AudioInput::storageType
virtual primo::Stream* stream ( ) const
pure virtual

Gets the audio stream set with setStream.

Returns
A pointer to an object that implements primo::Stream or NULL if no stream is set.