rill-node 0.0.0-stage → 2026.11.15

package/native-src/src/rill/format_selector.cr

@@ -0,0 +1,143 @@
+require "./download_plan"
+require "./format"
+
+module Rill
+  enum FormatPreference
+    AudioAndVideo
+    AudioOnly
+    VideoOnly
+  end
+end
+
+module Rill::FormatSelector
+  extend self
+
+  CONTAINER_RANK = {
+    "mp4"  => 5,
+    "webm" => 4,
+    "mkv"  => 4,
+    "m4v"  => 3,
+    "mov"  => 3,
+    "ogv"  => 2,
+    "avi"  => 1,
+  }
+
+  def best(formats : Array(Format)) : Format?
+    return nil if formats.empty?
+
+    combined = formats.select { |format| format.kind == FormatKind::Combined }
+    return best_video(combined) unless combined.empty?
+
+    video = formats.select { |format| format.kind == FormatKind::Video }
+    return best_video(video) unless video.empty?
+
+    best_audio(formats)
+  end
+
+  def plan(
+    formats : Array(Format),
+    format_id : String? = nil,
+    preference : FormatPreference = FormatPreference::AudioAndVideo,
+  ) : DownloadPlan?
+    return nil if formats.empty?
+
+    if format_id
+      selected = by_id(formats, format_id)
+      return nil unless selected
+
+      return plan_for(selected, formats)
+    end
+
+    case preference
+    when .audio_only?
+      audio = best_audio_only(formats)
+      audio ? DownloadPlan.new(audio) : nil
+    when .video_only?
+      video = best_video_only(formats)
+      video ? DownloadPlan.new(video) : nil
+    else
+      audio_and_video_plan(formats)
+    end
+  end
+
+  private def audio_and_video_plan(formats : Array(Format)) : DownloadPlan?
+    combined = formats.select { |format| format.kind == FormatKind::Combined }
+    unless combined.empty?
+      return DownloadPlan.new(best_video(combined))
+    end
+
+    video = best_video_only(formats)
+    unless video.nil?
+      return DownloadPlan.new(video, best_audio_for(video, formats))
+    end
+
+    audio = best_audio_only(formats)
+    audio ? DownloadPlan.new(audio) : nil
+  end
+
+  private def best_video_only(formats : Array(Format)) : Format?
+    video = formats.select { |format| format.kind == FormatKind::Video }
+    return nil if video.empty?
+
+    best_video(video)
+  end
+
+  private def best_audio_only(formats : Array(Format)) : Format?
+    audio = formats.select { |format| format.kind == FormatKind::Audio }
+    return nil if audio.empty?
+
+    audio.max_by? do |format|
+      {
+        (format.bitrate || 0).to_i64,
+        (format.audio_bitrate || 0).to_i64,
+        format.filesize || 0_i64,
+      }
+    end || audio.first
+  end
+
+  def by_id(formats : Array(Format), format_id : String) : Format?
+    formats.find { |format| format.format_id == format_id }
+  end
+
+  private def plan_for(selected : Format, formats : Array(Format)) : DownloadPlan
+    return DownloadPlan.new(selected) unless selected.kind == FormatKind::Video
+
+    DownloadPlan.new(selected, best_audio_for(selected, formats))
+  end
+
+  private def best_audio_for(video : Format, formats : Array(Format)) : Format?
+    audio = formats.select { |format| format.kind == FormatKind::Audio }
+    return nil if audio.empty?
+
+    audio.max_by? do |format|
+      {
+        video.container && format.container == video.container ? 1 : 0,
+        (format.bitrate || 0).to_i64,
+        (format.audio_bitrate || 0).to_i64,
+        format.filesize || 0_i64,
+      }
+    end || audio.first
+  end
+
+  private def best_video(formats : Array(Format)) : Format
+    formats.max_by? do |format|
+      {
+        format.height || 0,
+        CONTAINER_RANK[format.container || ""]? || 0,
+        (format.video_bitrate || 0).to_i64,
+        format.bitrate || 0_i64,
+        format.filesize || 0_i64,
+      }
+    end || formats.first
+  end
+
+  private def best_audio(formats : Array(Format)) : Format
+    formats.max_by? do |format|
+      {
+        (format.bitrate || 0).to_i64,
+        (format.audio_bitrate || 0).to_i64,
+        format.filesize || 0_i64,
+      }
+    end || formats.first
+  end
+end

package/native-src/src/rill/hls/parser.cr

