@revizly/node-av 5.2.2-beta.1

package/dist/api/utilities/streaming.d.ts

@@ -0,0 +1,186 @@
+import { FormatContext } from '../../lib/format-context.js';
+import type { AVCodecID } from '../../constants/index.js';
+import type { Muxer } from '../muxer.js';
+/**
+ * Streaming protocol utilities.
+ *
+ * Provides static methods for SDP generation, RTP URL building, and
+ * network streaming helpers for RTP/RTSP protocols.
+ *
+ * @example
+ * ```typescript
+ * import { StreamingUtils, Muxer } from 'node-av/api';
+ *
+ * // Create RTP outputs
+ * const videoOutput = await Muxer.open('rtp://127.0.0.1:5004');
+ * const audioOutput = await Muxer.open('rtp://127.0.0.1:5006');
+ *
+ * // Generate SDP for streaming
+ * const sdp = StreamingUtils.createSdp([videoOutput, audioOutput]);
+ * if (sdp) {
+ *   console.log('SDP for streaming:', sdp);
+ *   // Save to .sdp file or serve via RTSP server
+ * }
+ * ```
+ */
+export declare class StreamingUtils {
+    /**
+     * Create an SDP (Session Description Protocol) string from demuxer/muxer
+     *
+     * Generates an SDP description for RTP/RTSP streaming from one or more
+     * configured demuxer/muxer. The inputs/outputs should be configured with RTP
+     * format and have their streams set up before calling this method.
+     *
+     * @param contexts - Alternatively, array of FormatContext objects
+     *
+     * @returns SDP string if successful, null if failed
+     *
+     * @example
+     * ```typescript
+     * // Set up RTP outputs with streams
+     * const output1 = await Muxer.open('rtp://239.0.0.1:5004');
+     * await output1.addStream(encoder1);
+     *
+     * const output2 = await Muxer.open('rtp://239.0.0.1:5006');
+     * await output2.addStream(encoder2);
+     *
+     * // Generate SDP for multicast streaming
+     * const sdp = StreamingUtils.createSdp([output1.getFormatContext(), output2.getFormatContext()]);
+     * if (sdp) {
+     *   // Write to file for VLC or other players
+     *   await fs.writeFile('stream.sdp', sdp);
+     * }
+     * ```
+     */
+    static createSdp(contexts: FormatContext[]): string | null;
+    /**
+     * Generate SDP for RTP/SRTP input using FFmpeg's native SDP generator
+     *
+     * Creates an RFC-compliant SDP description using FFmpeg's internal logic.
+     * This ensures correct codec names, clock rates, and formatting for all codecs.
+     *
+     * @param configs - Array of stream configurations
+     *
+     * @param sessionName - Optional session name for the SDP (default: 'RTP Stream')
+     *
+     * @returns SDP string with proper rtpmap and optional crypto attributes
+     *
+     * @example
+     * ```typescript
+     * import { StreamingUtils } from 'node-av/api';
+     * import { AV_CODEC_ID_OPUS, AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * // Single audio stream with SRTP
+     * const sdp = StreamingUtils.createInputSDP([{
+     *   port: 5004,
+     *   codecId: AV_CODEC_ID_OPUS,
+     *   payloadType: 111,
+     *   clockRate: 48000,
+     *   channels: 2,
+     *   srtp: {
+     *     key: Buffer.alloc(16, 0x12),
+     *     salt: Buffer.alloc(14, 0x34)
+     *   }
+     * }]);
+     *
+     * // Multi-stream (video + audio)
+     * const sdp = StreamingUtils.createInputSDP([
+     *   { port: 5006, codecId: AV_CODEC_ID_H264, payloadType: 96, clockRate: 90000 },
+     *   { port: 5004, codecId: AV_CODEC_ID_OPUS, payloadType: 111, clockRate: 48000, channels: 2 }
+     * ], 'My Stream');
+     * ```
+     */
+    static createInputSDP(configs: {
+        port: number;
+        codecId: AVCodecID;
+        payloadType: number;
+        clockRate: number;
+        channels?: number;
+        fmtp?: string;
+        srtp?: {
+            key: Buffer;
+            salt: Buffer;
+            suite?: 'AES_CM_128_HMAC_SHA1_80' | 'AES_CM_256_HMAC_SHA1_80';
+        };
+    }[], sessionName?: string): string;
+    /**
+     * Validate if an output is configured for RTP streaming
+     *
+     * @param output - Muxer to check
+     *
+     * @returns true if configured for RTP
+     *
+     * @example
+     * ```typescript
+     * const output = await Muxer.open('rtp://127.0.0.1:5004');
+     * if (StreamingUtils.isRtpOutput(output)) {
+     *   const sdp = StreamingUtils.createSdpForOutput(output);
+     * }
+     * ```
+     */
+    static isRtpOutput(output: Muxer): boolean;
+    /**
+     * Build RTP URL from components
+     *
+     * Helper to construct RTP URLs with proper formatting.
+     *
+     * @param host - IP address or hostname
+     *
+     * @param port - Port number
+     *
+     * @param options - Additional options
+     *
+     * @param options.ttl - Time-to-live for multicast
+     *
+     * @param options.localrtpport - Local RTP port
+     *
+     * @param options.localrtcpport - Local RTCP port
+     *
+     * @param options.pkt_size - Packet size
+     *
+     * @returns Formatted RTP URL
+     *
+     * @example
+     * ```typescript
+     * // Unicast
+     * const url1 = StreamingUtils.buildRtpUrl('127.0.0.1', 5004);
+     * // 'rtp://127.0.0.1:5004'
+     *
+     * // Multicast
+     * const url2 = StreamingUtils.buildRtpUrl('239.0.0.1', 5004, { ttl: 64 });
+     * // 'rtp://239.0.0.1:5004?ttl=64'
+     * ```
+     */
+    static buildRtpUrl(host: string, port: number, options?: {
+        ttl?: number;
+        localrtpport?: number;
+        localrtcpport?: number;
+        pkt_size?: number;
+    }): string;
+    /**
+     * Extract all UDP ports from SDP content
+     *
+     * @param sdp - SDP content string
+     *
+     * @returns Array of port numbers (one per stream)
+     *
+     * @example
+     * ```typescript
+     * import { StreamingUtils } from 'node-av/api';
+     *
+     * const sdp = `v=0
+     * o=- 0 0 IN IP4 127.0.0.1
+     * s=Test Stream
+     * c=IN IP4 127.0.0.1
+     * t=0 0
+     * m=audio 5004 RTP/AVP 111
+     * a=rtpmap:111 OPUS/48000/2
+     * m=video 5006 RTP/AVP 96
+     * a=rtpmap:96 H264/90000`;
+     *
+     * const ports = StreamingUtils.extractPortsFromSDP(sdp);
+     * console.log(ports); // [5004, 5006]
+     * ```
+     */
+    static extractPortsFromSDP(sdp: string): number[];
+}

