Difference between revisions of "Lib Music"
m (Part III) |
m (Added volume parameter) |
||
Line 32: | Line 32: | ||
'''Parameters:''' |
'''Parameters:''' |
||
− | :;obj:Object. See [[#$media|$media]] for its members. The entries must contain |
+ | :;obj:Object. See [[#$media|$media]] for its members. The entries must contain |
+ | :::;snd: <filename> |
||
+ | :::;dur: duration seconds <integer> |
||
+ | :::;vol: volume 0...1 <float> (Optional) {{AV|1.1}} |
||
'''Returns:''' |
'''Returns:''' |
||
Line 118: | Line 118: | ||
:;obj:Object with members: |
:;obj:Object with members: |
||
::;name:String. |
::;name:String. |
||
− | ::;sounds:Array. The entries must contain |
+ | ::;sounds:Array. The entries must contain |
+ | :::;snd: <filename> |
||
+ | :::;dur: duration seconds <integer> |
||
+ | :::;vol: volume 0...1 <float> (Optional) {{AV|1.1}} |
||
::;radio:Boolean. Optional. |
::;radio:Boolean. Optional. |
||
Revision as of 15:05, 28 October 2016
Contents
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.