Upload

Use the UI or the API's /transcribe endpoint to upload audio and metadata files to folders configured to process audio with properties that match your upload data.

Audio may be uploaded:

  • As individual audio files.
  • Individually in a zip file.
  • In a batch of other audio files in a zip.
  • In a batch of other audio and JSON or XML metadata files in a zip.
  • With or without a file extension.

Uploaded files that are not supported are flagged as UNSUPPORTED in the folder's processing log.

Reprocessing transcripts

Previously processed JSON transcripts can be re-uploaded to any folder in V‑Spark using these methods without the ASR engine needing to re-transcribe the files.

To be reprocessed, the uploaded JSON transcript must have the same filename as the original audio file (except for the extension). For example, to reprocess the transcript for audio uploaded as File1.wav, you must upload a JSON transcript with the filename File1.json.

Filenames

The names of uploaded audio files and zip archives must adhere to the installation's filename requirements whether they are uploaded through the UI or with the API. By default, these characters are not permitted in uploaded filenames: #*<>:?/\|{}$!'`"=^

When uploading a zip file, only the name of the zip file is validated against these requirements; files inside the zip are not checked. This feature was first implemented with version 4.0.1-3 to help protect against remote code executions.

To disable filename validation, set the filename_validation system configuration setting to off. To define custom filename character requirements, specify a regular expression for the filename_validation_pattern system configuration setting.

Duplicate rejection

Files are not required to have unique names at a system level, but as of V‑Spark 4.2.0-1, individual folders may be configured to reject files with duplicate filenames. In either case, filenames should be unique as a best practice. Consider adding the file's timestamp, call ID, or a UUID to create a unique filename. Duplicate filenames make some processing take longer.

Note: Independently of the duplicate rejection setting, if two files with identical names are submitted to the same folder at the exact same second, only one of those files will be processed.

When a folder has the deduplication setting enabled, that folder will reject file uploads in the following scenarios:

  • A file is uploaded with the same name as a previously uploaded file.

  • A zip file contains a file with the same name as a previously uploaded file.

  • A zip file contains two or more files with the same name.

Filename-based deduplication may fail if the first file is still in the Job Manager queue waiting to be processed.

The entire zip file is rejected when a duplicate file is detected inside the zip. Duplicate file rejection for zip files nested inside other zip files is not supported. When folder-level deduplication causes a file to be rejected, V‑Spark generates a WARNING -level message in server.log and the Activity Log.

A request submitted to the /transcribe API endpoint with an invalid filename parameter fails and returns HTTP error code 422.

Metadata

To associate custom metadata uploads with the correct audio, the metadata and audio files must have the same name except for the extension.