package/dist/api/utilities/streaming.js

@@ -0,0 +1,309 @@
+import { AVMEDIA_TYPE_VIDEO } from '../../constants/constants.js';
+import { Codec } from '../../lib/codec.js';
+import { FormatContext } from '../../lib/format-context.js';
+import { Rational } from '../../lib/rational.js';
+import { avSdpCreate } from '../../lib/utilities.js';
+/**
+ * Streaming protocol utilities.
+ *
+ * Provides static methods for SDP generation, RTP URL building, and
+ * network streaming helpers for RTP/RTSP protocols.
+ *
+ * @example
+ * ```typescript
+ * import { StreamingUtils, Muxer } from 'node-av/api';
+ *
+ * // Create RTP outputs
+ * const videoOutput = await Muxer.open('rtp://127.0.0.1:5004');
+ * const audioOutput = await Muxer.open('rtp://127.0.0.1:5006');
+ *
+ * // Generate SDP for streaming
+ * const sdp = StreamingUtils.createSdp([videoOutput, audioOutput]);
+ * if (sdp) {
+ *   console.log('SDP for streaming:', sdp);
+ *   // Save to .sdp file or serve via RTSP server
+ * }
+ * ```
+ */
+export class StreamingUtils {
+    /**
+     * Create an SDP (Session Description Protocol) string from demuxer/muxer
+     *
+     * Generates an SDP description for RTP/RTSP streaming from one or more
+     * configured demuxer/muxer. The inputs/outputs should be configured with RTP
+     * format and have their streams set up before calling this method.
+     *
+     * @param contexts - Alternatively, array of FormatContext objects
+     *
+     * @returns SDP string if successful, null if failed
+     *
+     * @example
+     * ```typescript
+     * // Set up RTP outputs with streams
+     * const output1 = await Muxer.open('rtp://239.0.0.1:5004');
+     * await output1.addStream(encoder1);
+     *
+     * const output2 = await Muxer.open('rtp://239.0.0.1:5006');
+     * await output2.addStream(encoder2);
+     *
+     * // Generate SDP for multicast streaming
+     * const sdp = StreamingUtils.createSdp([output1.getFormatContext(), output2.getFormatContext()]);
+     * if (sdp) {
+     *   // Write to file for VLC or other players
+     *   await fs.writeFile('stream.sdp', sdp);
+     * }
+     * ```
+     */
+    static createSdp(contexts) {
+        if (contexts?.length === 0) {
+            return null;
+        }
+        return avSdpCreate(contexts);
+    }
+    /**
+     * Generate SDP for RTP/SRTP input using FFmpeg's native SDP generator
+     *
+     * Creates an RFC-compliant SDP description using FFmpeg's internal logic.
+     * This ensures correct codec names, clock rates, and formatting for all codecs.
+     *
+     * @param configs - Array of stream configurations
+     *
+     * @param sessionName - Optional session name for the SDP (default: 'RTP Stream')
+     *
+     * @returns SDP string with proper rtpmap and optional crypto attributes
+     *
+     * @example
+     * ```typescript
+     * import { StreamingUtils } from 'node-av/api';
+     * import { AV_CODEC_ID_OPUS, AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * // Single audio stream with SRTP
+     * const sdp = StreamingUtils.createInputSDP([{
+     *   port: 5004,
+     *   codecId: AV_CODEC_ID_OPUS,
+     *   payloadType: 111,
+     *   clockRate: 48000,
+     *   channels: 2,
+     *   srtp: {
+     *     key: Buffer.alloc(16, 0x12),
+     *     salt: Buffer.alloc(14, 0x34)
+     *   }
+     * }]);
+     *
+     * // Multi-stream (video + audio)
+     * const sdp = StreamingUtils.createInputSDP([
+     *   { port: 5006, codecId: AV_CODEC_ID_H264, payloadType: 96, clockRate: 90000 },
+     *   { port: 5004, codecId: AV_CODEC_ID_OPUS, payloadType: 111, clockRate: 48000, channels: 2 }
+     * ], 'My Stream');
+     * ```
+     */
+    static createInputSDP(configs, sessionName = 'RTP Stream') {
+        const contexts = [];
+        try {
+            // Create one FormatContext per stream with individual URL (port)
+            for (const streamConfig of configs) {
+                const codec = Codec.findDecoder(streamConfig.codecId);
+                if (!codec) {
+                    throw new Error(`Codec not found for codec ID: ${streamConfig.codecId}`);
+                }
+                // Create format context with URL containing the port
+                const ctx = new FormatContext();
+                ctx.allocContext();
+                ctx.url = `rtp://127.0.0.1:${streamConfig.port}`;
+                // Create stream with codec parameters
+                const stream = ctx.newStream(null);
+                stream.codecpar.codecId = streamConfig.codecId;
+                stream.codecpar.codecType = codec.type;
+                // Set audio-specific parameters
+                if (codec.type !== AVMEDIA_TYPE_VIDEO) {
+                    if (streamConfig.clockRate) {
+                        stream.codecpar.sampleRate = streamConfig.clockRate;
+                    }
+                    if (streamConfig.channels) {
+                        stream.codecpar.channels = streamConfig.channels;
+                    }
+                }
+                // Set time base (required for SDP generation)
+                stream.timeBase = new Rational(1, streamConfig.clockRate);
+                contexts.push(ctx);
+            }
+            // Generate SDP using FFmpeg's native generator
+            // FFmpeg will automatically use the port from each context's URL and generate RFC-compliant codec names
+            let sdp = avSdpCreate(contexts);
+            if (!sdp) {
+                throw new Error('Failed to generate SDP');
+            }
+            // Post-process: Replace session name if provided
+            if (sessionName !== 'RTP Stream') {
+                sdp = sdp.replace(/^s=.*$/m, `s=${sessionName}`);
+            }
+            // Post-process: Replace payload types, add SRTP crypto lines, and/or custom fmtp
+            // Note: We always need to process because FFmpeg assigns payload types automatically
+            const sdpLines = sdp.split('\n');
+            const newLines = [];
+            let streamIndex = -1;
+            for (let i = 0; i < sdpLines.length; i++) {
+                const line = sdpLines[i];
+                if (line.startsWith('m=')) {
+                    // New media section
+                    streamIndex++;
+                    const streamCfg = configs[streamIndex];
+                    // Replace FFmpeg's auto-assigned payload type with user-specified one
+                    const replaced = line.replace(/RTP\/AVP\s+(\d+)/, `RTP/AVP ${streamCfg.payloadType}`);
+                    newLines.push(replaced);
+                    // Add SRTP crypto line right after m= line if configured
+                    if (streamCfg?.srtp) {
+                        const suite = streamCfg.srtp.suite ?? 'AES_CM_128_HMAC_SHA1_80';
+                        const keyMaterial = Buffer.concat([streamCfg.srtp.key, streamCfg.srtp.salt]).toString('base64');
+                        newLines.push(`a=crypto:1 ${suite} inline:${keyMaterial}`);
+                    }
+                }
+                else if (line.startsWith('a=rtpmap:')) {
+                    // Replace payload type in rtpmap line
+                    const streamCfg = configs[streamIndex];
+                    const replaced = line.replace(/^a=rtpmap:(\d+)/, `a=rtpmap:${streamCfg.payloadType}`);
+                    newLines.push(replaced);
+                    // If custom fmtp is provided but FFmpeg didn't generate one, add it
+                    if (streamCfg?.fmtp && !sdpLines[i + 1]?.startsWith('a=fmtp:')) {
+                        newLines.push(`a=fmtp:${streamCfg.payloadType} ${streamCfg.fmtp}`);
+                    }
+                }
+                else if (line.startsWith('a=fmtp:')) {
+                    // Replace payload type in fmtp line and optionally replace content
+                    const streamCfg = configs[streamIndex];
+                    if (streamCfg?.fmtp) {
+                        newLines.push(`a=fmtp:${streamCfg.payloadType} ${streamCfg.fmtp}`);
+                    }
+                    else {
+                        const replaced = line.replace(/^a=fmtp:(\d+)/, `a=fmtp:${streamCfg.payloadType}`);
+                        newLines.push(replaced);
+                    }
+                }
+                else {
+                    newLines.push(line);
+                }
+            }
+            return newLines.join('\n');
+        }
+        finally {
+            // Cleanup all contexts
+            for (const ctx of contexts) {
+                ctx.freeContext();
+            }
+        }
+    }
+    /**
+     * Validate if an output is configured for RTP streaming
+     *
+     * @param output - Muxer to check
+     *
+     * @returns true if configured for RTP
+     *
+     * @example
+     * ```typescript
+     * const output = await Muxer.open('rtp://127.0.0.1:5004');
+     * if (StreamingUtils.isRtpOutput(output)) {
+     *   const sdp = StreamingUtils.createSdpForOutput(output);
+     * }
+     * ```
+     */
+    static isRtpOutput(output) {
+        // Check if the output format is RTP
+        const formatContext = output.getFormatContext();
+        const oformat = formatContext?.oformat;
+        if (oformat) {
+            const name = oformat.name;
+            return name === 'rtp' || name === 'rtp_mpegts';
+        }
+        return false;
+    }
+    /**
+     * Build RTP URL from components
+     *
+     * Helper to construct RTP URLs with proper formatting.
+     *
+     * @param host - IP address or hostname
+     *
+     * @param port - Port number
+     *
+     * @param options - Additional options
+     *
+     * @param options.ttl - Time-to-live for multicast
+     *
+     * @param options.localrtpport - Local RTP port
+     *
+     * @param options.localrtcpport - Local RTCP port
+     *
+     * @param options.pkt_size - Packet size
+     *
+     * @returns Formatted RTP URL
+     *
+     * @example
+     * ```typescript
+     * // Unicast
+     * const url1 = StreamingUtils.buildRtpUrl('127.0.0.1', 5004);
+     * // 'rtp://127.0.0.1:5004'
+     *
+     * // Multicast
+     * const url2 = StreamingUtils.buildRtpUrl('239.0.0.1', 5004, { ttl: 64 });
+     * // 'rtp://239.0.0.1:5004?ttl=64'
+     * ```
+     */
+    static buildRtpUrl(host, port, options) {
+        let url = `rtp://${host}:${port}`;
+        if (options && Object.keys(options).length > 0) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(options)) {
+                if (value !== undefined) {
+                    params.append(key, String(value));
+                }
+            }
+            const queryString = params.toString();
+            if (queryString) {
+                url += `?${queryString}`;
+            }
+        }
+        return url;
+    }
+    /**
+     * Extract all UDP ports from SDP content
+     *
+     * @param sdp - SDP content string
+     *
+     * @returns Array of port numbers (one per stream)
+     *
+     * @example
+     * ```typescript
+     * import { StreamingUtils } from 'node-av/api';
+     *
+     * const sdp = `v=0
+     * o=- 0 0 IN IP4 127.0.0.1
+     * s=Test Stream
+     * c=IN IP4 127.0.0.1
+     * t=0 0
+     * m=audio 5004 RTP/AVP 111
+     * a=rtpmap:111 OPUS/48000/2
+     * m=video 5006 RTP/AVP 96
+     * a=rtpmap:96 H264/90000`;
+     *
+     * const ports = StreamingUtils.extractPortsFromSDP(sdp);
+     * console.log(ports); // [5004, 5006]
+     * ```
+     */
+    static extractPortsFromSDP(sdp) {
+        const ports = [];
+        const lines = sdp.split('\n');
+        for (const line of lines) {
+            if (line.startsWith('m=')) {
+                // m=audio 5004 RTP/AVP 111
+                // m=video 5006 RTP/AVP 96
+                const match = /m=\w+\s+(\d+)/.exec(line);
+                if (match) {
+                    ports.push(parseInt(match[1], 10));
+                }
+            }
+        }
+        return ports;
+    }
+}
+//# sourceMappingURL=streaming.js.map

