media_playlist.h

// Copyright 2016 Google LLC. All rights reserved.
//
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file or at
// https://developers.google.com/open-source/licenses/bsd
 
#ifndef PACKAGER_HLS_BASE_MEDIA_PLAYLIST_H_
#define PACKAGER_HLS_BASE_MEDIA_PLAYLIST_H_
 
#include <cstdint>
#include <filesystem>
#include <list>
#include <memory>
#include <string>
#include <vector>
 
#include <absl/time/time.h>
 
#include <packager/hls_params.h>
#include <packager/macros/classes.h>
#include <packager/media/base/fourccs.h>
#include <packager/mpd/base/bandwidth_estimator.h>
#include <packager/mpd/base/media_info.pb.h>
 
namespace shaka {
 
class File;
 
namespace hls {
 
class HlsEntry {
 public:
  enum class EntryType {
    kExtInf,
    kExtKey,
    kExtDiscontinuity,
    kExtPlacementOpportunity,
    kProgramDateTime,
  };
  virtual ~HlsEntry();
 
  EntryType type() const { return type_; }
  virtual std::string ToString() = 0;
 
 protected:
  explicit HlsEntry(EntryType type);
 
 private:
  EntryType type_;
};
 
class MediaPlaylist {
 public:
  enum class MediaPlaylistStreamType {
    kUnknown,
    kAudio,
    kVideo,
    kVideoIFramesOnly,
    kSubtitle,
  };
  enum class EncryptionMethod {
    kNone,           // No encryption, i.e. clear.
    kAes128,         // Completely encrypted using AES-CBC.
    kSampleAes,      // Encrypted using SAMPLE-AES method.
    kSampleAesCenc,  // 'cenc' encrypted content.
  };
 
  MediaPlaylist(const HlsParams& hls_params,
                const std::string& file_name,
                const std::string& name,
                const std::string& group_id);
  virtual ~MediaPlaylist();
 
  const std::string& file_name() const { return file_name_; }
  const std::string& name() const { return name_; }
  const std::string& group_id() const { return group_id_; }
  MediaPlaylistStreamType stream_type() const { return stream_type_; }
  const std::string& codec() const { return codec_; }
  const std::string& supplemental_codec() const { return supplemental_codec_; }
  const media::FourCC& compatible_brand() const { return compatible_brand_; }
  const std::list<std::unique_ptr<HlsEntry>>& entries() const {
    return entries_;
  }
 
  void SetStreamTypeForTesting(MediaPlaylistStreamType stream_type);
 
  void SetCodecForTesting(const std::string& codec);
 
  void SetLanguageForTesting(const std::string& language);
 
  void SetForcedSubtitleForTesting(const bool forced_subtitle);
 
  void SetCharacteristicsForTesting(
      const std::vector<std::string>& characteristics);
 
  void SetIndexForTesting(uint32_t index);
 
  void AddEncryptionInfoForTesting(MediaPlaylist::EncryptionMethod method,
                                   const std::string& url,
                                   const std::string& key_id,
                                   const std::string& iv,
                                   const std::string& key_format,
                                   const std::string& key_format_versions);
 
  virtual bool SetMediaInfo(const MediaInfo& media_info);
  MediaInfo GetMediaInfo() const { return media_info_; }
 
  virtual void SetSampleDuration(int32_t sample_duration);
 
  virtual void AddSegment(const std::string& file_name,
                          int64_t start_time,
                          int64_t duration,
                          uint64_t start_byte_offset,
                          uint64_t size);
 
  virtual void SetReferenceTime(const absl::Time& reference_time);
 
  virtual void AddKeyFrame(int64_t timestamp,
                           uint64_t start_byte_offset,
                           uint64_t size);
 
  virtual void AddEncryptionInfo(EncryptionMethod method,
                                 const std::string& url,
                                 const std::string& key_id,
                                 const std::string& iv,
                                 const std::string& key_format,
                                 const std::string& key_format_versions);
 
  virtual void AddPlacementOpportunity();
 
  virtual bool WriteToFile(const std::filesystem::path& file_path,
                           bool event_to_vod_on_end_of_stream,
                           bool end_stream);
 
  virtual uint64_t MaxBitrate() const;
 
  virtual uint64_t AvgBitrate() const;
 
  virtual double GetLongestSegmentDuration() const;
 
  virtual void SetTargetDuration(int32_t target_duration);
 
  virtual int GetNumChannels() const;
 
  virtual int GetEC3JocComplexity() const;
 
  virtual bool GetAC4ImsFlag() const;
 
  virtual bool GetAC4CbiFlag() const;
 
  virtual bool GetDisplayResolution(uint32_t* width, uint32_t* height) const;
 
  virtual std::string GetVideoRange() const;
 
  virtual double GetFrameRate() const;
 
  const std::string& language() const { return language_; }
 
