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)

Checks to see what runtimes are supported, and passes an array of them to callback. Obviously, NONE is never included in the array.

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.setRepeat(repeat : boolean)

Sets whether the track plays infinitely or stops when the end of the track is reached.

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

Tracks are SPC files, which may or may not be part of an archive. They include metadata fields, which are described in the Properties section below Methods.

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

Playlists allow multiple tracks to be played automatically. By default, tracks are played in the order they are loaded from the Zip archive, but they can be sorted using Playlist.sort(), or you can create new playlists entirely using the constructor.

Constructor

Playlist(tracks : ImoSPC.Track[])

Creates a new playlist from an array of tracks. All objects in the array must be an instance of ImoSPC.Track.

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

Properties

• const InitEvent.version = ImoSPC.version: The version information for the loaded ImoSPC runtime.
• const InitEvent.error : ImoSPC.Error: A value indicating what error, if any, prevented ImoSPC from being initialized.

ImoSPC.LoadEvent

Properties

• const LoadEvent.url : string: The full URL of the file that was loaded or being attempted to load.
• const LoadEvent.userdata : object: The same object that was passed to ImoSPC.open().
• const LoadEvent.track : ImoSPC.Track: The track that was loaded, or undefined if an error occurred or an archive containing multiple SPC files was loaded.
• const LoadEvent.playlist : ImoSPC.Playlist: A playlist containing all tracks in the file that was loaded, or undefined if an error occurred.
• const LoadEvent.corruptFiles : string[]: An array containing the paths of all corrupt SPC files, or SPC files with unsupported compression modes, in the Zip archive that was loaded. This will be an empty array if no SPC files were corrupt.
• const LoadEvent.error : ImoSPC.Error: What error prevented the file from being loaded, if any.
• const LoadEvent.httpStatus : number: If error is DOWNLOAD_ERROR, then contains the HTTP response code that was returned. If httpStatus is not an HTTP error code, then a miscellaneous non-HTTP download error occurred.

ImoSPC.PlayStateEvent

Properties

• const PlayStateEvent.state : ImoSPC.PlaybackState: Defines the current state of the SPC player.
• const PlayStateEvent.track : ImoSPC.Track: The track that state applies to.
• const PlayStateEvent.playlist : ImoSPC.Playlist: The playlist that state applies to.
• const PlayStateEvent.index : number: The index of the track that state applies to.
• const PlayStateEvent.previousTrack : ImoSPC.Track: The previous track that was playing, or undefined if nothing. This property only exists for the LOADING state, and isn’t used when switching from one playlist to another playlist.
• const PlayStateEvent.previousIndex : number: The index of the previous track that was playing, or undefined if nothing. This property only exists for the LOADING state, and isn’t used when switching from one playlist to another playlist.

Enumerations

ImoSPC.Error

• const Error.SUCCESS: Self-explanatory. Evaluates to false. All other error codes evaluate to true.
• const Error.UNKNOWN: An unknown error occurred.
• const Error.INVALID_SPC: Attempted to load a bad SPC file.
• const Error.INVALID_ZIP: Attempted to load a bad Zip archive.
• const Error.EMPTY_ARCHIVE: Attempted to load an empty archive.
• const Error.UNKNOWN_FILE_TYPE: Attempted to load a file that was neither an SPC file nor a Zip archive.
• const Error.BAD_URL: The URL is malformed.
• const 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.
• const Error.IO_ERROR: An I/O error occurred when trying to download or read a file.
• const Error.PATH_NOT_FOUND: The requested file could not be found in the archive.
• const 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.
• const Error.TIMEOUT: The initialization timeout has expired.
• const 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: Self-explanatory. Also raised when a playlist or solo track finishes playing, or when switching from one playlist to another, from one solo track to another, from a playlist to a solo track, and vice-versa. Note that after the STOPPED state event is raised, there is no longer a “current track.”
• const PlaybackState.PLAYING: Self-explanatory.
• const PlaybackState.PAUSED: Self-explanatory. Note that the paused track is still loaded as the current track.
• const PlaybackState.BUFFERING: Raised when waiting for more audio to play. This usually happens after seeking, although when using the HTML5 player on a slow computer, it may also be raised when a track first starts playing.
• const PlaybackState.LOADING: Raised when loading a file.

ImoSPC.TrackSort

• const TrackSort.Title
• const TrackSort.Game
• const TrackSort.URL
• const TrackSort.Filename
• const TrackSort.Chronological: Sort tracks by their OST title, disc number, and track numbers, where possible. Otherwise, sort by title.

These are mostly self-explanatory.

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.