Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

fix: record the transcription service's detected language on the recording and send it in the webhook completion payload as documented

Murtaza Nasire61fe900dd6a
diff --git a/docs/admin-guide/webhooks.md b/docs/admin-guide/webhooks.md
index ab9093dc..58d0825e 100644
--- a/docs/admin-guide/webhooks.md
+++ b/docs/admin-guide/webhooks.md
@@ -14,7 +14,7 @@ or programmatically via the `/api/v1/webhooks` API.
|---|---|---|
| `recording.created` | A recording row is created (upload arrived) | `recording_id`, `title`, `file_size`, `original_filename` |
| `recording.transcription.started` | Worker picks up a transcribe or reprocess-transcription job and the audio file is on disk | `recording_id`, `title` |
-| `recording.transcription.completed` | Transcription job finished successfully | `recording_id`, `title`, `audio_duration_seconds`, `transcription_duration_seconds` |
+| `recording.transcription.completed` | Transcription job finished successfully | `recording_id`, `title`, `language`, `audio_duration_seconds`, `transcription_duration_seconds` |
| `recording.transcription.failed` | Transcription failed permanently (retries exhausted) | `recording_id`, `title`, `error` |
| `recording.summary.completed` | Summary generated successfully | `recording_id`, `title`, `summarization_duration_seconds` |
| `recording.summary.failed` | Summary failed permanently | `recording_id`, `title`, `error` |
@@ -48,12 +48,20 @@ Every delivery is a `POST` with a JSON body shaped like:
"data": {
"recording_id": 9173,
"title": "Q3 planning",
+ "language": "en",
"audio_duration_seconds": 3624.7,
"transcription_duration_seconds": 212
}
}
```
+`language` is the language the transcription service reported for that recording,
+as an ISO 639-1 code. It reflects what was detected or used for that audio, not the
+user's current transcription-language preference. Fields are omitted when Speakr does
+not have a value, so `language` is absent for backends that report none, and for
+recordings transcribed before v0.10.6-alpha, which is when Speakr began storing it.
+
+
Headers:
| Header | Purpose |
diff --git a/src/init_db.py b/src/init_db.py
index 09595124..e5e1cbde 100644
--- a/src/init_db.py
+++ b/src/init_db.py
@@ -224,6 +224,11 @@ def _run_migrations(app, engine):
with _migration_section(app, failures, "recording, tag, speaker and processing columns"):
if add_column_if_not_exists(engine, 'recording', 'mime_type', 'VARCHAR(100)'):
app.logger.info("Added mime_type column to recording table")
+ # Detected transcription language (#386). Existing rows stay NULL:
+ # the audio would have to be re-transcribed to learn it, and the
+ # webhook simply omits the field when it is not known.
+ if add_column_if_not_exists(engine, 'recording', 'transcription_language', 'VARCHAR(20)'):
+ app.logger.info("Added transcription_language column to recording table")
if add_column_if_not_exists(engine, 'recording', 'audio_duration_seconds', 'FLOAT'):
app.logger.info("Added audio_duration_seconds column to recording table")
if add_column_if_not_exists(engine, 'recording', 'completed_at', 'DATETIME'):
diff --git a/src/models/recording.py b/src/models/recording.py
index a84a1b29..2f2533d8 100644
--- a/src/models/recording.py
+++ b/src/models/recording.py
@@ -25,6 +25,12 @@ class Recording(db.Model):
participants = db.Column(db.String(500))
notes = db.Column(db.Text)
transcription = db.Column(db.Text, nullable=True)
+ # Language the transcription service reported for THIS recording, as an
+ # ISO 639-1 code. Recorded at transcription time rather than read from the
+ # user's preference, which is a live setting and would describe today's
+ # configuration rather than the audio. None when the backend did not
+ # report one, or reported something that is not a language code.
+ transcription_language = db.Column(db.String(20), nullable=True)
summary = db.Column(db.Text, nullable=True)
status = db.Column(db.String(50), default='PENDING') # PENDING, PROCESSING, SUMMARIZING, COMPLETED, FAILED
audio_path = db.Column(db.String(500))
@@ -429,6 +435,7 @@ class Recording(db.Model):
'participants': self.participants,
'notes': user_notes,
'transcription': self.transcription,
+ 'transcription_language': self.transcription_language,
'summary': self.summary,
'status': self.status,
'created_at': self.created_at.isoformat() if self.created_at else None,
diff --git a/src/services/job_queue.py b/src/services/job_queue.py
index 5b7f7de5..99efb120 100644
--- a/src/services/job_queue.py
+++ b/src/services/job_queue.py
@@ -850,17 +850,21 @@ class FairJobQueue:
recording = db.session.get(Recording, recording_id)
if not recording:
return
- # audio_duration_seconds read `recording.audio_duration`, which is
- # not a column on Recording, so getattr's default made it None and
- # the None-filter below dropped the key. Subscribers have never
- # received it despite it being documented since #275. `language`
- # was dropped outright for the same reason: there is no per-recording
- # language anywhere. The nearest thing, User.transcription_language,
- # is a live preference rather than a property of this recording, so
- # sending it would report today's setting for last month's audio.
+ # Both of these were documented from #275 and neither was ever
+ # sent. audio_duration_seconds read `recording.audio_duration`,
+ # which is not a column, and `language` read a per-recording
+ # language that did not exist either. getattr's default made both
+ # None and the None-filter below then dropped the keys.
+ #
+ # The language is now recorded at transcription time from what the
+ # service reports, so it describes this audio rather than the
+ # user's current preference. It stays absent for recordings
+ # transcribed before that column existed, and for backends that
+ # report no language.
data = {
'recording_id': recording.id,
'title': recording.title,
+ 'language': recording.transcription_language,
'audio_duration_seconds': recording.audio_duration_seconds,
'transcription_duration_seconds': recording.transcription_duration_seconds,
'summarization_duration_seconds': recording.summarization_duration_seconds,
diff --git a/src/tasks/processing.py b/src/tasks/processing.py
index 79e1da2c..31b3656d 100644
--- a/src/tasks/processing.py
+++ b/src/tasks/processing.py
@@ -2026,6 +2026,9 @@ def transcribe_with_connector(app_context, recording_id, filepath, original_file
transcription_model=transcription_model,
)
+ recording.transcription_language = normalize_language_code(
+ getattr(chunk_result, 'language', None))
+
# Handle result based on type (TranscriptionResponse for diarized, string for plain)
if hasattr(chunk_result, 'segments') and chunk_result.segments and chunk_result.has_diarization():
# Diarized response - store with segments for click-to-seek and speaker identification
@@ -2083,6 +2086,14 @@ def transcribe_with_connector(app_context, recording_id, filepath, original_file
if funasr_active:
cleanup_funasr_staging(recording)
+ # Record the language the service reported for this
+ # audio. Normalised because backends differ on whether
+ # they return 'en' or 'english', and normalisation
+ # yields None rather than raising on anything it does
+ # not recognise.
+ recording.transcription_language = normalize_language_code(
+ getattr(response, 'language', None))
+
# Store the result
if response.segments and response.has_diarization():
# Store as JSON with segments (diarized format)
diff --git a/tests/test_transcription_language_capture.py b/tests/test_transcription_language_capture.py
new file mode 100644
index 00000000..b11c66b2
--- /dev/null
+++ b/tests/test_transcription_language_capture.py
@@ -0,0 +1,125 @@
+"""The detected transcription language is recorded on the recording (#386).
+
+`TranscriptionResponse.language` has carried the service's detected language
+since the connector architecture landed, and every connector that can report
+one populates it. Nothing consumed it, so it was discarded after each run.
+
+The webhook payload had documented a `language` field since #275 by reading
+`recording.transcription_language`, a column that was never added, so the value
+was always None and the payload's None-filter dropped the key. Subscribers have
+never received it. These tests cover the column that closes that gap, and the
+distinction that makes it correct: the language belongs to the AUDIO, recorded
+once at transcription time, not to the user's live preference.
+"""
+
+import os
+
+import pytest
+
+from src.app import app
+from src.database import db
+from src.models import Recording, User
+from src.utils.language import normalize_language_code
+
+
+def owner():
+ with app.app_context():
+ user = User(username=f'lang_owner_{os.getpid()}',
+ email=f'lang_owner_{os.getpid()}@example.com', password='x')
+ db.session.add(user)
+ db.session.commit()
+ uid = user.id
+ yield uid
+ with app.app_context():
+ Recording.query.filter_by(user_id=uid).delete()
+ User.query.filter_by(id=uid).delete()
+ db.session.commit()
+
+
+def test_the_column_exists_and_is_distinct_from_the_user_preference():
+ """User.transcription_language is what the user ASKED for and can change at
+ any time. Recording.transcription_language is what the service reported for
+ that audio. Conflating them would make old recordings report today's
+ setting, which is why the webhook could not simply read the user's."""
+ recording_cols = {c.name for c in Recording.__table__.columns}
+ user_cols = {c.name for c in User.__table__.columns}
+ assert 'transcription_language' in recording_cols
+ assert 'transcription_language' in user_cols, 'the user preference should still exist'
+
+
+def test_it_round_trips_through_the_database_and_the_api(owner):
+ with app.app_context():
+ rec = Recording(user_id=owner, title='Nederlandse vergadering',
+ audio_path='/tmp/x.wav', transcription_language='nl')
+ db.session.add(rec)
+ db.session.commit()
+
+ stored = db.session.get(Recording, rec.id)
+ assert stored.transcription_language == 'nl'
+ assert stored.to_dict()['transcription_language'] == 'nl'
+
+
+def test_it_is_nullable_for_recordings_that_predate_it(owner):
+ """Existing rows stay NULL. The audio would have to be re-transcribed to
+ learn the language, so the field is simply absent rather than guessed."""
+ with app.app_context():
+ rec = Recording(user_id=owner, title='Older recording', audio_path='/tmp/x.wav')
+ db.session.add(rec)
+ db.session.commit()
+ assert db.session.get(Recording, rec.id).transcription_language is None
+ assert db.session.get(Recording, rec.id).to_dict()['transcription_language'] is None
+
+
[email protected]('reported,expected', [
+ ('en', 'en'),
+ ('EN', 'en'),
+ ('en-US', 'en'), # locale codes are stripped to the language
+ ('English', 'en'), # some backends report a display name
+ ('nl', 'nl'),
+ (None, None),
+ ('', None),
+ ('auto', None), # not a language; means the backend detected nothing
+ ('gibberish', None), # unrecognised, and better absent than wrong
+])
+def test_what_the_backend_reports_is_normalised_before_storage(reported, expected):
+ """Backends disagree on the form: 'en', 'EN', 'en-US', 'English'. Storing
+ them raw would make the field useless to a subscriber trying to route on
+ it, and normalisation yields None rather than raising on anything odd."""
+ assert normalize_language_code(reported) == expected
+
+
+def test_the_stored_value_fits_the_column(owner):
+ """VARCHAR(20) against normalised output, which is a 2-letter code."""
+ length = Recording.__table__.columns['transcription_language'].type.length
+ assert length >= 10
+ for candidate in ('en', 'nl', 'zh', 'pt'):
+ assert len(normalize_language_code(candidate) or '') <= length
+
+
+def test_the_transcription_task_assigns_it_from_the_response():
+ """Pins the wiring, not just the column. Both storage paths in
+ transcribe_with_connector, chunked and single-file, must set it, or a
+ large file would silently lose the language a small one records."""
+ import ast
+ import inspect as _inspect
+ from src.tasks import processing
+
+ source = _inspect.getsource(processing.transcribe_with_connector)
+ tree = ast.parse(source.lstrip())
+
+ assignments = [
+ node for node in ast.walk(tree)
+ if isinstance(node, ast.Assign)
+ and any(isinstance(t, ast.Attribute) and t.attr == 'transcription_language'
+ for t in node.targets)
+ ]
+ assert len(assignments) == 2, (
+ f'expected the single-file and chunked paths each to record the language, '
+ f'found {len(assignments)} assignment(s)')
+
+ # Each must go through the normaliser rather than storing the raw value.
+ for node in assignments:
+ call = node.value
+ assert isinstance(call, ast.Call), 'the reported language must be normalised'
+ assert getattr(call.func, 'id', None) == 'normalize_language_code'
diff --git a/tests/test_webhooks.py b/tests/test_webhooks.py
index 7e48a1d5..1cf1a4ee 100644
--- a/tests/test_webhooks.py
+++ b/tests/test_webhooks.py
@@ -1196,12 +1196,12 @@ def teardown_module(module):
db.session.commit()
-def test_completion_payload_carries_the_documented_duration_fields():
- """The completion payload promised `audio_duration_seconds` from #275 but
- read `recording.audio_duration`, which is not a column. getattr's default
- made it None and the None-filter dropped the key, so no subscriber has
- ever received it. This pins the real attribute names against the model.
- """
+def test_completion_payload_carries_the_documented_fields():
+ """`audio_duration_seconds` and `language` were both documented from #275
+ and neither was ever sent: the first read `recording.audio_duration` and
+ the second a per-recording language, and neither is a column, so getattr's
+ default made them None and the None-filter dropped both keys. This pins
+ the attribute names against the model so it cannot regress silently."""
from unittest.mock import patch
from src.app import app
from src.models import Recording
@@ -1209,13 +1209,14 @@ def test_completion_payload_carries_the_documented_duration_fields():
model_columns = {c.name for c in Recording.__table__.columns}
for field in ('audio_duration_seconds', 'transcription_duration_seconds',
- 'summarization_duration_seconds'):
+ 'summarization_duration_seconds', 'transcription_language'):
assert field in model_columns, f'{field} is not a Recording column'
class _Rec:
id = 5150
user_id = 7
title = 'Q3 planning'
+ transcription_language = 'en'
audio_duration_seconds = 3624.7
transcription_duration_seconds = 212
summarization_duration_seconds = None
@@ -1230,7 +1231,34 @@ def test_completion_payload_carries_the_documented_duration_fields():
data = emit.call_args.kwargs['data']
assert data['audio_duration_seconds'] == 3624.7
assert data['transcription_duration_seconds'] == 212
+ assert data['language'] == 'en'
# None-valued keys are still filtered out.
assert 'summarization_duration_seconds' not in data
- # `language` was removed: there is no per-recording language to send.
- assert 'language' not in data
+
+
+def test_language_is_omitted_rather_than_null_when_it_is_unknown():
+ """Absent is normal: backends that report no language, and every recording
+ transcribed before the column existed. Subscribers must not have to
+ distinguish null from missing."""
+ from unittest.mock import patch
+ from src.app import app
+ from src.services.job_queue import job_queue
+
+ class _Rec:
+ id = 5151
+ user_id = 7
+ title = 'Old recording'
+ transcription_language = None
+ audio_duration_seconds = 12.0
+ transcription_duration_seconds = 3
+ summarization_duration_seconds = None
+
+ with app.app_context():
+ job_queue.init_app(app)
+ with patch('src.services.webhook_dispatch.emit_webhook_event') as emit, \
+ patch('src.database.db.session.get', return_value=_Rec()):
+ job_queue._emit_completion_webhook('transcribe', 5151)
+ data = emit.call_args.kwargs['data']
+
+ assert 'language' not in data
+ assert data['audio_duration_seconds'] == 12.0