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.mdindex 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.pyindex 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.pyindex 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, FAILEDaudio_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.pyindex 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.pyindex 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_filetranscription_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_fileif 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 resultif 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.pynew file mode 100644index 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.pyindex 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 patchfrom src.app import appfrom 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 = 5150user_id = 7title = 'Q3 planning'+ transcription_language = 'en'audio_duration_seconds = 3624.7transcription_duration_seconds = 212summarization_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.7assert 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