src.core.media

#Media (public Module)

Provides Media functionality to Butter.

Usage:

var Media = require('path/to/module/media.js');

#Media::Media (public Class)

Supplies access to Popcorn and the Butter Tracks and TrackEvents that comprise a Popcorn experience for one media element (one set of urls).

• mediaOptions [ Dictionary ]: Initialization options, such as name, url, and target.

Usage:

var m = new Media(mediaOptions);

##Media::Media::currentTime (read-write Property)

Current time of this Media and underlying Popcorn object. Safe proxy for Popcorn.

@event: mediatimeupdate
@return [ Number ]: Current time of Popcorn media.

##Media::Media::duration (read-write Property)

Duration of this Media. Rarely needs to be set manually.

@event: mediadurationchanged
@return [ Number ]: Length of media in seconds.

##Media::Media::ended (read-only Property)

Safely wraps Popcorn's ended() getter function, reporting the "ended" state for this Media object.

@return [ Boolean ]: If Popcorn is not initialized, or the media it wraps has not ended, false is returned. Otherwise, true.

##Media::Media::id (read-only Property)

Id of this Media object.

@return [ String ]

##Media::Media::json (read-write Property)

JSON object representing the current state of this Media object.

@return [ JSON ]: Portable state of this object.

##Media::Media::muted (read-write Property)

Mute state of this Media object.

@return [ Boolean ]: True if muted, false otherwise.

##Media::Media::name (read-only Property)

Name of this Media object.

@return [ String ]

##Media::Media::orderedTracks (read-only Property)

Ordered array of Tracks attached to this Media object. Should always be ordered.

@return [ Array ]: Array of Tracks.

##Media::Media::paused (read-write Property)

Paused state of this Media object.

@return [ Boolean ]: True if paused, false otherwise.

##Media::Media::popcorn (read-only Property)

PopcornWrapper object housing an instance of Popcorn.

@return [ PopcornWrapper ]

##Media::Media::popcornOptions (read-write Property)

Options object used to initialize Popcorn media.

@event: mediapopcornsettingschanged
@return [ Dictionary ]

##Media::Media::ready (read-only Property)

Ready state of this Media object.

@return [ Boolean ]: True if media is in the ready state; false otherwise.

##Media::Media::registry (read-write Property)

Shortcut to Popcorn plugin registry.

@return [ Dictionary ]

##Media::Media::target (read-write Property)

Target for Popcorn media. Whenever this property changes, Popcorn is re-initialized.

@event: mediatargetchanged
@return [ String ]: Id of the element Popcorn will use for its media source.

##Media::Media::tracks (read-only Property)

Array of Tracks attached to this Media object. Not ordered.

@return [ Array ]: Array of Tracks.

##Media::Media::url (read-write Property)

Url used to initialize Popcorn. Whenever this property changes, Popcorn is re-initialized.

@event: mediacontentchanged
@return [ String ]: String containing comma-delimited urls to be passed to Popcorn for initialization.

##Media::Media::volume (read-write Property)

Volume of this Media object.

@return [ Number ]

##Media::Media::addNewTrackTrackEvents (private Member Function)

Loops through TrackEvents on a each Track, dispatching a trackeventadded event. This functionality is used to notify other objects when a Track gets re-inserted or re-added to a Media object, since there may be TrackEvents on a Track before it is added.

• track [ Track ]: Track object from which TrackEvents are read.

@event: trackeventadded

Usage:

addNewTrackTrackEvents(track);

##Media::Media::addTrack (public Member Function)

Adds a Track object to this Media object in order.

• track [ Track or Object ]: Track to be added. If track is an basic object, it will be converted to a Track.

@event: trackadded, trackorderchanged

Usage:

m.addTrack(track);

##Media::Media::cleanUpEmptyTracks (public Member Function)

Removes Tracks which contain no TrackEvents.

Usage:

m.cleanUpEmptyTracks();

##Media::Media::clear (public Member Function)

Removes all tracks from this Media object.

Usage:

m.clear();

##Media::Media::compareTrackOrder (public Member Function)

Helper function for sorting Tracks by their order.

• a [ Track ]: A Track to compare with another.
• b [ Track ]: A Track to compare with another.

Usage:

compareTrackOrder(a, b);

##Media::Media::destroy (public Member Function)

Disengages this Media object from use by severing link to Popcorn.

Usage:

m.destroy();

##Media::Media::ensureNewTrackIsTrack (private Member Function)

Ensures that the provided object is a Track object. If it isn't, a new Track object is created and returned. Otherwise, the original object is returned.

• track [ Track or Object ]: Track object to inspect.

@return [ Track ]: A Track object

Usage:

ensureNewTrackIsTrack(track);

##Media::Media::findNextAvailableTrackFromTimes (public Member Function)

Returns a Track with an available space between the specified start and end times. If no such Track exists, null is returned.

• start [ Number ]: Low bound of time window to search for.
• end [ Number ]: High bound of time window to search for.

@return [ Track or null ]: A Track with space available between the specified times.

Usage:

m.findNextAvailableTrackFromTimes(start, end);

##Media::Media::findTrackWithTrackEventId (public Member Function)

