Xaudio SYNC API


The Xaudio SYNC API is a low-level API that is used when the client software needs precise and detailed access to the decoding loop and to the input and output data samples.
In general, this API is not used when writing applications that have a GUI (Graphical User Interface), because the Xaudio ASYNC API is much better suited to this kind of application.
Typical client software applications that will use the SYNC API include, but are not limited to:
With the SYNC API, the controlling application first creates a decoder object ( XA_DecoderInfo), then registers the input and output modules it wishes to use (decoder_input_module_register(), decoder_output_module_register()), possibly adds input or output filters (decoder_input_add_filter(), decoder_output_add_filter()), and is ready to decode and play the input stream.
To start decoding an input stream, the controlling application needs to create an input stream (decoder_input_new()), then open it (decoder_input_open()). Then, if the controlling application wants the decoded audio samples to be sent to an output module like the built-in Audio Sound Card Output Module, it needs to create an output module (decoder_output_new()), and open it (decoder_output_open()), otherwise, if it just needs to decode the input stream and get access to the decoded data, it can work without an output module.
At this point, the controlling application can make calls to decode small chunks of the input stream (called frames), by calling decoder_play() if it wants the decoded samples to be sent to the output, or decoder_decode() it if wants to simple decode the chunk and get access to the decoded buffer.
As the controlling application repeats calls to decoder_play() or decoder_decode(), the library will maintain the XA_DecoderInfo up to date, with information about the current offset in the input stream, the stream information, etc...
If the controlling application needs to change to a different location in the input stream, it can do so by calling one of the seek functions (decoder_input_seek_to_position(), decoder_input_seek_to_time(), decoder_input_seek_to_timecode()).
When the end of the input stream is reached, the call to decoder_play() or decoder_decode() will return XA_ERROR_INPUT_EOF. At this point (or at any other point during the decoding), the controlling application can choose to close the input (decoder_input_close()), and open a new one, or any other action it needs to do.
At any point, the controlling application can use the supporting functions to set/get environment variables, set/get the codec equalizer, etc...

Function Index


decoder_version

Returns information about the version of the Xaudio library.
char* XA_EXPORT decoder_version(char **major, char **minor, char **state);
char* XA_Decoder::Version(char **major, char **minor, char **state);
major [returns] A pointer to a read-only string containing the major version name. This parameter can be NULL if the caller does not want to receive this information.
minor [returns] A pointer to a read-only string containing the minor version number. This parameter can be NULL if the caller does not want to receive this information.
state [returns] A pointer to a read-only string containing the state (alpha, beta, etc...). This parameter can be NULL if the caller does not want to receive this information.
A read-only string with the full version name.
decoder.h

decoder_new

Creates a new instance of a decoder object. If it succeeds, a pointer to the new object is returned by storing it in the location passed as an argument.
int XA_EXPORT decoder_new(XA_DecoderInfo **decoder);
XA_Decoder::XA_Decoder();
decoder Pointer to the variable in which the pointer to the new decoder object will be returned.
Returns XA_SUCCESS if the decoder has been created, or a negative error code if the call failed.
decoder.h
decoder_delete()

decoder_delete

Deletes a decoder object previously created by a call to decoder_new(). Resources attached to the decoder object are released. If the decoder still has any instantiated input or output objects, they will be closed and deleted.
int XA_EXPORT decoder_delete(XA_DecoderInfo *decoder);
XA_Decoder:~XA_Decoder();
decoder Pointer to the decoder object to delete.
Returns XA_SUCCESS if the decoder has been deleted, or a negative error code if the call failed.
decoder.h
decoder_new()

decoder_input_module_register

Registers an input module in the list of attached input modules. If the call succeeds, a module ID (positive integer) is returned, that can be used subsequently to identify this specific module.
See section on input modules for more details.
int XA_EXPORT decoder_input_module_register(XA_DecoderInfo *decoder, const XA_InputModule *module);
int XA_Decoder::InputModuleRegister(const XA_InputModule *module);
decoder Pointer to an instantiated decoder object.
module Pointer to the input module to register.
Returns a positive input module ID if the registration succeeds, or a negative error code if it fails.
decoder.h
decoder_input_open()

