Built-In Modules

The Xaudio Library contains a number of built-in input and output modules.

When using the ASYNC API (sending messages to an XA_Player object), all built-in modules are automatically registered  when the player is created. If the client software wants to get a list of the attached built-in modules, it can do so by sending the XA_MSG_COMMAND_INPUT_MODULES_LIST, or XA_MSG_COMMAND_OUTPUT_MODULES_LIST.
When using the SYNC API (managing an XA_DecoderInfo object through direct function calls), if the client software needs to use any of the built-in modules, it needs to register them just after creating the XA_DecoderInfo object. It can also register any number of custom input or output modules.


Input Modules

File Input Module

This is a very simple input module, and any player that runs on  a platform with a disk drive will probably want to use it.
It takes care of doing the input from a regular file on the disk.

Input Name Syntax

The syntax for an input name for the file input module is simply the file name, using the platform's file naming conventions.

Examples

control_message_send(player, XA_MSG_COMMAND_INPUT_OPEN, "c:\bits\mp3\miles.mp3"); (Windows)
or
control_message_send(player, XA_MSG_COMMAND_INPUT_OPEN, "/bits/mp3/miles.mp3"); (Unix)

Registration Function (SYNC API only)

int XA_EXPORT file_input_module_register(XA_InputModule *module);
When registering the module using the SYNC API, the header file file_input.h should be included to get the prototype of the registration function of the file input module.
 

Network Stream Input Module

This is an input module that supports streaming from a network connection. It supports HTTP, FTP, and raw UDP. This modules does smooth buffering to avoid network jitters, etc...

Input Name Syntax

For HTTP and FTP, the input name is simply a URL.
For UDP, the syntax is: udp://hostname:port, where hostname is the host where the UDP packets come from (currently, the module will ignore that value, and will accept UDP packets regardless of where they come from), and port is the UDP port number for receiving the packets.

Examples

control_message_send(player, XA_MSG_COMMAND_INPUT_OPEN, "http://my.sever.com/mp3/miles.mp3");
or
control_message_send(player, XA_MSG_COMMAND_INPUT_OPEN, "ftp://myname:mypassword@my.server.com/mp3/miles.mp3");
or
control_message_send(player, XA_MSG_COMMAND_INPUT_OPEN, "udp://localhost:9000");
 

Registration Function (SYNC API only)

int XA_EXPORT stream_input_module_register(XA_InputModule *module);
When registering the module using the SYNC API, the header file stream_input.h should be included to get the prototype of the registration function of the stream input module.
 

Memory Input Module

This is a simple input module that is used when you want to decode a bitstream from a memory buffer. It supports 2 modes: reading the stream from a circular input buffer (streaming input, never ends), or reading the stream from a linear input buffer (ends when all the input bytes have been consumed).
When using a circular input buffer, an additional function is provided for the client to store data into the circular buffer.
This module is only used with the SYNC API.

Input Name Syntax

The name syntax for that module is:
An NULL or empty string ("") name tells the module to work in circular buffer mode.
A name in the form "size@addr" tells the module to use a linear buffer of 'size' bytes, starting at address 'addr', size and addr are expressed as hexadecimal numbers (Example: 2FFD6@8FFCDA23C)

Examples

decoder_input_new(decoder, NULL, XA_DECODER_INPUT_AUTOSELECT);
(for a circular input buffer)

or

decoder_input_new(decoder, "65536@1576869476", XA_DECODER_INPUT_AUTOSELECT);
(for a linear input buffer)

NOTE: if you use the XA_DECODER_INPUT_AUTOSELECT method, the memory input module should probably be the only input module registered at that time, otherwise another module might accept the NULL name.
 

Registration Function (SYNC API only)

int XA_EXPORT memory_input_module_register(XA_InputModule *module);
When registering the module using the SYNC API, the header file memory_input.h should be included to get the prototype of the registration function of the memory input module.

Support Functions

int XA_EXPORT memory_input_feed(void *device, unsigned char *data, unsigned int bytes);
Call this function to store data into the circular input buffer. Pass a pointer ('data') to  the data you want to store into the buffer, and the number of bytes of data ('bytes'). This function returns the number of bytes that have been stored into the buffer (it could be less than the number of bytes passed as an argument, because there might not have been enough space available in the input buffer).


int XA_EXPORT memory_input_flush(void *device);

Call this function to flush the contents of the circular input buffer (when using the streaming mode).


Output Modules

Audio Sound Card Ouput Module

For each of the supported platforms, a built-in module will implement the output to the sound card.

Output Name Syntax

To get the output to be played back through the default soundcard, use a NULL or empty ("") name. In that case, the output module will automatically select the first available soundcard.
If the platform has several soundcards, and the client software needs to specify a specific card, then a non NULL can be used to choose the card. In that case, the name syntax depends on the platform. (see the section about platform specific options for more details).

Registration Function (SYNC API only)

int XA_EXPORT audio_output_module_register(XA_OutputModule *module);
When registering the module using the SYNC API, the header file file_input.h should be included to get the prototype of the registration function of the file input module.

File Output Module

This is a very simple output module, and any player that runs on  a platform with a disk drive will probably want to use it.
It takes care of doing the output to a regular file on the disk (either in RAW or WAVE format).

Output Name Syntax

The syntax for an input name for the file output module is simply the file name, using the platform's file naming conventions, or the file name preceded with the prefix "wav:" to add a WAVE file header at the beginning of the file.

Examples

control_message_send(player, XA_MSG_COMMAND_OUTPUT_OPEN, "wav:c:\bits\wav\miles.wav"); (Windows)
or
control_message_send(player, XA_MSG_COMMAND_OUTPUT_OPEN, "wav:/bits/wav/miles.wav"); (Unix)

Registration Function (SYNC API only)

int XA_EXPORT file_output_module_register(XA_OutputModule *module);
When registering the module using the SYNC API, the header file file_input.h should be included to get the prototype of the registration function of the file input module.