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

function ImoSPC.querySupportedRuntimes(callback : Function)

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.

function 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

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

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

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

function ImoSPC.pause() : boolean

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

function 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.

function ImoSPC.stop() : boolean

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

function ImoSPC.time() : number

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

function ImoSPC.getVolume() : number

function 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].

function ImoSPC.currentTrack() : ImoSPC.Track

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

function ImoSPC.currentPlaylist() : ImoSPC.Playlist

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

Properties

var ImoSPC.autostart : boolean

If true, then when metadata for a file is loaded, it will play automatically. The default value is false.

var ImoSPC.autoplay : boolean

If true, then sequential playlists are enabled when calling Playlist.play. Otherwise, only one track will be played. The default value is true.

var ImoSPC.allowMultipleInstances : boolean

If true, then the runtime will allow multiple SPC files to be playing simultaneously in separate browser tabs. The default value is false.

Important: This can only affect instances of ImoSPC running on the same domain. Furthermore, an instance in one browser can’t pause an instance running in a different browser.

const ImoSPC.version

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

The version number of the loaded ImoSPC build.

const 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

function Track.play(startAt : number = 0)

Plays a solo track, starting at the specified time.

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

If the track is playing, then the track will relocate to the specified time, and return true. Otherwise, returns false.

function Track.pause() : boolean

Pauses the track and returns true, if it is playing. Otherwise, returns false. Also returns false if the track is already paused.

function Track.unpause() : boolean

Unpauses the track and returns true, if it is paused. Otherwise, returns false.

function Track.stop() : boolean

Stops the track and returns true if it is playing.

function Track.time() : number

Gets returns the time in seconds at which the track is playing, or -1 if the track is not playing or paused.

Properties

• Track.url : string: The complete URL from which the track was loaded.
• Track.path : string: The path to the track within its parent archive, or undefined if the track wasn’t loaded from an archive.
• Track.archive : string: The complete URL of the archive from which the track was loaded, or undefined if the track wasn’t loaded from an archive.
• Track.title : string: The title of the track, or undefined if the SPC file doesn’t have a title in its metadata.
• Track.length : number: The length of the track, in seconds.
• Track.game : string: The name of the game the track is from, or undefined if the SPC file doesn’t have the name of the game in its metadata.
• Track.artist : string: The name of the artist who composed the track, or undefined if the SPC file doesn’t have the name of the track’s artist in its metadata.
• Track.publisher : string: The name of the publisher who published the game the track is from, or undefined if the SPC file doesn’t have the publisher name in its metadata.
• Track.copyright : number: The copyright year, or undefined if the SPC file doesn’t specify a copyright year in its metadata.
• Track.osttitle : string: The title of the original sound track (OST) the track is from, if any.
• Track.ostdisc : number: The OST disc the track is from, if any.
• Track.osttrack : string: The track number, if any, which may have an arbitrary ASCII character appended.
  • Track.osttracknum : number: The track number, as a number. Since alphabetical sorting doesn’t work with numbers, this value should be used when sorting tracks manually.
  • Track.osttrackchar : string: An optional character appended to the track number.
• Track.userdata : object: The object that was passed to ImoSPC.open(), if any.

ImoSPC.Playlist

Constructor

Playlist(tracks : Array)

Methods

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

function Playlist.pause() : boolean

function Playlist.unpause() : boolean

function Playlist.stop() : boolean

function Playlist.first() : Track

function Playlist.previous() : Track

function Playlist.current() : Track

function Playlist.next() : Track

function Playlist.last() : Track

function Playlist.indexOfFirst() : number

function Playlist.indexOfPrevious() : number

function Playlist.indexOfCurrent() : number

function Playlist.indexOfNext() : number

function Playlist.indexOfLast() : number

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

function 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

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

ImoSPC.PlaybackState

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

ImoSPC.TrackSort

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

Events

event init : ImoSPC.InitEvent

Raised when ImoSPC has been initialized successfully.

event initerror : ImoSPC.InitEvent

Raised when ImoSPC couldn’t be initialized. The event descriptor’s error field will indicate what error occurred.

event load : ImoSPC.LoadEvent

Raised when the metadata for a file is loaded. This event can be used even when autostart is enabled.

event loaderror : ImoSPC.LoadEvent

Raised when either:

• The metadata for a file could not be loaded.
• A file could not be downloaded for playback.

event playstatechange : ImoSPC.PlayStateEvent

Raised whenever ImoSPC’s playback state changes.

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

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.