rill-node 0.0.0-stage → 2026.11.15

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

@@ -0,0 +1,109 @@
+require "json"
+require "uri"
+
+require "./errors"
+require "./media"
+
+module Rill
+  class PlaylistEntry
+    getter url : URI
+    getter title : String?
+    getter id : String?
+    getter media : Media?
+    getter error : String?
+
+    def initialize(
+      @url : URI,
+      @title : String? = nil,
+      @id : String? = nil,
+      @media : Media? = nil,
+      @error : String? = nil,
+    )
+    end
+
+    def to_json(json : JSON::Builder) : Nil
+      json.object do
+        json.field "url", url.to_s
+        json.field "title", title
+        json.field "id", id
+        json.field "error", error
+        json.field "media" do
+          if item = media
+            item.to_json(json)
+          else
+            json.null
+          end
+        end
+      end
+    end
+  end
+
+  class Playlist
+    getter id : String?
+    getter title : String
+    getter description : String?
+    getter webpage_url : URI
+    getter extractor : String
+    getter entries : Array(PlaylistEntry)
+
+    def initialize(
+      @title : String,
+      @webpage_url : URI,
+      @extractor : String,
+      @entries : Array(PlaylistEntry),
+      @id : String? = nil,
+      @description : String? = nil,
+    )
+    end
+
+    def validate! : Nil
+      if title.empty?
+        raise InvalidExtractionError.new(webpage_url.to_s, "playlist title is empty")
+      end
+
+      if entries.empty?
+        raise InvalidExtractionError.new(webpage_url.to_s, "playlist has no entries")
+      end
+
+      entries.each do |entry|
+        validate_entry!(entry)
+      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 "extractor", extractor
+        json.field "entries" do
+          json.array do
+            entries.each(&.to_json(json))
+          end
+        end
+      end
+    end
+
+    def to_pretty_json : String
+      JSON.build(indent: 2) do |json|
+        to_json(json)
+      end
+    end
+
+    private def validate_entry!(entry : PlaylistEntry) : Nil
+      scheme = entry.url.scheme
+      if scheme != "http" && scheme != "https"
+        raise InvalidExtractionError.new(webpage_url.to_s, "entry has a non-HTTP URL")
+      end
+
+      if entry.url.host.nil?
+        raise InvalidExtractionError.new(webpage_url.to_s, "entry has no host")
+      end
+
+      if entry.media && entry.error
+        raise InvalidExtractionError.new(webpage_url.to_s, "entry has both media and an error")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+require "http/headers"
+require "json"
+
+require "./errors"
+require "./version"
+
+module Rill
+  class RequestOptions
+    DEFAULT_USER_AGENT         = "rill/#{VERSION}"
+    DEFAULT_CONNECT_TIMEOUT    = 15.seconds
+    DEFAULT_READ_TIMEOUT       = 30.seconds
+    DEFAULT_MAX_REDIRECTS      = 10
+    DEFAULT_RETRIES            =  2
+    DEFAULT_RETRY_DELAY        = 1.second
+    DEFAULT_MAX_RESPONSE_BYTES = 16_i64 * 1024 * 1024
+
+    property user_agent : String = DEFAULT_USER_AGENT
+    property headers : HTTP::Headers = HTTP::Headers.new
+    property cookies : Hash(String, String) = {} of String => String
+    property connect_timeout : Time::Span = DEFAULT_CONNECT_TIMEOUT
+    property read_timeout : Time::Span = DEFAULT_READ_TIMEOUT
+    property max_redirects : Int32 = DEFAULT_MAX_REDIRECTS
+    property retries : Int32 = DEFAULT_RETRIES
+    property retry_delay : Time::Span = DEFAULT_RETRY_DELAY
+    property max_response_bytes : Int64 = DEFAULT_MAX_RESPONSE_BYTES
+
+    def retry_wait(attempt : Int32) : Time::Span
+      exponent = Math.min(attempt - 1, 5)
+      @retry_delay * (1 << exponent)
+    end
+
+    def self.from_json(source : String) : RequestOptions
+      object = begin
+        JSON.parse(source)
+      rescue JSON::ParseException
+        raise InvalidOptionsError.new("options are not valid JSON")
+      end.as_h?
+
+      unless object
+        raise InvalidOptionsError.new("options must be a JSON object")
+      end
+
+      options = new
+
+      object.each do |key, value|
+        case key
+        when "user_agent"
+          options.user_agent = string_option(key, value)
+        when "headers"
+          apply_headers(options, value)
+        when "cookies"
+          apply_cookies(options, value)
+        when "connect_timeout_seconds"
+          options.connect_timeout = seconds_option(key, value)
+        when "read_timeout_seconds"
+          options.read_timeout = seconds_option(key, value)
+        when "retry_delay_seconds"
+          options.retry_delay = seconds_option(key, value, allow_zero: true)
+        when "max_redirects"
+          options.max_redirects = int32_option(key, value)
+        when "retries"
+          options.retries = int32_option(key, value)
+        when "max_response_bytes"
+          options.max_response_bytes = integer_option(key, value)
+        else
+          raise InvalidOptionsError.new("unknown option #{key}")
+        end
+      end
+
+      validate(options)
+      options
+    end
+
+    private def self.apply_headers(options : RequestOptions, value : JSON::Any) : Nil
+      headers = value.as_h?
+      unless headers
+        raise InvalidOptionsError.new("headers must be a JSON object")
+      end
+
+      headers.each do |name, header_value|
+        if name.empty?
+          raise InvalidOptionsError.new("header names must not be empty")
+        end
+
+        if text = header_value.as_s?
+          options.headers.add(name, text)
+        elsif values = header_value.as_a?
+          values.each do |item|
+            text = item.as_s?
+            unless text
+              raise InvalidOptionsError.new("header #{name} must be a string or an array of strings")
+            end
+            options.headers.add(name, text)
+          end
+        else
+          raise InvalidOptionsError.new("header #{name} must be a string or an array of strings")
+        end
+      end
+    end
+
+    private def self.apply_cookies(options : RequestOptions, value : JSON::Any) : Nil
+      cookies = value.as_h?
+      unless cookies
+        raise InvalidOptionsError.new("cookies must be a JSON object")
+      end
+
+      cookies.each do |name, cookie_value|
+        text = cookie_value.as_s?
+        unless text
+          raise InvalidOptionsError.new("cookie #{name} must be a string")
+        end
+
+        if name.empty?
+          raise InvalidOptionsError.new("cookie names must not be empty")
+        end
+
+        options.cookies[name] = text
+      end
+    end
+
+    private def self.string_option(key : String, value : JSON::Any) : String
+      value.as_s? || raise InvalidOptionsError.new("#{key} must be a string")
+    end
+
+    private def self.integer_option(key : String, value : JSON::Any) : Int64
+      value.as_i64? || raise InvalidOptionsError.new("#{key} must be an integer")
+    end
+
+    private def self.int32_option(key : String, value : JSON::Any) : Int32
+      integer = integer_option(key, value)
+      unless Int32::MIN <= integer <= Int32::MAX
+        raise InvalidOptionsError.new("#{key} is out of range")
+      end
+      integer.to_i32
+    end
+
+    private def self.seconds_option(
+      key : String,
+      value : JSON::Any,
+      allow_zero : Bool = false,
+    ) : Time::Span
+      number = if float = value.as_f?
+                 float
+               elsif integer = value.as_i64?
+                 integer.to_f
+               else
+                 raise InvalidOptionsError.new("#{key} must be a number")
+               end
+
+      if allow_zero ? number < 0 : number <= 0
+        raise InvalidOptionsError.new("#{key} must be greater than zero")
+      end
+
+      number.seconds
+    end
+
+    private def self.validate(options : RequestOptions) : Nil
+      if options.user_agent.empty?
+        raise InvalidOptionsError.new("user_agent must not be empty")
+      end
+
+      if options.max_redirects < 0
+        raise InvalidOptionsError.new("max_redirects must not be negative")
+      end
+
+      if options.retries < 0
+        raise InvalidOptionsError.new("retries must not be negative")
+      end
+
+      if options.retries > 10
+        raise InvalidOptionsError.new("retries must not exceed 10")
+      end
+
+      if options.max_response_bytes <= 0
+        raise InvalidOptionsError.new("max_response_bytes must be positive")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,70 @@
+require "uri"
+
+require "./errors"
+require "./mime_type"
+
+module Rill::SegmentAssembly
+  enum Family
+    MpegTs
+    FragmentedMp4
+    Webm
+    Adts
+    Mp3
+  end
+
+  FRAGMENTED_EXTENSIONS = {
+    "m4s", "mp4", "m4a", "m4v", "cmfv", "cmfa",
+  }
+
+  def self.for_hls(map_url : URI?, extensions : Array(String)) : Family
+    unique = extensions.map(&.downcase).uniq
+
+    if map_url
+      unless unique.all? { |extension| extension.empty? || FRAGMENTED_EXTENSIONS.includes?(extension) }
+        raise UnsupportedManifestError.new("HLS segments are not a supported fragmented MP4 layout")
+      end
+
+      return Family::FragmentedMp4
+    end
+
+    case unique
+    when ["ts"]
+      Family::MpegTs
+    when ["aac"]
+      Family::Adts
+    when ["mp3"]
+      Family::Mp3
+    else
+      raise UnsupportedManifestError.new(
+        "HLS segment concatenation is not verified for #{unique.inspect}",
+      )
+    end
+  end
+
+  def self.for_dash(mime : MimeType, has_init : Bool) : Family
+    case mime.subtype
+    when "mp4", "m4a", "m4v"
+      unless has_init
+        raise UnsupportedManifestError.new("DASH fragmented MP4 needs an initialization segment")
+      end
+
+      Family::FragmentedMp4
+    when "webm"
+      unless has_init
+        raise UnsupportedManifestError.new("DASH WebM needs an initialization segment")
+      end
+
+      Family::Webm
+    when "mp2t"
+      Family::MpegTs
+    when "aac"
+      Family::Adts
+    when "mpeg"
+      Family::Mp3
+    else
+      raise UnsupportedManifestError.new(
+        "DASH segment concatenation is not verified for #{mime.type}/#{mime.subtype}",
+      )
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Rill
+  module Timestamp
+    extend self
+
+    def clock_seconds(value : String?) : Float64?
+      return nil unless value
+
+      total = 0.0
+      value.split(':').each do |part|
+        number = part.to_f?
+        return nil unless number && number.finite? && number >= 0
+
+        total = total * 60 + number
+      end
+
+      total
+    end
+
+    def iso8601_seconds(value : String?) : Float64?
+      return nil unless value
+
+      match = /\AP(?:(\d+)D)?T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?\z/.match(value)
+      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
+
+      total = days * 86_400 + hours * 3600 + minutes * 60 + seconds
+      total if total > 0
+    end
+  end
+end

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

