freesmartphone.org Audio Interface

Description

This interface provides access to notification sounds, sound scenarios, and mixer controls.

Namespace

org.freesmartphone.Device.Audio

Methods

Signals

Properties

None

Errors

Methods

PlaySound ( sii )

Description: Play a sound resource.

Parameters:*

s: name The identification of the sound resource. Will be treated as filename, if no schema is given. Format-specific options may be supplied by appending multiple “;foo=bar” statements to the filename. Player engines that do not support these options should ignore them.

i: loop Loop. Set this to 1, if you want the sound resource to be restarted, once it ends. 0, otherwise.

i: length Length in seconds. Set this to anything other than 0 if you want to override the length of the sound resource. Note that some audio resources have no concept of length or do know when the sound resource ends. In these cases, you have to provide a reasonable length value or the sound will play endlessly.

StopSound ( s )

Description: Stop playing a sound resource.

Parameters:*

s: name The identification of the sound resource. Will be treated as filename, if no schema is given.

StopAllSounds ( )

Description: Stop all currently played sound resources.

GetAvailableScenarios ( ) → as

Description: Returns a list of supported audio scenarios.

Returns:

as: scenarios The supported audio scenarios.

GetScenario ( ) → s

Description: Get the current audio scenario.

Returns:

s: scenario The name of the scenario.

SetScenario ( s )

Description: Set a new audio scenario.

Parameters:*

s: scenario The name of the scenario.

PushScenario ( s )

Description: Push a new audio scenario onto the stack and active it.

Parameters:*

s: scenario The new active scenario.

PullScenario ( ) → s

Description: Pull an audio scenario from the stack and activate the next one.

Returns:

s: scenario The new active scenario.

SaveScenario ( s )

Description: Save the current scenario as a file.

Parameters:*

s: scenario The name of the scenario.

GetVolume ( ) → y

Description: Get the current main audio volume.

Implementation Note

The main volume can depend on the current scenario. A change of scenario may change the main volume as well.

Returns:

y: volume The volume in percent (0-100).

SetVolume ( y )

Description: Set the new main audio volume.

Implementation Note

The main volume can depend on the current scenario. A change of scenario may change the main volume as well.

Parameters:*

y: volume The volume in percent (0-100).

Signals

SoundStatus ( ssa{sv} )

Description: Sent whenever a sound has been started or stopped.

Parameters:

s: id The identification of sound resource that changed its status.

s: status The new status for the sound resource.

a{sv}: properties An array of property values. Note that properties are optional. Expected tuples are:

  • …to be defined…

Scenario ( ss )

Description: Sent whenever there is a change of the global sound scenario.

Parameters:

s: scenario The scenario that is now active.

s: reason The reason for this change. Expected reasons are:

  • …to be defined…

Errors

UnknownFormat

Description: Raised, if the audio format is not supported.

PlayerError

Description: Raised, if the player emits an (internal) error.

NotPlaying

Description: Raised, if the audio file is not playing.

AlreadyPlaying

Description: Raised, if the audio file is already playing.

ScenarioInvalid

Description: Raised, if the audio scenario can not be activated.

ScenarioStackUnderflow

Description: Raised, if there is no more scenario to pull from the stack.

DeviceFailed

Description: Raised, if the audio device reported a problem.