Packagenet.FlashDen.ourben
Classpublic class MP3Plus
InheritanceMP3Plus Inheritance flash.events.EventDispatcher

Advanced MP3 playlist, file and stream playback for FlashPlayer 9.

MP3Plus provides advanced MP3 playback features and supports multiple playlist formats, as well as HTML scraping and a builtin XML playlist format.

Supported Playlists

Supported Media and Meta Data Formats

Features

Using the XML playlist format

The XML playlist format must be like: 
 <playlist base="[URL root path]" [any alphanumeric name]="[any value]">

 <file resource="[URL]" [any alphanumeric name]="[any value]">

 [any number of repeats]

 <stream resource="[URL]" [any alphanumeric name]="[any value]">

 [any number of repeats]

 </playlist>

Required XML

The <playlist> root node:
The playlist root node must have the local name "playlist".
The playlist.@base attribute:
The playlist root node must have a "base" attribute which should be a URL root path followed by a "/" character. 
 http://www.domain.tld/path  = invalid
 http://www.domain.tld/path/ = valid
The <file> node:
The file node must have the local name "file".
The file.@resource attribute:
The file node must have a "resource" attribute which can be an absolute URL or a playlist.@base relative URL.

The <stream> node:
The stream node must have the local name "stream".
The stream.@resource attribute:
The stream node must have a "resource" attribute which can be an absolute URL or a playlist.@base relative URL.

Using automatic playlists

The HTML playlist generator parses HTML document structures to find a href locations that point to MP3 resources.

The parser will work with most hosting environments that enable directory browsing. Directory recursion is not performed be the HTML parser.

Standard compliant HTML is not a requirement for the parser. The parser will ignore all data except a href tags.

Anchor tags found by the parser may be relative or absolute. The parser will use the document path to build absolute paths for relative links.


Public Properties
 PropertyDefined by
  AlwaysReadTags : Boolean
Determines whether to perform deep tag reading even when basic ID3 information is available.
MP3Plus
  AutoPlay : Boolean
Determines whether to start playback automatically on successfully loading a playlist.
MP3Plus
  FadeStop : Boolean
Determines whether or not to apply a fade effect when changing playback to another playlist item.
MP3Plus
  IcyMetaDuration : uint
The millisecond loop duration for stream metadata refreshing.
MP3Plus
  InspectMeta : Boolean
Determines whether to perform metadata extraction from IceCast/Shoutcast streams.
MP3Plus
  iPlaylist : XML
[read-only] Read/write enabled playlist object, made available to namespace classes and helper extensions.
MP3Plus
  MP3Channel : SoundChannel
[read-only] Provides direct access to the current playback channel.
MP3Plus
  NowPlaying : XML
[read-only] The current playlist item XML metadata, the metadata returned is may not be syncronised.
MP3Plus
  NowPlayingID3 : ID3Info
[read-only] The cached ID3 metadata for the current playlist entry.
MP3Plus
  NowPlayingIndex : int
[read-only] The current playlist item zero based playlist index.
MP3Plus
  NowPlayingRef : XML
[read-only] Returns the current playlist item as a reference, enabling editing of in-playlist data.
MP3Plus
  Playing : Boolean
[read-only] Returns true if playback is active, else false.
MP3Plus
  Playlist : XML
[read-only] A copy of the complete playlist.
MP3Plus
  PlaylistAsArray : Array
[read-only] Returns a read/write safe copy of the playlist as an array of XML elements.
MP3Plus
  PositionMS : uint
The current playlist item playback position in milliseconds.
MP3Plus
  Repeat : uint
Determines the playback repeat mode.
MP3Plus
  Shuffle : Boolean
Determines whether playback should choose tracks at random when changing from one item to the next.
MP3Plus
  SoundFactory : Sound
[read-only] Provides direct access to the sound channel generator.
MP3Plus
  Volume : Number
MP3Plus
Public Methods
 MethodDefined by
  
MP3Plus(redherring:String = null)
Creates a new MP3Plus instance, optionally specifying a new global RedHerring URL.
MP3Plus
  
AddFile(resource:String, meta:Object = null):XML
Adds an MP3 file URL to the playlist.
MP3Plus
  
