ennuizel.d.ts

/*
 * Copyright (c) 2021 Yahweasel
 *
 * Permission to use, copy, modify, and/or distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
 * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
 * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */

/*
 * This file defines the API for plugins
 *
 * Note that more functionality is exposed than is documented in this file.
 * ANYTHING THAT IS NOT DOCUMENTED IN THIS FILE IS NOT PART OF THE PUBLIC API
 * AND IS SUBJECT TO CHANGE AT ANY TIME. Only use the listed functionality
 * here.
 */

declare namespace ennuizel {
    type TypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array |
                      Int32Array | Uint32Array | Float32Array | Float64Array;

    /**
     * The frame format given by libav.js
     */
    interface LibAVFrame {
        /**
         * The actual data. Note that in real libav.js frames, this could be an
         * array of typed arrays, if it's planar, but Ennuizel only handles
         * non-planar data.
         */
        data: TypedArray;

        /**
         * The sample rate.
         */
        sample_rate: number;

        /**
         * The sample format.
         */
        format: number;

        /**
         * The number of channels. Either this or channel_layout should be set.
         */
        channels?: number;

        /**
         * The layout of the channels. Either this or channels should be set.
         */
        channel_layout?: number;

        /**
         * The number of samples. This does not have to be set, and can be divined
         * from the length of data.
         */
        nb_samples?: number;

        /**
         * Not part of original libav.js, but provided by streams for tracks.
         */
        node?: unknown;
    }

    /**
     * A ReadableStream paired with the ability to push back data. Use
     * Ennuizel.EZStream, not ennuizel.EZStream.
     */
    class EZStream<R> {
        /**
         * Create an EZStream.
         * @param readableStream  The underlying ReadableStream.
         */
        constructor(readableStream: ReadableStream<R>);

        /**
         * Read an element. Returns null if the stream has ended.
         */
        read(): Promise<R>;

        /**
         * Cancel the stream.
         */
        cancel(): void;

        /**
         * Push this chunk back. It will be returned eagerly by the next read.
         */
        push(chunk: R): void;

        /**
         * Is this stream finished?
         */
        isDone(): boolean;
    }

    /**
     * An Ennuizel project. Only one project can be loaded at a time, so there
     * should only ever be one instance of this type at a time.
     */
    interface Project {
        /**
         * Delete this project.
         */
        del(): Promise<void>;

        /**
         * Internal ID for the project.
         */
        readonly id: string;

        /**
         * Name of the project.
         */
        readonly name: string;

        /**
         * Create a new audio track. The track is added to the project if it's not temporary.
         * @param opts  Options for creating the track.
         */
        newAudioTrack(opts?: {name?: string, temp?: boolean}): Promise<track.AudioTrack>;

        /**
         * Create a new caption track.
         * @param opts  Options for creating the track.
         */
        newCaptionTrack(opts?: {name?: string, temp?: boolean}): Promise<captions.CaptionTrack>;

        /**
         * Add a track that's already been created.
         * @param track  The track to add.
         */
        addTrack(track: track.Track): Promise<void>;

        /**
         * Remove a track. The track is deleted even if it was never actually added
         * to the project, so this is also the way to delete a track.
         * @param track  The track to remove.
         */
        removeTrack(track: track.Track): Promise<void>;
    }

    // Audio tracks
    namespace track {
        /**
         * A unifying track type for all tracks.
         */
        interface Track {
            /**
             * Return the type of this track.
             */
            type(): number;

            /**
             * The name for this track.
             */
            readonly name: string;
        }

        interface AudioTrack extends Track {
            /**
             * Append data from a stream of raw data. The chunks must be LibAVFrames.
             * If they don't have the correct format, sample rate, or channel count,
             * they will be filtered, but this is only applied after the first has
             * arrived, so the caller can change the track properties before then.
             * @param rstream  The stream to read from.
             */
            append(rstream: EZStream<LibAVFrame>): Promise<void>;

            /**
             * Append a single chunk of raw data.
             * @param data  The single chunk of data.
             */
            appendRaw(data: TypedArray): Promise<void>;

            /**
             * Get the duration, in seconds, of this track.
             */
            duration(): number;

            /**
             * Get the number of samples in this track. This is, in essence, the
             * duration in samples times the number of channels.
             */
            sampleCount(): number;

