Lib Music

Overview

Lib_Music (part of Library) is an expandable event driven music player, but also the successor to Hyperradio. If 'Radio'-AddOns are used the radio-channels are configurable through Lib_Config.

Events

Events are handled through Oolites handler (e.g. shipExitedWitchspace). Lib_Music uses handlers which are not fired repeatedly and selects one of the music entries randomly for the specified event. Event music is particulary interesting for mission related things.

Used handlers:

• alertConditionChanged
• playerStartedAutoPilot
• playerRescuedEscapePod
• shipDockedWithStation
• shipEnteredPlanetaryVicinity
• shipEnteredStationAegis
• shipExitedStationAegis
• shipExitedPlanetaryVicinity
• shipExitedWitchspace
• shipKilledOther
• shipScoopedFuel
• shipScoopedOther
• shipTargetDestroyed
• shipWillDockWithStation
• shipWillLaunchFromStation

Any of the following methods should be used on .startUpComplete or later.

_addEventMusic

	_addEventMusic: function( obj, ID )

Clones the passed Object and adds entries silently to the event Arrays. Without activating the GroupID via _toggleGroup none of them will be played. The passed Object can use any of the members of $media, except radio (which is reserved for queued music)!

Parameters:

obj

Object. See $media for its members. The entries must contain

snd

<filename>

dur

duration seconds <integer>

vol

volume 0...1 <float> (Optional) Added in v1.1

Returns:

true or false.

Example:

 worldScripts.Lib_Music._addEventMusic({
   aegis:{
     enter:[ {snd:"MyOXP_AegisFile.ogg",dur:98} ]
   }
 },"MyGroupID");

_toggleGroup

	_toggleGroup: function( ID )

Toggles the status for GroupID if it exists. If priority mode is active the change is inactive until priority mode is cleared.

Parameters:

ID

String.

Returns:

n

Number. 0 or 1. The current status.

Example:

 worldScripts.Lib_Music._toggleGroup("MyGroupID");

_setPriorityGroup

	_setPriorityGroup: function( ID )

Take priority for specified GroupID. Stores the current status, disables all other GroupIDs and enables this GroupID. This method is particulary interesting for mission related things.

Parameters:

ID

String.

Returns:

true or false.

Example:

 worldScripts.Lib_Music._setPriorityGroup("MyGroupID");

_clrPriorityGroup

	_clrPriorityGroup: function( )

Clear priority mode. Resets the status of all GroupIDs.

Parameters:

none.

Returns:

nothing.

Example

 worldScripts.Lib_Music._clrPriorityGroup();

$media

The structure.

 {
   aegis:{enter:[], exit:[]},
   alert:{red:[]},
   docked:{main:[], any:[]},
   exitWS:{inter:[], goneNova:[], doNova:[], standard:[]},
   killed:{any:[]},
   launch:{inter:[], goneNova:[], doNova:[], main:[], any:[]},
   planetIn:{enterMain:[], enterSun:[], any:[]},
   planetOut:{exitMain:[], exitSun:[], any:[]},
   radio:{generic:[]},
   rescued:{any:[]},
   scooped:{any:[]},
   scoopFuel:{fuel:[]}
 };

Channels

Channels are used as playlists. As long as no other event gets triggered and the status doesn't change Lib_Music will continue to pick another one from the currently active radio channel. If a channel is explicitely set via _setChannel() it will use this channel until it gets unset (both docked and inflight). Otherwise - if docked it will use either a channel that is equal to the name of the station or the "generic" channel. Inflight it uses either the "docking" channel for the autopilot, "fight" for dangerous situations or "generic".

Any of the following methods should be used on .startUpComplete or later.

_addChannel

	_addChannel: function( obj )

Clones the passed Object and adds or merges the channel to the queued music lists.

Parameters:

obj

Object with members:

name

String.

sounds

Array. The entries must contain

snd

<filename>

dur

duration seconds <integer>

vol

volume 0...1 <float> (Optional) Added in v1.1

radio

Boolean. Optional.

Returns:

true or false.

Example:

 worldScripts.Lib_Music._addChannel({name:"docking",sounds:[ {snd:"MyOXP_Docking.ogg",dur:180} ]});

_setChannel

	_setChannel: function( str )

Sets or clears custom radio channel.

Parameters:

str

String or null. Channel name.

Returns:

String or null

Channel name.

Execution order

The priority is as follows:

• Event with active priority mode (GroupID).
• Event standard (e.g. .main).
• Event for specified entity.
• Event .any.
• Radio channel set through _setChannel().
• Radio channel.