decoder_input_module_query

Retrieves information about a registered input module. Information about a given module ID (as returned by decoder_input_module_register()) is returned in the fields of an XA_InputModuleQuery structure. The type of information returned depends on the flags passed as a parameter.
See section on input module queries for details about the query flags and returned information.
int XA_EXPORT decoder_input_module_query(XA_DecoderInfo *decoder, int module, XA_InputModuleQuery *query, unsigned long query_flags);
int XA_Decoder::InputModuleQuery(int module, XA_InputModuleQuery *query, unsigned long query_flags);
decoder Pointer to an instantiated decoder object.
module Integer ID of a registered input module.
query Pointer to a XA_InputModuleQuery where information about the module will be returned.
query_flags Flags (combined bitmask) specifying what type of information should be returned.
Returns XA_SUCCESS if the information requested can be returned, or a negative error code if it cannot.
decoder.h
decoder_input_module_register()

decoder_input_add_filter

Adds an input filter for the decoder. An input filter is a function table that will bridge calls between the decoder and the input module. Several input filters can be inserted between the decoder and the input module. Filters are chained, they are called in order from the first to the last. When inserting a new filter, an ID specifies at which point in the list of current input filters it should be added. The special value XA_DECODER_INPUT_FILTER_FIRSTCODE(XA_DECODER_INPUT_FILTER_LAST) will insert it as the last in the chain, and any other ID value will insert the filter before the existing filter with that ID.
int XA_EXPORT decoder_input_add_filter(XA_DecoderInfo *decoder, const XA_InputFilter *filter, int where);
int XA_Decoder::InputAddFilter(const XA_InputFilter *filter, int where);
decoder Pointer to an instantiated decoder.
filter Pointer to a XA_InputFilter containing the filter's function table.
where ID of the filter before which the new filter should be inserted, or the special values XA_DECODER_INPUT_FILTER_FIRST or XA_DECODER_INPUT_FILTER_LAST.
Returns a positive integer filter ID if the call succeeds, or a negative error code if it fails.
decoder.h
decoder_input_remove_filter()

decoder_input_remove_filter

Removes a filter from the decoder's input filters chain. The filter to be removed can be identified by name or by ID. If the filter ID parameter has the special value XA_DECODER_INPUT_FILTER_BY_NAME, then the filter to be removed will be identified by name, for any other value of that parameter, the filter will be identified by ID, and the 'name' parameter will be ignored. Special value XA_DECODER_INPUT_FILTER_FIRSTCODE(XA_DECODER_INPUT_FILTER_LAST) will remove the last filter in the chain, and any other ID value will remove the filter with that ID.
int XA_EXPORT decoder_input_remove_filter(XA_DecoderInfo *decoder, const char *name, int id);
int XA_Decoder::InputRemoveFilter(const char *name, int id);
decoder Pointer to an instantiated decoder.
name Name of the filter to remove (this parameter is only valid when the 'id' parameter is XA_DECODER_INPUT_FILTER_BY_NAME).
id ID of the filter to remove, or values XA_DECODER_INPUT_FILTER_FIRSTCODE(XA_DECODER_INPUT_FILTER_LAST).
Returns XA_SUCCESS if the call succeeds, or a negative error code if it fails.
decoder.h
decoder_input_add_filter()

decoder_input_new

Instantiates a new input object for the decoder.
An input is created based on its name and module ID (passed as a parameter to the function). If the module ID is a positive integer of a registered input module (value returned by decoder_input_module_register()), an input object of that type will be created. If the module ID has the special value XA_DECODER_INPUT_AUTOSELECT, then the library will perform a probe of the registered input modules to find which one to use.
See section about input modules for more details about probing and other instantiation details.
When a new input object is instantiated, a handle to the object is stored in the decoder's internal data structure, and its value is not available to the client of the decoder (and it is not needed). If the decoder had already a handle to an instantiated input object, this object will be automatically deleted before the new one is created, because the decoder can only have one active input at any given time.
int XA_EXPORT decoder_input_new(XA_DecoderInfo *decoder, const char *name, int module);
int XA_Decoder::InputNew(const char *name, int module);
decoder Pointer to an instantiated decoder object.
name Name (character string) of the input.
module Positive ID of the input module to use, or special value XA_DECODER_INPUT_AUTOSELECT.
Returns XA_SUCCESS if the input object has been created, or a negative error code if the call failed.
decoder.h
decoder_input_delete()