AddStream(resource:String, meta:Object = null):XML
Adds an MP3 stream URL to the playlist.
MP3Plus
  
ExtractURL(meta:XML):String
Extracts the absolute URL from a playlist item.
MP3Plus
  
LoadPlaylist(url:URLRequest):Boolean
Loads a playlist from a URL, replacing the current playlist.
MP3Plus
  
Mute():Boolean
Toggles the mute status of the player.
MP3Plus
  
NewPlaylist(title:String = "Default", artist:String = "Default", album:String = "Default", base:String = null):void
Create a new playlist with no items.
MP3Plus
  
ParseHTML(data:String, createNewPlaylist:Boolean = true):Boolean
Adds files extracted from a HTML document.
MP3Plus
  
ParseM3U(data:String, createNewPlaylist:Boolean = true):Boolean
Adds items from a M3U playlist to the current playlist.
MP3Plus
  
ParsePLS(data:String, createNewPlaylist:Boolean = true):Boolean
Adds items from a PLS playlist to the current playlist.
MP3Plus
  
ParseXML(data:String, createNewPlaylist:Boolean = true):Boolean
Adds files from an XML playlist into the current playlist.
MP3Plus
  
Pause():Boolean
Toggles the pause status of the current playlist item.
MP3Plus
  
Play(index:int = 0):Boolean
Starts playback from the beginning of a file or stream.
MP3Plus
  
PlayFrom(ms:uint = 0):Boolean
Plays the current playlist item from a specified position.
MP3Plus
  
PlayNext():void
Plays the next playlist item.
MP3Plus
  
PlayPrevious():void
Plays the previous playlist item.
MP3Plus
  
QueryLength():uint
Calculates the current playlist item length in milliseconds.
MP3Plus
  
RefreshMetadata():void
Refreshes metadata for the current playlist item.
MP3Plus
  
Stop(force:Boolean = false):void
Stops playback.
MP3Plus
Events
 EventSummaryDefined by
  
BadPlaylistFormat
This event is triggered when no playlist parser can process the input playlist.MP3Plus
  
extendedNotImplemented
This event is triggered when an ID3v2 version 3+ extended header is found.MP3Plus
  
gotIcyMeta
This event is triggered when domain independent IcyMeta data is available.MP3Plus
  
gotId3Simple
This event is triggered when builtin Sound.id3 data is available.MP3Plus
  
gotId3V1x
This event is triggered when domain independent ID3v1.x data is available.MP3Plus
  
gotId3V2x
This event is triggered when domain independent ID3v2.x data is available.MP3Plus
  
icyMetaNull
This event is triggered when a ICY metadata block is found, but contains no data.MP3Plus
  
ioError
This event is triggered when a remote resource is unavailable.MP3Plus
  
metaDataUpdated
This event is triggered when stream metadata is updated, and file metadata is available that supercedes existing the metadata version.MP3Plus
  
noTagFound
This event is triggered when no ID3 tag information is available for a resource.MP3Plus
  
open
This event is triggered when a file or stream is successfully opened.MP3Plus
  
PlaylistLoadError
This event is triggered when a playlist load operation fails.MP3Plus
  
PlaylistReady
This event is triggered when a playlist has loaded and is ready to play.MP3Plus
  
progress
This event is triggered when new downloaded data is available.MP3Plus
  
resourceLoaded
This event is triggered when a playlist item media resource is completely loaded.MP3Plus
  
soundComplete
This event is triggered when a playlist item playback finishes.MP3Plus
  
tagError
This event is triggered when a tag is found to be damaged, corrupt or otherwise unusable.MP3Plus
Public Constants
 ConstantDefined by
  ER_BADPLAYLISTFORMAT : String = "BadPlaylistFormat"
[static] Defines the value of the type property of a BadPlaylistFormat event object.
MP3Plus
  ER_PLAYLISTLOADERROR : String = "PlaylistLoadError"
[static] Defines the value of the type property of a PlaylistLoadError event object.
MP3Plus
  EV_GOTICYMETA : String = "gotIcyMeta"
