hls

package
v0.0.0-...-ffcc1d7 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2024 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package hls implements the Manifest interface of package m3u8 to encode/parse playlists used in HTTP Live Streaming. Comments explaining type attributes are related to HLS Spec 'MUST' and 'MUST NOT' recommendations, and should be considered when creating your MediaPlaylist and MasterPlaylist objects for encoding.

Example usage:

Encoding Manifest 

import "github.com/ingest/manifest/hls"

func main(){
  //Will start a MediaPlaylist object for hls version 7
  p := hls.NewMediaPlaylist(7)
  p.TargetDuration = 10
  p.EndList = true
  segment := &hls.Segment{
    URI:       "segmenturi.ts",
    Inf:       &hls.Inf{Duration: 9.052},
    Byterange: &hls.Byterange{Length: 400},
  }
  p.Segments = append(p.Segments, segment)
  reader, err := p.Encode()
  if err!=nil{
  //handle error
  }

  buf := new(bytes.Buffer)
  buf.ReadFrom(reader)

  if err := ioutil.WriteFile("path/to/file", buf.Bytes(), 0666); err != nil {
  //handle error
  }
}

Decoding Manifest 

import "github.com/ingest/manifest/hls"

func main(){
  f, err := os.Open("path/to/file.m3u8")
  if err != nil {
    //handle error
  }
  defer f.Close()

  playlist := &hls.MasterPlaylist{}
  if err = playlist.Parse(bufio.NewReader(f)); err!=io.EOF{
    //handle error
  }
  //manipulate playlist
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Byterange 

type Byterange struct {
	Length int64
	Offset *int64
}

Byterange represents tag #EXT-X-BYTERANGE. Introduced in HLSv4. Format: length[@offset].

func (*Byterange) Equal 

func (b *Byterange) Equal(other *Byterange) bool

Equal determines if the two byterange objects are equal and contain the same values

type DateRange 

type DateRange struct {
	ID               string    //Required. If more than one tag with same ID exists, att values MUST be the same.
	Class            string    //Optional. Specifies some set of attributes and their associated value semantics.
	StartDate        time.Time //Required.
	EndDate          time.Time //Optional.
	Duration         *float64  //Optional. If both EndDate and Duration present, check EndDate equal to Duration + StartDate
	PlannedDuration  *float64  //Optional. Expected duration.
	XClientAttribute []string  //Optional. Namespace reserved for client-defined att. eg. X-COM-EXAMPLE="example".
	EndOnNext        bool      //Optional. Possible Value: YES. Indicates the end of the current date range is equal to the start date of the following range of the samePROGRAM-DATE-TIME class.
	SCTE35           *SCTE35
}

DateRange represents tag #EXT-X-DATERANGE:<attribute=value>.

If present, playlist MUST also contain at least one EXT-X-PROGRAM-DATE-TIME tag. Tags with the same Class MUST NOT indicate ranges that overlap.

type DateRanges 

type DateRanges []*DateRange

type Inf 

type Inf struct {
	Duration float64
	Title    string
}

Inf represents tag 

#EXTINF: <duration>,[<title>]

type Key 

type Key struct {
	IsSession         bool   //Identifies if #EXT-X-KEY or #EXT-X-SESSION-KEY. If #EXT-X-SESSION-KEY, Method MUST NOT be NONE.
	Method            string //Required. Possible Values: NONE, AES-128, SAMPLE-AES. If NONE, other attributes MUST NOT be present.
	URI               string //Required unless the method is NONE. Specifies how to get the key for the encryption method.
	IV                string //Optional. Hexadecimal that specifies a 128-bit int Initialization Vector to be used with the key.
	Keyformat         string //Optional. Specifies how the key is represented in the resource. V5 or higher
	Keyformatversions string //Optional. Indicates which Keyformat versions this instance complies with. Default value is 1. V5 or higher
	// contains filtered or unexported fields
}

Key represents tags #EXT-X-KEY:<attribute=value> and #EXT-X-SESSION-KEY. Specifies how to decrypt an encrypted media segment. #EXT-X-SESSION-KEY is exclusively a Master Playlist tag (HLS V7) and it SHOULD be used if multiple Variant Streams use the same encryption keys. TODO(jstackhouse): Split SESSION-KEY into it's own type as it's got different validation properties, and is part of the master playlist, not media playlist.

func (*Key) AbsoluteURL 

func (k *Key) AbsoluteURL() (string, error)

AbsoluteURL will resolve the Key URI to a absolute path, given it is a URL.

func (*Key) Equal 

func (k *Key) Equal(other *Key) bool

Equal checks whether all public fields are equal in a Key with the exception of the IV field.

func (*Key) Request 

func (k *Key) Request() (*http.Request, error)

Request creates a new http request ready to retrieve the segment

type Map 

type Map struct {
	URI       string     //Required.
	Byterange *Byterange //Optional. Indicates the byte range into the URI resource containing the Media Initialization Section.
	// contains filtered or unexported fields
}

Map represents tag #EXT-X-MAP:<attribute=value>. Specifies how to get the Media Initialization Section

func (*Map) AbsoluteURL 

func (m *Map) AbsoluteURL() (string, error)

AbsoluteURL will resolve the EXT-X-MAP URI to a absolute path, given it is a URL.

func (*Map) Equal 

func (m *Map) Equal(other *Map) bool

Equal determines if the two maps are equal, does not check private fields for equality so this does not guarantee that two maps will act identically. Works on nil structures, if both m and other are nil, they are considered equal.

func (*Map) Request 

func (m *Map) Request() (*http.Request, error)

Request creates a new http request ready to retrieve the segment

type MasterPlaylist 

type MasterPlaylist struct {
	URI                 string       // Location of the master playlist
	M3U                 bool         // Represents tag #EXTM3U. Indicates if present. MUST be present.
	Version             int          // Represents tag #EXT-X-VERSION. MUST be present.
	Variants            []*Variant   // Represents the #EXT-X-I-FRAME-STREAM-INF and #EXT-X-STREAM-INF playlists
	Renditions          []*Rendition // Represents the #EXT-X-MEDIA tags
	SessionData         []*SessionData
	SessionKeys         []*Key
	IndependentSegments bool // Represents tag #EXT-X-INDEPENDENT-SEGMENTS. Applies to every Media Segment of every Media Playlist referenced. V6 or higher.
	StartPoint          *StartPoint
}

MasterPlaylist represents a Master Playlist and its tags

func NewMasterPlaylist 

func NewMasterPlaylist(version int) *MasterPlaylist

NewMasterPlaylist returns an instance of a MasterPlaylist with a set version

func (*MasterPlaylist) Encode 

func (p *MasterPlaylist) Encode() (io.Reader, error)

Encode writes a Master Playlist file

func (*MasterPlaylist) Parse 

func (p *MasterPlaylist) Parse(reader io.Reader) error

Parse reads a Master Playlist file and converts it to a MasterPlaylist object

func (*MasterPlaylist) Request 

func (m *MasterPlaylist) Request() (*http.Request, error)

Request creates a new http request ready to retrieve the segment

type MediaPlaylist 

type MediaPlaylist struct {
	*Variant                          // Variant is embedded, contains information on how the master playlist represented this media playlist.
	Version               int         // Version is required, is written #EXT-X-VERSION: <int>.
	Segments              Segments    // Segments are represented by #EXT-INF\n <duration>.
	TargetDuration        int         // TargetDuration is required, is written #EXT-X-TARGETDURATION: <int>. MUST BE >= largest EXT-INF duration
	MediaSequence         int         //Represents tag #EXT-X-MEDIA-SEQUENCE. Number of the first media sequence in the playlist.
	DiscontinuitySequence int         //Represents tag #EXT-X-DISCONTINUITY-SEQUENCE. If present, MUST appear before the first Media Segment. MUST appear before any EXT-X-DISCONTINUITY Media Segment tag.
	EndList               bool        //Represents tag #EXT-X-ENDLIST. Indicates no more media segments will be added to the playlist.
	Type                  string      //Possible Values: EVENT or VOD. Represents tag #EXT-X-PLAYLIST-TYPE. If EVENT - segments can only be added to the end of playlist. If VOD - playlist cannot change. If segments need to be removed from playlist, this tag MUST NOT be present
	IFramesOnly           bool        //Represents tag #EXT-X-I-FRAMES-ONLY. If present, segments MUST begin with either a Media Initialization Section or have a EXT-X-MAP tag.
	AllowCache            bool        //Possible Values: YES or NO. Represents tag #EXT-X-ALLOW-CACHE. Versions 3 - 6 only.
	IndependentSegments   bool        //Represents tag #EXT-X-INDEPENDENT-SEGMENTS. Applies to every Media Segment in the playlist.
	StartPoint            *StartPoint //Represents tag #EXT-X-START
}

MediaPlaylist represents a Media Playlist and its tags.

TODO:(sliding window) - add field for sliding window to represent either the max amount of segments or the max duration of a window (TBD). Also would be useful to add variable to track the current first and last sequence numbers as a helper to adding and removing segments and tracking MediaSequence, DiscontinuitySequence etc

func NewMediaPlaylist 

func NewMediaPlaylist(version int) *MediaPlaylist

NewMediaPlaylist returns an instance of a MediaPlaylist with a set version

func (*MediaPlaylist) Encode 

func (p *MediaPlaylist) Encode() (io.Reader, error)

Encode writes a Media Playlist file

func (*MediaPlaylist) Parse 

func (p *MediaPlaylist) Parse(reader io.Reader) error

Parse reads a Media Playlist file and convert it to MediaPlaylist object

func (*MediaPlaylist) WithVariant 

func (p *MediaPlaylist) WithVariant(v *Variant) *MediaPlaylist

WithVariant supplies the data which was processed from the master playlist.

type Rendition 

type Rendition struct {
	Type            string //Possible Values: AUDIO, VIDEO, SUBTITLES, CLOSED-CAPTIONS. Required.
	URI             string //URI containing the media playlist. If type is CLOSED-CAPTIONS, URI MUST NOT be present.
	GroupID         string //Required.
	Language        string //Optional. Identifies the primary language used in the rendition. Must be one of the standard tags RFC5646
	AssocLanguage   string //Optional. Language tag RFC5646
	Name            string //Required. Description of the rendition. SHOULD be written in the same language as Language
	Default         bool   //Possible Values: YES, NO. Optional. Defines if rendition should be played by client if user doesn't choose a rendition. Default: NO
	AutoSelect      bool   //Possible Values: YES, NO. Optional. Client MAY choose this rendition if user doesn't choose one. if present, MUST be YES if Default=YES. Default: NO.
	Forced          bool   //Possible Values: YES, NO. Optional. MUST NOT be present unless Type is SUBTITLES. Default: NO.
	InstreamID      string //Specifies a rendition within the Media Playlist. MUST NOT be present unless Type is CLOSED-CAPTIONS. Possible Values: CC1, CC2, CC3, CC4, or SERVICEn where n is int between 1 - 63
	Characteristics string //Optional. One or more Uniform Type Indentifiers separated by comma. Each UTI indicates an individual characteristic of the Rendition.
	// contains filtered or unexported fields
}

Rendition represents the tag #EXT-X-MEDIA

Relates Media Playlists with alternative renditions of the same content. Eg. Audio only playlists containing English, French and Spanish renditions of the same content. One or more X-MEDIA tags with same GroupID and Type sets a group of renditions and MUST meet the following constraints: 

-Tags in the same group MUST have different Name att.
-MUST NOT have more than one member with a Default att of YES
-All members whose AutoSelect att is YES MUST have Language att with unique values

func (*Rendition) AbsoluteURL 

func (r *Rendition) AbsoluteURL() (string, error)

AbsoluteURL will resolve the rendition URI to a absolute path, given it is a URL.

func (*Rendition) Request 

func (r *Rendition) Request() (*http.Request, error)

Request creates a new http request ready to retrieve the segment

type SCTE35 

type SCTE35 struct {
	Type  string //Possible Values: IN, OUT, CMD
	Value string //big-endian binary representation of the splice_info_section(), expressed as a hexadecimal-sequence.
}

SCTE35 represents a DateRange attribute SCTE35-OUT, SCTE35-IN or SCTE35-CMD

type Segment 

type Segment struct {
	ID              int //Sequence number
	URI             string
	Inf             *Inf //Required.
	Byterange       *Byterange
	Discontinuity   bool //Represents tag #EXT-X-DISCONTINUITY. MUST be present if there's change in file format; number, type and identifiers of tracks or timestamp sequence
	Keys            []*Key
	Map             *Map
	ProgramDateTime time.Time //Represents tag #EXT-X-PROGRAM-DATE-TIME
	DateRanges      DateRanges
	// contains filtered or unexported fields
}

Segment represents the Media Segment and its tags

func (*Segment) AbsoluteURL 

func (s *Segment) AbsoluteURL() (string, error)

AbsoluteURL will resolve the segment URI to a absolute path, given it is a relative URL.

func (*Segment) Request 

func (s *Segment) Request() (*http.Request, error)

Request creates a new http request ready to send to retrieve the segment

type Segments 

type Segments []*Segment

Segments implements golang/sort interface to sort a Segment slice by Segment ID

func (Segments) Len 

func (s Segments) Len() int

func (Segments) Less 

func (s Segments) Less(i, j int) bool

func (Segments) Swap 

func (s Segments) Swap(i, j int)

type SessionData 

type SessionData struct {
	DataID   string //Required. SHOULD conform with a reverse DNS naming convention.
	Value    string //Required IF URI is not present. Contains the session data
	URI      string //Required IF Value is not present. Resource with the session data
	Language string //Optional. RFC5646 language tag that identifies the language of the data
	// contains filtered or unexported fields
}

SessionData represents tag #EXT-X-SESSION-DATA. Master Playlist MAY contain more than one tag with the same DataID but the Language MUST be different. Introduced in HLSv7.

func (*SessionData) AbsoluteURL 

func (s *SessionData) AbsoluteURL() (string, error)

AbsoluteURL will resolve the SessionData URI to a absolute path, given it is a URL.

func (*SessionData) Request 

func (s *SessionData) Request() (*http.Request, error)

Request creates a new http request ready to retrieve the segment

type Source 

type Source interface {
	Master(ctx context.Context, uri string) (*MasterPlaylist, error)
	Media(ctx context.Context, variant *Variant) (*MediaPlaylist, error)
	Resource(ctx context.Context, uri string) (io.ReadCloser, error)
}

Source represents how you can fetch the components of a HLS manifest from different locations

type StartPoint 

type StartPoint struct {
	TimeOffset float64 //Required. If positive, time offset from the beginning of the Playlist. If negative, time offset from the end of the last segment of the playlist
	Precise    bool    //Possible Values: YES or NO.
}

StartPoint represents tag #EXT-X-START. Indicates preferred point at which to start playing a Playlist.

type Variant 

type Variant struct {
	IsIframe       bool    //Identifies if #EXT-X-STREAM-INF or #EXT-X-I-FRAME-STREAM-INF
	URI            string  //If #EXT-X-STREAM-INF, URI line MUST follow the tag. If #EXT-X-I-FRAME-STREAM-INF, URI MUST appear as an attribute of the tag.
	ProgramID      int64   //Removed on Version 6
	Bandwidth      int64   //Required. Peak segment bit rate.
	AvgBandwidth   int64   //Optional. Average segment bit rate of the Variant Stream.
	Codecs         string  //Optional. Comma-separated list of formats. Valid formats are the ones specified in RFC6381. SHOULD be present.
	Resolution     string  //Optional. Optimal pixel resolution.
	FrameRate      float64 //Optional. Maximum frame rate. Optional. SHOULD be included if any video exceeds 30 frames per second.
	Audio          string  //Optional. Indicates the set of audio renditions that SHOULD be used. MUST match GroupID value of an EXT-X-MEDIA tag whose Type is AUDIO.
	Video          string  //Optional. Indicates the set of video renditions that SHOULD be used. MUST match GroupID value of an EXT-X-MEDIA tag whose Type is VIDEO.
	Subtitles      string  //Optional. Indicates the set of subtitle renditions that SHOULD be used. MUST match GroupID value of an EXT-X-MEDIA tag whose Type is SUBTITLES.
	ClosedCaptions string  //Optional. Indicates the set of closed-caption renditions that SHOULD be used. Can be quoted-string or NONE.
	// contains filtered or unexported fields
}

Variant represents the tag #EXT-X-STREAM-INF: <attribute-list> and tag #EXT-X-I-FRAME-STREAM-INF. #EXT-X-STREAM-INF specifies a Variant Stream, which is one of the ren which can be combined to play the presentation. A URI line following the tag indicates the Media Playlist carrying a rendition of the Variant Stream and it MUST be present.

#EXT-X-I-FRAME-STREAM-INF identifies Media Playlist file containing the I-frames of a multimedia presentation. It supports the same parameters as EXT-X-STREAM-INF except Audio, Subtitles and ClosedCaptions.

func (*Variant) AbsoluteURL 

func (v *Variant) AbsoluteURL() (string, error)

AbsoluteURL will resolve the variant URI to a absolute path, given it is a URL.

func (*Variant) Request 

func (v *Variant) Request() (*http.Request, error)

Request creates a new http request ready to retrieve the segment

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.