decoder_input_delete

Deletes the input object of the decoder. Resources associated with the input are released. If the input was open, it will automatically be closed before being deleted.
int XA_EXPORT decoder_input_delete(XA_DecoderInfo *decoder);
int XA_Decoder::InputDelete(XA_DecoderInfo *decoder);
decoder Pointer to an instantiated decoder object.
Returns XA_SUCCESS if the call succeeds, or negative error code if it fails.
decoder.h
decoder_input_new()

decoder_input_open

Opens the input of the decoder.
int XA_EXPORT decoder_input_open(XA_DecoderInfo *decoder);
int XA_Decoder::InputOpen();
decoder Pointer to an instantiated decoder object.
Returns XA_SUCCESS if the input has been successfully opened, or a negative error code if it has not.
decoder.h
decoder_input_close()

decoder_input_close

Closes the input of the decoder.
int XA_EXPORT decoder_input_close(XA_DecoderInfo *decoder);
int XA_Decoder::InputClose();
decoder Pointer to an instantiated decoder object.
Returns XA_SUCCESS if the input has been closed, or a negative error code if the call failed.
decoder.h
decoder_input_open()

decoder_input_seek_to_offset

Seeks to a specified position in the input stream. If the current input does not have the ability to seek (flag XA_DECODER_INPUT_SEEKABLE) set in the input capabilities flags), nothing is done.
The offset parameter to this call is a byte offset from the start of the input stream.
int XA_EXPORT decoder_input_seek_to_offset(XA_DecoderInfo *decoder, unsigned long offset);
int XA_Decoder::InputSeekToOffset(unsigned long offset);
decoder Pointer to an instantiated decoder object.
offset Integer byte offset from the start of the input stream.
Returns XA_SUCCESS if it succeeds, or a negative error code if it fails.
decoder.h
decoder_input_seek_to_position(), decoder_input_seek_to_time(), decoder_input_seek_to_timecode().

decoder_input_seek_to_position

Seeks to a specified position in the input stream. If the current input does not have the ability to seek (flag XA_DECODER_INPUT_SEEKABLE set in the input capabilities flags), nothing is done.
The position parameter to this call is a floating point number between 0.0 and 1.0, where 0.0 is the start of the input stream, and 1.0 the end of the input stream (ex: 0.5 would be the middle of the input stream).
int XA_EXPORT decoder_input_seek_to_position(XA_DecoderInfo *decoder, float position);
int XA_Decoder::InputSeekToPosition(float position);
decoder Pointer to an instantiated decoder object.
position Floating point position between the start and the end of the input stream.
Returns XA_SUCCESS if it succeeds, or a negative error code if it fails.
decoder.h
decoder_input_seek_to_offset(), decoder_input_seek_to_time(), decoder_input_seek_to_timecode().

decoder_input_seek_to_time

Seeks to a specified position in the input stream. If the current input does not have the ability to seek (flag XA_DECODER_INPUT_SEEKABLE set in the input capabilities flags), nothing is done.
The seconds parameter to this call is the number of seconds from the start of the input stream (floating point).
int XA_EXPORT decoder_input_seek_to_time(XA_DecoderInfo *decoder, float seconds);
int XA_Decoder::InputSeekToTime(float seconds);
decoder Pointer to an instantiated decoder object.
seconds Floating point number of seconds from the start of the input stream.
Returns XA_SUCCESS if it succeeds, or a negative error code if it fails.
decoder.h
decoder_input_seek_to_offset(), decoder_input_seek_to_position(), decoder_input_seek_to_timecode().

