Speechmatics Transcriptions module for ProcessWire

[AAD Web Team]

Automatically generate captions and transcripts for audio and video files using the Speechmatics API.

You can find the module on Github, or in the ProcessWire modules directory (submission pending).

A ProcessWire CMS module that watches selected file fields, submits supported media files to Speechmatics for transcription, and automatically saves the resulting WebVTT .vtt caption files back into ProcessWire.

Once configured, editors upload audio or video files as usual. The module handles the transcription workflow in the background and stores the returned caption files in a set field, ready for use.

Why use this module?

• Automatic caption generation for uploaded media
• Supports both audio and video files
• Bring your own Speechmatics API key
• Stores standard WebVTT (.vtt) caption files
• Minimal editor involvement once configured
• Allows for caption files to be tagged as a 'draft'
• Improves accessibility and compliance for your media
• Integrates directly into existing ProcessWire content workflows

Requirements

• PHP 7.3+
• ProcessWire 3.0.244+
• FFmpeg installed on the server
• A Speechmatics account and API key
• An allowed connection between your web server and the Speechmatics API endpoint (both ways, to send the file and recieve a callback)

How it works

1. An editor uploads an audio or video file to a configured file field
2. The module detects the new media file on page save
3. The file is submitted to the Speechmatics transcription API
4. Speechmatics processes the media and generates captions
5. A WebVTT (.vtt) caption file is returned via a webhook
6. The caption file is automatically saved into the configured ProcessWire file field
7. The captions are available, optionally tagged to indiciate they have not been reviewed yet

Configuration

• URL to the Speechmatics API
  Allows you to change the URL used for the Speechmatics API, usually the default is fine.
• Speechmatics API Key
  Enter your Speechmatics API key.
• The module will validate the key when the configuration is saved and display an error if it cannot authenticate with the Speechmatics API.
• Callback URL
  Specify the URL in which you would like to recieve the callback from Speechmatics once a job is complete and ready to import.
  On saving, the route will be tested to ensure it does not conflict with an existing page.
• Path to FFmpeg
  The path to run the FFmpeg CLI tool. This is used to strip audio from video files to save bandwidth communicating with the API.
• Model
  Allows you to choose which Speechmatics model to use, between 'Standard' and 'Enhanced'.
• Language
  The language that content is in. See a full list of ISO language codes. Only 2 letter codes are supported, use en instead of en-US for example.
• Output Locale
  Language locale to be used, normally specified as an ISO language code.
  See a full list of ISO language codes. Full length language codes are supported, like en-US.
• Content File Field
  Select which field stores the audio/video file to be sent to Speechmatics for transcription. Only files uploaded to this field will be processed.
• Caption Output Field
  Select the file field that should receive generated .vtt caption files.
  The module will automatically save caption files here once transcription has completed.
• Caption File Field
  Select which field to store the .vtt caption file from Speechmatics.
• Tags to skip
  Allows you to choose which files are skipped from being transcribed. Can be helpful to skip processing files that are have no dialog, or have another reason to be skipped.
• Tag to give files that have no dialog
  Choose what tag is given to media files that have no transcribable dialog detected. Handy for ensuring they are not sent to Speechmatics for repeat processing needlessly.
• Tag to give caption files that have been added
  Choose a tag to give any captions files that have been added. handy for tracking drafts that need a review before being used.
• Phonetic "sounds like" suggestions
  Allow a list of custom words to be added for each transcription job. This helps when a specific word is not recognised during transcription.
  Format as a comma seperated list, where the first phrase/word is the correct spelling and the following words/phrases are what it may sound like. Every new line is a new word.
  Example: gnocchi,nyohki,nokey,nochi
  The first word is the intended word, following are phonetic phrases the word may sound like.

Using this module
You can hook the SpeechmaticsTranscription::saveCaptionsToPage to trigger actions when captions are being returned and saved to a page.

This can be useful for triggering notifications when captions are ready, such as an email using WireMail.

/**
 * Example of a notification to the author whenever
 * captions have been added to a page
 */
wire()->addHookAfter('SpeechmaticsTranscription::saveCaptionsToPage', function (HookEvent $e) {
    $page = $e->arguments(0);

    if ($page->id === 0) {
        return; // null page, cancel notification
    }

    // Email body
    $emailBody = <<<HTML
        <p>New automated captions have been uploaded for the <em>$page->title</em> page
        on the <a href='$page->httpUrl'>$page->title</a> page.</p>
        <p>Edit: <a href='{$page->editUrl(true)}'>$page->httpUrl</a></p>
        <p>Please review the draft caption file, make any edits necessary and remove the ‘draft’ tag when they are
        ready to use.</p>
    HTML;

    // Send email using WireMail
    wire('mail')
        ->to('firstname.lastname@example.com')
        ->from('noreply@example.com')
        ->subject("A page has new captions to review")
        ->bodyHTML($emailBody)
        ->send();
});

Let us know how you go using this module! We've found it rather useful.