Proposed changes to media Track and children

[David DeHaven]

To support multi-track movies (primarily for alternate languages and subtitles/captioning), we need to make some changes to the existing public media API. Other changes will be discussed separately...

I have two (and a half) options at the moment and I thought I'd throw it out to you guys to help decide which direction to go.

Option 1>
Make the following changes to Track and it's subclasses:
Changes to Track:
- Add public final Locale getLocale(), returns a Locale if one is provided by the container or null if not
- Add public final long getTrackId(), returns a unique numeric track ID that will be used by the stack to identify this specific track
- Add public final Map<String,Object> getMetadata(), returns any metadata specific to this Track (returned Map is an UnmodifiableMap for security)

Changes to AudioTrack:
- getLanguage(): deprecate, "use Track.getLocale() instead." Which is all that method does now anyways.


Option 2> 
- Deprecate Track, AudioTrack, VideoTrack and the Media.tracks property
- Add a "tracks" value to the Media metadata Map (retrieved by Media.getMetadata()). This would essentially be a Map<Number,Map<String,Object>>. The outer Map would contain one entry per track, keyed to the tracks unique ID (what would be returned by getTrackID() above) and it's Map would be the metadata associated with that track, including all the fields currently contained in the Track classes.


Option 1.5, a compromise between Option 1 and Option 2>
- Deprecate AudioTrack and VideoTrack, leave Track and Media.tracks property
- Add a track type property (yet another enum?) and reflect the type in the track metadata (textually, using names like "video" and "audio")
- Include the other changes to Track in option 1
- The properties of Audio/VideoTrack would be accessed from the track metadata


Reasoning (read: my lousy attempt at kicking off a discussion):

The Track classes are pure metadata (I've no intention of ever changing that…) and at the moment we have kind of a duality of metadata representation for Media, provided as a Map via the Media metadata property and also represented by an assortment of properties in Media and the Track classes. Option 1 basically sticks with the current split model, extending it to allow more flexibility moving forward. Of particular importance is the unique track ID which will be required to select which tracks are active in the future. Option 2 reduces classes in the API and treats tracks purely as metadata, but it also ends up embedding Maps three levels deep which seems a bit ugly to me. Option 1.5 is a bit of a compromise between the two, leaving the tracks property that can be listened to (which is handy for UI purposes and might be handy for streaming, if it's supported) but still moving information into a metadata table instead of cluttering the classes up with a bunch of properties for data that may or may not exist.


I've opened a JIRA issue to track this:
http://javafx-jira.kenai.com/browse/RT-25678

-DrD-