decoder_input_seek_to_timecode

Seeks to a specified position in the input stream. If the current input does not have the ability to seek (flag XA_DECODER_INPUT_SEEKABLE set in the input capabilities flags), nothing is done.
The timecode parameter to this call is a pointer to an absolute timecode structure.
int XA_EXPORT decoder_input_seek_to_timecode(XA_DecoderInfo *decoder, const XA_TimeCode *timecode);
int XA_Decoder::InputSeekToTimecode(const XA_TimeCode *timecode);
decoder Pointer to an instantiated decoder object.
timecode Pointer to a XA_TimeCode structure that specifies where to seek.
Returns XA_SUCCESS if it succeeds, or a negative error code if it fails.
decoder.h
decoder_input_seek_to_offset(), decoder_input_seek_to_position(), decoder_input_seek_to_time().

decoder_output_module_register

Registers an output module in the list of attached output modules. If the call succeeds, a module ID (positive integer) is returned, that can be used subsequently to identify this specific module.
See section on output modules for more details.
int XA_EXPORT decoder_output_module_register(XA_DecoderInfo *decoder, const XA_OutputModule *module);
int XA_Decoder::OutputModuleRegister(const XA_OutputModule *module);
decoder Pointer to an instantiated decoder object.
module Pointer to the output module to register.
Returns a positive output module ID if the registration succeeds, or a negative error code if it fails.
decoder.h
decoder_output_open()

decoder_output_module_query

Retrieves information about a registered output module. Information about a given module ID (as returned by decoder_output_module_register()) is returned in the fields of an XA_OutputModuleQuery structure. The type of information returned depends on the flags passed as a parameter.
See section on output module queries for details about the query flags and returned information.
int XA_EXPORT decoder_output_module_query(XA_DecoderInfo *decoder, int module, XA_OutputModuleQuery *query, unsigned long query_flags);
int XA_Decoder::OutputModuleQuery(int module, XA_OutputModuleQuery *query, unsigned long query_flags);
decoder Pointer to an instantiated decoder object.
module Integer ID of a registered output module.
query Pointer to a XA_OutputModuleQuery where information about the module will be returned.
query_flags Flags (combined bitmask) specifying what type of information should be returned.
Returns XA_SUCCESS if the information requested can be returned, or a negative error code if it cannot.
decoder.h
decoder_output_module_register()

decoder_output_add_filter

Adds an output filter for the decoder. An output filter is a function table that will bridge calls between the decoder and the output module. Several output filters can be inserted between the decoder and the output module. Output filters are chained, and called in order from the first to the last. When inserting a new filter, an ID specifies at which point in the list of current output filters it should be added. The special value XA_DECODER_OUTPUT_FILTER_FIRSTCODE(XA_DECODER_OUTPUT_FILTER_LAST) will insert it as the last filter in the chain, and any other ID value will insert the filter before the existing filter with that ID.
int XA_EXPORT decoder_output_add_filter(XA_DecoderInfo *decoder, const XA_OutputFilter *filter, int where);
int XA_Decoder::OutputAddFilter(const XA_OutputFilter *filter, int where);
decoder Pointer to an instantiated decoder.
filter Pointer to a XA_OutputFilter containing the filter's function table.
where ID of the filter before which the new filter should be inserted, or the special values XA_DECODER_OUTPUT_FILTER_FIRST or XA_DECODER_OUTPUT_FILTER_LAST.
Returns a positive integer filter id is the call succeeds, or a negative error code if it fails.
decoder.h
decoder_output_remove_filter()

decoder_output_remove_filter