  const std::vector<std::string>& characteristics() const {
    return characteristics_;
  }
 
  bool forced_subtitle() const { return forced_subtitle_; }
 
  bool is_dvs() const {
    // HLS Authoring Specification for Apple Devices
    // https://developer.apple.com/documentation/http_live_streaming/hls_authoring_specification_for_apple_devices#overview
    // Section 2.12.
    const char DVS_CHARACTERISTICS[] = "public.accessibility.describes-video";
    return characteristics_.size() == 1 &&
           characteristics_[0] == DVS_CHARACTERISTICS;
  }
 
 private:
  // Add a SegmentInfoEntry (#EXTINF).
  void AddSegmentInfoEntry(const std::string& segment_file_name,
                           int64_t start_time,
                           int64_t duration,
                           uint64_t start_byte_offset,
                           uint64_t size);
  // Adjust the duration of the last SegmentInfoEntry to end on
  // |next_timestamp|.
  void AdjustLastSegmentInfoEntryDuration(int64_t next_timestamp);
  // Remove elements from |entries_| for live profile. Increments
  // |sequence_number_| by the number of segments removed.
  void SlideWindow();
  // Remove the segment specified by |start_time|. The actual deletion can
  // happen at a later time depending on the value of
  // |preserved_segment_outside_live_window| in |hls_params_|.
  void RemoveOldSegment(int64_t start_time);
 
  const HlsParams& hls_params_;
  // Mainly for MasterPlaylist to use these values.
  const std::string file_name_;
  const std::string name_;
  const std::string group_id_;
  MediaInfo media_info_;
  MediaPlaylistStreamType stream_type_ = MediaPlaylistStreamType::kUnknown;
  // Whether to use byte range for SegmentInfoEntry.
  bool use_byte_range_ = false;
  std::string codec_;
  std::string supplemental_codec_;
  media::FourCC compatible_brand_;
  std::string language_;
  std::vector<std::string> characteristics_;
  bool forced_subtitle_ = false;
  uint32_t media_sequence_number_ = 0;
  bool inserted_discontinuity_tag_ = false;
  int discontinuity_sequence_number_ = 0;
 
  double longest_segment_duration_seconds_ = 0.0;
  int32_t time_scale_ = 0;
 
  BandwidthEstimator bandwidth_estimator_;
 
  // Cache the previous calls AddSegment() end offset. This is used to construct
  // SegmentInfoEntry.
  uint64_t previous_segment_end_offset_ = 0;
 
  // See SetTargetDuration() comments.
  bool target_duration_set_ = false;
  int32_t target_duration_ = 0;
 
  // TODO(kqyang): This could be managed better by a separate class, than having
  // all them managed in MediaPlaylist.
  std::list<std::unique_ptr<HlsEntry>> entries_;
  double current_buffer_depth_ = 0;
  // A list to hold the file names of the segments to be removed temporarily.
  // Once a file is actually removed, it is removed from the list.
  std::list<std::string> segments_to_be_removed_;
 
  // This is the wall clock time when media timestamp is 0.
  absl::Time reference_time_;
 
  // Used by kVideoIFrameOnly playlists to track the i-frames (key frames).
  struct KeyFrameInfo {
    int64_t timestamp;
    uint64_t start_byte_offset;
    uint64_t size;
    std::string segment_file_name;
  };
  std::list<KeyFrameInfo> key_frames_;
 
  DISALLOW_COPY_AND_ASSIGN(MediaPlaylist);
};
 
class ProgramDateTimeEntry : public HlsEntry {
 public:
  explicit ProgramDateTimeEntry(const absl::Time& program_time);
 
  std::string ToString() override;
 
 private:
  ProgramDateTimeEntry(const ProgramDateTimeEntry&) = delete;
  ProgramDateTimeEntry& operator=(const ProgramDateTimeEntry&) = delete;
 
  const absl::Time program_time_;
};
 
class EncryptionInfoEntry : public HlsEntry {
 public:
  EncryptionInfoEntry(MediaPlaylist::EncryptionMethod method,
                      const std::string& url,
                      const std::string& key_id,
                      const std::string& iv,
                      const std::string& key_format,
                      const std::string& key_format_versions);
 
  std::string ToString() override;
  std::string ToString(std::string);
 
 private:
  EncryptionInfoEntry(const EncryptionInfoEntry&) = delete;
  EncryptionInfoEntry& operator=(const EncryptionInfoEntry&) = delete;
 
  const MediaPlaylist::EncryptionMethod method_;
  const std::string url_;
  const std::string key_id_;
  const std::string iv_;
  const std::string key_format_;
  const std::string key_format_versions_;
};
 
}  // namespace hls
}  // namespace shaka
 
#endif  // PACKAGER_HLS_BASE_MEDIA_PLAYLIST_H_