rill-node 0.0.0-stage → 2026.11.15

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

@@ -0,0 +1,151 @@
+require "json"
+require "set"
+require "uri"
+
+require "./errors"
+require "./format"
+
+module Rill
+  class Media
+    getter id : String?
+    getter title : String
+    getter description : String?
+    getter webpage_url : URI
+    getter uploader : String?
+    getter duration_seconds : Float64?
+    getter thumbnail_url : URI?
+    getter upload_date : String?
+    getter extractor : String
+    getter formats : Array(Format)
+    getter warnings : Array(String)
+
+    def initialize(
+      @title : String,
+      @webpage_url : URI,
+      @extractor : String,
+      @formats : Array(Format),
+      @id : String? = nil,
+      @description : String? = nil,
+      @uploader : String? = nil,
+      @duration_seconds : Float64? = nil,
+      @thumbnail_url : URI? = nil,
+      @upload_date : String? = nil,
+      @warnings : Array(String) = [] of String,
+    )
+    end
+
+    def validate! : Nil
+      if title.empty?
+        raise InvalidExtractionError.new(webpage_url.to_s, "title is empty")
+      end
+
+      if formats.empty?
+        raise InvalidExtractionError.new(webpage_url.to_s, "no formats")
+      end
+
+      validate_duration!(duration_seconds, "media duration")
+
+      format_ids = Set(String).new
+      formats.each do |format|
+        validate_format!(format, format_ids)
+      end
+    end
+
+    def to_json(json : JSON::Builder) : Nil
+      json.object do
+        json.field "id", id
+        json.field "title", title
+        json.field "description", description
+        json.field "webpage_url", webpage_url.to_s
+        json.field "uploader", uploader
+        json.field "duration_seconds", duration_seconds
+        json.field "thumbnail_url", thumbnail_url.try(&.to_s)
+        json.field "upload_date", upload_date
+        json.field "extractor", extractor
+        json.field "formats" do
+          json.array do
+            formats.each(&.to_json(json))
+          end
+        end
+        json.field "warnings" do
+          json.array do
+            warnings.each { |warning| json.string(warning) }
+          end
+        end
+      end
+    end
+
+    def to_pretty_json : String
+      JSON.build(indent: 2) do |json|
+        to_json(json)
+      end
+    end
+
+    private def validate_format!(format : Format, format_ids : Set(String)) : Nil
+      if format.url.host.nil?
+        raise InvalidExtractionError.new(webpage_url.to_s, "format #{format.format_id} has no host")
+      end
+
+      scheme = format.url.scheme
+      if scheme != "http" && scheme != "https"
+        raise InvalidExtractionError.new(webpage_url.to_s, "format #{format.format_id} has a non-HTTP URL")
+      end
+
+      unless format_ids.add?(format.format_id)
+        raise InvalidExtractionError.new(webpage_url.to_s, "duplicate format id #{format.format_id}")
+      end
+
+      validate_duration!(format.duration_seconds, "format #{format.format_id} duration")
+      validate_positive!(format.width, "format #{format.format_id} width")
+      validate_positive!(format.height, "format #{format.format_id} height")
+      validate_non_negative!(format.filesize, "format #{format.format_id} filesize")
+
+      if chunk_size = format.range_chunk_size
+        if chunk_size <= 0
+          raise InvalidExtractionError.new(webpage_url.to_s, "format #{format.format_id} chunk size is invalid")
+        end
+      end
+      validate_non_negative!(format.video_bitrate, "format #{format.format_id} video bitrate")
+      validate_non_negative!(format.audio_bitrate, "format #{format.format_id} audio bitrate")
+      validate_non_negative!(format.bitrate, "format #{format.format_id} bitrate")
+
+      if fps = format.fps
+        unless fps.finite? && fps > 0
+          raise InvalidExtractionError.new(webpage_url.to_s, "format #{format.format_id} has an invalid fps")
+        end
+      end
+    end
+
+    private def validate_duration!(value : Float64?, label : String) : Nil
+      return unless value
+
+      unless value.finite? && value >= 0
+        raise InvalidExtractionError.new(webpage_url.to_s, "#{label} is invalid")
+      end
+    end
+
+    private def validate_positive!(value : Int32?, label : String) : Nil
+      return unless value
+
+      if value <= 0
+        raise InvalidExtractionError.new(webpage_url.to_s, "#{label} is invalid")
+      end
+    end
+
+    private def validate_non_negative!(value : Int32?, label : String) : Nil
+      return unless value
+
+      if value < 0
+        raise InvalidExtractionError.new(webpage_url.to_s, "#{label} is invalid")
+      end
+    end
+
+    private def validate_non_negative!(value : Int64?, label : String) : Nil
+      return unless value
+
+      if value < 0
+        raise InvalidExtractionError.new(webpage_url.to_s, "#{label} is invalid")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,333 @@
+require "path"
+require "process"
+
+require "./cancellation"
+require "./errors"
+
+module Rill
+  class MediaMuxer
+    enum Backend
+      Auto
+      Helper
+      System
+      Off
+    end
+
+    HELPER_NAME = {% if flag?(:win32) %} "rill-media.exe" {% else %} "rill-media" {% end %}
+
+    @backend : Backend
+    @helper_path : String?
+    @ffmpeg_path : String
+
+    def initialize(
+      @backend : Backend = self.class.backend_from_environment,
+      @helper_path : String? = nil,
+      @ffmpeg_path : String = ENV["RILL_FFMPEG"]? || "ffmpeg",
+    )
+    end
+
+    def self.backend_from_environment : Backend
+      case ENV["RILL_MEDIA_BACKEND"]?.try(&.downcase)
+      when "helper"
+        Backend::Helper
+      when "system"
+        Backend::System
+      when "off", "none", "disabled"
+        Backend::Off
+      else
+        Backend::Auto
+      end
+    end
+
+    def self.parse_backend(value : String) : Backend?
+      case value.downcase
+      when "auto"
+        Backend::Auto
+      when "helper"
+        Backend::Helper
+      when "system"
+        Backend::System
+      when "off", "none", "disabled"
+        Backend::Off
+      else
+        nil
+      end
+    end
+
+    def merge(
+      video : String | Path,
+      audio : String | Path,
+      output : String | Path,
+      overwrite : Bool = false,
+      cancellation : Cancellation? = nil,
+    ) : Path
+      video_path = Path.new(video.to_s)
+      audio_path = Path.new(audio.to_s)
+      output_path = Path.new(output.to_s)
+
+      validate_paths!(video_path, audio_path, output_path, overwrite)
+      backend = resolve_backend
+      temporary_path = temporary_output_path(output_path)
+      File.delete(temporary_path) if File.exists?(temporary_path)
+
+      begin
+        case backend
+        when :helper
+          run_helper(video_path, audio_path, temporary_path, overwrite, cancellation)
+        when :system
+          run_system(video_path, audio_path, temporary_path, overwrite, cancellation)
+        else
+          raise MediaBackendUnavailableError.new("no media backend is available")
+        end
+
+        publish(temporary_path, output_path, overwrite)
+      ensure
+        File.delete(temporary_path) if File.exists?(temporary_path)
+      end
+
+      output_path
+    end
+
+    private def temporary_output_path(output : Path) : Path
+      extension = output.extension
+      stem = output.basename.chomp(extension)
+      output.parent / "#{stem}.part#{extension}"
+    end
+
+    private def publish(temporary : Path, output : Path, overwrite : Bool) : Nil
+      if !overwrite && File.exists?(output)
+        raise FileExistsError.new(output.to_s)
+      end
+
+      begin
+        File.rename(temporary, output)
+      rescue ex : File::Error
+        unless overwrite && File.exists?(output)
+          raise ex
+        end
+
+        File.delete(output)
+        File.rename(temporary, output)
+      end
+    end
+
+    private def resolve_backend : Symbol
+      case @backend
+      when .off?
+        raise MediaBackendUnavailableError.new("media processing is disabled")
+      when .helper?
+        unless find_helper
+          raise MediaBackendUnavailableError.new("media helper not found: #{HELPER_NAME}")
+        end
+        :helper
+      when .system?
+        unless find_ffmpeg
+          raise MediaBackendUnavailableError.new("ffmpeg not found: #{@ffmpeg_path}")
+        end
+        :system
+      when .auto?
+        if find_helper
+          :helper
+        elsif find_ffmpeg
+          :system
+        else
+          raise MediaBackendUnavailableError.new("no media helper or ffmpeg was found")
+        end
+      else
+        raise MediaBackendUnavailableError.new("unknown media backend")
+      end
+    end
+
+    private def validate_paths!(
+      video : Path,
+      audio : Path,
+      output : Path,
+      overwrite : Bool,
+    ) : Nil
+      unless File.file?(video)
+        raise MediaMuxError.new("video input not found: #{video}")
+      end
+
+      unless File.file?(audio)
+        raise MediaMuxError.new("audio input not found: #{audio}")
+      end
+
+      if File.directory?(output)
+        raise MediaMuxError.new("output is a directory: #{output}")
+      end
+
+      if File.exists?(output) && !overwrite
+        raise FileExistsError.new(output.to_s)
+      end
+
+      expanded_output = output.expand
+      if video.expand == expanded_output || audio.expand == expanded_output
+        raise MediaMuxError.new("output must differ from the inputs")
+      end
+    end
+
+    private def run_helper(
+      video : Path,
+      audio : Path,
+      output : Path,
+      overwrite : Bool,
+      cancellation : Cancellation?,
+    ) : Nil
+      helper = find_helper.not_nil!
+      args = [
+        "merge",
+        "--video", video.to_s,
+        "--audio", audio.to_s,
+        "--output", output.to_s,
+      ]
+      args << "--overwrite" if overwrite
+
+      run_process(helper, args, cancellation, "media helper")
+    end
+
+    private def run_system(
+      video : Path,
+      audio : Path,
+      output : Path,
+      overwrite : Bool,
+      cancellation : Cancellation?,
+    ) : Nil
+      ffmpeg = find_ffmpeg.not_nil!
+      args = [
+        "-hide_banner",
+        "-loglevel", "error",
+        "-nostdin",
+        overwrite ? "-y" : "-n",
+        "-i", video.to_s,
+        "-i", audio.to_s,
+        "-map", "0:v:0?",
+        "-map", "1:a:0?",
+        "-c", "copy",
+      ]
+
+      if {".mp4", ".m4v", ".mov"}.includes?(output.extension.downcase)
+        args.concat(["-movflags", "+faststart"])
+      end
+
+      args << output.to_s
+      run_process(ffmpeg, args, cancellation, "ffmpeg")
+    end
+
+    private def run_process(
+      command : String,
+      args : Array(String),
+      cancellation : Cancellation?,
+      label : String,
+    ) : Nil
+      error_io = IO::Memory.new
+      process = begin
+        Process.new(
+          command,
+          args,
+          input: Process::Redirect::Close,
+          output: Process::Redirect::Close,
+          error: error_io,
+        )
+      rescue File::NotFoundError
+        raise MediaBackendUnavailableError.new("#{label} not found: #{command}")
+      end
+
+      status : Process::Status? = nil
+
+      begin
+        loop do
+          if cancellation.try(&.cancelled?)
+            process.terminate unless process.terminated?
+            status = process.wait
+            raise CancelledError.new
+          end
+
+          break if process.terminated?
+          sleep 50.milliseconds
+        end
+
+        status = process.wait
+      ensure
+        if status.nil?
+          process.terminate unless process.terminated?
+          process.wait
+        end
+      end
+
+      unless status.not_nil!.success?
+        message = error_io.to_s.strip
+        message = "#{label} exited with status #{status.not_nil!.exit_code}" if message.empty?
+        raise MediaMuxError.new(message)
+      end
+    end
+
+    private def find_helper : String?
+      candidates = [] of String
+
+      if value = ENV["RILL_MEDIA_HELPER"]?
+        candidates << value
+      end
+
+      if value = @helper_path
+        candidates << value
+      end
+
+      if executable = Process.executable_path
+        executable_directory = File.dirname(executable)
+        candidates << File.join(executable_directory, HELPER_NAME)
+        candidates << File.join(executable_directory, "..", "build", HELPER_NAME)
+      end
+
+      candidates << File.join("build", HELPER_NAME)
+      candidates << File.join("build", "native", HELPER_NAME)
+
+      candidates.each do |candidate|
+        if candidate.includes?('/') || candidate.includes?('\\')
+          return candidate if executable_file?(candidate)
+        elsif found = find_in_path(candidate)
+          return found
+        end
+      end
+
+      nil
+    end
+
+    private def find_ffmpeg : String?
+      if @ffmpeg_path.includes?('/') || @ffmpeg_path.includes?('\\')
+        return @ffmpeg_path if executable_file?(@ffmpeg_path)
+        return nil
+      end
+
+      find_in_path(@ffmpeg_path)
+    end
+
+    private def executable_file?(path : String) : Bool
+      {% if flag?(:win32) %}
+        File.file?(path)
+      {% else %}
+        info = File.info?(path)
+        return false unless info && info.file?
+
+        permissions = info.permissions
+        permissions.owner_execute? || permissions.group_execute? || permissions.other_execute?
+      {% end %}
+    rescue File::Error
+      false
+    end
+
+    private def find_in_path(name : String) : String?
+      path = ENV["PATH"]?
+      return nil unless path
+
+      separator = {% if flag?(:win32) %} ';' {% else %} ':' {% end %}
+      path.split(separator).each do |directory|
+        next if directory.empty?
+
+        candidate = File.join(directory, name)
+        return candidate if executable_file?(candidate)
+      end
+
+      nil
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+module Rill
+  struct MimeType
+    getter type : String
+    getter subtype : String
+    getter codecs : String?
+
+    def self.parse(value : String) : self
+      parts = value.split(';').map(&.strip)
+      media_type = parts.first?.try(&.downcase) || ""
+      type, _, subtype = media_type.partition('/')
+
+      codecs = parts.skip(1).compact_map do |part|
+        name, separator, codec = part.partition('=')
+        next unless separator == "=" && name.strip.downcase == "codecs"
+
+        codec = codec.strip
+        if codec.starts_with?('"') && codec.ends_with?('"')
+          codec = codec[1..-2]
+        end
+        codec
+      end.first?
+
+      new(type, subtype, codecs)
+    end
+
+    def initialize(@type : String, @subtype : String, @codecs : String? = nil)
+    end
+
+    def audio? : Bool
+      @type == "audio"
+    end
+
+    def video? : Bool
+      @type == "video"
+    end
+
+    def empty? : Bool
+      @type.empty? || @subtype.empty?
+    end
+
+    def container : String?
+      return nil if @subtype.empty?
+
+      @subtype == "mpeg" ? "mp3" : @subtype
+    end
+
+    def audio_codec : String?
+      return @codecs if @codecs
+      return nil if @subtype.empty?
+
+      @subtype == "mpeg" ? "mp3" : @subtype
+    end
+
+    def codec_list : Array(String)
+      @codecs.try(&.split(',').map(&.strip).reject(&.empty?)) || [] of String
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+require "path"
+
+require "./errors"
+
+module Rill::OutputFileName
+  extend self
+
+  MAX_BYTES = 180
+
+  INVALID_CHARACTERS      = /[<>:"\/\\|?*\x00-\x1f]/
+  LEADING_DOTS_OR_SPACES  = /\A[.\s]+/
+  TRAILING_DOTS_OR_SPACES = /[.\s]+\z/
+  WHITESPACE              = /\s+/
+  VALID_EXTENSION         = /\A[a-z0-9]+\z/
+
+  RESERVED_NAMES = %w(
+    con prn aux nul
+    com1 com2 com3 com4 com5 com6 com7 com8 com9
+    lpt1 lpt2 lpt3 lpt4 lpt5 lpt6 lpt7 lpt8 lpt9
+  )
+
+  def from_title(title : String, extension : String? = nil) : String
+    extension = normalize_extension(extension)
+    limit = MAX_BYTES - (extension ? extension.bytesize + 1 : 0)
+    base = sanitize(title, limit)
+
+    if extension && !base.downcase.ends_with?(".#{extension}")
+      base = "#{base}.#{extension}"
+    end
+
+    reserved_name?(base) ? "_#{base}" : base
+  end
+
+  def resolve(directory : String | Path, title : String, extension : String? = nil) : Path
+    resolve_path(directory, from_title(title, extension))
+  end
+
+  def resolve_path(directory : String | Path, file_name : String) : Path
+    dir = Path.new(directory.to_s).expand
+    target = (dir / file_name).expand
+
+    unless target.parent == dir
+      raise InvalidOutputPathError.new(target.to_s, dir.to_s)
+    end
+
+    target
+  end
+
+  private def sanitize(title : String, limit : Int32) : String
+    value = title.gsub(INVALID_CHARACTERS, "_")
+    value = value.gsub(WHITESPACE, " ")
+    value = value.sub(LEADING_DOTS_OR_SPACES, "")
+    value = value.sub(TRAILING_DOTS_OR_SPACES, "")
+    value = truncate(value, limit)
+    value = value.sub(TRAILING_DOTS_OR_SPACES, "")
+    value.empty? ? "download" : value
+  end
+
+  private def truncate(value : String, limit : Int32) : String
+    return value if value.bytesize <= limit
+
+    builder = String::Builder.new
+    bytes = 0
+
+    value.each_char do |char|
+      size = char.bytesize
+      break if bytes + size > limit
+
+      builder << char
+      bytes += size
+    end
+
+    builder.to_s
+  end
+
+  private def normalize_extension(extension : String?) : String?
+    return nil unless extension
+
+    value = extension.lchop('.').downcase
+    return nil if value.empty?
+    return nil if value.bytesize > 16
+    return nil unless VALID_EXTENSION.matches?(value)
+
+    value
+  end
+
+  private def reserved_name?(value : String) : Bool
+    base = value.split('.').first? || value
+    RESERVED_NAMES.includes?(base.downcase)
+  end
+end