Removes a filter from the decoder's output filter chain. The filter to be removed can be identified by name or by ID. If the filter ID parameter has the special value XA_DECODER_OUTPUT_FILTER_BY_NAME, then the filter to be removed will be identified by name, for any other value of that parameter, the filter will be identified by ID, and the 'name' parameter will be ignored. Special value XA_DECODER_OUTPUT_FILTER_FIRSTCODE(XA_DECODER_OUTPUT_FILTER_LAST) will remove the last filter in the chain, and any other ID value will remove the filter with that ID.
int XA_EXPORT decoder_output_remove_filter(XA_DecoderInfo *decoder, const char *name, int id);
int XA_Decoder::OutputRemoveFilter(const char *name, int id);
decoder Pointer to an instantiated decoder.
name Name of the filter to remove (this parameter is only valid when the 'id' parameter is XA_DECODER_OUTPUT_FILTER_BY_NAME).
id ID of the filter to remove, or values XA_DECODER_OUTPUT_FILTER_FIRSTCODE(XA_DECODER_OUTPUT_FILTER_LAST).
Returns XA_SUCCESS if the call succeeds, or a negative error code if it fails.
decoder.h
decoder_output_add_filter()

decoder_output_new

Instantiates a new output object for the decoder.
An output is created based on its name and module ID (passed as a parameter to the function). If the module ID is a positive integer of a registered output module (value returned by decoder_output_module_register()), an output object of that type will be created. If the module ID has the special value XA_DECODER_OUTPUT_AUTOSELECT, then the library will perform a probe of the registered output modules to find which one to use.
See section about output modules for more details about probing and other instantiation details.
If the name is the NULL pointer, or an empty string (""), the default output of the required module will be chosen (typically, the default soundcard for a soundcard driver output module).When a new output object is instantiated, a handle to the object is stored in the decoder's internal data structure, and its value is not available to the client of the decoder (and it is not needed). If the decoder had already a handle to an instantiated output object, this object will be automatically deleted before the new one is created, because the decoder can only have one active output at any given time.
int XA_EXPORT decoder_output_new(XA_DecoderInfo *decoder, const char *name, int module);
int XA_Decoder::OutputNew(const char *name, int module);
decoder Pointer to an instantiated decoder object.
name Name (character string) of the output.
module Positive ID of the output module to use, or special value XA_DECODER_OUTPUT_AUTOSELECT.
Returns XA_SUCCESS if the output object has been created, or a negative error code if the call failed.
decoder.h
decoder_output_delete()

decoder_output_delete

Deletes the output object of the decoder. Resources associated with the output are released. If the output was open, it will automatically be closed before being deleted.
int XA_EXPORT decoder_output_delete(XA_DecoderInfo *decoder);
int XA_Decoder::OutputDelete();
decoder Pointer to an instantiated decoder object.
Returns XA_SUCCESS if the call succeeds, or negative error code if it fails.
decoder.h
decoder_output_new()

decoder_output_open

Opens the output of the decoder.
int XA_EXPORT decoder_output_open(XA_DecoderInfo *decoder);
int XA_Decoder::OutputOpen();
decoder Pointer to an instantiated decoder object.
Returns XA_SUCCESS if the output has been successfully opened, or a negative error code if it has not.
decoder.h
decoder_output_close()

decoder_output_close

Closes the output of the decoder.
int XA_EXPORT decoder_output_close(XA_DecoderInfo *decoder);
int XA_Decoder::OutputClose();
decoder Pointer to an instantiated decoder object.
Returns XA_SUCCESS if the output has been closed, or a negative error code if the call failed.
decoder.h
decoder_output_open()

decoder_output_set_control

Sets device-specific parameters of the output of the decoder, and/or performs device-specific operations on the output of the decoder. The control_flags function parameter specifies which operations to perform and which parameters to set. The control function parameter points to a structure that contains the values of the parameters to set, or NULL if not parameter is to be set (only operations are to be performed).
int XA_EXPORT decoder_output_set_control(XA_DecoderInfo *decoder, XA_OutputControl *control, unsigned long control_flags);
int XA_Decoder::OutputSetControl(XA_OutputControl *control, unsigned long control_flags);
decoder Pointer to an instantiated decoder object.
control Pointer to a XA_OutputControl structure that contains the values of parameters to set, or NULL if not parameter values are needed.
control_flags Combination of output operation flags and parameter setting flags. See section on output control for more details on the operations that can be performed and parameters that can be set.
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed.
decoder.h
decoder_output_get_control()