            /**
             * Get this data as a ReadableStream. Packets are sent roughly in libav.js
             * format, but with the AudioData node specified in a `node` field.
             * @param opts  Options. In particular, you can set the start and end time
             *              here.
             */
            stream(opts?: {
                start?: number;
                end?: number;
                keepOpen?: boolean;
            }): ReadableStream<any>;

            /**
             * Overwrite a specific range of data from a ReadableStream. The stream
             * must give TypedArray chunks, and must be of the same length as is being
             * overwritten. A stream() with keepOpen and an overwrite() with closeTwice
             * creates an effective filter.
             * @param data  Input data.
             * @param opts  Options. In particular, you can set the start and end time
             *              here.
             */
            overwrite(data: EZStream<LibAVFrame>, opts?: {
                start?: number;
                end?: number;
                closeTwice?: boolean;
            }): Promise<void>;

            /**
             * Replace a segment of audio data with the audio data from another track.
             * The other track will be deleted. Can clip (by not giving a replacement)
             * or insert (by replacing no time) as well.
             * @param start  Start time, in seconds.
             * @param end  End time, in seconds.
             * @param replacement  Track containing replacement data, which must be in
             *                     the same format, sample rate, number of tracks.
             */
            replace(start: number, end: number, replacement: AudioTrack): Promise<void>;

            /**
             * Format of samples in this track, in libav format code.
             */
            format: number;

            /**
             * Sample rate of this track.
             */
            sampleRate: number;

            /**
             * Number of channels in this track.
             */
            channels: number;
        }
    }

    // Caption tracks
    namespace captions {
        /**
         * Vosk-style caption data.
         */
        interface VoskWord {
            /**
             * The actual word represented.
             */
            word: string;

            /**
             * Start time.
             */
            start: number;

            /**
             * End time.
             */
            end: number;

            /**
             * Confidence (optional).
             */
            conf?: number;
        }

        /**
         * A caption track. A CaptionTrack is stored in an array of CaptionDatas, each
         * of which is a "line" of caption words, associated with their HTML nodes. The
         * CaptionTrack itself holds a link to the associated AudioTrack by ID, if
         * there is one. CaptionTracks are stored as caption-track-id.
         */
        interface CaptionTrack extends track.Track {
            /**
             * Append data from a stream of raw data. The chunks must be arrays of
             * VoskWords.
             * @param rstream  The stream to read from.
             */
            append(rstream: EZStream<VoskWord[]>): Promise<void>;

            /**
             * Append chunks of raw data.
             * @param lines  Chunks of data (lines of vosk words).
             * @param opts  Other options, really only intended to be used by append.
             */
            appendRaw(lines: VoskWord[][], opts?: {
                noSave?: boolean
            }): Promise<void>;

            /**
             * Get this data as a ReadableStream. Packets are set as lines (arrays of
             * VoskWords).
             * @param opts  Options. In particular, you can set the start and end time
             *              here.
             */
            stream(opts?: {
                start?: number;
                end?: number;
            }): ReadableStream<VoskWord[]>;

            /**
             * Replace a segment of caption data with the caption data from another
             * track. The other track will be deleted. Can clip (by not giving a
             * replacement) or insert (by replacing no time) as well.
             * @param start  Start time, in seconds.
             * @param end  End time, in seconds.
             * @param replacement  Track containing replacement data.
             */
            replace(start: number, end: number, replacement: CaptionTrack): Promise<void>;

            /**
             * Convert this track to WebVTT.
             */
            toVTT(): string;

            /**
             * Display name for this track.
             */
            readonly name: string;

            /**
             * The associated audio track.
             */
            readonly audioTrack: string;
        }
    }

    namespace filters {
        /**
         * A custom (presumably non-FFmpeg) filter, provided by a plugin.
         */
        interface CustomFilter {
            /**
             * User-visible name for the filter. May include underscores for
             * hotkeyability, but beware overlaps.
             */
            name: string;

            /**
             * Function to run to perform the filter *from the UI*. If you want an
             * automated filter, expose it as part of your plugin API.
             */
            filter: (d: ui.Dialog) => Promise<void>;
        }

        interface Filters {
            /**
             * Convert this LibAVFrame stream to the desired sample rate, format, and
             * channel count.
             * @param stream  Input LibAVFrame stream.
             * @param sampleRate  Desired sample rate.
             * @param format  Desired sample format.
             * @param channels  Desired channel count.
             * @param opts  Other options.
             */
            resample(
                stream: EZStream<LibAVFrame>, sampleRate: number,
                format: number, channels: number, opts?: {
                    fs?: string,
                    reframe?: boolean
                }
            ): Promise<ReadableStream<LibAVFrame>>;

