| Methods |
Description |
|
Init |
Initializes
the control. |
|
Priority |
Sets the priority of the
player. |
|
Play |
Plays the opened file. |
|
Pause |
Pauses the file
currently being played. |
|
Stop |
Stops the current file. |
|
Seek |
Seeks to a specified offset in the file.
Offset and Range are used to dictate
the percentage of the file that you want to seek past.
For example: offset = 10, range = 100 would seek past
the first 10% of the file.
|
| InputOpen |
Tells the player to open the input stream. The parameter
to this message is the name (text string) of the input
to open. Unless the input module has been set to a specific
value the player will 'autoselect' the correct input
module based on the input name.
Typically, the input name is the name of the file on
the disk that contains the stream, or a URL for network
streaming.
If the player can successfully open the input, it will
notify of the new input state by sending back an XA_MSG_NOTIFY_INPUT_STATE
message with a state field of XA_PLAYER_INPUT_STATE_OPEN
|
| InputClose |
Closes the open file. |
| OutputMute |
Mutes
the sound output. |
| OutputUnmute |
Unmutes the sound. |
| PositionRange |
Sets
the range to use for the position. For example,
a value of 10 would make the position go from 0-10 over
the course of playing the file. |
| TimecodeGranularity |
Sets the player's timecode granularity.
This is used by the player to know how frequently
to send back INPUT_TIMECODE messages to notify of the
current stream's timecode. The default is 100, which
means that the player will send an INPUT_TIMECODE message
every 100 'ticks' (there are 100 'ticks' per second,
so this will trigger a message every second).
The client should increase or decrease this value depending
on how often it wishes to receive timecode notifications.
|
| Volume |
Sets the player's output volume parameters.
The output volume is specified as a set or 3 values
(master level, pcm level, and balance).
The master level refers to the general sound volume
of the soundcard (affects all of the soundcards inputs,
like CD, Microphone, WAV, MIDI, etc...). The master
level value is an integer between 0 (silent) and 100
(maximum loudness).The PCM level refers to the sound
volume of the PCM (also called WAVE on some mixers)
input to the mixer (does not affect other soundcard
inputs). The PCM level value is an integer between 0
(silent) and 100 (maximum loudness).
The balance is used to give a higher sound level to
the left or right speaker. The balance setting is a
value between 0 (sound totally on the left side) and
100 (sound totally on the right side), so a sound evenly
distributed between left and right sides would be a
balance setting of 50.
When the player is created it uses the current setting
of the soundcard.
|
| Channels |
Sets the player's output channels settings.
There are 4 different channels settings possible:
XA_OUTPUT_STEREO: decode and output both channels if
the stream is stereo.
XA_OUTPUT_MONO_LEFT: decode and output the left channel
only channels if the stream is stereo.
XA_OUTPUT_MONO_RIGHT: decode and output the right channel
only if the stream is stereo.
XA_OUTPUT_MONO_MIX: decode both channels and output
one channel that is a mix of both decoded channels (this
uses less CPU than XA_OUTPUT_STEREO).
|
| Ports |
Sets the player's output ports settings.
An output ports configuration is a combination of flags
that indicate which of the different ports of the soundcard
is enabled.
There are 3 flags defined:
XA_DECODER_CONTROL_OUTPUT_LINE: the 'line out' output
of the soundcard.
XA_DECODER_CONTROL_OUTPUT_SPEAKER: the 'speaker out'
output of the soundcard.
XA_DECODER_CONTROL_OUTPUT_HEADPHONE: the 'headphone
out' output of the soundcard.
Note that not all soundcards support multiple output
ports.
|
| NotificationMask |
Sets the player's notification mask. This mask is used
to block or unblock certain types of notification messages.
If the client wished not to receive certain notification
messages, it can set the notification mask with those
messages' flag turned off.
The default for the notification mask is to send back
all notification messages.
Valid notification mask flags are:
XA_NOTIFY_MASK_ERROR
XA_NOTIFY_MASK_DEBUG
XA_NOTIFY_MASK_PROGRESS
XA_NOTIFY_MASK_ACK
XA_NOTIFY_MASK_NACK
XA_NOTIFY_MASK_PLAYER_STATE
XA_NOTIFY_MASK_INPUT_STATE
XA_NOTIFY_MASK_INPUT_CAPS
XA_NOTIFY_MASK_INPUT_NAME
XA_NOTIFY_MASK_INPUT_DURATION
XA_NOTIFY_MASK_INPUT_POSITION_RANGE
XA_NOTIFY_MASK_INPUT_POSITION
XA_NOTIFY_MASK_INPUT_TIMECODE_GRANULARITY
XA_NOTIFY_MASK_INPUT_TIMECODE
XA_NOTIFY_MASK_INPUT_STREAM_INFO
XA_NOTIFY_MASK_OUTPUT_STATE
XA_NOTIFY_MASK_OUTPUT_NAME
XA_NOTIFY_MASK_OUTPUT_VOLUME
XA_NOTIFY_MASK_OUTPUT_BALANCE
XA_NOTIFY_MASK_OUTPUT_PCM_LEVEL
XA_NOTIFY_MASK_OUTPUT_MASTER_LEVEL
XA_NOTIFY_MASK_OUTPUT_PORTS
XA_NOTIFY_MASK_OUTPUT_CAPS
XA_NOTIFY_MASK_CODEC_EQUALIZER
XA_NOTIFY_MASK_FEEDBACK_EVENT
|
| DebugLevel |
Sets
the debug level |
| Mode |
Sets flags that modify the player's behavior.
A mode is a combination of behavior flags that can
individually be on or off.
Currently supported flags are:
XA_PLAYER_MODE_OUTPUT_AUTO_CLOSE_ON_STOP: if this flag
is set, the player will close the output whenever it
is stopped. This is convenient, since it will automatically
release the audio driver on systems where the audio
driver cannot be shared by several processes.
XA_PLAYER_MODE_OUTPUT_AUTO_CLOSE_ON_PAUSE: if this flag
is set, the player will close the output when paused.
XA_PLAYER_MODE_OUTPUT_AUTO_CLOSE_ON_EOF: if this flag
is set, the player will close the output when it reaches
the end of the input stream.
|
| OutputOpen |
Open
the specified device for output |
| OutputClose |
Closes the ouput device |
| Exit |
Exits
the control |
| Ping |
Sends a 'ping tag' to the
player, which will trigger a 'pong tag' reply. This is
used to synchronize with the asynchronous player: it is
guaranteed that all messages sent to the player before
a 'ping tag' will have been processed before the player
sends back a 'pong tag' notification with the tag that
was passed with the message. |
| InputSendMessage |
Sends
a private message to the input module. This is used to
implement custom behavior for dynamically attached plugin
input modules (most users will never need to use that
message). A custom message sent to a module has a type
(short integer) and a payload (a user-defined data buffer)
identified by a pointer to a memory location and a size
in bytes. |
| InputRemoveFilter |
Removes a filter from the
decoder's input filters chain. The filter to be removed
can be identified by name or by ID. |
| InputFilterList |
Tells
the player to list the input filters currently in the
chain. |
| InputModuleRegister |
Registers an input module
in the list of attached input modules. The built-in input
modules are: file input module, network stream input module,
and memory input module. |
| InputModuleList |
Retrieves
a list of currently registered input modules. For each
of the registered input module, the player will send back
an INPUT_MODULE_INFO message describing the module. |
| OutputReset |
Resets the output. This will
flush any sound that might be buffered by the output module.
|
| OutputDrain |
Tells
the player to wait until the buffered samples in the output
module have finished playing |
| OutputSendMessage |
Sends a private message to
the output module. This is used to implement custom behavior
for dynamically attached plugin output modules (most users
will never need to use that message). A custom message
sent to a module has a type (short integer) and a payload
(a user-defined data buffer) identified by a pointer to
a memory location and a size in bytes. |
| OutputRemoveFilter |
Removes
a filter from the decoder's output filter chain. The filter
to be removed can be identified by name or by ID. |
| OutputFilterList |
Tells the player to list the
output filters currently in the chain. For each of the
filters in the chain, the decoder will send back an OUTPUT_FILTER_INFO
message describing the filter and it's ID. |
| OutputModuleRegister |
Registers
an output module in the list of attached output modules.
The built-in output modules are Audio Sound Card Ouput
Module and File Output Module. |
| OutputModuleList |
Tells the player to list the
output filters currently in the chain. For each of the
filters in the chain, the decoder will send back an OUTPUT_FILTER_INFO
message describing the filter and it's ID. |
| SetPlayerEnvironmentInteger |
Sets
the value of a player's integer environment variable.
The environment variable is specified by name. |
| SetPlayerEnvironmentString |
Sets the value of a player's
string environment variable. The environment variable
is specified by name. |
| UnsetPlayerEnvironment |
Deletes
on of the player's environment variables. |
| SetInputName |
Sets the input name.
Functions similar to InputOpen |
| SetOutputName |
Sets the player's default output name.
When the OutputOpen method is called with a name parameter
that is NULL or an empty string (""), or when the Play
method is called and the player needs to automatically
open the output device, the player will use the default
output device. Normally, the default output has NULL
name value, which will open the default audio driver.
If you wish to have a different default output device,
you should set its name by calling this method.
|
| SetOutputFeedbackRate |
Currently not implemented.
|
| SetCodecQuality |
Sets
the decoding quality of the codec (if the codec supports
different decoding qualities). |
| InputAddFilter |
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. |
| OutputAddFilter |
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. |
| InputModuleQuery |
Retrieves information about
a registered input module. |
| OutputModuleQuery |
Retrieves
information about a registered output module. |
| SetInputModule |
Sets the player's input module.
By default, the player automatically selects the input
module based on the input name by probing all the registered
input modules. However, if the client needs to constrain
the player to always use a specific input module, it
should do so by setting the input module to the ID of
the registered input module that it wishes to use.
This will only take effect the next time the player
needs to open the input stream. If the player has a
currently open input stream, it will remain until it
is explicitly closed, or a new input stream is opened.
|
| SetOutputModule |
Sets the player's output module.
By default, the player automatically selects the output
module based on the output name by probing all the registered
output modules. However, if the client needs to constrain
the player to always use a specific output module, it
should do so by setting the output module to the ID
of the registered output module that it wishes to use.
This will only take effect the next time the player
needs to open the output device. If the player has a
currently open output device, it will remain until it
is explicitly closed, or a new output device is opened.
|
| GetPlayerMode |
Retrieves the current player
mode.
Upon receipt of this message, the player sends back a
PLAYER_MODE message with the player's current mode. |
| GetPlayerEnvironmentInteger |
Retrieves the value of a player's integer environment
variable.
The environment variable is specified by name.
Upon receipt of this message, the player sends back
a PLAYER_ENVIRONMENT_INTEGER message with the variable's
value.
|
| GetPlayerEnvironmentString |
Retrieves the value of a player's string environment
variable.
The environment variable is specified by name.
Upon receipt of this message, the player sends back
a PLAYER_ENVIRONMENT_STRING message with the variable's
value.
|
| GetInputModuleName |
Retrieves the ID of the current input module.
Upon receipt of this message, the player sends back
an INPUT_MODULE message with the current input module's
ID, or the special value XA_DECODER_INPUT_AUTOSELECT
|
| GetInputName |
Retrieves the name of the current input
|
| GetPositionRange |
Gets
the position range |
| GetOutputName |
Retrieves the name of the current output device.
Upon receipt of this message, the player sends back
an OUTPUT_NAME message with the current output name.
|
| GetMasterVolume |
Gets
the master volume level |
| GetDebugLevel |
Gets the current debug level
|
| GetPositionPercentage |
Gets
the position (as a percentage of the range) |
| GetTimecodeGranularity |
Retrieves the current value of the input timecode granularity.
Upon receipt of this message, the player sends back
an INPUT_TIMECODE_GRANULARITY message with the current
granularity value.
|
| GetPosition |
Retrieves
the current position |
| GetTime |
Gets the current time. The parameter specifies how
the time should be returned:
| 0 - total seconds returned |
| 1 - current hours |
| 2 - current minutes |
| 3 - current seconds returned |
| 4 - current minutes/10 |
| 5 - current minutes mod 10 |
| 6 - current seconds/10 |
| 7 - current seconds mod 10 |
| 8 - total seconds |
Returns the current time in the format specified |
| GetTagStringInfo |
Gets information from the file tag |
| Events |
Description |
|
Ready |
This event is fired after the control has finished loading.
|
|
Ack |
An acknowledgement
event which is fired to acknowledge a method invocation.
|
|
Nack |
A negative acknowledgement - the last command could not
be processed. An error code is returned. |
|
State |
Fires on a state
change. Possible values:
Stopped - 0
Playing - 1
Paused - 2
EOF (end of input stream) - 3 |
|
Mode |
Fires when GetPlayerMode is called
The value of the player's mode is an OR'ed combination
of mode flags.
See the documentation of the "Mode" method for more
details.
|
|
InputState |
Fires on an input state change (e.g. when a file is
opened).
The new value of the player's input state is passed
with the message.
Valid values for the state are:
Open - 0
Closed - 1
|
|
InputPos |
Fires when the input position has changed.
|
|
InputTimecode |
Fires when the input timecode has changed.
|
|
OutputState |
Fires on an output state change (e.g. a file begins
to play). The new value of the player's output state
is passed with the message.
Valid values for the state are:
Open - 0
Closed - 1
|
|
Volume |
Fires to inform of the current volume.
|
|
Balance |
Fires when an output is set and when GetMasterVolume
is called.
|
|
Debug |
Debug messages are used by the decoder and the different
input and output modules and filters to send back debug
information that can be displayed by the application.
|
|
XError |
|
|
InputDuration |
Contains the duration of the current input stream.
|
|
Pong |
This event is fired in response to the "Ping" method
being called.
|
|
Exited |
Fires when the control is exited.
|
|
PlayerEnvironmentInteger |
Contains the value of a integer environment variable.
|
|
PlayerEnvironmentString |
Contains the value of an string environment variable.
|
|
InputName |
Fires when the input name is set or GetInputName is
called.
|
|
InputCaps |
Contains the players current input capabilities.
|
|
InputPositionRange |
Fires when GetPositionRange and GetPositionPercentage
is called.
|
| InputTimecodeGranularity |
Containts the current input timecode granularity value.
|
| InputStreamInfo |
Contains information about the current input stream:
MPEG level (1 for MPEG 1, 2 for MPEG 2, 0 for MPEG 2.5)
MPEG layer (1, 2 or 3)
bitrate in bits per second
sampling frequency in Hz
MPEG mode (0 for stereo, 1 for joint-stereo, 2 for dual-channel,
3 for mono)
|
| InputModule |
Fires on GetInputModuleName call, contains the current
input module ID.
|
| InputModuleInfo |
Contains information about an input module:
ID of the module
number of devices handled by this module
name of the module
description of the module
|
| InputDeviceInfo |
Contains information about an input device of an input
module:
ID of the module this device belongs to
index of this device within a module (first
is 0).
device flags
device name
device description
|
| InputFilterInfo |
Contains information about an input filter:
filter name
ID of the filter
|
| OutputName |
Fires when the output name is set or GetOutputName
is called.
|
| OutputCaps |
Contains the current output capabilities.
|
| PCMLevel |
Fires when an output is set and when GetMasterVolume
is called.
|
| MasterLevel |
Fires when an output is set and when GetMasterVolume
is called.
|
| OutputChannels |
Contains the current output channels configuration.
|
| OutputPorts |
Contains the current output ports configuration.
|
| OutputModule |
Contains the current output module ID.
|
| OutputModuleInfo |
Contains information about an output module:
ID of the module
number of devices handled by this module
name of the module
description of the module
|
| OutputDeviceInfo |
Contains information about an output device of an output
module:
ID of the module this device belongs to
index of this device within a module (first
is 0)
device flags
device name
device description
|
| OutputFilterInfo |
Contains information about an output filter:
filter name
ID of the filter
|
| NotificationMask |
Contains the current notification mask.
|
| DebugLevel |
Fires when GetDebugLevel is called.
|
| Progress |
A progress message (typically used by input modules
like the network streaming module to notify the client
of progress info like buffer fullness, network connection
status, etc...)
Information includes:
ID of the module that sent the message
progress code (user-defined)
a progress value
a user-defined string that gives textual
information about the progress message
|