decoder_output_get_control

Reads device-specific parameters of the output of the decoder. The control_flags function parameter specifies which parameters to read. The control function parameter points to a structure where the values of the parameters to read will be returned.
int XA_EXPORT decoder_output_get_control(XA_DecoderInfo *decoder, XA_OutputControl *control, unsigned long control_flags);
int XA_Decoder::OutputGetControl(XA_OutputControl *control, unsigned long control_flags);
decoder Pointer to an instantiated decoder object.
control Pointer to a XA_OutputControl structure where the values of parameters to read will be returned.
control_flags Combination of output operation flags and parameter setting flags. See section on output control for more details on the operations that can be performed and parameters that can be set.
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed.
decoder.h
decoder_output_set_control()

decoder_codec_set_equalizer

Sets the values for the codec equalizer of the decoder. The equalizer consists of scaling factors for each of the frequency bands of the codec. See section on Codec Equalizer for more details on equalizer values.
int XA_EXPORT decoder_codec_set_equalizer(XA_DecoderInfo *decoder, XA_EqualizerInfo *equalizer);
int XA_Decoder::CodecSetEqualizer(XA_EqualizerInfo *equalizer);
decoder Pointer to an instantiated decoder object.
equalizer Pointer to a structure that contains the scaling factors for the frequency bands of the codec.
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed.
decoder.h
decoder_codec_get_equalizer()

decoder_codec_get_equalizer

Reads the values of the codec equalizer of the decoder. The equalizer consists of scaling factors for each of the frequency bands of the codec. See section on Codec Equalizer for more details on equalizer values.
int XA_EXPORT decoder_codec_get_equalizer(XA_DecoderInfo *decoder, XA_EqualizerInfo *equalizer);
int XA_Decoder::CodecGetEqualizer(XA_EqualizerInfo *equalizer);
decoder Pointer to an instantiated decoder object.
equalizer Pointer to a structure where the scaling factors for the frequency bands of the codec will be returned.
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed.
decoder.h
decoder_codec_set_equalizer()

decoder_set_environment_integer

Assigns an integer value to an environment variable. See section on environment variables for more details about the use of environment variables.
int XA_EXPORT decoder_set_environment_integer(XA_DecoderInfo *decoder, const char *name, long value);
int XA_Decoder::SetEnvironemtInteger(const char *name, long value);
decoder Pointer to an instantiated decoder object.
name Name of the environment variable (constant string).
value Integer value to assign to the environment variable.
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed.
decoder.h
decoder_get_environment_integer(), decoder_set_environment_string(), decoder_get_environment_string()

decoder_get_environment_integer

Reads the value of an environment variable containing an integer. See section on environment variables for more details about the use of environment variables.
int XA_EXPORT decoder_get_environment_integer(XA_DecoderInfo *decoder, const char *name, long *value);
int XA_Decoder::GetEnvironmentInteger(const char *name, long *value);
decoder Pointer to an instantiated decoder object.
name Name of the environment variable (constant string).
value Pointer to the address where the integer value of the environment variable should be returned
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed. If no environment variable with the requested name exists, XA_ERROR_NO_SUCH_ENVIRONMENT is returned. If an environment variable with the required name exists but does not have an integer value, XA_ERROR_ENVIRONMENT_TYPE_MISMATCH is returned.
decoder.h
decoder_set_environment_integer(), decoder_set_environment_string(), decoder_get_environment_string()

decoder_set_environment_string

Assigns a string value to an environment variable. See section on environment variables for more details about the use of environment variables.
int XA_EXPORT decoder_set_environment_string(XA_DecoderInfo *decoder, const char *name, const char *value);
int XA_Decoder::SetEnvironmentString(const char *name, const char *value);
decoder Pointer to an instantiated decoder object.
name Name of the environment variable (constant string).
value String value to assign to the environment variable.
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed.
decoder.h
decoder_get_environment_string(), decoder_set_environment_integer(), decoder_get_environment_integer()

decoder_get_environment_string