            /**
             * Create a stream to apply the given libav filter, described by a filter
             * string.
             * @param stream  The input stream.
             * @param fs  The filter string.
             */
            ffmpegStream(
                stream: EZStream<LibAVFrame>, fs: string
            ): Promise<ReadableStream<LibAVFrame>>;

            /**
             * Apply a filter function to a selection.
             * @param ff  The filter function.
             * @param changesDuration  Set if this filter changes duration, so the process
             *                         must use a temporary track.
             * @param sel  The selection to filter.
             * @param d  (Optional) The dialog in which to show the status, if applicable.
             *           This dialog will *not* be closed.
             */
            selectionFilter(
                ff: (x: EZStream<LibAVFrame>) => Promise<ReadableStream<LibAVFrame>>,
                changesDuration: boolean, sel: select.Selection, d: ui.Dialog
            ): Promise<void>;

            /**
             * Register a custom filter.
             * @param filter  The filter.
             */
            registerCustomFilter(filter: CustomFilter): void;

            /**
             * Mix the selected tracks into a new track. Note that the track is
             * *not* automatically added to the project.
             * @param sel  The selection to mix.
             * @param d  (Optional) The dialog in which to show the status, if applicable.
             *           This dialog will *not* be closed.
             * @param opts  Other options.
             */
            mixTracks(
                sel: select.Selection, d: ui.Dialog, opts?: {
                    preFilter?:
                        (x: EZStream<LibAVFrame>) =>
                        Promise<ReadableStream<LibAVFrame>>,
                    postFilter?:
                        (x: EZStream<LibAVFrame>) =>
                        Promise<ReadableStream<LibAVFrame>>
                }
            ): Promise<track.Track>;
        }
    }

    // Named with two t's since "export" is reserved
    namespace exportt {
        /**
         * Format options for exporting.
         */
        interface ExportOptionsBase {
            /**
             * File format for export.
             */
            format: string;

            /**
             * Codec, in libav terms.
             */
            codec: string;

            /**
             * Sample format, in libav terms.
             */
            sampleFormat: number;

            /**
             * Sample rate, if not variable.
             */
            sampleRate?: number;

            /**
             * Filename extension, if not the same as format.
             */
            ext?: string;
        }

        /**
         * Per-export options for exporting.
         */
        interface ExportOptions extends ExportOptionsBase {
            /**
             * Filename prefix.
             */
            prefix: string;

            /**
             * Export all audio on selected tracks, not just selected audio.
             */
            allAudio?: boolean;

            /**
             * Export with the track name suffixed, even if only exporting one track.
             */
            suffixTrackName?: boolean;
        }
    }

    namespace avthreads {
        /**
         * Threaded libav access.
         */
        interface AVThreads {
            /**
             * Get a libav thread.
             */
            get(): Promise<any>;
        }
    }

    namespace util {
        /**
         * Utility functions.
         */
        interface Util {
            /**
             * Convert a time in seconds to a string timestamp.
             * @param s  The time.
             * @param min  Show only the fields needed.
             */
            timestamp(s: number, min?: boolean): string;
        }
    }

    namespace ui {
        /**
         * A dialog box.
         */
        interface Dialog {
            readonly box: HTMLElement;
        }

        /**
         * Options for opening a dialog.
         */
        interface DialogOptions {
            reuse?: Dialog;
            closeable?: boolean;
            keepOpen?: boolean;
            forceClose?: boolean;
        }

        /**
         * UI-related support for hotkeys.
         */
        interface Hotkeys {
            /**
             * Register a hotkey.
             * @param el  The element to click when the hotkey is pressed.
             * @param dialog  The dialog that the hotkey element is contained in, or null
             *                if it's not in a dialog.
             * @param key  The hot key itself.
             */
            registerHotkey(el: HTMLElement, dialog: ui.Dialog, key: string): void;

            /**
             * Unregister an element's hotkey.
             * @param el  The element.
             */
            unregisterHotkey(el: HTMLElement): void;

            /**
             * Make an element hotkeyable.
             * @param parent  The dialog that the element will be placed in (but note that
             *                it's the caller's job to place the element).
             * @param lbl  The label to be hotkey-ified. Will be passed back to the
             *             callback without its _.
             * @param callback  The function to actually create the element, and presumably
             *                  add it to the DOM (though you're free to do that later).
             */
            mk<T extends HTMLElement>(parent: ui.Dialog, lbl: string, callback: (lbl: string) => T): T;

