API Reference

ImoSPC provides methods giving you both basic playback controls as well as more “sophisticated” features such as fairly accurate time-telling, seeking, volume controls, getting SPC metadata, and detecting playback state changes.

Important: ImoSPC2 is currently in an alpha stage, so its API is subject to change.

(under construction)

Functions

ImoSPC.querySupportedRuntimes(callback : Function)

ImoSPC.init(options = null)

The following optional parameters can be passed as the object options:

• autostart : boolean: If true, then when open() is called, files will begin playing immediately after they are loaded. The default value is false.
• autoplay : boolean: If false, then playlists will not automatically switch from one track to the next at the end of the track.
• preferredRuntime : Runtime: If specified, then ImoSPC will try to load the specified runtime, if possible.
• timeout : number: If specified, then the maximum amount of time in seconds to wait for ImoSPC to load before failing with TIMEOUT. The default value is 5 seconds.

Initializes the ImoSPC runtime so it can be used. The initialization is asynchronous, so listen for the init event rather than doing anything immediately. If there is a failure, initerror will be raised instead.

ImoSPC.open(url : string, options = null)

The following optional parameters can be passed as the object options:

• autostart : boolean: If defined, then overrides the current autostart setting.
• userdata : object: An arbitrary JavaScript object to be associated with the loaded track and playlist.

Loads SPC metadata from the specified SPC file or Zip archive.

To open a single SPC file out of an archive, use a fragment identifier, like so:

http://example.com/archive.zip#file.spc

The fragment identifier cannot contain hash characters; they must be URL-encoded. All special URL characters

Nested zip files are not supported; URLs such as the following will fail with BAD_URL:

http://example.com/archive.zip#inner.zip#file.spc

Once the SPC metadata is loaded, the load event will be raised. If the metadata can’t be loaded, then the loaderror event will be raised instead.

Important: There are security restrictions on loading files across domains. In order to use cross-domain requests, you must first:

• Enable CORS on your server. This is for the HTML5 backend.
• Add a cross-domain policy file to your server. This is for the Flash backend.

Other

ImoSPC.play(track : Track, startAt : number = 0)

ImoSPC.play(playlist : Playlist, track : Track | number = 0, startAt : number = 0)

Plays the specified track or playlist, starting at the specified time in seconds.

ImoSPC.pause() : boolean

Pauses the currently playing track or playlist. If nothing was playing, then false is returned; otherwise, true is returned.

ImoSPC.unpause() : boolean

Resumes the previously playing track or playlist after it was paused. If nothing was playing, or if something was playing but not paused, then false is returned; otherwise, true is returned.

ImoSPC.stop() : boolean

Stops the currently playing track or playlist. If nothing was playing, then false is returned; otherwise, true is returned.

ImoSPC.time() : number

Gets the playback position of the current track, in seconds, or -1 if nothing is playing.

ImoSPC.getVolume() : number

ImoSPC.setVolume(volume : number)

Gets and sets the volume at which all SPC files will be played, respectively. volume must be in the range of [0, 1].

ImoSPC.currentTrack() : ImoSPC.Track

Gets the currently playing track, or null if nothing is playing.

ImoSPC.currentPlaylist() : ImoSPC.Playlist

Gets the currently playing playlist, or null if no playlist is playing.

Properties

ImoSPC.autostart : boolean

ImoSPC.autoplay : boolean

ImoSPC.allowMultipleInstances : boolean

ImoSPC.version

version.major : number
version.minor : number
version.build : number

The version number of the loaded ImoSPC build.

version.runtime : Runtime

Indicates what runtime, if any, is currently running.

Note: ImoSPC2 is currently in an alpha stage, so interpret 1.9.1 as "alpha."

Classes

ImoSPC.Track

Methods

Track.play(startAt : number = 0)

Track.pause() : boolean

Track.unpause() : boolean

Track.stop() : boolean

Track.seek(to : number, isRelative : boolean = false) : boolean

Track.time() : number

Properties

• Track.url : string
• Track.path : string
• Track.archive : string
• Track.title : string
• Track.length : number
• Track.game : string
• Track.artist : string
• Track.publisher : string
• Track.copyright : number
• Track.osttitle : string
• Track.ostdisc : number
• Track.osttrack : string
  • Track.osttracknum : number
  • Track.osttrackchar : string
• Track.userdata : object

ImoSPC.Playlist

Constructor

Playlist(tracks : Array)

Methods

Playlist.play(track : Track | number = 0, startAt : number = 0)

Playlist.pause() : boolean

Playlist.unpause() : boolean

Playlist.stop() : boolean

Playlist.first() : Track

Playlist.previous() : Track

Playlist.current() : Track

Playlist.next() : Track

Playlist.last() : Track

Playlist.indexOfFirst() : number

Playlist.indexOfPrevious() : number

Playlist.indexOfCurrent() : number

Playlist.indexOfNext() : number

Playlist.indexOfLast() : number

Playlist.sort(trackSort = TrackSort.Chronological) : Playlist

Playlist.sortReverse(trackSort = TrackSort.Chronological) : Playlist

Properties

• Playlist.tracks : Array
• Playlist.length : number
• Playlist.userdata : object

ImoSPC.InitEvent

ImoSPC.LoadEvent

ImoSPC.PlayStateEvent

Enumerations

ImoSPC.Error

• Error.SUCCESS: Self-explanatory.
• Error.UNKNOWN: An unknown error occurred.
• Error.INVALID_SPC: Attempted to load a bad SPC file.
• Error.INVALID_ZIP: Attempted to load a bad Zip archive.
• Error.EMPTY_ARCHIVE: Attempted to load an empty archive.
• Error.UNKNOWN_FILE_TYPE: Attempted to load a file that was neither an SPC file nor a Zip archive.
• Error.BAD_URL: The URL is malformed.
• Error.DOWNLOAD_ERROR: A download error occurred. If the error was an HTTP error, then the error message will be accompanied with the HTTP response code.
• Error.IO_ERROR: An I/O error occurred when trying to download or read a file.
• Error.PATH_NOT_FOUND: The requested file could not be found in the archive.
• Error.BROWSER_NOT_SUPPORTED: The user is using a browser that doesn’t support HTML5 and either doesn’t have Flash installed, or has the Flash plug-in disabled.
• Error.TIMEOUT: The initialization timeout has expired.
• Error.FLASHBLOCK: Flashblock-like behaviour was detected. The initialization is still pending, and will complete as soon as ImoSPC’s Flash backend is allowed to run.

ImoSPC.Runtime

• Runtime.NONE: init() has not been called, or it has been called, but is still initializing.
• Runtime.FLASH: ImoSPC is running through its Flash backend.
• Runtime.HTML5: ImoSPC is running through its HTML5 backend.

ImoSPC.PlaybackState

• PlaybackState.STOPPED
• PlaybackState.PLAYING
• PlaybackState.PAUSED
• PlaybackState.BUFFERING
• PlaybackState.LOADING

ImoSPC.TrackSort

• TrackSort.Title
• TrackSort.Game
• TrackSort.URL
• TrackSort.Filename
• TrackSort.Chronological

Events

init : ImoSPC.InitEvent

initerror : ImoSPC.InitEvent

load : ImoSPC.LoadEvent

loaderror : ImoSPC.LoadEvent

playstatechange : ImoSPC.PlayStateEvent

ImoSPC.addEventListener(type : string, listener : Function)

ImoSPC.removeEventListener(type : string, listener : Function)

Adds and removes an event listener, respectively. Event listeners are called in the order they are added, and they are removed in the reverse order; i.e. when a single listener is added twice and removed once, the second listener will be removed.

listener must be a function.