m3u8 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75266714b1670b4990419287c300fa920604bf1c
-  data.tar.gz: af15a6e305fcbf82517d0b2858aed3fa848a80b2
+  metadata.gz: 266fa2220bfc0c9acdc04144747da7d7a01d9b5f
+  data.tar.gz: ed5b06cd8baccf5eec7a4fd592a4715a367fa791
 SHA512:
-  metadata.gz: 787197f4b3f4807c17125928e3b976c46f66b914b4bf7566c34e5748dd9200d84492c7fa858874d21cbbb9b7dbbfc9b91f04bac8954760a8e18689514459589e
-  data.tar.gz: 7d279886bd83eacfcd8e2e71463f6b96075dd5e3ed8d742d3b0c5ee7c0dc97932a7c07943fe5b49bad9e44c6631023f916479c5b0a7936c035d9d37adec79e74
+  metadata.gz: 9942efab7468eaa317280e6b465251d972700e43ce3b7b0ca281c4fe3084ad3743acbe24074a324fdaa4f9421be0da732a3128e00311b468caf257814337ba1e
+  data.tar.gz: d02d9f3c6853f68557ff89d5a6a7d3d4f3a2c77a5d1ea535fa3e5c89911ec0c724e8646dfaa2da6f951a8672494fb32cfc1b9dd0502da95d29ed0a82e94e3d94

data/.gitignore

@@ -1,15 +1,6 @@
-/.bundle/
-/.yardoc
-/Gemfile.lock
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-*.bundle
-*.so
-*.o
-*.a
-mkmf.log
+/.bundle
+/coverage
+/pkg
+/tmp
+.Gemfile.lock
 .ruby-version

data/.travis.yml

@@ -1,8 +1,8 @@
 language: ruby
 sudo: true
 rvm:
-- 2.4.0
-- 2.3.3
-- 2.2.6
+- 2.4.1
+- 2.3.4
+- 2.2.7
 
 script: rspec spec

data/CHANGELOG.md

