net.FlashDen.ourben.MP3PlusHelper

	Method	Defined by
		FormatPlaylist(player:MP3Plus, format:String):Array [static] Returns a custom formatted version of an MP3Plus playlist.	MP3PlusHelper
		LinkBuffer(mp3player:MP3Plus, bufferExposer:*):Boolean [static] Binds buffer information to objects exposing .buffering:Boolean, .loadedbytes:int, .totalbytes:int and .mslookahead:int .	MP3PlusHelper
		LinkButtons(mp3player:MP3Plus, play:* = null, pause:* = null, stop:* = null, back:* = null, next:* = null, mute:* = null, fadeout:* = null, shuffle:* = null, repeatone:* = null, repeatall:* = null):void [static] Binds playback controls to UI objects.	MP3PlusHelper
		LinkMetaImage(mp3player:MP3Plus, loadBytesExposer:, pattern:):Boolean [static] Binds media metadata to objects exposing .loadBytes(bytes:ByteArray):void .	MP3PlusHelper
		LinkMetaText(mp3player:MP3Plus, textExposer:String, format:*):Boolean [static] Binds media metadata to objects exposing .text:String .	MP3PlusHelper
		LinkPlaylist(mp3player:MP3Plus, selectExposer:String, format:*):Boolean [static] Binds formatted playlists to objects exposing .select(i:int):void and a writeable .items:Array .	MP3PlusHelper
		LinkPosition(mp3player:MP3Plus, positionExposer:*):Boolean [static] Binds playback position to objects exposing .position:int, .requestPosition:int, .maximum:int and .live:Boolean .	MP3PlusHelper
		LinkVolume(mp3player:MP3Plus, volumeExposer:*):Boolean [static] Binds volume control to objects exposing .volume:Number(>= 0.0 <= 1.0) .	MP3PlusHelper

Method detail

FormatPlaylist

()

method

public static function FormatPlaylist(player:MP3Plus, format:String):Array

Returns a custom formatted version of an MP3Plus playlist.

Parameters

	`player:MP3Plus` — The MP3Plus whose playlist will be formatted.

	`format:String` — The metadata format string, see Formatting metadata strings.

Returns

Array — An Array of String safe objects (Array<{string:String, owner:XML, toString:{return string}}>)

Exposer Prototype

MP3PlusHelper will automatically update BufferExposer.buffering when sound channel buffering status changes.
MP3PlusHelper will automatically update BufferExposer.loadBytes when sound channel available data changes.
MP3PlusHelper will automatically update BufferExposer.totalBytes when a total filesize is available or estimated.
MP3PlusHelper will automatically update BufferExposer.mslookahead during stream playback.

Any class passed to LinkBuffer as parameter bufferExposer must be like:

   public class BufferExposer [extends] [implements] {
     public set buffering(buffering:Boolean):ignored {
      [...]
     }
     public set loadedBytes(loadedBytes:int):ignored {
      [...]
     }
     public set totalBytes(totalBytes:int):ignored {
      [...]
     }
     public set mslookahead(mslookahead:int):ignored {
      [...]
     }
   }

Or as an object like:

   var BufferExposer:Object = { buffering:Boolean, loadedBytes:int, totalBytes:int, mslookahead:int [...] };

In many cases totalBytes will not immediately reflect a files size, and even with static files (as opposed to live streams) sometimes due to a lack of ID3 data or no Content-Length header, totalBytes may not ever be accurate.
Wherever possible ensure any HTTP services provide the Content-Length header if you need to guarantee file size accuracy.
The mslookahead property furbishes your exposer objects with the loaded buffer length in milliseconds, and is intended for use within streaming projects. The value of mslookahead is the total buffer length (ms) - the buffer position (ms)

Parameters

	`mp3player:MP3Plus` — The MP3Plus instance to link with.

	`bufferExposer:*` — Any object which exposes .buffering:Boolean, .loadedbytes:int, .totalbytes:int and .mslookahead:int

Returns

Boolean — true or false signifying a successful binding to the render objects members.

LinkButtons

()

method

public static function LinkButtons(mp3player:MP3Plus, play:* = null, pause:* = null, stop:* = null, back:* = null, next:* = null, mute:* = null, fadeout:* = null, shuffle:* = null, repeatone:* = null, repeatall:* = null):void

Binds playback controls to UI objects.

Parameters

mp3player:MP3Plus — The MP3Plus instance to link with.

play:* (default = null) — An object that can dispatch MouseEvent.CLICK

pause:* (default = null) — An object that can dispatch MouseEvent.CLICK

