rill-node 0.0.0-stage → 2026.11.14

package/native-src/src/rill/dash/manifest.cr

@@ -0,0 +1,279 @@
+require "uri"
+
+require "../errors"
+require "../mime_type"
+
+module Rill::Dash
+  DURATION = /\AP(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?\z/
+  TEMPLATE = /\$(\$|RepresentationID|Bandwidth|Number|Time)(?:%0(\d+)d)?\$/
+
+  struct Segment
+    getter url : URI
+    getter duration_seconds : Float64?
+
+    def initialize(@url : URI, @duration_seconds : Float64? = nil)
+    end
+  end
+
+  class SegmentList
+    getter initialization : URI?
+    getter segments : Array(Segment)
+
+    def initialize(@initialization : URI?, @segments : Array(Segment))
+    end
+  end
+
+  class SegmentTemplate
+    getter initialization : String?
+    getter media : String
+    getter timescale : Int64
+    getter duration : Int64?
+    getter start_number : Int64
+    getter presentation_time_offset : Int64
+    getter timeline : Array(TimelineEntry)
+
+    def initialize(
+      @media : String,
+      @initialization : String? = nil,
+      @timescale : Int64 = 1,
+      @duration : Int64? = nil,
+      @start_number : Int64 = 1,
+      @presentation_time_offset : Int64 = 0,
+      @timeline : Array(TimelineEntry) = [] of TimelineEntry,
+    )
+    end
+
+    def supported?(period_duration : Float64?) : Bool
+      return true unless @timeline.empty?
+
+      duration = @duration
+      return false unless duration && duration > 0
+
+      !period_duration.nil?
+    end
+
+    def expand(
+      base_url : URI,
+      reference : String,
+      bandwidth : Int64?,
+      period_duration : Float64?,
+    ) : Tuple(URI?, Array(Segment))
+      init_url = if template = @initialization
+                   Dash.resolve_url(
+                     base_url,
+                     Dash.expand_template(template, reference, bandwidth, @start_number, @presentation_time_offset),
+                   )
+                 end
+
+      segments = if @timeline.empty?
+                   expand_fixed(base_url, reference, bandwidth, period_duration)
+                 else
+                   expand_timeline(base_url, reference, bandwidth, period_duration)
+                 end
+
+      {init_url, segments}
+    end
+
+    private def expand_fixed(
+      base_url : URI,
+      reference : String,
+      bandwidth : Int64?,
+      period_duration : Float64?,
+    ) : Array(Segment)
+      duration = @duration
+      total = period_duration
+      unless duration && duration > 0 && total
+        raise UnsupportedManifestError.new("DASH segment template needs a duration and a period duration")
+      end
+
+      count = ((total * @timescale) / duration).ceil.to_i64
+      segments = [] of Segment
+
+      count.times do |index|
+        number = @start_number + index
+        time = @presentation_time_offset + index * duration
+        value = Dash.expand_template(@media, reference, bandwidth, number, time)
+        segments << Segment.new(
+          Dash.resolve_url(base_url, value),
+          duration.to_f / @timescale,
+        )
+      end
+
+      segments
+    end
+
+    private def expand_timeline(
+      base_url : URI,
+      reference : String,
+      bandwidth : Int64?,
+      period_duration : Float64?,
+    ) : Array(Segment)
+      segments = [] of Segment
+      number = @start_number
+      current_time = @presentation_time_offset
+      period_ticks = period_duration.try { |seconds| (seconds * @timescale).ceil.to_i64 }
+
+      @timeline.each do |entry|
+        start_time = entry.time || current_time
+        repeats = entry.repeat
+
+        if repeats < 0
+          total = period_ticks
+          unless total
+            raise UnsupportedManifestError.new("DASH timeline repeats need a period duration")
+          end
+          repeats = ((total - start_time) / entry.duration).ceil.to_i64 - 1
+          repeats = 0 if repeats < 0
+        end
+
+        (repeats + 1).times do |index|
+          time = start_time + index * entry.duration
+          value = Dash.expand_template(@media, reference, bandwidth, number, time)
+          segments << Segment.new(
+            Dash.resolve_url(base_url, value),
+            entry.duration.to_f / @timescale,
+          )
+          number += 1
+        end
+
+        current_time = start_time + (repeats + 1) * entry.duration
+      end
+
+      segments
+    end
+  end
+
+  struct TimelineEntry
+    getter time : Int64?
+    getter duration : Int64
+    getter repeat : Int64
+
+    def initialize(@duration : Int64, @time : Int64? = nil, @repeat : Int64 = 0)
+    end
+  end
+
+  class Representation
+    getter reference : String
+    getter id : String?
+    getter bandwidth : Int64?
+    getter mime : MimeType?
+    getter codecs : String?
+    getter width : Int32?
+    getter height : Int32?
+    getter fps : Float64?
+    getter language : String?
+    getter base_url : URI
+    getter duration_seconds : Float64?
+    getter template : SegmentTemplate?
+    getter list : SegmentList?
+    getter segment_base : Bool
+
+    def initialize(
+      @reference : String,
+      @base_url : URI,
+      @duration_seconds : Float64?,
+      @id : String? = nil,
+      @bandwidth : Int64? = nil,
+      @mime : MimeType? = nil,
+      @codecs : String? = nil,
+      @width : Int32? = nil,
+      @height : Int32? = nil,
+      @fps : Float64? = nil,
+      @language : String? = nil,
+      @template : SegmentTemplate? = nil,
+      @list : SegmentList? = nil,
+      @segment_base : Bool = false,
+    )
+    end
+
+    def supported? : Bool
+      return false if @segment_base
+      return true if @list
+
+      @template.try(&.supported?(@duration_seconds)) || false
+    end
+
+    def expand : Tuple(URI?, Array(Segment))
+      if list = @list
+        {list.initialization, list.segments}
+      elsif template = @template
+        template.expand(@base_url, @reference, @bandwidth, @duration_seconds)
+      else
+        raise UnsupportedManifestError.new("DASH representation has no segment information")
+      end
+    end
+  end
+
+  struct Manifest
+    getter representations : Array(Representation)
+    getter duration_seconds : Float64?
+
+    def initialize(@representations : Array(Representation), @duration_seconds : Float64? = nil)
+    end
+  end
+
+  def self.parse_duration(value : String?) : Float64?
+    return nil unless value
+
+    match = DURATION.match(value.strip)
+    return nil unless match
+
+    days = match[1]?.try(&.to_f) || 0.0
+    hours = match[2]?.try(&.to_f) || 0.0
+    minutes = match[3]?.try(&.to_f) || 0.0
+    seconds = match[4]?.try(&.to_f) || 0.0
+
+    days * 86400 + hours * 3600 + minutes * 60 + seconds
+  end
+
+  def self.expand_template(
+    template : String,
+    reference : String,
+    bandwidth : Int64?,
+    number : Int64,
+    time : Int64,
+  ) : String
+    String.build do |io|
+      index = 0
+
+      while match = TEMPLATE.match(template, index)
+        io << template[index, match.begin(0) - index]
+        value = case match[1]
+                when "$"
+                  "$"
+                when "RepresentationID"
+                  reference
+                when "Bandwidth"
+                  (bandwidth || 0).to_s
+                when "Number"
+                  number.to_s
+                when "Time"
+                  time.to_s
+                else
+                  ""
+                end
+
+        if width = match[2]?.try(&.to_i?)
+          value = value.rjust(width, '0')
+        end
+
+        io << value
+        index = match.end(0)
+      end
+
+      io << template[index, template.size - index]
+    end
+  end
+
+  def self.resolve_url(base : URI, value : String) : URI
+    uri = base.resolve(value)
+    unless uri.scheme == "http" || uri.scheme == "https"
+      raise UnsupportedManifestError.new("DASH segment URL is not HTTP")
+    end
+    return uri if uri.host
+
+    raise UnsupportedManifestError.new("DASH segment URL has no host")
+  rescue URI::Error
+    raise ManifestError.new("invalid DASH segment URL: #{value}")
+  end
+end

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

@@ -0,0 +1,227 @@
+require "set"
+require "uri"
+require "xml"
+
+require "../errors"
+require "../mime_type"
+require "./manifest"
+
+module Rill::Dash::Parser
+  extend self
+
+  def parse(source : String, base_url : URI) : Manifest
+    document = begin
+      XML.parse(source)
+    rescue XML::Error
+      raise ManifestError.new("DASH manifest is not valid XML")
+    end
+
+    root = document.root
+    unless root && root.name == "MPD"
+      raise ManifestError.new("DASH manifest has no MPD root")
+    end
+
+    if root["type"]? == "dynamic"
+      raise UnsupportedManifestError.new("live DASH manifests are not supported")
+    end
+
+    duration = Dash.parse_duration(root["mediaPresentationDuration"]?)
+    manifest_base = resolve_base(root, base_url)
+    periods = element_children(root, "Period")
+
+    if periods.empty?
+      raise ManifestError.new("DASH manifest has no periods")
+    end
+
+    if periods.size > 1
+      raise UnsupportedManifestError.new("multi-period DASH manifests are not supported")
+    end
+
+    period = periods.first
+    period_start = Dash.parse_duration(period["start"]?) || 0.0
+    period_duration = Dash.parse_duration(period["duration"]?)
+    period_duration ||= duration.try { |value| value - period_start }
+    period_base = resolve_base(period, manifest_base)
+
+    representations = [] of Representation
+    references = Set(String).new
+
+    element_children(period, "AdaptationSet").each_with_index do |adaptation, adaptation_index|
+      next if element_children(adaptation, "ContentProtection").any?
+
+      adaptation_base = resolve_base(adaptation, period_base)
+      adaptation_template = parse_template(adaptation, adaptation_base)
+      adaptation_list = parse_list(adaptation, adaptation_base)
+      adaptation_segment_base = element_children(adaptation, "SegmentBase").any?
+
+      element_children(adaptation, "Representation").each_with_index do |node, representation_index|
+        next if element_children(node, "ContentProtection").any?
+
+        id = attribute(node, "id")
+        reference = unique_reference(id, adaptation_index, representation_index, references)
+
+        representation_base = resolve_base(node, adaptation_base)
+        template = parse_template(node, representation_base) || adaptation_template
+        list = parse_list(node, representation_base) || adaptation_list
+        segment_base = adaptation_segment_base || element_children(node, "SegmentBase").any?
+
+        mime_value = attribute(node, "mimeType") ||
+                     attribute(adaptation, "mimeType") ||
+                     mime_for_content_type(adaptation)
+        mime = mime_value.try { |value| MimeType.parse(value) }
+        next if mime.nil? || mime.empty?
+
+        representations << Representation.new(
+          reference: reference,
+          base_url: representation_base,
+          duration_seconds: period_duration,
+          id: id,
+          bandwidth: attribute(node, "bandwidth").try(&.to_i64?),
+          mime: mime,
+          codecs: attribute(node, "codecs") || attribute(adaptation, "codecs"),
+          width: dimension(attribute(node, "width") || attribute(adaptation, "width")),
+          height: dimension(attribute(node, "height") || attribute(adaptation, "height")),
+          fps: frame_rate(attribute(node, "frameRate") || attribute(adaptation, "frameRate")),
+          language: attribute(node, "lang") || attribute(adaptation, "lang"),
+          template: template,
+          list: list,
+          segment_base: segment_base,
+        )
+      end
+    end
+
+    Manifest.new(representations, period_duration)
+  end
+
+  private def unique_reference(
+    id : String?,
+    adaptation_index : Int32,
+    representation_index : Int32,
+    references : Set(String),
+  ) : String
+    generated = "rep-#{adaptation_index}-#{representation_index}"
+    reference = if id.nil? || id.empty?
+                  generated
+                elsif references.includes?(id)
+                  "#{id}-#{adaptation_index}-#{representation_index}"
+                else
+                  id
+                end
+    references << reference
+    reference
+  end
+
+  private def resolve_base(node : XML::Node, current : URI) : URI
+    value = element_children(node, "BaseURL").first?.try(&.content.strip)
+    return current if value.nil? || value.empty?
+
+    Dash.resolve_url(current, value)
+  end
+
+  private def parse_template(node : XML::Node, base_url : URI) : SegmentTemplate?
+    template_node = element_children(node, "SegmentTemplate").first?
+    return nil unless template_node
+
+    media = attribute(template_node, "media")
+    return nil unless media
+
+    timeline = [] of TimelineEntry
+    if timeline_node = element_children(template_node, "SegmentTimeline").first?
+      element_children(timeline_node, "S").each do |entry|
+        duration = attribute(entry, "d").try(&.to_i64?)
+        unless duration && duration > 0
+          raise ManifestError.new("DASH timeline entry has no duration")
+        end
+
+        timeline << TimelineEntry.new(
+          duration,
+          attribute(entry, "t").try(&.to_i64?),
+          attribute(entry, "r").try(&.to_i64?) || 0_i64,
+        )
+      end
+    end
+
+    SegmentTemplate.new(
+      media: media,
+      initialization: attribute(template_node, "initialization"),
+      timescale: attribute(template_node, "timescale").try(&.to_i64?) || 1_i64,
+      duration: attribute(template_node, "duration").try(&.to_i64?),
+      start_number: attribute(template_node, "startNumber").try(&.to_i64?) || 1_i64,
+      presentation_time_offset: attribute(template_node, "presentationTimeOffset").try(&.to_i64?) || 0_i64,
+      timeline: timeline,
+    )
+  end
+
+  private def parse_list(node : XML::Node, base_url : URI) : SegmentList?
+    list_node = element_children(node, "SegmentList").first?
+    return nil unless list_node
+
+    initialization = element_children(list_node, "Initialization").first?
+    init_url = if initialization
+                 if initialization["range"]?
+                   raise UnsupportedManifestError.new("DASH byte-range initialization is not supported")
+                 end
+                 source = attribute(initialization, "sourceURL")
+                 source ? Dash.resolve_url(base_url, source) : nil
+               end
+
+    segments = [] of Segment
+    element_children(list_node, "SegmentURL").each do |segment_node|
+      if segment_node["mediaRange"]?
+        raise UnsupportedManifestError.new("DASH byte-range segments are not supported")
+      end
+
+      media = attribute(segment_node, "media")
+      next unless media
+
+      segments << Segment.new(Dash.resolve_url(base_url, media))
+    end
+
+    SegmentList.new(init_url, segments)
+  end
+
+  private def mime_for_content_type(adaptation : XML::Node) : String?
+    case attribute(adaptation, "contentType")
+    when "audio"
+      "audio/mp4"
+    when "video"
+      "video/mp4"
+    else
+      nil
+    end
+  end
+
+  private def element_children(node : XML::Node, name : String) : Array(XML::Node)
+    node.children.select { |child| child.element? && child.name == name }
+  end
+
+  private def attribute(node : XML::Node, name : String) : String?
+    value = node[name]?.try(&.strip)
+    return nil if value.nil? || value.empty?
+
+    value
+  end
+
+  private def dimension(value : String?) : Int32?
+    parsed = value.try(&.to_i64?)
+    return nil unless parsed && 0 < parsed <= 100_000
+
+    parsed.to_i32
+  end
+
+  private def frame_rate(value : String?) : Float64?
+    return nil unless value
+
+    if value.includes?('/')
+      numerator, denominator = value.split('/', 2).map(&.to_f?)
+      return nil unless numerator && denominator && denominator > 0
+
+      rate = numerator / denominator
+    else
+      rate = value.to_f?
+    end
+    return nil unless rate && rate.finite? && rate > 0
+
+    rate
+  end
+end

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

@@ -0,0 +1,96 @@
+require "json"
+
+require "./errors"
+require "./format_selector"
+require "./media_muxer"
+require "./request_options"
+
+module Rill
+  class DownloadOptions
+    getter request : RequestOptions
+    getter format_id : String?
+    getter preference : FormatPreference
+    getter overwrite : Bool
+    getter resume : Bool
+    getter media_backend : MediaMuxer::Backend
+
+    def initialize(
+      @request : RequestOptions = RequestOptions.new,
+      @format_id : String? = nil,
+      @preference : FormatPreference = FormatPreference::AudioAndVideo,
+      @overwrite : Bool = false,
+      @resume : Bool = true,
+      @media_backend : MediaMuxer::Backend = MediaMuxer.backend_from_environment,
+    )
+    end
+
+    def self.from_json(source : String?) : DownloadOptions
+      if source.nil? || source.empty?
+        return new
+      end
+
+      object = JSON.parse(source).as_h?
+      unless object
+        raise InvalidOptionsError.new("download options must be a JSON object")
+      end
+
+      request = RequestOptions.new
+      format_id = nil
+      audio_only = false
+      video_only = false
+      overwrite = false
+      resume = true
+      media_backend = MediaMuxer.backend_from_environment
+
+      object.each do |key, value|
+        case key
+        when "request"
+          request = RequestOptions.from_json(value.to_json)
+        when "format_id"
+          format_id = value.as_s? || raise InvalidOptionsError.new("format_id must be a string")
+        when "audio_only"
+          audio_only = boolean_option(key, value)
+        when "video_only"
+          video_only = boolean_option(key, value)
+        when "overwrite"
+          overwrite = boolean_option(key, value)
+        when "resume"
+          resume = boolean_option(key, value)
+        when "media_backend"
+          name = value.as_s? || raise InvalidOptionsError.new("media_backend must be a string")
+          media_backend = MediaMuxer.parse_backend(name) ||
+                          raise InvalidOptionsError.new("unknown media_backend #{name}")
+        else
+          raise InvalidOptionsError.new("unknown download option #{key}")
+        end
+      end
+
+      if audio_only && video_only
+        raise InvalidOptionsError.new("audio_only and video_only cannot be combined")
+      end
+
+      if format_id && (audio_only || video_only)
+        raise InvalidOptionsError.new("format_id cannot be combined with audio_only or video_only")
+      end
+
+      preference = if audio_only
+                     FormatPreference::AudioOnly
+                   elsif video_only
+                     FormatPreference::VideoOnly
+                   else
+                     FormatPreference::AudioAndVideo
+                   end
+
+      new(request, format_id, preference, overwrite, resume, media_backend)
+    rescue JSON::ParseException
+      raise InvalidOptionsError.new("download options are not valid JSON")
+    end
+
+    private def self.boolean_option(key : String, value : JSON::Any) : Bool
+      raw = value.raw
+      return raw if raw.is_a?(Bool)
+
+      raise InvalidOptionsError.new("#{key} must be a boolean")
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+require "./format"
+
+module Rill
+  struct DownloadPlan
+    getter stream : Format
+    getter audio : Format?
+
+    def initialize(@stream : Format, @audio : Format? = nil)
+    end
+
+    def formats : Array(Format)
+      if audio = @audio
+        [@stream, audio]
+      else
+        [@stream]
+      end
+    end
+
+    def container : String?
+      @stream.container || @audio.try(&.container)
+    end
+
+    def requires_merge? : Bool
+      !@audio.nil?
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Rill
+  struct DownloadProgress
+    getter downloaded_bytes : Int64
+    getter total_bytes : Int64?
+
+    def initialize(@downloaded_bytes : Int64, @total_bytes : Int64? = nil)
+    end
+
+    def fraction : Float64?
+      total = @total_bytes
+      return nil unless total && total > 0
+
+      (downloaded_bytes.to_f / total).clamp(0.0, 1.0)
+    end
+  end
+end