[static] Defines the value of the type property of a gotIcyMeta event object.
MP3Plus
  EV_GOTID3SIMPLE : String = "gotId3Simple"
[static] Defines the value of the type property of a gotId3Simple event object.
MP3Plus
  EV_GOTID3V1X : String = "gotId3V1x"
[static] Defines the value of the type property of a gotId3V1x event object.
MP3Plus
  EV_GOTID3V2X : String = "gotId3V2x"
[static] Defines the value of the type property of a gotId3V2x event object.
MP3Plus
  EV_ICYMETANULL : String = "icyMetaNull"
[static] Defines the valut of the type property of a icyMetaNulled event object.
MP3Plus
  EV_METADATAUPDATED : String = "metaDataUpdated"
[static] Defines the value of the type property of a metaDataUpdated event object.
MP3Plus
  EV_PLAYLISTREADY : String = "PlaylistReady"
[static] Defines the value of the type property of a PlaylistReady event object.
MP3Plus
  EV_RESOURCELOADED : String = "resourceLoaded"
[static] Defines the value of the type property of a resourceLoaded event object.
MP3Plus
  MODE_REPEAT_ALL : uint = 2
[static] The Repeat All constant.
MP3Plus
  MODE_REPEAT_NONE : uint = 0
[static] The No Repeat constant.
MP3Plus
  MODE_REPEAT_ONE : uint = 1
[static] The Repeat One constant.
MP3Plus
Property detail
AlwaysReadTagsproperty
AlwaysReadTags:Boolean  [read-write]

Determines whether to perform deep tag reading even when basic ID3 information is available.

Implementation
    public function get AlwaysReadTags():Boolean
    public function set AlwaysReadTags(value:Boolean):void
AutoPlayproperty 
AutoPlay:Boolean  [read-write]

Determines whether to start playback automatically on successfully loading a playlist.

Implementation
    public function get AutoPlay():Boolean
    public function set AutoPlay(value:Boolean):void
FadeStopproperty 
FadeStop:Boolean  [read-write]

Determines whether or not to apply a fade effect when changing playback to another playlist item. Fading is applied to Play(index:int), Stop(), PlayNext(), PlayPrevious()

Implementation
    public function get FadeStop():Boolean
    public function set FadeStop(value:Boolean):void
IcyMetaDurationproperty 
IcyMetaDuration:uint  [read-write]

The millisecond loop duration for stream metadata refreshing. Higher values improve network performance at the cost of metadata accuracy. By default metadata from streams is polled every 30 seconds, or 30000 milliseconds.

Implementation
    public function get IcyMetaDuration():uint
    public function set IcyMetaDuration(value:uint):void
InspectMetaproperty 
InspectMeta:Boolean  [read-write]

Determines whether to perform metadata extraction from IceCast/Shoutcast streams.

Implementation
    public function get InspectMeta():Boolean
    public function set InspectMeta(value:Boolean):void
iPlaylistproperty 
iPlaylist:XML  [read-only]

Read/write enabled playlist object, made available to namespace classes and helper extensions. For non volatile access to playlist data, use public MP3Plus.Playlist

Implementation
    public function get iPlaylist():XML

See also

Playlist
MP3Channelproperty 
MP3Channel:SoundChannel  [read-only]

Provides direct access to the current playback channel.

Implementation
    public function get MP3Channel():SoundChannel
NowPlayingproperty 
NowPlaying:XML  [read-only]

The current playlist item XML metadata, the metadata returned is may not be syncronised. To use syncronised data, the internal MP3Plus.NowPlayingRef can be used by namespace net.FlashDen.ourben

Implementation
    public function get NowPlaying():XML

See also

NowPlayingRef
NowPlayingID3property 
NowPlayingID3:ID3Info  [read-only]

The cached ID3 metadata for the current playlist entry.

Implementation
    public function get NowPlayingID3():ID3Info
NowPlayingIndexproperty 
NowPlayingIndex:int  [read-only]

The current playlist item zero based playlist index.

Implementation
    public function get NowPlayingIndex():int
NowPlayingRefproperty 
NowPlayingRef:XML  [read-only]

Returns the current playlist item as a reference, enabling editing of in-playlist data. For safe read access, use public MP3Plus.NowPlaying

