source: main/trunk/model-interfaces-dev/atea/js/asr/TranscribeService.js@ 35259

/**
 * @file Defines components that are used to interact with the transcription proxy servlet.
 * @author Carl Stephens
 */

/**
 * The transcription object returned from our transcription endpoint.
 * 
 * @typedef {Object} TranscriptionModel
 * @property {String} file_name The name of the file that was transcribed.
 * @property {String} log A note of how the transcription was processed.
 * @property {{char: String, confidence: Number, start_time: Number}[]} metadata The character metadata.
 * @property {boolean} success A value indicating if the transcription was successful or not.
 * @property {String} transcription The transcription.
 */

class TranscribeError
{
    /**
     * Initialises a new instance of the {@link TranscribeError} object.
     * 
     * @param {Number | undefined} statusCode The status code of the error.
     * @param {String | undefined} statusMessage The status message.
     */
    constructor(statusCode, statusMessage)
    {
        this.statusCode = statusCode;
        this.statusMessage = statusMessage;
    }
}

/**
 * A service that uploads audio files in a multipart request to the Korero Maori API Interface servlet, and interprets the result.
 */
class TranscribeService
{
    constructor()
    {
        /** @type {String} The URL to which query POST requests should be made. */
        this.queryUrl = "/gs3-koreromaori/transcribe";

        /** @type {Number} The maximum number of files which can be transcribed in one request to the API. */
        this.MAX_BATCH_COUNT = 3;

        /** @type {Number} The soft upper limit on how many bytes can be submitted in one request. */
        this.BATCH_BYTE_LIMIT = 5242880; // 5 MiB
    }

    /**
     * Performs chunked queries to transcribe the given audio files, returning the data in iterations.
     * Data is chunked according to which ever occurs first:
     * A maximum of three files per request, or;
     * A maximum of 5 MiB before chunking.
     * 
     * @param {FileList} files The files to upload
     * @returns {AsyncGenerator<TranscriptionModel[]>} The transcribed audio files.
     */
    async* batchTranscribeFiles(files)
    {
        let filesToSubmit = [];
        let fileCounter = 0;
        let byteCounter = 0;

        for (let file of files)
        {
            if (fileCounter == this.MAX_BATCH_COUNT || byteCounter > this.BATCH_BYTE_LIMIT) // 5 MiB
            {
                yield await this.transcribeFiles(filesToSubmit);
                filesToSubmit = [];
                byteCounter = 0;
                fileCounter = 0;
            }

            filesToSubmit[fileCounter++] = file;
            byteCounter += file.size;
        }

        if (filesToSubmit.length > 0) {
            yield await this.transcribeFiles(filesToSubmit);
        }
    }

    /**
     * Performs a query to transcribe the given audio files.
     * 
     * @param {FileList | File[]} files The files to upload.
     * @returns {Promise<TranscriptionModel[]>} The transcribed audio file.
     */
    async transcribeFiles(files)
    {
        const that = this;
        const formData = new FormData();

        let audioFileKeys = "";
        for (let i = 0; i < files.length; i++)
        {
            const f = files[i];
            const key = "audioFile" + i;

            formData.append(key, f, f.name);
            audioFileKeys += key + "|";
        }
        formData.append("audioFileKeys", audioFileKeys);

        let response;
        try
        {
            response = await fetch
            (
                that.queryUrl, 
                {
                    method: "POST",
                    body: formData
                }
            );
        }
        catch (e)
        {
            console.error(`Transcription failed with reason ${e}`);
            throw new TranscribeError(undefined, undefined);
        }

        if (!response.ok)
        {
            console.error(`Transcription API failed with status ${response.status} and message ${response.statusText}`);
            throw new TranscribeError(response.status, response.statusText);
        }
        
        return await response.json();
    }

    // OBSOLETE. Kept for reference purposes on XMLHttpRequest usage. See doFetchUpload instead.
    //
    // Based on https://stackoverflow.com/questions/2320069/jquery-ajax-file-upload
    // doUpload(files, resultCallback, progressCallback)
    // {
    //     let that = this;
    //     let formData = new FormData();

    //     let audioFileKeys = "";
    //     for (let f of files)
    //     {
    //         formData.append(f.name, f, f.name);
    //         audioFileKeys += f.name + "|";
    //     }
    //     formData.append("audioFileKeys", audioFileKeys);

    //     $.ajax({
    //         type: "POST",
    //         url: this.queryUrl,
    //         xhr: function ()
    //         {
    //             var myXhr = $.ajaxSettings.xhr();
    //             if (myXhr.upload && progressCallback != undefined)
    //             {
    //                 myXhr.upload.addEventListener("progress", progressCallback, false);
    //             }
    //             return myXhr;
    //         },
    //         success: function (data)
    //         {
    //             resultCallback(data);
    //         },
    //         error: function (error)
    //         {
    //             console.error("Failed to upload file via AJAX POST: " + error);
    //         },
    //         async: true,
    //         data: formData,
    //         cache: false,
    //         contentType: false,
    //         processData: false,
    //         timeout: 60000 // TODO: Consider if we need a longer timeout.
    //     });
    // }
}