Reads the value of an environment variable containing a string. See section on environment variables for more details about the use of environment variables.
int XA_EXPORT decoder_get_environment_string(XA_DecoderInfo *decoder, const char *name, char *value);
int XA_Decoder::GetEnvironmentString(const char *name, char *value);
decoder Pointer to an instantiated decoder object.
name Name of the environment variable (constant string).
value Pointer to the address where the string value of the environment variable should be returned
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed. If no environment variable with the requested name exists, XA_ERROR_NO_SUCH_ENVIRONMENT is returned. If an environment variable with the required name exists but does not have a string value, XA_ERROR_ENVIRONMENT_TYPE_MISMATCH is returned.
decoder.h
decoder_set_environment_string(), decoder_set_environment_integer(), decoder_get_environment_integer()

decoder_unset_environment

Removes an environment variable from the pool of current environment variables of the decoder.
int XA_EXPORT decoder_unset_environment(XA_DecoderInfo *decoder, const char *name);
int XA_Decoder::UnsetEnvironment(const char *name);
decoder Pointer to an instantiated decoder object.
name Name of the environment variable (constant string).
Returns XA_SUCCESS if the call succeeds, or a negative error code if the call failed. If no environment variable with the requested name exists, XA_ERROR_NO_SUCH_ENVIRONMENT is returned.
decoder.h
decoder_set_environment_string(), decoder_get_environment_string(), decoder_set_environment_integer(), decoder_get_environment_integer()

decoder_decode

Decodes one frame of compressed audio data.
The decoder object must have an instantiated and open input (see decoder_input_new() and decoder_input_open()). The location of the buffer where the output samples should be stored can be specified as a parameter, or the decoder can use its internal samples buffer if that parameter is set to NULL. The return value of the function indicates whether a frame has been successfully decoded, and the resulting samples stored in the output buffer, or if an error has occurred. If a frame has been decoded, all the information about the output buffer is contained in the fields of the output_buffer structure (type XA_OutputBufferInfo) of the decoder object, including the pointer to the memory location where the samples are stored.
See section about the Samples Format for more details on how samples are stored in the output buffer.
int XA_EXPORT decoder_decode(XA_DecoderInfo *decoder, void *output_buffer);
int XA_Decoder::Decode(void *output_buffer);
decoder Pointer to an instantiated decoder object.
output_buffer Pointer to memory location where the samples should be stored (if this value is NULL, the library will use an internal buffer to store the samples, and the address of this internal buffer can be read from the field decoder->output_buffer->pcm_samples.
Returns XA_SUCCESS if a frame has been decoded and the samples stored in the buffer, XA_ERROR_INVALID_FRAME if the decoder detected an error in the bitstream (this is a non fatal error, the client can continue to decode subsequent frames), XA_ERROR_TIMEOUT if there was not enough data available to decode one full frame (this might happen if the input source is a network stream, or a circular buffer filled by an external client. This is also a non fatal error, and the client can continue do decode from the same point), or a negative error code for any other error.
decoder.h
decoder_play()

decoder_play

Decodes one frame of compressed audio data and sends the samples to the output module.
This function internally calls decoder_decode() to decode a frame, and if the decoding is successful, the output samples are sent to the output module by calling the output module's output_write() function. In addition for the requirements of the decoder_decode() function, the decoder object must have an instantiated and open output object (see decoder_output_new() and decoder_output_open()).
int XA_EXPORT decoder_play(XA_DecoderInfo *decoder);
int XA_Decoder::Play();
decoder Pointer to an instantiated decoder object.
Returns XA_SUCCESS if a frame has been decoded, the samples stored in the buffer and sent to the output module, XA_ERROR_INVALID_FRAME if the decoder detected an error in the bitstream (this is a non fatal error, the client can continue to decode subsequent frames), XA_ERROR_TIMEOUT if there was not enough data available to decode one full frame (this might happen if the input source is a network stream, or a circular buffer filled by an external client. This is also a non fatal error, and the client can continue do decode from the same point), or a negative error code for any other error.
decoder.h
decoder_decode()