@cesdk/engine 1.59.0-nightly.20250825 → 1.59.0

package/index.d.ts

@@ -1148,6 +1148,33 @@ export declare type AudioExportOptions = {
  */
 export declare type AudioMimeType = Extract<MimeType_2, 'audio/wav'>;
 
+/**
+ * Information about a single audio track from a video.
+ * This interface provides comprehensive metadata about audio tracks,
+ * including codec information, technical specifications, and track details.
+ * @public
+ */
+export declare interface AudioTrackInfo {
+    /** The codec string */
+    audioCodec: string;
+    /** The number of audio channels */
+    channels: number;
+    /** The audio sample rate */
+    sampleRate: number;
+    /** Duration of the audio track in seconds */
+    audioDuration: number;
+    /** The number of audio packets (matches the number of encoded chunks) */
+    numAudioPackets: number;
+    /** The number of audio frames */
+    numAudioFrames: number;
+    /** Optional track name/label if available in metadata */
+    trackName: string;
+    /** Track index in the container */
+    trackIndex: number;
+    /** Track language code (ISO 639-2T format: "und", "eng", "deu", etc.) */
+    language: string;
+}
+
 /**
  * Represents the blend mode of a layer or effect.
  *
@@ -1535,6 +1562,84 @@ export declare class BlockAPI {
      * @returns The created fill's handle.
      */
     createFill(type: FillType): DesignBlockId;
+    /**
+     * Gets the number of available audio tracks in a video fill block.
+     *
+     * ```javascript
+     * const trackCount = engine.block.getAudioTrackCountFromVideo(videoBlock);
+     * console.log(`Video has ${trackCount} audio tracks`);
+     * ```
+     *
+     * @category Block Audio
+     * @param videoFillBlock - The video fill block to examine.
+     * @returns The number of audio tracks.
+     * @throws Will throw an error if the block is not a video fill or has no audio.
+     */
+    getAudioTrackCountFromVideo(videoFillBlock: DesignBlockId): number;
+    /**
+     * Creates a new audio block by extracting a specific audio track from a video fill block.
+     *
+     * ```javascript
+     * // Extract the first audio track (usually the main mix)
+     * const audioBlock = engine.block.createAudioFromVideo(videoFillBlock, 0);
+     *
+     * // Extract a specific track and mute the original video
+     * const dialogueTrack = engine.block.createAudioFromVideo(videoFillBlock, 1, true);
+     * ```
+     *
+     * @category Block Audio
+     * @param videoFillBlock - The video fill block to extract audio from.
+     * @param trackIndex - The index of the audio track to extract (0-based).
+     * @param muteOriginalVideo - If true, mutes the audio of the original video fill block (default: false).
+     * @returns The handle of the newly created audio block with extracted audio from the specified track.
+     * @throws Will throw an error if the track index is invalid or the block has no audio.
+     */
+    createAudioFromVideo(videoFillBlock: DesignBlockId, trackIndex: number, muteOriginalVideo?: boolean): DesignBlockId;
+    /**
+     * Creates multiple audio blocks by extracting all audio tracks from a video fill block.
+     *
+     * ```javascript
+     * // Extract all audio tracks from a video
+     * const audioBlocks = engine.block.createAudiosFromVideo(videoFillBlock);
+     * console.log(`Created ${audioBlocks.length} audio blocks`);
+     *
+     * // Extract all tracks and mute the original video
+     * const audioBlocks = engine.block.createAudiosFromVideo(videoFillBlock, true);
+     * ```
+     *
+     * @category Block Audio
+     * @param videoFillBlock - The video fill block to extract audio from.
+     * @param muteOriginalVideo - If true, mutes the audio of the original video fill block (default: false).
+     * @returns An array of handles for the newly created audio blocks, one per track.
+     * @throws Will throw an error if the block has no audio or extraction fails.
+     */
+    createAudiosFromVideo(videoFillBlock: DesignBlockId, muteOriginalVideo?: boolean): DesignBlockId[];
+    /**
+     * Gets information about all audio tracks from a video fill block.
+     *
+     * ```javascript
+     * // Get information about all audio tracks
+     * const trackInfos = engine.block.getAudioInfoFromVideo(videoFillBlock);
+     * console.log(`Video has ${trackInfos.length} audio tracks`);
+     *
+     * // Display track information
+     * trackInfos.forEach((track, index) => {
+     *   console.log(`Track ${index}: ${track.channels} channels, ${track.sampleRate}Hz, ${track.language}`);
+     * });
+     *
+     * // Use track info to create audio blocks selectively
+     * const englishTracks = trackInfos.filter(track => track.language === 'eng');
+     * const audioBlocks = englishTracks.map(track =>
+     *   engine.block.createAudioFromVideo(videoFillBlock, track.trackIndex)
+     * );
+     * ```
+     *
+     * @category Block Audio
+     * @param videoFillBlock - The video fill block to analyze for audio track information.
+     * @returns An array containing information about each audio track.
+     * @throws Will throw an error if the block is not a video fill or has no audio.
+     */
+    getAudioInfoFromVideo(videoFillBlock: DesignBlockId): AudioTrackInfo[];
     /**
      * Creates new caption blocks from an SRT or VTT file URI.
      *
@@ -5695,6 +5800,12 @@ export declare type DesignBlockTypeShorthand = 'scene' | 'stack' | 'camera' | 'p
  */
 export declare type DesignUnit = 'Pixel' | 'Millimeter' | 'Inch';
 
+/**
+ * Information about a single audio track from a video.
+ * This interface provides comprehensive metadata about audio tracks,
+ * including codec information, technical specifications, and track details.
+ * @public
+ */
 /**
  * Options for configuring drop shadow effects on blocks.
  * @public