Speechmatics Transcription

Speechmatics Transcriptions module for ProcessWire

Module for https://www.processwire.com/
Copyright (c) 2026 Commonwealth of Australia

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

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)

Installing

Create a Speechmatics API key

Before using this module, create a Speechmatics account and generate an API key.

Keep a copy of the API key as it will be required during module configuration.

Installing the module in ProcessWire

This module is installed just like any other ProcessWire module: copy or clone this module to your /site/modules/ directory, log in, go to Admin > Modules, click "Check for new modules", and install the "Speechmatics Transcription" module.

How it works

• An editor uploads an audio or video file to a configured file field
• The module detects the new media file on page save
• The file is submitted to the Speechmatics transcription API
• Speechmatics processes the media and generates captions
• A WebVTT (.vtt) caption file is returned via a webhook
• The caption file is automatically saved into the configured ProcessWire file field
• 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

Hooks

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();
});

Error Handling

If a transcription request cannot be completed:

• Superusers will see detailed error information
• Non-superuser editors will see a simplified editor-friendly message
• Authentication failures are reported during configuration
• Failed transcription requests are logged through ProcessWire's standard logging system
• Invalid or unsupported media files are skipped and logged

Notes

• Processing time depends on media duration and Speechmatics API availability
• Caption generation requires an active internet connection
• Speechmatics API usage charges may apply according to your subscription
• Generated caption files are stored in standard WebVTT format for maximum compatibility
• A history of jobs will be available via the Speechmatics dashboard. Jobs are kept for 7 days by default.