Implementation
    public function get NowPlayingRef():XML

See also

NowPlaying
Playingproperty 
Playing:Boolean  [read-only]

Returns true if playback is active, else false.

Implementation
    public function get Playing():Boolean
Playlistproperty 
Playlist:XML  [read-only]

A copy of the complete playlist. Playlist is not a reference to the runtime playlist object, but a duplicate of it.
Direct access to the internal playlist is available through internal MP3Plus.iPlaylist in namespace net.FlashDen.ourben

Implementation
    public function get Playlist():XML

See also

iPlaylist
PlaylistAsArrayproperty 
PlaylistAsArray:Array  [read-only]

Returns a read/write safe copy of the playlist as an array of XML elements.

Implementation
    public function get PlaylistAsArray():Array
PositionMSproperty 
PositionMS:uint  [read-write]

The current playlist item playback position in milliseconds.

Implementation
    public function get PositionMS():uint
    public function set PositionMS(value:uint):void
Repeatproperty 
Repeat:uint  [read-write]

Determines the playback repeat mode. Valid options are MODE_REPEAT_NONE = 0, MODE_REPEAT_ONE = 1, MODE_REPEAT_ALL 2 If an invalid value is copied to Repeat, the value MODE_REPEAT_NONE = 0 is used.

Implementation
    public function get Repeat():uint
    public function set Repeat(value:uint):void

Example
Using Repeat to toggle mode 
   var player:MP3Plus = new MP3Plus();
   
   trace(player.Repeat); // "0" MODE_REPEAT_NONE
   
   // toggle
   trace(++player.Repeat); // "1" MODE_REPEAT_ONE
   trace(++player.Repeat); // "2" MODE_REPEAT_ALL
   trace(++player.Repeat); // "0" MODE_REPEAT_NONE
   trace(++player.Repeat); // "1" MODE_REPEAT_ONE
   trace(++player.Repeat); // "2" MODE_REPEAT_ALL

Shuffleproperty 
Shuffle:Boolean  [read-write]

Determines whether playback should choose tracks at random when changing from one item to the next. When Shuffle is true, methods PlayNext() and PlayPrevious() will change to random tracks.

Implementation
    public function get Shuffle():Boolean
    public function set Shuffle(value:Boolean):void
SoundFactoryproperty 
SoundFactory:Sound  [read-only]

Provides direct access to the sound channel generator.

Implementation
    public function get SoundFactory():Sound
Volumeproperty 
Volume:Number  [read-write]Implementation
    public function get Volume():Number
    public function set Volume(value:Number):void
Constructor detail
MP3Plus()constructor
public function MP3Plus(redherring:String = null)

Creates a new MP3Plus instance, optionally specifying a new global RedHerring URL.

Parameters
redherring:String (default = null) — Optional RedHerring URL. If specified updates the global RedHerring URL used by all classes that depend on it.
Method detail
AddFile()method
public function AddFile(resource:String, meta:Object = null):XML

Adds an MP3 file URL to the playlist.

Parameters
resource:String — MP3 URL
 
meta:Object (default = null) — Optional metadata object. Each property of the supplied object is copied to the attributes if the new XML node.

Returns
XML — The new files playlist entry, as a reference.
AddStream()method 
public function AddStream(resource:String, meta:Object = null):XML

Adds an MP3 stream URL to the playlist.

Parameters
resource:String — Stream URL
 
meta:Object (default = null) — Optional metadata object. Each property of the supplied object is copied to the attributes if the new XML node.

Returns
XML — The new streams playlist entry, as a reference.
ExtractURL()method 
public function ExtractURL(meta:XML):String

Extracts the absolute URL from a playlist item.

Parameters
meta:XML — The playlist item whose metadata is used to detect its origin.

Returns
String — The absolute URL for the supplied metadata.
LoadPlaylist()method 
public function LoadPlaylist(url:URLRequest):Boolean

Loads a playlist from a URL, replacing the current playlist. The loaded playlist can be PLS, M3U, HTML or XML

Parameters
url:URLRequest — The playlist URL

