@revizly/node-av 5.2.2-beta.1

package/dist/lib/rational.d.ts

@@ -0,0 +1,251 @@
+import type { IRational } from './types.js';
+/**
+ * Rational number type for precise fractional representations.
+ *
+ * Represents a rational number as a fraction (numerator/denominator).
+ * Used throughout FFmpeg for time bases, aspect ratios, frame rates,
+ * and other fractional values that require exact precision.
+ *
+ * @example
+ * ```typescript
+ * import { Rational } from 'node-av';
+ *
+ * // Common time bases
+ * const timebase = new Rational(1, 90000); // 90kHz for MPEG-TS
+ * const videoTimebase = new Rational(1, 25); // 25 fps
+ * const audioTimebase = new Rational(1, 48000); // 48kHz audio
+ *
+ * // Frame rates
+ * const framerate = new Rational(30, 1);    // 30 fps
+ * const ntscFramerate = new Rational(30000, 1001); // 29.97 fps NTSC
+ * const palFramerate = new Rational(25, 1); // 25 fps PAL
+ *
+ * // Aspect ratios
+ * const aspectRatio = new Rational(16, 9); // 16:9
+ * const pixelAspect = new Rational(1, 1); // Square pixels
+ *
+ * // Arithmetic operations
+ * const doubled = timebase.mul(new Rational(2, 1));
+ * const inverted = framerate.inv(); // Get frame duration
+ * const sum = framerate.add(new Rational(5, 1)); // Add 5 fps
+ * ```
+ */
+export declare class Rational {
+    readonly num: number;
+    readonly den: number;
+    /**
+     * Create a new rational number.
+     *
+     * Represents the fraction num/den.
+     *
+     * @param num - Numerator of the fraction
+     *
+     * @param den - Denominator of the fraction (must not be 0)
+     *
+     * @throws {Error} If denominator is 0
+     *
+     * @example
+     * ```typescript
+     * import { Rational } from 'node-av';
+     *
+     * // Create time base for 25 fps video
+     * const timebase = new Rational(1, 25);
+     *
+     * // Create NTSC frame rate (29.97 fps)
+     * const ntsc = new Rational(30000, 1001);
+     *
+     * // Will throw error
+     * try {
+     *   const invalid = new Rational(1, 0);
+     * } catch (error) {
+     *   console.error('Cannot have zero denominator');
+     * }
+     * ```
+     */
+    constructor(num: number, den: number);
+    /**
+     * Create a Rational from an IRational object.
+     *
+     * @param rational - The IRational object with num and den properties
+     *
+     * @returns A new Rational instance
+     *
+     * @example
+     * ```typescript
+     * import { Rational } from 'node-av';
+     *
+     * const obj = { num: 3, den: 4 };
+     * const rational = Rational.fromObject(obj);
+     * console.log(rational.toString()); // "3/4"
+     * ```
+     */
+    static fromObject(rational: IRational): Rational;
+    /**
+     * Add two rational numbers.
+     *
+     * Performs addition: (a/b) + (c/d) = (ad + bc) / bd
+     *
+     * @param other - The rational number to add
+     *
+     * @returns A new Rational representing the sum
+     *
+     * @example
+     * ```typescript
+     * const a = new Rational(1, 2); // 1/2
+     * const b = new Rational(1, 3); // 1/3
+     * const sum = a.add(b); // 5/6
+     * console.log(sum.toString()); // "5/6"
+     * ```
+     */
+    add(other: Rational): Rational;
+    /**
+     * Subtract two rational numbers.
+     *
+     * Performs subtraction: (a/b) - (c/d) = (ad - bc) / bd
+     *
+     * @param other - The rational number to subtract
+     *
+     * @returns A new Rational representing the difference
+     *
+     * @example
+     * ```typescript
+     * const a = new Rational(3, 4); // 3/4
+     * const b = new Rational(1, 4); // 1/4
+     * const diff = a.sub(b); // 2/4 = 1/2
+     * console.log(diff.toString()); // "2/4"
+     * ```
+     */
+    sub(other: Rational): Rational;
+    /**
+     * Multiply two rational numbers.
+     *
+     * Performs multiplication: (a/b) × (c/d) = (ac) / (bd)
+     *
+     * @param other - The rational number to multiply by
+     *
+     * @returns A new Rational representing the product
+     *
+     * @example
+     * ```typescript
+     * const framerate = new Rational(30, 1); // 30 fps
+     * const duration = new Rational(5, 1); // 5 seconds
+     * const frames = framerate.mul(duration); // 150/1 = 150 frames
+     * console.log(frames.toDouble()); // 150
+     * ```
+     */
+    mul(other: Rational): Rational;
+    /**
+     * Divide two rational numbers.
+     *
+     * Performs division: (a/b) ÷ (c/d) = (ad) / (bc)
+     *
+     * @param other - The rational number to divide by
+     *
+     * @returns A new Rational representing the quotient
+     *
+     * @example
+     * ```typescript
+     * const pixels = new Rational(1920, 1); // 1920 pixels width
+     * const aspect = new Rational(16, 9); // 16:9 aspect ratio
+     * const height = pixels.div(aspect); // Calculate height
+     * console.log(height.toDouble()); // 1080
+     * ```
+     */
+    div(other: Rational): Rational;
+    /**
+     * Check if this rational is valid (both num and den are positive).
+     *
+     * FFmpeg uses { 0, 0 } as "undefined" and { num, 0 } as infinity.
+     * This method returns true only if both values are positive.
+     *
+     * @returns true if num > 0 and den > 0
+     *
+     * @example
+     * ```typescript
+     * const valid = new Rational(25, 1);
+     * console.log(valid.isValid()); // true
+     *
+     * const undefined = new Rational(0, 0);
+     * console.log(undefined.isValid()); // false
+     *
+     * const infinity = new Rational(1, 0);
+     * console.log(infinity.isValid()); // false
+     * ```
+     */
+    isValid(): boolean;
+    /**
+     * Invert the rational number (reciprocal).
+     *
+     * Returns the reciprocal: 1/(a/b) = b/a
+     *
+     * @returns A new Rational representing the reciprocal
+     *
+     * @example
+     * ```typescript
+     * const framerate = new Rational(25, 1); // 25 fps
+     * const frameDuration = framerate.inv(); // 1/25 seconds per frame
+     * console.log(frameDuration.toString()); // "1/25"
+     * console.log(frameDuration.toDouble()); // 0.04 seconds
+     * ```
+     */
+    inv(): Rational;
+    /**
+     * Convert rational to floating point number.
+     *
+     * Calculates the decimal value: num / den
+     * Note: This may lose precision for some rational values.
+     *
+     * @returns The floating point representation (Infinity if den = 0, NaN if both = 0)
+     *
+     * @example
+     * ```typescript
+     * const ntsc = new Rational(30000, 1001); // NTSC frame rate
+     * console.log(ntsc.toDouble()); // 29.97002997...
+     *
+     * const half = new Rational(1, 2);
+     * console.log(half.toDouble()); // 0.5
+     *
+     * const infinity = new Rational(1, 0);
+     * console.log(infinity.toDouble()); // Infinity
+     * ```
+     */
+    toDouble(): number;
+    /**
+     * Check if this rational equals another.
+     *
+     * Compares using cross-multiplication to avoid floating point errors.
+     * Two rationals a/b and c/d are equal if ad = bc.
+     *
+     * @param other - The rational to compare with
+     *
+     * @returns true if the rationals are equal, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const a = new Rational(2, 4);
+     * const b = new Rational(1, 2);
+     * const c = new Rational(3, 4);
+     *
+     * console.log(a.equals(b)); // true (both are 1/2)
+     * console.log(a.equals(c)); // false
+     * ```
+     */
+    equals(other: Rational): boolean;
+    /**
+     * Get string representation of the rational.
+     *
+     * Returns the rational in "num/den" format.
+     *
+     * @returns String representation as "numerator/denominator"
+     *
+     * @example
+     * ```typescript
+     * const framerate = new Rational(30000, 1001);
+     * console.log(framerate.toString()); // "30000/1001"
+     *
+     * const timebase = new Rational(1, 90000);
+     * console.log(`Timebase: ${timebase}`); // "Timebase: 1/90000"
+     * ```
+     */
+    toString(): string;
+}