stop:* (default = null) — An object that can dispatch MouseEvent.CLICK

back:* (default = null) — An object that can dispatch MouseEvent.CLICK

next:* (default = null) — An object that can dispatch MouseEvent.CLICK

mute:* (default = null) — An object that can dispatch MouseEvent.CLICK

fadeout:* (default = null) — An object that can dispatch MouseEvent.CLICK

shuffle:* (default = null) — An object that can dispatch MouseEvent.CLICK

repeatone:* (default = null) — An object that can dispatch MouseEvent.CLICK

repeatall:* (default = null) — An object that can dispatch MouseEvent.CLICK

Developers can use existing Sprite, MovieClip, Graphic and numerous other types that can dispatch mouse events as buttons (play, pause... repeatall).
Buttons cannot be decoupled only reassigned. The default null properties are ignored and do remove linkage.

As well as supporting any object that dispatchs MouseEvent.CLICK, some button objects may also feature toggle states:

Button	Action	Toggles
play	Plays the current playlist item	yes
pause	Pause/Plays the current playlist item	yes
stop	Stops playback	no
back	Plays the previous playlist item	no
next	Plays the next playlist item	no
mute	Mutes playback	yes
fadeout	Fades when changing tracks	yes
shuffle	Shuffles play order	yes
repeatone	Repeats current playlist item	yes
repeatall	Repeats all playlist items	yes

Toggling is performed on any UI object that exposes a Boolean property armed

UI objects do not need to expose armed if a project doesn't require that feature, MP3PlusHelper will check whether objects expose armed before attempting to set it.

Example
A toggle pause button

   public class ButtonClass extends Sprite {
     // expose public armed:Boolean property
     public function set armed(value:Boolean) {
      if (value)
       showPausedGraphic();
      else
       showDefaultGraphic();
     }
     ...
   }

LinkMetaImage

()

method

public static function LinkMetaImage(mp3player:MP3Plus, loadBytesExposer:*, pattern:*):Boolean

Binds media metadata to objects exposing .loadBytes(bytes:ByteArray):void .

Exposer Prototype

MP3PlusHelper will automatically call LoadBytesExposer.loadBytes when metadata is updated.

Any class passed to LinkMetaImage as parameter loadBytesExposer must be like:

   public class LoadBytesExposer [extends] [implements] {
     public function loadBytes(bytes:ByteArray):ignored {
      [...]
     }
   }

Or as an object like:

   var LoadBytesExposer:Object = { loadBytes:function(bytes:ByteArray):ignored [...] };

Parameters

	`mp3player:MP3Plus` — The MP3Plus instance to link with.

	`loadBytesExposer:*` — Any object which exposes .loadBytes(bytes:ByteArray):void

	`pattern:*` — The String or RegExp used to match against ID3Info.pictures[].picturetype

Returns

Boolean — true or false signifying a successful binding to the render objects members.

LinkMetaText

()

method

public static function LinkMetaText(mp3player:MP3Plus, textExposer:String, format:*):Boolean

Binds media metadata to objects exposing .text:String .

Exposer Prototype

MP3PlusHelper will automatically update MetaTextExposer.text when metadata is updated.

Any class passed to LinkMetaText as parameter textExposer must be like:

   public class MetaTextExposer [extends] [implements] {
     public set text(string:String):ignored {
      [...]
     }
   }

Or as an object like:

   var MetaTextExposer:Object = { text:String [...] };

Parameters

	`mp3player:MP3Plus` — The MP3Plus instance to link with.

	`textExposer:String` — Any object which exposes a writable .text:String

	`format:*` — The metadata format string, see Formatting metadata strings.

Returns

Boolean — true or false signifying a successful binding to the render objects members.

LinkPlaylist

()

method

public static function LinkPlaylist(mp3player:MP3Plus, selectExposer:String, format:*):Boolean

Binds formatted playlists to objects exposing .select(i:int):void and a writeable .items:Array .

Exposer Prototype

MP3PlusHelper will automatically call PlaylistExposer.select when a playlist item is opened.
MP3PlusHelper will automatically update PlaylistExposer.items when a playlist is modifed or created.

Any class passed to LinkPlaylist as parameter selectExposer must be like:

   public class PlaylistExposer [extends] [implements] {
     public function select(index:int):ignored {
      [...]
     }
     public set items(array:Array):ignored {
      [...]
     }
   }

Or as an object like:

   var PlaylistExposer:Object = { items:Array, select:function(index:int):ignored [...] };

The elements in the PlaylistExposer.items array take the form:

   { string:String, owner:XML, toString:function(){ return string; } }