@@ -0,0 +1,257 @@
+require "uri"
+
+require "../errors"
+require "./playlist"
+
+module Rill::Hls::Parser
+  extend self
+
+  STREAM_INF = "#EXT-X-STREAM-INF:"
+  MEDIA      = "#EXT-X-MEDIA:"
+  EXTINF     = "#EXTINF:"
+  KEY        = "#EXT-X-KEY:"
+  MAP        = "#EXT-X-MAP:"
+  BYTERANGE  = "#EXT-X-BYTERANGE:"
+  ENDLIST    = "#EXT-X-ENDLIST"
+
+  def parse(source : String, base_url : URI) : MultivariantPlaylist | MediaPlaylist
+    text = source.lchop('\uFEFF')
+    lines = text.lines.map(&.strip).reject(&.empty?)
+
+    unless lines.first? == "#EXTM3U"
+      raise ManifestError.new("HLS playlist is missing #EXTM3U")
+    end
+
+    if lines.any?(&.starts_with?(STREAM_INF))
+      parse_master(lines, base_url)
+    else
+      parse_media(lines, base_url)
+    end
+  end
+
+  def parse_attributes(text : String) : Hash(String, String)
+    attributes = {} of String => String
+    index = 0
+
+    while index < text.size
+      while index < text.size && (text[index] == ' ' || text[index] == ',')
+        index += 1
+      end
+      break if index >= text.size
+
+      key_start = index
+      while index < text.size && text[index] != '='
+        index += 1
+      end
+
+      if index >= text.size
+        raise ManifestError.new("invalid HLS attribute: #{text}")
+      end
+
+      key = text[key_start, index - key_start].strip
+      index += 1
+
+      value = if index < text.size && text[index] == '"'
+                index += 1
+                value_start = index
+                while index < text.size && text[index] != '"'
+                  index += 1
+                end
+
+                if index >= text.size
+                  raise ManifestError.new("unterminated HLS attribute: #{text}")
+                end
+
+                result = text[value_start, index - value_start]
+                index += 1
+                result
+              else
+                value_start = index
+                while index < text.size && text[index] != ','
+                  index += 1
+                end
+                text[value_start, index - value_start].strip
+              end
+
+      attributes[key.upcase] = value unless key.empty?
+    end
+
+    attributes
+  end
+
+  private def parse_master(lines : Array(String), base_url : URI) : MultivariantPlaylist
+    variants = [] of Variant
+    renditions = [] of Rendition
+    pending : Hash(String, String)? = nil
+
+    lines.each do |line|
+      if line.starts_with?(STREAM_INF)
+        pending = parse_attributes(line[STREAM_INF.size..])
+        next
+      end
+
+      if line.starts_with?(MEDIA)
+        renditions << build_rendition(parse_attributes(line[MEDIA.size..]), base_url)
+        next
+      end
+
+      next if line.starts_with?('#')
+
+      if attributes = pending
+        variants << build_variant(attributes, line, base_url)
+        pending = nil
+      end
+    end
+
+    raise ManifestError.new("HLS master playlist has a dangling stream") if pending
+    raise ManifestError.new("HLS master playlist has no variants") if variants.empty?
+
+    MultivariantPlaylist.new(variants, renditions)
+  end
+
+  private def build_rendition(
+    attributes : Hash(String, String),
+    base_url : URI,
+  ) : Rendition
+    type = attributes["TYPE"]?
+    raise ManifestError.new("HLS media rendition is missing a type") unless type
+
+    uri = attributes["URI"]?
+
+    Rendition.new(
+      type: type.upcase,
+      group_id: attributes["GROUP-ID"]?,
+      name: attributes["NAME"]?,
+      language: attributes["LANGUAGE"]?,
+      url: uri ? resolve(uri, base_url) : nil,
+      default: attributes["DEFAULT"]? == "YES",
+      autoselect: attributes["AUTOSELECT"]? == "YES",
+    )
+  end
+
+  private def build_variant(
+    attributes : Hash(String, String),
+    uri_text : String,
+    base_url : URI,
+  ) : Variant
+    width = nil
+    height = nil
+
+    if resolution = attributes["RESOLUTION"]?
+      if match = /\A(\d+)x(\d+)\z/.match(resolution)
+        width = match[1].to_i?
+        height = match[2].to_i?
+      end
+    end
+
+    Variant.new(
+      url: resolve(uri_text, base_url),
+      bandwidth: parse_i64(attributes["BANDWIDTH"]?),
+      average_bandwidth: parse_i64(attributes["AVERAGE-BANDWIDTH"]?),
+      width: width,
+      height: height,
+      codecs: attributes["CODECS"]?,
+      audio_group: attributes["AUDIO"]?,
+      subtitle_group: attributes["SUBTITLES"]?,
+    )
+  end
+
+  private def parse_media(lines : Array(String), base_url : URI) : MediaPlaylist
+    segments = [] of Segment
+    map_url : URI? = nil
+    map_byte_range : ByteRange? = nil
+    encrypted = false
+    ended = false
+    duration = 0.0
+    pending_duration = 0.0
+    pending_title : String? = nil
+    pending_range : ByteRange? = nil
+
+    lines.each do |line|
+      case
+      when line.starts_with?(EXTINF)
+        pending_duration, pending_title = parse_extinf(line[EXTINF.size..])
+      when line.starts_with?(KEY)
+        attributes = parse_attributes(line[KEY.size..])
+        method = attributes["METHOD"]?
+        encrypted = true unless method.nil? || method == "NONE"
+      when line.starts_with?(MAP)
+        attributes = parse_attributes(line[MAP.size..])
+        uri = attributes["URI"]?
+        raise ManifestError.new("HLS map section is missing a URI") unless uri
+
+        map_url = resolve(uri, base_url)
+        if range = attributes["BYTERANGE"]?
+          map_byte_range = parse_byte_range(range)
+        end
+      when line.starts_with?(BYTERANGE)
+        pending_range = parse_byte_range(line[BYTERANGE.size..])
+      when line.starts_with?(ENDLIST)
+        ended = true
+      when line.starts_with?('#')
+        next
+      else
+        segments << Segment.new(
+          url: resolve(line, base_url),
+          duration: pending_duration,
+          title: pending_title,
+          byte_range: pending_range,
+        )
+        duration += pending_duration
+        pending_duration = 0.0
+        pending_title = nil
+        pending_range = nil
+      end
+    end
+
+    raise ManifestError.new("HLS media playlist has no segments") if segments.empty?
+
+    MediaPlaylist.new(
+      segments: segments,
+      duration_seconds: duration,
+      ended: ended,
+      encrypted: encrypted,
+      map_url: map_url,
+      map_byte_range: map_byte_range,
+    )
+  end
+
+  private def parse_extinf(text : String) : Tuple(Float64, String?)
+    duration_text, comma, title = text.partition(',')
+    duration = duration_text.to_f?
+    unless duration && duration.finite? && duration >= 0
+      raise ManifestError.new("invalid HLS segment duration: #{duration_text}")
+    end
+
+    parsed_title = comma.empty? || title.empty? ? nil : title
+    {duration, parsed_title}
+  end
+
+  private def parse_byte_range(value : String) : ByteRange
+    length_text, separator, offset_text = value.strip.partition('@')
+    length = length_text.to_i64?
+    raise ManifestError.new("invalid HLS byte range: #{value}") unless length
+
+    offset = nil
+    unless separator.empty?
+      offset = offset_text.to_i64?
+      raise ManifestError.new("invalid HLS byte range offset: #{value}") unless offset
+    end
+
+    ByteRange.new(length, offset)
+  end
+
+  private def parse_i64(value : String?) : Int64?
+    value.try(&.to_i64?)
+  end
+
+  private def resolve(value : String, base_url : URI) : URI
+    uri = base_url.resolve(value)
+    unless uri.scheme == "http" || uri.scheme == "https"
+      raise ManifestError.new("unsupported HLS URI: #{value}")
+    end
+    uri
+  rescue URI::Error
+    raise ManifestError.new("invalid HLS URI: #{value}")
+  end
+end

