feat: support for VODs with subtitles (#90)

Support for VOD with subtitles. A dummy URL can be provided as a fallback when no subtitle segments are available

---------

Co-authored-by: Jonas Birmé <jonas.birme@eyevinn.se>

removed unnecessary files from testvectors and added a new test

added support for starting without subs and added dummy fallback on all vods with subs enabled

added bugfix to aduio

solved issue regarind deltaTime/playhead position

solved bug regarding overwrighting and shifting of subtitltes

chore: removed mac OS file

chore: remove mac OS file

fixed code review comments

updated documentation

forgot to account for capital letters and added a shouldContainSubtitleCheck

removed unused varible

.gitignore

@@ -1,2 +1,4 @@
 node_modules
 .nyc_output
+.DS_Store
+.vscode

API.md

@@ -14,15 +14,21 @@
     * [.getLiveMediaSequenceSegments(seqIdx)](#HLSVod+getLiveMediaSequenceSegments)
     * [.getMediaSegments()](#HLSVod+getMediaSegments)
     * [.getLiveMediaSequenceAudioSegments(audioGroupId, audioLanguage, seqIdx)](#HLSVod+getLiveMediaSequenceAudioSegments)
+    * [.getLiveMediaSequenceSubtitleSegments(subtitleGroupId, subtitleLanguage, seqIdx)](#HLSVod+getLiveMediaSequenceSubtitleSegments)
     * [.getBandwidths()](#HLSVod+getBandwidths)
-    * [.getLiveMediaSequencesCount()](#HLSVod+getLiveMediaSequencesCount)
+    * [.getSubtitleGroups(all?)](#HLSVod+getSubtitleGroups)
+    * [.getSubtitleLangsForSubtitleGroup(groupId, all?)](#HLSVod+getSubtitleLangsForSubtitleGroup)
+    * [.getLiveMediaSequencesCount(media?)](#HLSVod+getLiveMediaSequencesCount)
     * [.getLastSequenceMediaSequenceValue()](#HLSVod+getLastSequenceMediaSequenceValue)
     * [.getLastSequenceMediaSequenceValueAudio()](#HLSVod+getLastSequenceMediaSequenceValueAudio)
+    * [.getLastSequenceMediaSequenceValueSubtitle()](#HLSVod+getLastSequenceMediaSequenceValueSubtitle)
     * [.getLiveMediaSequences(offset, bandwidth, seqIdx, discOffset, padding, forceTargetDuration)](#HLSVod+getLiveMediaSequences)
-    * [.getLiveMediaAudioSequences()](#HLSVod+getLiveMediaAudioSequences)
+    * [.getLiveMediaAudioSequences(offset, bandwidth, seqIdx, discOffset, padding, forceTargetDuration)](#HLSVod+getLiveMediaAudioSequences)
+    * [.getLiveMediaSubtitleSequences(offset, bandwidth, seqIdx, discOffset, padding, forceTargetDuration)](#HLSVod+getLiveMediaSubtitleSequences)
     * [.getUsageProfiles()](#HLSVod+getUsageProfiles)
     * [.getLastDiscontinuity()](#HLSVod+getLastDiscontinuity)
     * [.getLastDiscontinuityAudio()](#HLSVod+getLastDiscontinuityAudio)
+    * [.getLastDiscontinuitySubtitle()](#HLSVod+getLastDiscontinuitySubtitle)
     * [.getDeltaTimes()](#HLSVod+getDeltaTimes)
     * [.getPlayheadPositions()](#HLSVod+getPlayheadPositions)
     * [.releasePreviousVod()](#HLSVod+releasePreviousVod)
@@ -136,15 +142,57 @@ Get all audio segments (duration, uri) for a specific media sequence
 | audioLanguage | <code>string</code> | audio language |
 | seqIdx | <code>number</code> | media sequence index (first is 0) |
 
+**Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
+<a name="HLSVod+getLiveMediaSequenceSubtitleSegments"></a>
+
+### hlsVod.getLiveMediaSequenceSubtitleSegments(subtitleGroupId, subtitleLanguage, seqIdx)
+Get all subtitle segments (duration, uri) for a specific media sequence
+
+**Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| subtitleGroupId | <code>string</code> | subtitle group Id |
+| subtitleLanguage | <code>string</code> | subtitle language |
+| seqIdx | <code>number</code> | media sequence index (first is 0) |
+
+**Kind**: instance method of [<code>HLSVod</code>](#HLSVod)
 <a name="HLSVod+getBandwidths"></a>
 
 ### hlsVod.getBandwidths()
 Get the available bandwidths for this VOD
 
+**Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
+<a name="HLSVod+getSubtitleGroups"></a>
+
+### hlsVod.getSubtitleGroups(all?)
+Get the available subtitle group for this VOD
+
+there exists a default group with a lang used to create dummy segments which can be filtered using all parameter
+
+| Param | Type | Description |
+| --- | --- | --- |
+| all | <code>boolean</code> | used to determine if you want all the langs or not, false by default |
+
+**Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
+<a name="HLSVod+getSubtitleLangsForSubtitleGroup"></a>
+
+### hlsVod.getSubtitleLangsForSubtitleGroup(groupId)
+Get the all language for a specific groupId
+
+| Param | Type | Description |
+| --- | --- | --- |
+| groupId | <code>string</code> | subtitle group Id |
+
 **Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
 <a name="HLSVod+getLiveMediaSequencesCount"></a>
 
-### hlsVod.getLiveMediaSequencesCount()
+### hlsVod.getLiveMediaSequencesCount(media?)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| media | <code>string</code> | pass this variable to select video, audio or subtitle. If omitted video is assumed |
+
 Get the number of media sequences for this VOD
 
 **Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
@@ -160,6 +208,22 @@ Get the media-sequence value for the last media sequence of this VOD
 Get the media-sequence value for the last audio media sequence of this VOD
 
 **Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
+<a name="HLSVod+getLastSequenceMediaSequenceValueSubtitle"></a>
+
+### hlsVod.getLastSequenceMediaSequenceValueSubtitle()
+Get the media-sequence value for the last subtitle media sequence of this VOD
+
+**Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| offset | <code>number</code> | add this offset to all media sequences in the EXT-X-MEDIA-SEQUENCE tag |
+| bandwidth | <code>string</code> |  |
+| seqIdx | <code>number</code> |  |
+| discOffset | <code>number</code> | add this offset to all discontinuity sequences in the EXT-X-DISCONTINUITY-SEQUENCE tag |
+| padding | <code>number</code> | add extra seconds on the EXT-X-TARGETDURATION |
+| forceTargetDuration | <code>number</code> | enforce a fixed EXT-X-TARGETDURATION |
+
 <a name="HLSVod+getLiveMediaSequences"></a>
 
 ### hlsVod.getLiveMediaSequences(offset, bandwidth, seqIdx, discOffset, padding, forceTargetDuration)
@@ -178,10 +242,28 @@ Get the HLS live media sequence for a specific media sequence and bandwidth
 
 <a name="HLSVod+getLiveMediaAudioSequences"></a>
 
-### hlsVod.getLiveMediaAudioSequences()
+### hlsVod.getLiveMediaAudioSequences(offset, bandwidth, seqIdx, discOffset, padding, forceTargetDuration)
 Gets a hls/makes m3u8-file with all of the correct audio segments
 belonging to a given groupID & language for a particular sequence.
 
+**Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| offset | <code>number</code> | add this offset to all media sequences in the EXT-X-MEDIA-SEQUENCE tag |
+| bandwidth | <code>string</code> |  |
+| seqIdx | <code>number</code> |  |
+| discOffset | <code>number</code> | add this offset to all discontinuity sequences in the EXT-X-DISCONTINUITY-SEQUENCE tag |
+| padding | <code>number</code> | add extra seconds on the EXT-X-TARGETDURATION |
+| forceTargetDuration | <code>number</code> | enforce a fixed EXT-X-TARGETDURATION |
+
+
+<a name="HLSVod+getLiveMediaSubtitleSequences"></a>
+
+### hlsVod.getLiveMediaSubtitleSequences(offset, bandwidth, seqIdx, discOffset, padding, forceTargetDuration)
+Gets a hls/makes m3u8-file with all of the correct subtitle segments
+belonging to a given groupID & language for a particular sequence.
+
 **Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
 <a name="HLSVod+getUsageProfiles"></a>
 
@@ -200,6 +282,12 @@ Get the last discontinuity sequence number
 ### hlsVod.getLastDiscontinuityAudio()
 Get the last audio discontinuity sequence number
 
+**Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
+<a name="HLSVod+getLastDiscontinuitySubtitle"></a>
+
+### hlsVod.getLastDiscontinuitySubtitle()
+Get the last subtitle discontinuity sequence number
+
 **Kind**: instance method of [<code>HLSVod</code>](#HLSVod)  
 <a name="HLSVod+getDeltaTimes"></a>
 

README.md

@@ -12,7 +12,7 @@ npm install --save @eyevinn/hls-vodtolive
 
 ## Usage
 
-This library load and parses HLS VOD manifests and generates HLS Live manifests. The example below loads one HLS VOD and then another HLS VOD that is appendend to the first one. The `getLiveMediaSequences(mediaseq)` returns HLS Live media sequence slices, and in the example below outputs the last live media sequence representation of the first VOD.
+This library load and parses HLS VOD manifests and generates HLS Live manifests. The example below loads one HLS VOD and then another HLS VOD that is appended to the first one. The `getLiveMediaSequences(mediaseq)` returns HLS Live media sequence slices, and in the example below outputs the last live media sequence representation of the first VOD.
 
 ```
 const HLSVod = require('@eyevinn/hls-vodtolive');
@@ -116,6 +116,16 @@ segB2.ts
 segB3.ts
 ```
 
+
+To use this library with subtitles the following options are required to be supplied when creating a new instance of HLSVod
+ ```
+shouldContainSubtitles: true, // says that the loaded VOD should contain subtitles and to create dummy if missing.
+expectedSubtitleTracks: subtitleTracks, // says that the loaded VOD should contain subtitles and to create dummy if missing
+dummySubtitleEndpoint: "/dummysubs.vtt", // it should link to an endpoint that will serve empty vtt files.
+subtitleSliceEndpoint: "/subtitlevtt.vtt", // it should link to an endpoint that can splice and vtt file and serve it in case a VOD contains
+    subtitle segments longer than video segments.
+```
+
 # Documentation
 
 - [API Documentation](API.md)