@@ -0,0 +1,3 @@
+module Rill
+  VERSION = "2026.11.15"
+end

package/native-src/src/rill.cr

@@ -0,0 +1,47 @@
+require "uri"
+
+require "./rill/version"
+require "./rill/errors"
+require "./rill/request_options"
+require "./rill/http_client"
+require "./rill/format"
+require "./rill/http_url"
+require "./rill/json_value"
+require "./rill/mime_type"
+require "./rill/segment_assembly"
+require "./rill/timestamp"
+require "./rill/media"
+require "./rill/extractor"
+require "./rill/playlist"
+require "./rill/extractors/bandcamp"
+require "./rill/extractors/dash"
+require "./rill/extractors/direct_media"
+require "./rill/extractors/generic"
+require "./rill/extractors/hls"
+require "./rill/extractors/internet_archive"
+require "./rill/extractors/m3u"
+require "./rill/extractors/media_ccc_de"
+require "./rill/extractors/mixcloud"
+require "./rill/extractors/peer_tube"
+require "./rill/extractors/rumble"
+require "./rill/extractors/soundcloud"
+require "./rill/extractors/spotify"
+require "./rill/extractors/twitch_clip"
+require "./rill/extractors/youtube"
+require "./rill/extractor_registry"
+require "./rill/format_selector"
+require "./rill/cancellation"
+require "./rill/cookie_jar"
+require "./rill/download_progress"
+require "./rill/output_file_name"
+require "./rill/download_options"
+require "./rill/download_plan"
+require "./rill/downloader"
+require "./rill/client"
+require "./rill/media_muxer"
+
+module Rill
+  def self.extract(url : String | URI, options : RequestOptions = RequestOptions.new) : Media | Playlist
+    ExtractorRegistry.default.extract(url, options)
+  end
+end

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "rill-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2026.11.15",
+  "description": "Node.js bindings for the Rill media extractor and downloader",
+  "license": "Apache-2.0",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "gypfile": true,
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "binding.gyp",
+    "src/**/*",
+    "scripts/**/*",
+    "native-src/**/*",
+    "native/**/*",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SimaoMoreira5228/rill.git",
+    "directory": "bindings/node"
+  },
+  "homepage": "https://github.com/SimaoMoreira5228/rill",
+  "bugs": {
+    "url": "https://github.com/SimaoMoreira5228/rill/issues"
+  },
+  "keywords": [
+    "rill",
+    "media",
+    "video",
+    "audio",
+    "download",
+    "extractor"
+  ],
+  "scripts": {
+    "prepack": "node scripts/prepack.js",
+    "install": "node scripts/install.js",
+    "package-native": "node scripts/package-native.js",
+    "test": "node smoke.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/build-native.js

@@ -0,0 +1,46 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const packageDir = path.resolve(__dirname, "..");
+const nativeDir = path.join(packageDir, "native");
+const libraryName =
+  process.platform === "darwin"
+    ? "librill.dylib"
+    : process.platform === "win32"
+      ? "rill.dll"
+      : "librill.so";
+const library = path.join(nativeDir, libraryName);
+
+if (fs.existsSync(library) || process.env.RILL_LIBRARY || process.env.RILL_LIB_DIR) {
+  process.exit(0);
+}
+
+const vendored = path.join(packageDir, "native-src");
+const root = fs.existsSync(path.join(vendored, "src", "c_api.cr"))
+  ? vendored
+  : path.resolve(packageDir, "..", "..");
+const source = path.join(root, "src", "c_api.cr");
+
+if (!fs.existsSync(source)) {
+  console.error(`Rill source not found at ${source}`);
+  console.error("Set RILL_LIB_DIR or RILL_LIBRARY to an existing librill build.");
+  process.exit(1);
+}
+
+fs.mkdirSync(nativeDir, { recursive: true });
+
+const linkFlag = process.platform === "win32" ? "/DLL" : "-shared";
+const result = spawnSync(
+  process.env.CRYSTAL || "crystal",
+  ["build", "--single-module", "--link-flags", linkFlag, "-o", library, source],
+  { cwd: root, stdio: "inherit" },
+);
+
+if (result.error) {
+  console.error("Unable to run crystal. Install Crystal 1.22 or set RILL_LIB_DIR.");
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/scripts/install-gyp.js

@@ -0,0 +1,10 @@
+const { spawnSync } = require("node:child_process");
+
+const result = spawnSync("node-gyp", ["rebuild"], { stdio: "inherit" });
+
+if (result.error && result.error.code === "ENOENT") {
+  const fallback = spawnSync("npx", ["--yes", "node-gyp", "rebuild"], { stdio: "inherit" });
+  process.exit(fallback.status ?? 1);
+}
+
+process.exit(result.status ?? 1);

package/scripts/install.js

@@ -0,0 +1,19 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { nativeDir } = require("./platform.js");
+
+const packageDir = path.resolve(__dirname, "..");
+
+if (fs.existsSync(path.join(nativeDir(packageDir), "rill_node.node"))) {
+  process.exit(0);
+}
+
+for (const script of ["build-native.js", "install-gyp.js"]) {
+  const result = spawnSync(process.execPath, [path.join(__dirname, script)], {
+    stdio: "inherit",
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}

package/scripts/lib.js

@@ -0,0 +1 @@
+console.log(process.env.RILL_LIBRARY || "-lrill");

package/scripts/libdir.js

@@ -0,0 +1,23 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageDir = path.resolve(__dirname, "..");
+const libraryName =
+  process.platform === "darwin"
+    ? "librill.dylib"
+    : process.platform === "win32"
+      ? "rill.dll"
+      : "librill.so";
+
+if (process.env.RILL_LIBRARY) {
+  console.log(path.dirname(process.env.RILL_LIBRARY));
+} else if (process.env.RILL_LIB_DIR) {
+  console.log(process.env.RILL_LIB_DIR);
+} else {
+  const native = path.join(packageDir, "native");
+  if (fs.existsSync(path.join(native, libraryName))) {
+    console.log(native);
+  } else {
+    console.log(path.resolve(packageDir, "..", "..", "build"));
+  }
+}

package/scripts/package-native.js

@@ -0,0 +1,35 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const { helperName, libraryName, platformKey } = require("./platform.js");
+
+const packageDir = path.resolve(__dirname, "..");
+const root = path.resolve(packageDir, "..", "..");
+const output = path.join(packageDir, "native", platformKey());
+
+const library =
+  process.env.RILL_LIBRARY || path.join(root, "build", libraryName());
+const helper = path.join(root, "build", helperName());
+const addon = process.env.RILL_NODE_ADDON || path.join(packageDir, "build", "Release", "rill_node.node");
+
+for (const [label, source] of [
+  ["librill", library],
+  ["rill-media", helper],
+  ["rill_node.node", addon],
+]) {
+  if (!fs.existsSync(source)) {
+    console.error(`Missing ${label}: ${source}`);
+    process.exit(1);
+  }
+}
+
+fs.mkdirSync(output, { recursive: true });
+fs.copyFileSync(library, path.join(output, path.basename(library)));
+fs.copyFileSync(helper, path.join(output, path.basename(helper)));
+fs.copyFileSync(addon, path.join(output, "rill_node.node"));
+
+if (process.platform !== "win32") {
+  fs.chmodSync(path.join(output, path.basename(library)), 0o755);
+  fs.chmodSync(path.join(output, path.basename(helper)), 0o755);
+}
+
+console.log(output);

package/scripts/platform.js

@@ -0,0 +1,41 @@
+const path = require("node:path");
+
+function platformKey() {
+  if (process.env.RILL_PLATFORM_KEY) {
+    return process.env.RILL_PLATFORM_KEY;
+  }
+
+  const arch = process.arch;
+  if (process.platform === "linux") {
+    const report = process.report?.getReport?.();
+    const libc = report?.header?.glibcVersionRuntime ? "gnu" : "musl";
+    return `linux-${arch}-${libc}`;
+  }
+
+  return `${process.platform}-${arch}`;
+}
+
+function libraryName(platform = process.platform) {
+  if (platform === "darwin") {
+    return "librill.dylib";
+  }
+  if (platform === "win32") {
+    return "rill.dll";
+  }
+  return "librill.so";
+}
+
+function helperName(platform = process.platform) {
+  return platform === "win32" ? "rill-media.exe" : "rill-media";
+}
+
+function nativeDir(packageDir) {
+  return path.join(packageDir, "native", platformKey());
+}
+
+module.exports = {
+  helperName,
+  libraryName,
+  nativeDir,
+  platformKey,
+};