            /**
             * Make a button with a hotkey.
             * @param parent  The dialog to place the button in.
             * @param lbl  The label for the button, including an _ before the letter
             *             representing the hotkey.
             * @param opts  Other options.
             */
            btn(parent: ui.Dialog, lbl: string, opts?: any): any;

            /**
             * Make a <label/> with a hotkey.
             * @param parent  The dialog to place the label in.
             * @param htmlFor  ID of the element that this label corresponds to.
             * @param lbl  Text of the label.
             * @param opts  Other options.
             */
            lbl(parent: ui.Dialog, htmlFor: string, lbl: string, opts?: any): any;
        }

        /**
         * The UI API.
         */
        interface UI {
            /**
             * Create a dialog box. If it's not closeable by the user, will close
             * automatically after the callback finishes.
             * @param callback  Function to call with the dialog box.
             * @param opts  Other options.
             */
            dialog<T>(
                callback: (x: Dialog, y: (x: HTMLElement) => unknown) => Promise<T>,
                opts?: DialogOptions
            ): Promise<T>;

            /**
             * Wrapper to quickly close a dialog box that's been kept open.
             * @param d  The dialog.
             */
            dialogClose(d: Dialog): Promise<void>;

            /**
             * Show a loading screen while performing some task.
             * @param callback  The callback to run while the loading screen is shown.
             */
            loading<T>(
                callback: (x:Dialog) => Promise<T>, opts?: DialogOptions
            ): Promise<T>;

            /**
             * Show an OK-only alert box.
             * @param html  innerHTML of the dialog.
             */
            alert(html: string): Promise<void>;

            /**
             * Load a library.
             * @param name  URL of the library to load.
             */
            loadLibrary(name: string): Promise<void>;

            /**
             * Make an element.
             * @param el  Element type.
             * @param parent  Element to add it to.
             * @param opts  Attributes to set.
             */
            mk(el: string, parent: HTMLElement, opts?: any): any;

            /**
             * Make a <button/>
             * @param parent  Element to add it to.
             * @param innerHTML  Text of the button.
             * @param opts  Other options.
             */
            btn(parent: HTMLElement, innerHTML: string, opts?: any): any;

            /**
             * Make a <label/>
             * @param parent  Element to add it to.
             * @param htmlFor  ID of the element this label corresponds to.
             * @param innerHTML  Text of the label.
             * @param opts  Other options.
             */
            lbl(parent: HTMLElement, htmlFor: string, innerHTML: string, opts?: any): any;
        }
    }

    namespace select {
        /**
         * Interface for the current selection.
         */
        interface Selection {
            range: boolean;
            start: number;
            end: number;
            tracks: track.Track[];
        }

        interface Select {
            /**
             * Get the current selection.
             */
            getSelection(): Selection;

            /**
             * Set the *time* of the selection. Don't set the end time to select all time.
             * @param start  Start time. Default 0.
             * @param end  Optional end time.
             */
            selectTime(start?: number, end?: number): Promise<void>;

            /**
             * Set the *tracks* currently selected. Does not update the time.
             * @param tracks  Array of tracks to select. May be empty.
             */
            selectTracks(tracks: track.Track[]): Promise<void>;

            /**
             * Select all selectables, and clear the range so that everything is selected.
             * @param opts  Selection options.
             */
            selectAll(opts?: {tracksOnly?: boolean}): Promise<void>;
        }
    }

    /**
     * The interface the plugin writer must provide.
     */
    interface Plugin {
        /**
         * Public name of the plugin.
         */
        name: string;

        /**
         * API name of the plugin.
         */
        id: string;

        /**
         * URL for *information* on the plugin (not for the plugin itself)
         */
        infoURL: string;

        /**
         * A full description of the plugin, in HTML.
         */
        description: string;

        /**
         * License information.
         */
        licenseInfo: string;

        /**
         * The plugin's URL. This is set by registerPlugin, not the plugin.
         */
        url?: string;

        /**
         * An optional load function to finish loading the plugin.
         */
        load?: () => Promise<void>;

        /**
         * A "wizard" (optional) to use in place of the normal Ennuizel flow.
         */
        wizard?: (d: ui.Dialog) => Promise<void>;