package/native-src/src/rill/hls/playlist.cr

@@ -0,0 +1,100 @@
+require "uri"
+
+module Rill::Hls
+  struct ByteRange
+    getter length : Int64
+    getter offset : Int64?
+
+    def initialize(@length : Int64, @offset : Int64? = nil)
+    end
+  end
+
+  struct Variant
+    getter url : URI
+    getter bandwidth : Int64?
+    getter average_bandwidth : Int64?
+    getter width : Int32?
+    getter height : Int32?
+    getter codecs : String?
+    getter audio_group : String?
+    getter subtitle_group : String?
+
+    def initialize(
+      @url : URI,
+      @bandwidth : Int64? = nil,
+      @average_bandwidth : Int64? = nil,
+      @width : Int32? = nil,
+      @height : Int32? = nil,
+      @codecs : String? = nil,
+      @audio_group : String? = nil,
+      @subtitle_group : String? = nil,
+    )
+    end
+  end
+
+  struct Segment
+    getter url : URI
+    getter duration : Float64
+    getter title : String?
+    getter byte_range : ByteRange?
+
+    def initialize(
+      @url : URI,
+      @duration : Float64 = 0.0,
+      @title : String? = nil,
+      @byte_range : ByteRange? = nil,
+    )
+    end
+  end
+
+  struct Rendition
+    getter type : String
+    getter group_id : String?
+    getter name : String?
+    getter language : String?
+    getter url : URI?
+    getter? default : Bool
+    getter? autoselect : Bool
+
+    def initialize(
+      @type : String,
+      @group_id : String? = nil,
+      @name : String? = nil,
+      @language : String? = nil,
+      @url : URI? = nil,
+      @default : Bool = false,
+      @autoselect : Bool = false,
+    )
+    end
+  end
+
+  struct MediaPlaylist
+    getter segments : Array(Segment)
+    getter map_url : URI?
+    getter map_byte_range : ByteRange?
+    getter duration_seconds : Float64
+    getter ended : Bool
+    getter encrypted : Bool
+
+    def initialize(
+      @segments : Array(Segment),
+      @duration_seconds : Float64,
+      @ended : Bool,
+      @encrypted : Bool,
+      @map_url : URI? = nil,
+      @map_byte_range : ByteRange? = nil,
+    )
+    end
+  end
+
+  struct MultivariantPlaylist
+    getter variants : Array(Variant)
+    getter renditions : Array(Rendition)
+
+    def initialize(
+      @variants : Array(Variant),
+      @renditions : Array(Rendition) = [] of Rendition,
+    )
+    end
+  end
+end