Returns
Boolean — true or false indicating successful load initialising.
Mute()method 
public function Mute():Boolean

Toggles the mute status of the player.

Returns
Boolean — true when playback is muted, else false.
NewPlaylist()method 
public function NewPlaylist(title:String = "Default", artist:String = "Default", album:String = "Default", base:String = null):void

Create a new playlist with no items.

Parameters
title:String (default = "Default") — An optional title for the playlist.
 
artist:String (default = "Default") — An optional artist name for the playlist.
 
album:String (default = "Default") — An optional album name for the playlist.
 
base:String (default = null) — An optional base URL, used to resolve relative resource URL attributes. If no value is provided, a value is extracted from the most recent playlist URL.
ParseHTML()method 
public function ParseHTML(data:String, createNewPlaylist:Boolean = true):Boolean

Adds files extracted from a HTML document.

Parameters
data:String — A HTML document source.
 
createNewPlaylist:Boolean (default = true) — Clears the playlist before adding the new data.

Returns
Boolean — true or false indicating successful parsing of the input HTML.
ParseM3U()method 
public function ParseM3U(data:String, createNewPlaylist:Boolean = true):Boolean

Adds items from a M3U playlist to the current playlist.

Parameters
data:String — A M3U playlist source.
 
createNewPlaylist:Boolean (default = true) — Clears the playlist before adding the new data.

Returns
Boolean — true or false indicating successful parsing of the input M3U.
ParsePLS()method 
public function ParsePLS(data:String, createNewPlaylist:Boolean = true):Boolean

Adds items from a PLS playlist to the current playlist.

Parameters
data:String — A PLS playlist source.
 
createNewPlaylist:Boolean (default = true) — Clears the playlist before adding the new data.

Returns
Boolean — true or false indicating successful parsing of the input PLS.
ParseXML()method 
public function ParseXML(data:String, createNewPlaylist:Boolean = true):Boolean

Adds files from an XML playlist into the current playlist.

Parameters
data:String — An XML playlist source.
 
createNewPlaylist:Boolean (default = true) — Clears the playlist before adding the new data.

Returns
Boolean — true or false indicating successful parsing of the input XML.
Pause()method 
public function Pause():Boolean

Toggles the pause status of the current playlist item.

Returns
Boolean — true if playback is paused, else false.
Play()method 
public function Play(index:int = 0):Boolean

Starts playback from the beginning of a file or stream.

Parameters
index:int (default = 0) — The index of the item in the playlist, default 0 starts from the beginning of the playlist.

Returns
Boolean — true if the playback operation succeeded, else false.
PlayFrom()method 
public function PlayFrom(ms:uint = 0):Boolean

Plays the current playlist item from a specified position.

Parameters
ms:uint (default = 0) — The new start position in milliseconds.

Returns
Boolean — true if playback is active and tracking succeeded, else false.
PlayNext()method 
public function PlayNext():void

Plays the next playlist item.

PlayPrevious()method 
public function PlayPrevious():void

Plays the previous playlist item.

QueryLength()method 
public function QueryLength():uint

Calculates the current playlist item length in milliseconds. The accuracy of the calculation depends on the availabillity HTTP headers, data loaded and ID3 information. For this reason, if querying soon after playback starts the value returned may not be accurate.

Returns
uint — The calculated length of the current playlist item in milliseconds.
RefreshMetadata()method 
public function RefreshMetadata():void

Refreshes metadata for the current playlist item. If the current item is a file rather than a stream, RefreshMetadata will check the ID3 cache first.

Stop()method 
public function Stop(force:Boolean = false):void

Stops playback.

Parameters
force:Boolean (default = false) — If true, overrides the FadeStop effect.
Event detail
BadPlaylistFormatevent 
Event object type: flash.events.Event

This event is triggered when no playlist parser can process the input playlist.

extendedNotImplementedevent  
Event object type: com.curlyben.events.ID3Event

This event is triggered when an ID3v2 version 3+ extended header is found. Parsing ID3v2 extended headers is not performed by the version (1.0.0.0) of ID3TagReader used.

gotIcyMetaevent  
Event object type: com.curlyben.events.ID3Event

This event is triggered when domain independent IcyMeta data is available.