Checks each Track for the existence of a TrackEvent with a specific id.

• id [ String ]: Id of TrackEvent to look for.

Usage:

m.findTrackWithTrackEventId(id);

##Media::Media::fixTrackEventBounds (public Member Function)

Checks TrackEvents on Tracks to ensure that they have valid start and end times, 0 -> duration. If a TrackEvent is found to have an invalid start or end time, it is removed.

Usage:

m.fixTrackEventBounds();

##Media::Media::forceEmptyTrackSpaceAtTime (public Member Function)

Searches for a space on the specified Track between the given times. If the Track does not have space available, a new Track is added after the specified Track.

• track [ Track ]: Reference Track used to conduct an initial search. A new Tracks is added after this one when necessary.
• start [ Number ]: Low bound of time window to search for.
• end [ Number ]: High bound of time window to search for.
• ignoreTrackEvent [ TrackEvent ]: Optional. When specified, this TrackEvent is ignored during a search.

@return [ Track ]: A Track with available space between the specified times.

Usage:

m.forceEmptyTrackSpaceAtTime(track, start, end, ignoreTrackEvent);

##Media::Media::generatePopcornString (public Member Function)

Uses the current state of this Media object to generate a string representing the complete setup of a Popcorn environment containing all the TrackEvent contents attached to Tracks on this Media object.

• callbacks [ Dictionary ]: Named callbacks to run for different stages of string generation (see PopcornWrapper).
• scripts [ Dictionary ]: Named scripts to insert at different stages of string generation (see PopcornWrapper).

@return [ String ]: A string representing a complete Popcorn environment mirroring the functionality of this Media object.

Usage:

m.generatePopcornString(callbacks, scripts);

##Media::Media::getLastTrack (public Member Function)

Returns the previous Track object with respect to Track order. If the specified Track is the first Track, null is returned.

• currentTrack [ Track ]: Reference Track. The Track before currentTrack will be returned.

@return [ Track or null ]: The next Track.

Usage:

m.getLastTrack(currentTrack);

##Media::Media::getManifest (public Member Function)

Returns the Popcorn manifest for the specified plugin type.

• type [ String ]: Type of Popcorn plugin; e.g. text, footnote, googlemap

Usage:

m.getManifest(type);

##Media::Media::getNextTrack (public Member Function)

Returns the next Track object with respect to Track order. If the specified Track is the last Track, null is returned.

• currentTrack [ Track ]: Reference Track. The Track after currentTrack will be returned.

@return [ Track or null ]: The next Track.

Usage:

m.getNextTrack(currentTrack);

##Media::Media::getTrackById (public Member Function)

Loops over all Tracks and returns the first (if any) that has an id equal to that which is provided.

• id [ String ]: Id of Track to find.

Usage:

m.getTrackById(id);

##Media::Media::insertTrackBefore (public Member Function)

Inserts a Track object before another Track object already attached to this Media object. Order is preserved.

• otherTrack [ Track ]: Reference Track in front of which the new track will be added.
• newTrack [ Track or Object ]: Track to be added. If track is an basic object, it will be converted to a Track.

@event: trackadded, trackorderchanged

Usage:

m.insertTrackBefore(otherTrack, newTrack);

##Media::Media::onReady (public Member Function)

Calls the provided callback function when this Media object is ready to use. If this Media is not immediately ready, the callback will be called after the mediaready event is fired.

• callback [ Function ]: Callback to execute when ready.

Usage:

m.onReady(callback);

##Media::Media::pause (public Member Function)

Pauses the attached media; proxied through Popcorn using PopcornWrapper.

• callback [ Function ]: Callback to execute when ready.

Usage:

m.pause();

##Media::Media::play (public Member Function)

Plays the attached media; proxied through Popcorn using PopcornWrapper.

• callback [ Function ]: Callback to execute when ready.

Usage:

m.play();

##Media::Media::removeTrack (public Member Function)

Removes a Track from this Media object.

• track [ Track ]: Track to remove.

@event: trackremoved, trackeventremoved

Usage:

m.removeTrack(track);

##Media::Media::retrieveSrc (public Member Function)

Checks to see if there are any child source elements and uses them if neccessary.

• targetElement [ DOMElement ]: Element to check for a source.

Usage:

retrieveSrc(targetElement);

##Media::Media::sanitizeUrl (public Member Function)

Internally, URLs are decorated with a unique butteruid. This function strips it. Useful for exporting.

@return [ String ]: Sanitized url.

Usage:

sanitizeUrl();

##Media::Media::setupContent (public Member Function)

Begins the process of initializing Popcorn with the URL given to this Media object.

Usage:

setupContent();

##Media::Media::setupNewTrack (private Member Function)

Prepares a Track for use with this Media by setting up chain listeners, storing a reference to the Track, and providing access to a Popcorn wrapper.

• track [ Track ]: Track object to setup.

Usage:

setupNewTrack(track);

##Media::Media::sortTracks (public Member Function)

Sorts attached Tracks based on their order property using compareTrackOrder.

• suppressEvent [ Boolean ]: If true, trackorderchanged event is not dispatched.

@event: trackorderchanged

Usage:

m.sortTracks(suppressEvent);