Added support for #EXT-X-MEDIA:TYPE=SUBTITLES tracks

[neilrackett]

I have added support for WebVTT subtitles tracks on both live and VOD streams, modelled on the existing alternative audio classes and implemented using the TX3G timed text standard, with subtitles tracks announced via a NetStream client onMetaData event and subtitles FLVTag metadata injected into the stream as onTextData events.

As an alternative to using a NetStream client object, subtitles related events have also been added (see below).

Overview

Subtitles tracks are detected and selected in the same way as alternative audio tracks. When a subtitles track is selected, onTextData metadata is added to the stream and Flashls will dispatch SUBTITLES_CHANGE events when subtitles should be displayed.

There is currently no OSMF or Flowplayer specific integration.

New HLS class properties

• subtitlesPlaylistTracks:Vector.<SubtitlesPlaylistTrack> subtitles equivalent to altAudioTracks
• subtitlesTracks:Vector.<SubtitlesTrack>subtitles equivalent to audioTracks
• subtitlesTrack:int subtitles equivalent to audioTrack

New HLSEvent class constants and properties

Constants

• SUBTITLES_TRACKS_LIST_CHANGE when subtitles tracks are detected or changed
• SUBTITLES_TRACK_SWITCH when the selected subtitles track changes
• SUBTITLES_LEVEL_LOADING when the subtitles level is loading
• SUBTITLES_LEVEL_LOADED when the subtitles level is loaded
• SUBTITLES_CHANGE when the current subtitles change

Properties

• subtitlesTrack:int the subtitles track ID related to the current event
• subtitle:Subtitle model containing subtitles related to the current event

New HLSSettings properties

• autoSelectSubtitles:Boolean whether or not to select subtitles tracks flagged AUTOSELECT=YES that match the current system locale (taken from HLS spec)
• autoSelectDefaultSubtitles:Boolean whether or not to select subtitles tracks flagged DEFAULT=YES (selected in preference to AUTOSELECT=YES)
• autoSelectForcedSubtitles:Boolean whether or not to select subtitles tracks flagged FORCED=YES (selected in preference to any other)

Code example

// Using events
hls.addEventListener(HLSEvent.SUBTITLES_CHANGE, function(e:HLSEvent):void
{
    trace(e.subtitle.text);
});

// Using NetStream client
hls.stream.client = {
    onTextData: function(textData:Object):void {
        if (textData.trackid == hls.subtitlesTrack) trace(textData.text);
    }
}

if (hls.subtitlesTracks.length) hls.subtitlesTrack = 0;

Additional bug fixes

• Updated HLSNetStreamClient to ensure parameters are passed to client objects in original format rather than in one parameter as an Array
• Initialized _levels property in FragmentLoader as empty Vector.<Level> to prevent crash after "I/O Error while trying to load Playlist" caused by null object reference
• Updated Windows build script to support alternative build paths via first parameter, e.g. build ..\temp, to enable developers to build SWF/SWC files for testing without affecting SWF/SWC files in the repo (folders will be created if they don't exist)
• Added build-temp.bat as a quick way of building into bin-temp, which is ignored by git

[neilrackett]

An HLS stream with subtitles:
http://playertest.longtailvideo.com/adaptive/eleph-audio/playlist.m3u8

[Matrixian]

Thank you for working on this.

Am I correct in the assumption that the following would return the subtitles to the external javascript application (e.g. chromeless player):

var frags : Vector.<Fragment> = Manifest.getFragments(string, url, level);

// other code

_hls.dispatchEvent(new HLSEvent(HLSEvent.SUBTITLES_LEVEL_LOADED, metrics, frags));

[neilrackett]

I'm only working with the OSMF implementation, so I'm not familiar with how the chromeless player works.

Are you trying to expose the WebVTT file URLs or the parsed Subtitle objects? If you simply want to know when to display subtitles in JS, SUBTITLES_CHANGE would be more useful.

[klouskingsley]

Hi, what's the status of this PR, do we have a plan to review & merge it?