        /**
         * A wizard to be used *during* normal Ennuizel flow.
         */
        postWizard?: (project: Project) => Promise<void>;

        /**
         * The API for your plugin itself, which other plugins can use.
         */
        api?: any;
    }

    interface Ennuizel {
        /**
         * Call this to register your plugin. Every plugin *must* call this.
         * @param plugin  The plugin to register.
         */
        registerPlugin(plugin: Plugin): void;

        /**
         * Load a plugin by URL. Returns null if the plugin cannot be loaded.
         * @param url  The absolute URL (protocol optional) from which to load
         *             the plugin.
         */
        loadPlugin(url: string): Promise<Plugin>;

        /**
         * Get the loaded plugin with this ID, if such a plugin has been
         * loaded.
         * @param id  The ID of the plugin.
         */
        getPlugin(id: string): Plugin;

        /**
         * web-streams-polyfill's ReadableStream.
         */
        readonly ReadableStream: typeof ReadableStream;

        /**
         * And our own EZStream.
         */
        readonly EZStream: typeof EZStream;

        /**
         * The filter interface.
         */
        readonly filters: filters.Filters;

        /**
         * libav threading.
         */
        readonly avthreads: avthreads.AVThreads;

        /**
         * Utility functions.
         */
        readonly util: util.Util;

        /**
         * Hotkey interactions.
         */
        readonly hotkeys: ui.Hotkeys;

        /**
         * The UI.
         */
        readonly ui: ui.UI;

        /**
         * Selection.
         */
        readonly select: select.Select;

        /**
         * All supported track types.
         */
        readonly TrackType: {
            readonly Audio: number
        };

        /**
         * libav's sample formats.
         */
        readonly LibAVSampleFormat: {
            readonly U8: number,
            readonly S16: number,
            readonly S32: number,
            readonly FLT: number,
            readonly DBL: number,
            readonly U8P: number,
            readonly S16P: number,
            readonly S32P: number,
            readonly FLTP: number,
            readonly DBLP: number,
            readonly S64: number,
            readonly S64P: number
        };

        /**
         * Convert a (libav) format to its planar equivalent.
         * @param format  The input format, which may or may not be planar.
         */
        toPlanar(format: number): number;

        /**
         * Convert a (libav) format to its non-planar equivalent.
         * @param format  The input format, which may or may not be planar.
         */
        fromPlanar(format: number): number;

        /**
         * Create (and load) a new project with the given name.
         * @param name  Name for the project.
         */
        newProject(name: string): Promise<Project>;

        /**
         * Get the list of projects.
         */
        getProjects(): Promise<{id: string, name: string}[]>;

        /**
         * Load a project by ID.
         * @param id  The ID of the project to load.
         */
        loadProject(id: string): Promise<Project>;

        /**
         * Unload the current project from the user interface.
         */
        unloadProject(): Promise<void>;

        /**
         * Delete a project by ID. You can delete the *current* project with
         * its del() method.
         * @param id  ID of the project to delete.
         */
        deleteProjectById(id: string): Promise<void>;

        /**
         * Mark this as an undo point. If an undo is performed, it will stop
         * here. Should be done at any *UI* interaction that changes data.
         */
        undoPoint(): void;

        /**
         * Disable undo for the currently loaded project.
         */
        disableUndo(): Promise<void>;

        /**
         * Standard export formats.
         */
        readonly standardExports: {name: string, options: exportt.ExportOptionsBase}[];

        /**
         * Export selected audio with the given options.
         * @param opts  Export options.
         * @param sel  The selection to export.
         * @param d  A dialog in which to show progress, if desired.
         */
        exportAudio(
            opts: exportt.ExportOptions, sel: select.Selection, d: ui.Dialog
        ): Promise<unknown>;

        /**
         * Export an Audacity project from this audio.
         * @param opts  Export options. ext must be ogg.
         * @param sel  The selection to export.
         * @param d  A dialog in which to show progress, if desired.
         */
        exportAudacity(
            opts: exportt.ExportOptions, sel: select.Selection, d: ui.Dialog
        ): Promise<void>;

        /**
         * Export selected captions.
         * @param opts  Export options.
         * @param sel  The selection to export.
         * @param d  A dialog in which to show progress, if desired.
         */
        exportCaption(
            opts: {prefix: string}, sel: select.Selection, d: ui.Dialog
        ): Promise<void>;
    }
}

/**
 * The entry point for plugins.
 */
declare var Ennuizel: ennuizel.Ennuizel;