@@ -1,8 +1,17 @@
-0.7.1 (2/23/2017) - Added support for the EXT-X-DATERANGE tag. Minor refactoring of existing classes.
+**0.8.0 (4/13/2017)**
+
+* Added several improvements for writing playlists: Allow playlist to be initalized as master, expose `write_header`/`write_footer` on `Writer` class. 
+* Added support for the `#EXT-X-DISCONTINUITY-SEQUENCE` tag. Added missing attributes to `MediaItem`: `INSTREAM-ID`, `CHARACTERISTICS`, `CHANNELS`, Added missing `HDCP-LEVEL` attribute to `PlaylistItem`. 
+* Fixed issue [#20](https://github.com/sethdeckard/m3u8/issues/20). 
+* Merged pull request #21 from [rmberg](https://github.com/rmberg), adding support for live playlists to `Writer`.
+
+***
+
+0.7.1 (2/23/2017) - Added support for the `#EXT-X-DATERANGE` tag. Minor refactoring of existing classes.
 
 ***
 
-0.7.0 (2/3/2017) - Added support for EXT-X-INDEPENDENT-SEGMENTS and EXT-X-START tags. Minor version bumped due to changes of default values for new playlists.
+0.7.0 (2/3/2017) - Added support for `#EXT-X-INDEPENDENT-SEGMENTS` and `#EXT-X-START` tags. Minor version bumped due to changes of default values for new playlists.
 
 ***
 

data/README.md

@@ -6,7 +6,13 @@
 [![security](https://hakiri.io/github/sethdeckard/m3u8/master.svg)](https://hakiri.io/github/sethdeckard/m3u8/master)
 # m3u8
 
-m3u8 provides generation and parsing of m3u8 playlists used the [HTTP Live Streaming](https://developer.apple.com/library/ios/documentation/networkinginternet/conceptual/streamingmediaguide/Introduction/Introduction.html#//apple_ref/doc/uid/TP40008332-CH1-SW1) (HLS) specification created by Apple. This is useful if you wish to generate m3u8 playlists on the fly in your web application (to integrate authentication, do something custom,  etc) while of course serving up the actual MPEG transport stream files (.ts) from a CDN. You could also use m3u8 to generate playlist files as part of an encoding pipeline. You can also parse existing playlists, add content to them and generate a new output.
+m3u8 provides easy generation and parsing of m3u8 playlists defined in the [HTTP Live Streaming (HLS)](https://tools.ietf.org/html/draft-pantos-http-live-streaming-20) Internet Draft published by Apple.
+
+* The library completely implements version 20 of the HLS Internet Draft.
+* Provides parsing of an m3u8 playlist into an object model from any File, StringIO, or string.
+* Provides ability to write playlist to a File or StringIO or expose as string via to_s.
+* Distinction between a master and media playlist is handled automatically (single Playlist class).
+* Optionally, the library can automatically generate the audio/video codecs string used in the CODEC attribute based on specified H.264, AAC, or MP3 options (such as Profile/Level).
 
 ## Installation
 
@@ -86,23 +92,8 @@ options = { width: 1920, height: 1080, codecs: 'avc1.66.30,mp4a.40.2',
 item = M3u8::PlaylistItem.new(options)
 ```
 
-Just get the codec string for custom use:
-
-```ruby
-options = { profile: 'baseline', level: 3.0, audio_codec: 'aac-lc' }
-codecs = M3u8::Playlist.codecs(options)
-# => "avc1.66.30,mp4a.40.2"
-```  
-      
-Values for audio_codec (codec name): aac-lc, he-aac, mp3
-    
-Possible values for profile (H.264 Profile): baseline, main, high.
-    
-Possible values for level (H.264 Level): 3.0, 3.1, 4.0, 4.1. 
-
-Not all Levels and Profiles can be combined, consult H.264 documentation
 
-## Parsing Usage
+## Usage (parsing playlists)
 
 ```ruby
 file = File.open 'spec/fixtures/master.m3u8'
@@ -131,49 +122,26 @@ playlist.items.unshift(item)
 ```
 
 M3u8::Reader is the class handles parsing if you want more control over the process.
-    
-## Features
-* Distinction between segment and master playlists is handled automatically (no need to use a different class).
-* Automatically generates the audio/video codec string based on names and options you are familiar with.
-* Provides validation of input when adding playlists or segments.
-* Allows all options to be configured on a playlist (caching, version, etc.)
-* Can write playlist to an IO object (StringIO/File, etc) or access string via to_s.
-* Can read playlists into a model (Playlist and Items) from an IO object.
-* Any tag or attribute supported by the object model is supported both parsing and generation of m3u8 playlists.
-* Supports I-frames (Intra frames) and byte ranges in Segments.
-* Supports subtitles, closed captions, alternate audio and video, and comments.
-* Supports session data in master playlists.
-* Supports keys for encrypted media segments (EXT-X-KEY, EXT-SESSION-KEY).
-
-## HLS Spec Status (version 20)
-### Implemented:
-* EXTM3U
-* EXT-X-VERSION
-* EXTINF  
-* EXT-X-BYTERANGE
-* EXT-X-DISCONTINUITY
-* EXT-X-KEY
-* EXT-X-MAP
-* EXT-X-PROGRAM-DATE-TIME
-* EXT-X-TARGETDURATION
-* EXT-X-MEDIA-SEQUENCE
-* EXT-X-ENDLIST
-* EXT-X-PLAYLIST-TYPE
-* EXT-X-I-FRAMES-ONLY
-* EXT-X-MEDIA
-* EXT-X-STREAM-INF
-* EXT-X-I-FRAME-STREAM-INF
-* EXT-X-SESSION-DATA
-* EXT-X-SESSION-KEY
-* EXT-X-START
-
-### TODO:
-* EXT-X-DATERANGE
+
+## Usage (misc)
+Generate the codec string based on audio and video codec options without dealing a playlist instance:
+
+```ruby
+options = { profile: 'baseline', level: 3.0, audio_codec: 'aac-lc' }
+codecs = M3u8::Playlist.codecs(options)
+# => "avc1.66.30,mp4a.40.2"
+```  
+      
+* Values for audio_codec (codec name): aac-lc, he-aac, mp3   
+* Values for profile (H.264 Profile): baseline, main, high.
+* Values for level (H.264 Level): 3.0, 3.1, 4.0, 4.1. 
+
+Not all Levels and Profiles can be combined and validation is not currently implemented, consult H.264 documentation for further details.
+
 
 ## Roadmap 
-* Add the last remaining tags for latest version of the spec.
-* Validation of all attributes and their values to match the rules defined in the spec.
-* Support for different versions of spec, defaulting to latest.
+* Implement validation of all tags, attributes, and values per HLS I-D.
+* Perhaps support for different versions of HLS I-D, defaulting to latest.
 
 ## Contributing
 

data/lib/m3u8/byte_range.rb

@@ -11,11 +11,11 @@ module M3u8
     end
 
     def self.parse(text)
-      values = text.split '@'
+      values = text.split('@')
       length_value = values[0].to_i
       start_value = values[1].to_i unless values[1].nil?
       options = { length: length_value, start: start_value }
-      ByteRange.new options
+      ByteRange.new(options)
     end
 
     def to_s

data/lib/m3u8/discontinuity_item.rb

@@ -3,8 +3,6 @@ module M3u8
   # DiscontinuityItem represents a EXT-X-DISCONTINUITY tag to indicate a
   # discontinuity between the SegmentItems that proceed and follow it.
   class DiscontinuityItem
-    attr_accessor :tag
-
     def to_s
       "#EXT-X-DISCONTINUITY\n"
     end

data/lib/m3u8/error.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 module M3u8
-  class PlaylistTypeError < StandardError
+  class InvalidPlaylistError < StandardError
   end
 
   class MissingCodecError < StandardError
   end
+
+  class PlaylistTypeError < StandardError
+  end
 end

data/lib/m3u8/map_item.rb

@@ -12,11 +12,11 @@ module M3u8
     end
 
     def self.parse(text)
-      attributes = parse_attributes text
+      attributes = parse_attributes(text)
       range_value = attributes['BYTERANGE']
       range = ByteRange.parse(range_value) unless range_value.nil?
       options = { uri: attributes['URI'], byterange: range }
-      MapItem.new options
+      MapItem.new(options)
     end
 
     def to_s

data/lib/m3u8/media_item.rb

@@ -4,7 +4,8 @@ module M3u8
   class MediaItem
     extend M3u8
     attr_accessor :type, :group_id, :language, :assoc_language, :name,
-                  :autoselect, :default, :uri, :forced
+                  :autoselect, :default, :uri, :forced, :instream_id,
+                  :characteristics, :channels
 
     def initialize(params = {})
       params.each do |key, value|
@@ -13,7 +14,7 @@ module M3u8
     end
 
     def self.parse(text)
-      attributes = parse_attributes text
+      attributes = parse_attributes(text)
       options = { type: attributes['TYPE'], group_id: attributes['GROUP-ID'],
                   language: attributes['LANGUAGE'],
                   assoc_language: attributes['ASSOC-LANGUAGE'],
@@ -21,25 +22,34 @@ module M3u8
                   autoselect: parse_yes_no(attributes['AUTOSELECT']),
                   default: parse_yes_no(attributes['DEFAULT']),
                   forced: parse_yes_no(attributes['FORCED']),
-                  uri: attributes['URI'] }
-      MediaItem.new options
+                  uri: attributes['URI'],
+                  instream_id: attributes['INSTREAM-ID'],
+                  characteristics: attributes['CHARACTERISTICS'],
+                  channels: attributes['CHANNELS'] }
+      MediaItem.new(options)
     end
 
     def to_s
-      attributes = [type_format,
-                    group_id_format,
-                    language_format,
-                    assoc_language_format,
-                    name_format,
-                    autoselect_format,
-                    default_format,
-                    uri_format,
-                    forced_format].compact.join(',')
-      "#EXT-X-MEDIA:#{attributes}"
+      "#EXT-X-MEDIA:#{formatted_attributes.join(',')}"
     end
 
     private
 
+    def formatted_attributes
+      [type_format,
+       group_id_format,
+       language_format,
+       assoc_language_format,
+       name_format,
+       autoselect_format,
+       default_format,
+       uri_format,
+       forced_format,
+       instream_id_format,
+       characteristics_format,
+       channels_format].compact
+    end
+
     def type_format
       "TYPE=#{type}"
     end
@@ -82,6 +92,21 @@ module M3u8
       "FORCED=#{to_yes_no forced}"
     end
 
+    def instream_id_format
+      return if instream_id.nil?
+      %(INSTREAM-ID="#{instream_id}")
+    end
+
+    def characteristics_format
+      return if characteristics.nil?
+      %(CHARACTERISTICS="#{characteristics}")
+    end
+
+    def channels_format
+      return if channels.nil?
+      %(CHANNELS="#{channels}")
+    end
+
     def to_yes_no(boolean)
       boolean == true ? 'YES' : 'NO'
     end

data/lib/m3u8/playlist.rb

@@ -3,22 +3,23 @@ module M3u8
   # Playlist represents an m3u8 playlist, it can be a master playlist or a set
   # of media segments
   class Playlist
-    attr_accessor :items, :version, :cache, :target, :sequence, :type,
-                  :iframes_only, :independent_segments
+    attr_accessor :items, :version, :cache, :target, :sequence,
+                  :discontinuity_sequence, :type, :iframes_only,
+                  :independent_segments, :live
 
     def initialize(options = {})
-      assign_options options
-      self.items = []
+      assign_options(options)
+      @items = []
     end
 
     def self.codecs(options = {})
-      item = PlaylistItem.new options
+      item = PlaylistItem.new(options)
       item.codecs
     end
 
     def self.read(input)
       reader = Reader.new
-      reader.read input
+      reader.read(input)
     end
 
     def write(output)
@@ -26,8 +27,14 @@ module M3u8
       writer.write(self)
     end
 
+    def live?
+      return false if master?
+      @live
+    end
+
     def master?
-      return false if playlist_size == 0 && segment_size == 0
+      return @master unless @master.nil?
+      return false if playlist_size.zero? && segment_size.zero?
       playlist_size > 0
     end
 
@@ -55,13 +62,16 @@ module M3u8
     def assign_options(options)
       options = defaults.merge(options)
 
-      self.version = options[:version]
-      self.sequence = options[:sequence]
-      self.cache = options[:cache]
-      self.target = options[:target]
-      self.type = options[:type]
-      self.iframes_only = options[:iframes_only]
-      self.independent_segments = options[:independent_segments]
+      @version = options[:version]
+      @sequence = options[:sequence]
+      @discontinuity_sequence = options[:discontinuity_sequence]
+      @cache = options[:cache]
+      @target = options[:target]
+      @type = options[:type]
+      @iframes_only = options[:iframes_only]
+      @independent_segments = options[:independent_segments]
+      @master = options[:master]
+      @live = options[:live]
     end
 
     def defaults
@@ -69,7 +79,8 @@ module M3u8
         sequence: 0,
         target: 10,
         iframes_only: false,
-        independent_segments: false
+        independent_segments: false,
+        live: false
       }
     end
 

data/lib/m3u8/playlist_item.rb

@@ -7,7 +7,7 @@ module M3u8
     attr_accessor :program_id, :width, :height, :codecs, :bandwidth,
                   :audio_codec, :level, :profile, :video, :audio, :uri,
                   :average_bandwidth, :subtitles, :closed_captions, :iframe,
-                  :frame_rate, :name
+                  :frame_rate, :name, :hdcp_level
     MISSING_CODEC_MESSAGE = 'Audio or video codec info should be provided.'
 
     def initialize(params = {})
@@ -37,11 +37,11 @@ module M3u8
     def codecs
       return @codecs unless @codecs.nil?
 
-      video = video_codec(profile, level)
-      return audio_codec if video.nil?
-      return video if audio_codec.nil?
+      video_code = video_codec(profile, level)
+      return audio_codec_code if video_code.nil?
+      return video_code if audio_codec_code.nil?
 
-      "#{video},#{audio_codec}"
+      "#{video_code},#{audio_codec_code}"
     end
 
     def to_s
@@ -65,7 +65,7 @@ module M3u8
         video: attributes['VIDEO'], audio: attributes['AUDIO'],
         uri: attributes['URI'], subtitles: attributes['SUBTITLES'],
         closed_captions: attributes['CLOSED-CAPTIONS'],
-        name: attributes['NAME'] }
+        name: attributes['NAME'], hdcp_level: attributes['HDCP-LEVEL'] }
     end
 
     def parse_average_bandwidth(value)
@@ -105,6 +105,7 @@ module M3u8
        bandwidth_format,
        average_bandwidth_format,
        frame_rate_format,
+       hdcp_level_format,
        audio_format,
        video_format,
        subtitles_format,
@@ -127,6 +128,11 @@ module M3u8
       "FRAME-RATE=#{format('%.3f', frame_rate)}"
     end
 
+    def hdcp_level_format
+      return if hdcp_level.nil?
+      "HDCP-LEVEL=#{hdcp_level}"
+    end
+
     def codecs_format
       %(CODECS="#{codecs}")
     end
@@ -170,7 +176,7 @@ module M3u8
       %(NAME="#{name}")
     end
 
-    def audio_codec
+    def audio_codec_code
       return if @audio_codec.nil?
       return 'mp4a.40.2' if @audio_codec.casecmp('aac-lc').zero?
       return 'mp4a.40.5' if @audio_codec.casecmp('he-aac').zero?