Because of the toString override, the items array can behave as an array of strings - this technique allows smoother playlist implementation across text handling classes that treat arrays as lines.
Access to the custom formatted text is achievable with:

   for each(var item:Object in items) {
     // output formatted metadata
     trace(item); 
     // output formatted metadata
     trace(item.string); 
     // output all metadata XML
     trace(item.owner.toXMLString()); 
   }

Parameters

	`mp3player:MP3Plus` — The MP3Plus instance to link with.

	`selectExposer:String` — Any object which exposes .select(i:int):void and a writeable .items:Array

	`format:*` — The metadata format string, see Formatting metadata strings.

Returns

Boolean — true or false signifying a successful binding to the render objects members.

LinkPosition

()

method

public static function LinkPosition(mp3player:MP3Plus, positionExposer:*):Boolean

Binds playback position to objects exposing .position:int, .requestPosition:int, .maximum:int and .live:Boolean .

Exposer Prototype

MP3PlusHelper will automatically update PositionExposer.position (ms) during playback.
MP3PlusHelper will read PositionExposer.requestPosition (ms) during playback, when the value returned is > -1 MP3PlusHelper will instruct the player to track to that position and finally reset requestPosition to -1
MP3PlusHelper will automatically update PositionExposer.maximum (ms) during playback.
MP3PlusHelper will automatically update PositionExposer.live during playback.

Any class passed to LinkPosition as parameter positionExposer must be like:

   public class PositionExposer [extends] [implements] {
     public set position(position:int):ignored {
      [...]
     }
     public get requestPosition():int {
      // when no tracking occured
      return -1;
      // when tracking has occured
      return [int >= 0];
     }
     public set requestPosition(requestPosition:int):ignored {
      [...]
     }
     public set maximum(maximum:int):ignored {
      [...]
     }
     public set live(live:Boolean):ignored {
      [...]
     }

Or as an object like:

   var PositionExposer:Object = { position:int, requestPosition:int, maximum:int, live:Boolean };

Parameters

	`mp3player:MP3Plus` — The MP3Plus instance to link with.

	`positionExposer:*` — Any object which exposes .position:int, .requestPosition:int, .maximum:int and .live:Boolean

Returns

Boolean — true or false signifying a successful binding to the render objects members.

Example
How to implement requestPosition:

   // track bar logic
   ...
   [drag logic]
   ...
   
   // track bar handle mouseup event
   myButton.addEventListener(MouseEvent.MOUSEUP, updatePosition);
   
   private function updatePosition(e:MouseEvent):void {
     // set requestPosition
     requestPosition = (maximum / width) myButton.y;
   }

In this example a trackbar handle logic is implemented (not shown) and finally the MOUSEUP event is attached. When the MOUSEUP event fires, the requestPosition is set to the requested tracking position.
MP3PlusHelper will reset requestPosition after reading it, so it is important that nothing other than track logic is allowed to write to requestPosition.

LinkVolume

()

method

public static function LinkVolume(mp3player:MP3Plus, volumeExposer:*):Boolean

Binds volume control to objects exposing .volume:Number(>= 0.0 <= 1.0) .

Exposer Prototype

MP3PlusHelper will read VolumeExposer.volume and apply the value to the playback channel.

Any class passed to LinkMetaText as parameter volumeExposer must be like:

   public class VolumeExposer [extends] [implements] {
     public get volume():Number(>= 0.0 <= 1.0) {
      [...]
     }
   }

Or as an object like:

   var VolumeExposer:Object = { volume:Number(>= 0.0 <= 1.0) [...] };

Parameters

	`mp3player:MP3Plus` — The MP3Plus instance to link with.

	`volumeExposer:*` — Any object which exposes .volume:Number(>= 0.0 <= 1.0)

Returns

Boolean — true or false signifying a successful binding to the render objects members.

API Documentation	All Packages \| All Classes \| Index \| Frames No Frames
Class MP3PlusHelper	Methods

Token	Definition	MP3	IceCast/ShoutCast
$artist	Artist	usually	usually
$title	Title	usually	usually
$album	Album	usually	sometimes
$comment	Comment	Sometimes	sometimes
$genre	Genre	usually	usually
$track	Track Number	sometimes	rare
$year	Copyright Year	sometimes
$resource	Resource URL	always	always
$icy_url	Related URL		usually
$tlen	Length (ms)	usually
$length	Length (hh:MM:ss)	usually
$id3version	ID3 Version	usually

Formatting metadata strings.

Exposer Prototype

Exposer Prototype

Exposer Prototype

Exposer Prototype

Exposer Prototype

Exposer Prototype