package/dist/api/utilities/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../../../src/api/utilities/streaming.ts"],"names":[],"mappings":"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"}

package/dist/api/utilities/timestamp.d.ts

@@ -0,0 +1,193 @@
+import type { AVRounding } from '../../constants/index.js';
+import type { IRational } from '../../lib/types.js';
+/**
+ * Timestamp and time base utilities.
+ *
+ * Provides static methods for converting, rescaling, and comparing timestamps.
+ * These utilities are essential for working with different time bases in
+ * multimedia streams.
+ *
+ * @example
+ * ```typescript
+ * import { TimestampUtils } from 'node-av';
+ * import { AV_ROUND_NEAR_INF } from 'node-av/constants';
+ *
+ * // Convert timestamp to string representations
+ * const pts = 450000n;
+ * console.log(TimestampUtils.toString(pts));                    // "450000"
+ *
+ * const timebase = { num: 1, den: 90000 };
+ * console.log(TimestampUtils.toTimeString(pts, timebase));      // "5.000000"
+ *
+ * // Rescale between time bases
+ * const srcTb = { num: 1, den: 90000 };
+ * const dstTb = { num: 1, den: 1000 };
+ * const rescaled = TimestampUtils.rescale(pts, srcTb, dstTb);
+ * console.log(rescaled);                                         // 5000n
+ * ```
+ */
+export declare class TimestampUtils {
+    private constructor();
+    /**
+     * Convert timestamp to string.
+     *
+     * Converts a timestamp value to its string representation.
+     * Handles special values like AV_NOPTS_VALUE.
+     * Direct mapping to av_ts2str()
+     *
+     * @param ts - Timestamp value (bigint or number), or null
+     *
+     * @returns String representation
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     * import { AV_NOPTS_VALUE } from 'node-av/constants';
+     *
+     * console.log(TimestampUtils.toString(12345n));        // "12345"
+     * console.log(TimestampUtils.toString(AV_NOPTS_VALUE)); // "NOPTS"
+     * console.log(TimestampUtils.toString(null));          // "NOPTS"
+     * ```
+     */
+    static toString(ts: bigint | number | null): string;
+    /**
+     * Convert timestamp to time string.
+     *
+     * Converts a timestamp to a time string in seconds using the provided time base.
+     * Direct mapping to av_ts2timestr()
+     *
+     * @param ts - Timestamp value
+     *
+     * @param timeBase - Time base for conversion
+     *
+     * @returns Time string in seconds with decimal places
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * const pts = 450000n;
+     * const timebase = { num: 1, den: 90000 }; // 90kHz
+     *
+     * console.log(TimestampUtils.toTimeString(pts, timebase));     // "5.000000"
+     * console.log(TimestampUtils.toTimeString(90000n, timebase));  // "1.000000"
+     * ```
+     */
+    static toTimeString(ts: bigint | number | null, timeBase: IRational): string;
+    /**
+     * Compare timestamps from different time bases.
+     *
+     * Compares two timestamps that may have different time bases.
+     * Direct mapping to av_compare_ts()
+     *
+     * @param tsA - First timestamp
+     *
+     * @param tbA - Time base of first timestamp
+     *
+     * @param tsB - Second timestamp
+     *
+     * @param tbB - Time base of second timestamp
+     *
+     * @returns -1 if tsA < tsB, 0 if equal, 1 if tsA > tsB
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Compare timestamps from different time bases
+     * const pts1 = 90000n;
+     * const tb1 = { num: 1, den: 90000 };  // 1 second in 90kHz
+     *
+     * const pts2 = 1000n;
+     * const tb2 = { num: 1, den: 1000 };   // 1 second in 1kHz
+     *
+     * const result = TimestampUtils.compare(pts1, tb1, pts2, tb2);
+     * console.log(result); // 0 (equal - both represent 1 second)
+     * ```
+     */
+    static compare(tsA: bigint | number | null, tbA: IRational, tsB: bigint | number | null, tbB: IRational): number;
+    /**
+     * Rescale timestamp from one time base to another.
+     *
+     * Converts a timestamp from source time base to destination time base.
+     * Uses AV_ROUND_NEAR_INF rounding.
+     * Direct mapping to av_rescale_q()
+     *
+     * @param a - Timestamp to rescale
+     *
+     * @param bq - Source time base
+     *
+     * @param cq - Destination time base
+     *
+     * @returns Rescaled timestamp
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Convert from 90kHz to milliseconds
+     * const pts = 450000n;
+     * const srcTb = { num: 1, den: 90000 };
+     * const dstTb = { num: 1, den: 1000 };
+     *
+     * const rescaled = TimestampUtils.rescale(pts, srcTb, dstTb);
+     * console.log(rescaled); // 5000n (5000 milliseconds = 5 seconds)
+     * ```
+     */
+    static rescale(a: bigint | number | null, bq: IRational, cq: IRational): bigint;
+    /**
+     * Rescale with specified rounding.
+     *
+     * Rescales a value with explicit rounding mode.
+     * More general than rescale() as it doesn't use time bases.
+     * Direct mapping to av_rescale_rnd()
+     *
+     * @param a - Value to rescale
+     *
+     * @param b - Multiplier
+     *
+     * @param c - Divisor
+     *
+     * @param rnd - Rounding mode
+     *
+     * @returns Rescaled value: a * b / c
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     * import { AV_ROUND_UP, AV_ROUND_DOWN } from 'node-av/constants';
+     *
+     * // Scale with different rounding modes
+     * const value = 100n;
+     * const mul = 3n;
+     * const div = 7n;
+     *
+     * const roundUp = TimestampUtils.rescaleRounded(value, mul, div, AV_ROUND_UP);
+     * const roundDown = TimestampUtils.rescaleRounded(value, mul, div, AV_ROUND_DOWN);
+     *
+     * console.log(roundUp);   // 43n (rounds up)
+     * console.log(roundDown); // 42n (rounds down)
+     * ```
+     */
+    static rescaleRounded(a: bigint | number, b: bigint | number, c: bigint | number, rnd: AVRounding): bigint;
+    /**
+     * Sleep for specified microseconds.
+     *
+     * Sleeps for the specified number of microseconds.
+     * Direct mapping to av_usleep()
+     *
+     * @param usec - Microseconds to sleep
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Sleep for 100 milliseconds
+     * TimestampUtils.sleep(100000);
+     *
+     * // Sleep for 1 second
+     * TimestampUtils.sleep(1000000);
+     * ```
+     */
+    static sleep(usec: number): void;
+}