gotId3Simpleevent  
Event object type: com.curlyben.events.ID3Event

This event is triggered when builtin Sound.id3 data is available.

gotId3V1xevent  
Event object type: com.curlyben.events.ID3Event

This event is triggered when domain independent ID3v1.x data is available.

gotId3V2xevent  
Event object type: com.curlyben.events.ID3Event

This event is triggered when domain independent ID3v2.x data is available.

icyMetaNullevent  
Event object type: flash.events.Event

This event is triggered when a ICY metadata block is found, but contains no data. Empty ICY metadata blocks signify that the served item has no metadata, and occasionaly occur when a stream is inbetween items.

ioErrorevent  
Event object type: flash.events.IOErrorEvent

This event is triggered when a remote resource is unavailable.

metaDataUpdatedevent  
Event object type: flash.net.Event

This event is triggered when stream metadata is updated, and file metadata is available that supercedes existing the metadata version.

noTagFoundevent  
Event object type: com.curlyben.events.ID3Event

This event is triggered when no ID3 tag information is available for a resource.

openevent  
Event object type: flash.events.Event

This event is triggered when a file or stream is successfully opened.

PlaylistLoadErrorevent  
Event object type: flash.events.Event

This event is triggered when a playlist load operation fails.

PlaylistReadyevent  
Event object type: flash.events.Event

This event is triggered when a playlist has loaded and is ready to play.

progressevent  
Event object type: flash.events.ProgressEvent

This event is triggered when new downloaded data is available.

resourceLoadedevent  
Event object type: flash.events.Event

This event is triggered when a playlist item media resource is completely loaded.

soundCompleteevent  
Event object type: flash.events.Event

This event is triggered when a playlist item playback finishes.

tagErrorevent  
Event object type: com.curlyben.events.ID3Event

This event is triggered when a tag is found to be damaged, corrupt or otherwise unusable.

Constant detail
ER_BADPLAYLISTFORMATconstant
public static const ER_BADPLAYLISTFORMAT:String = "BadPlaylistFormat"

Defines the value of the type property of a BadPlaylistFormat event object.

ER_PLAYLISTLOADERRORconstant 
public static const ER_PLAYLISTLOADERROR:String = "PlaylistLoadError"

Defines the value of the type property of a PlaylistLoadError event object.

EV_GOTICYMETAconstant 
public static const EV_GOTICYMETA:String = "gotIcyMeta"

Defines the value of the type property of a gotIcyMeta event object.

EV_GOTID3SIMPLEconstant 
public static const EV_GOTID3SIMPLE:String = "gotId3Simple"

Defines the value of the type property of a gotId3Simple event object.

EV_GOTID3V1Xconstant 
public static const EV_GOTID3V1X:String = "gotId3V1x"

Defines the value of the type property of a gotId3V1x event object.

EV_GOTID3V2Xconstant 
public static const EV_GOTID3V2X:String = "gotId3V2x"

Defines the value of the type property of a gotId3V2x event object.

EV_ICYMETANULLconstant 
public static const EV_ICYMETANULL:String = "icyMetaNull"

Defines the valut of the type property of a icyMetaNulled event object.

EV_METADATAUPDATEDconstant 
public static const EV_METADATAUPDATED:String = "metaDataUpdated"

Defines the value of the type property of a metaDataUpdated event object.

EV_PLAYLISTREADYconstant 
public static const EV_PLAYLISTREADY:String = "PlaylistReady"

Defines the value of the type property of a PlaylistReady event object.

EV_RESOURCELOADEDconstant 
public static const EV_RESOURCELOADED:String = "resourceLoaded"

Defines the value of the type property of a resourceLoaded event object.

MODE_REPEAT_ALLconstant 
public static const MODE_REPEAT_ALL:uint = 2

The Repeat All constant. The current playlist repeats.

MODE_REPEAT_NONEconstant 
public static const MODE_REPEAT_NONE:uint = 0

The No Repeat constant. Playlists play in there defined order once.

MODE_REPEAT_ONEconstant 
public static const MODE_REPEAT_ONE:uint = 1

The Repeat One constant. The current playlist item repeats.