package/dist/lib/rational.js

@@ -0,0 +1,278 @@
+/**
+ * Rational number type for precise fractional representations.
+ *
+ * Represents a rational number as a fraction (numerator/denominator).
+ * Used throughout FFmpeg for time bases, aspect ratios, frame rates,
+ * and other fractional values that require exact precision.
+ *
+ * @example
+ * ```typescript
+ * import { Rational } from 'node-av';
+ *
+ * // Common time bases
+ * const timebase = new Rational(1, 90000); // 90kHz for MPEG-TS
+ * const videoTimebase = new Rational(1, 25); // 25 fps
+ * const audioTimebase = new Rational(1, 48000); // 48kHz audio
+ *
+ * // Frame rates
+ * const framerate = new Rational(30, 1);    // 30 fps
+ * const ntscFramerate = new Rational(30000, 1001); // 29.97 fps NTSC
+ * const palFramerate = new Rational(25, 1); // 25 fps PAL
+ *
+ * // Aspect ratios
+ * const aspectRatio = new Rational(16, 9); // 16:9
+ * const pixelAspect = new Rational(1, 1); // Square pixels
+ *
+ * // Arithmetic operations
+ * const doubled = timebase.mul(new Rational(2, 1));
+ * const inverted = framerate.inv(); // Get frame duration
+ * const sum = framerate.add(new Rational(5, 1)); // Add 5 fps
+ * ```
+ */
+export class Rational {
+    num;
+    den;
+    /**
+     * Create a new rational number.
+     *
+     * Represents the fraction num/den.
+     *
+     * @param num - Numerator of the fraction
+     *
+     * @param den - Denominator of the fraction (must not be 0)
+     *
+     * @throws {Error} If denominator is 0
+     *
+     * @example
+     * ```typescript
+     * import { Rational } from 'node-av';
+     *
+     * // Create time base for 25 fps video
+     * const timebase = new Rational(1, 25);
+     *
+     * // Create NTSC frame rate (29.97 fps)
+     * const ntsc = new Rational(30000, 1001);
+     *
+     * // Will throw error
+     * try {
+     *   const invalid = new Rational(1, 0);
+     * } catch (error) {
+     *   console.error('Cannot have zero denominator');
+     * }
+     * ```
+     */
+    constructor(num, den) {
+        this.num = num;
+        this.den = den;
+        // Note: FFmpeg allows den = 0 as a special value:
+        // - { 0, 0 } = undefined/not set
+        // - { num, 0 } = infinity
+        // We allow it for FFmpeg compatibility, but operations may fail.
+    }
+    /**
+     * Create a Rational from an IRational object.
+     *
+     * @param rational - The IRational object with num and den properties
+     *
+     * @returns A new Rational instance
+     *
+     * @example
+     * ```typescript
+     * import { Rational } from 'node-av';
+     *
+     * const obj = { num: 3, den: 4 };
+     * const rational = Rational.fromObject(obj);
+     * console.log(rational.toString()); // "3/4"
+     * ```
+     */
+    static fromObject(rational) {
+        return new Rational(rational.num, rational.den);
+    }
+    /**
+     * Add two rational numbers.
+     *
+     * Performs addition: (a/b) + (c/d) = (ad + bc) / bd
+     *
+     * @param other - The rational number to add
+     *
+     * @returns A new Rational representing the sum
+     *
+     * @example
+     * ```typescript
+     * const a = new Rational(1, 2); // 1/2
+     * const b = new Rational(1, 3); // 1/3
+     * const sum = a.add(b); // 5/6
+     * console.log(sum.toString()); // "5/6"
+     * ```
+     */
+    add(other) {
+        return new Rational(this.num * other.den + other.num * this.den, this.den * other.den);
+    }
+    /**
+     * Subtract two rational numbers.
+     *
+     * Performs subtraction: (a/b) - (c/d) = (ad - bc) / bd
+     *
+     * @param other - The rational number to subtract
+     *
+     * @returns A new Rational representing the difference
+     *
+     * @example
+     * ```typescript
+     * const a = new Rational(3, 4); // 3/4
+     * const b = new Rational(1, 4); // 1/4
+     * const diff = a.sub(b); // 2/4 = 1/2
+     * console.log(diff.toString()); // "2/4"
+     * ```
+     */
+    sub(other) {
+        return new Rational(this.num * other.den - other.num * this.den, this.den * other.den);
+    }
+    /**
+     * Multiply two rational numbers.
+     *
+     * Performs multiplication: (a/b) × (c/d) = (ac) / (bd)
+     *
+     * @param other - The rational number to multiply by
+     *
+     * @returns A new Rational representing the product
+     *
+     * @example
+     * ```typescript
+     * const framerate = new Rational(30, 1); // 30 fps
+     * const duration = new Rational(5, 1); // 5 seconds
+     * const frames = framerate.mul(duration); // 150/1 = 150 frames
+     * console.log(frames.toDouble()); // 150
+     * ```
+     */
+    mul(other) {
+        return new Rational(this.num * other.num, this.den * other.den);
+    }
+    /**
+     * Divide two rational numbers.
+     *
+     * Performs division: (a/b) ÷ (c/d) = (ad) / (bc)
+     *
+     * @param other - The rational number to divide by
+     *
+     * @returns A new Rational representing the quotient
+     *
+     * @example
+     * ```typescript
+     * const pixels = new Rational(1920, 1); // 1920 pixels width
+     * const aspect = new Rational(16, 9); // 16:9 aspect ratio
+     * const height = pixels.div(aspect); // Calculate height
+     * console.log(height.toDouble()); // 1080
+     * ```
+     */
+    div(other) {
+        return new Rational(this.num * other.den, this.den * other.num);
+    }
+    /**
+     * Check if this rational is valid (both num and den are positive).
+     *
+     * FFmpeg uses { 0, 0 } as "undefined" and { num, 0 } as infinity.
+     * This method returns true only if both values are positive.
+     *
+     * @returns true if num > 0 and den > 0
+     *
+     * @example
+     * ```typescript
+     * const valid = new Rational(25, 1);
+     * console.log(valid.isValid()); // true
+     *
+     * const undefined = new Rational(0, 0);
+     * console.log(undefined.isValid()); // false
+     *
+     * const infinity = new Rational(1, 0);
+     * console.log(infinity.isValid()); // false
+     * ```
+     */
+    isValid() {
+        return this.num > 0 && this.den > 0;
+    }
+    /**
+     * Invert the rational number (reciprocal).
+     *
+     * Returns the reciprocal: 1/(a/b) = b/a
+     *
+     * @returns A new Rational representing the reciprocal
+     *
+     * @example
+     * ```typescript
+     * const framerate = new Rational(25, 1); // 25 fps
+     * const frameDuration = framerate.inv(); // 1/25 seconds per frame
+     * console.log(frameDuration.toString()); // "1/25"
+     * console.log(frameDuration.toDouble()); // 0.04 seconds
+     * ```
+     */
+    inv() {
+        return new Rational(this.den, this.num);
+    }
+    /**
+     * Convert rational to floating point number.
+     *
+     * Calculates the decimal value: num / den
+     * Note: This may lose precision for some rational values.
+     *
+     * @returns The floating point representation (Infinity if den = 0, NaN if both = 0)
+     *
+     * @example
+     * ```typescript
+     * const ntsc = new Rational(30000, 1001); // NTSC frame rate
+     * console.log(ntsc.toDouble()); // 29.97002997...
+     *
+     * const half = new Rational(1, 2);
+     * console.log(half.toDouble()); // 0.5
+     *
+     * const infinity = new Rational(1, 0);
+     * console.log(infinity.toDouble()); // Infinity
+     * ```
+     */
+    toDouble() {
+        return this.num / this.den; // JavaScript handles division by zero correctly (Infinity/NaN)
+    }
+    /**
+     * Check if this rational equals another.
+     *
+     * Compares using cross-multiplication to avoid floating point errors.
+     * Two rationals a/b and c/d are equal if ad = bc.
+     *
+     * @param other - The rational to compare with
+     *
+     * @returns true if the rationals are equal, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const a = new Rational(2, 4);
+     * const b = new Rational(1, 2);
+     * const c = new Rational(3, 4);
+     *
+     * console.log(a.equals(b)); // true (both are 1/2)
+     * console.log(a.equals(c)); // false
+     * ```
+     */
+    equals(other) {
+        return this.num * other.den === other.num * this.den;
+    }
+    /**
+     * Get string representation of the rational.
+     *
+     * Returns the rational in "num/den" format.
+     *
+     * @returns String representation as "numerator/denominator"
+     *
+     * @example
+     * ```typescript
+     * const framerate = new Rational(30000, 1001);
+     * console.log(framerate.toString()); // "30000/1001"
+     *
+     * const timebase = new Rational(1, 90000);
+     * console.log(`Timebase: ${timebase}`); // "Timebase: 1/90000"
+     * ```
+     */
+    toString() {
+        return `${this.num}/${this.den}`;
+    }
+}
+//# sourceMappingURL=rational.js.map

package/dist/lib/rational.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rational.js","sourceRoot":"","sources":["../../src/lib/rational.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,QAAQ;IA+BD;IACA;IA/BlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,YACkB,GAAW,EACX,GAAW;QADX,QAAG,GAAH,GAAG,CAAQ;QACX,QAAG,GAAH,GAAG,CAAQ;QAE3B,kDAAkD;QAClD,iCAAiC;QACjC,0BAA0B;QAC1B,iEAAiE;IACnE,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,UAAU,CAAC,QAAmB;QACnC,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,KAAe;QACjB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,KAAe;QACjB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IACzF,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,KAAe;QACjB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,KAAe;QACjB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO;QACL,OAAO,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;IACtC,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,GAAG;QACD,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,+DAA+D;IAC7F,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,KAAe;QACpB,OAAO,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,QAAQ;QACN,OAAO,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACnC,CAAC;CACF"}