From 4a7529393ebbbc225939f21be783ec624d0a8168 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Thu, 14 May 2026 14:09:16 -0500 Subject: feat(transcription): extend dired T to transcribe videos via ffmpeg, with tests Pressing `T' in dired/dirvish on an audio file already transcribed it; on a video file it bounced with "Not an audio file". Real recordings ship as .mp4 / .mkv at least as often as raw .m4a, so the one-key flow ended at the wrong place. Pipeline now: - audio path -> direct into `cj/--start-transcription-process' (unchanged). - video path -> async ffmpeg extracts the audio track to a temp .mp3 under `temporary-file-directory' (libmp3lame, VBR q:a 4, ~165kbps -- right size for speech, accepted by every backend), then transcribes that file with the temp marked for cleanup after the transcription sentinel fires. Surface changes: - `cj/video-file-extensions' added to user-constants.el (mp4, mkv, mov, webm, avi, m4v, wmv, flv, mpg, mpeg, 3gp, ogv). - New predicates `cj/--video-file-p' / `cj/--media-file-p'. - New `cj/--extract-audio-from-video' (async ffmpeg with success callback; surfaces `cj/--notify' on failure; user-errors if ffmpeg isn't on PATH). - `cj/--start-transcription-process' gains optional `cleanup-file'. Sentinel deletes it after the existing logic runs. Backwards compatible -- the audio flow doesn't pass it. - `cj/transcribe-audio' renamed to `cj/transcribe-media' (dispatcher on audio vs video). `cj/transcribe-audio-at-point' renamed to `cj/transcribe-media-at-point'. Both old names kept as `defalias' so M-x history and any external references still work. - `T' in dired-mode-map + dirvish-mode-map points at `cj/transcribe-media-at-point'. - Module commentary USAGE block updated. 15 new ERT tests in `tests/test-transcription-video.el' cover the predicates (happy/boundary/error), ffmpeg invocation (correct args + missing-ffmpeg path), the dispatcher (audio direct, video via extraction, non-media rejected), the aliases, and the T binding. One existing test in `test-transcription-status-and-commands.el' updated to stub the new delegate name. Verified locally that ffmpeg is on PATH with libmp3lame, and that the exact arg list my code uses produces a valid MP3 from a synthetic test video. --- modules/transcription-config.el | 118 ++++++++++++++++++++++++++++++++++------ modules/user-constants.el | 6 ++ 2 files changed, 107 insertions(+), 17 deletions(-) (limited to 'modules') diff --git a/modules/transcription-config.el b/modules/transcription-config.el index 3736835d..d81ccba0 100644 --- a/modules/transcription-config.el +++ b/modules/transcription-config.el @@ -8,8 +8,9 @@ ;; Audio transcription workflow with multiple backend options. ;; ;; USAGE: -;; In dired: Press `T` on an audio file to transcribe -;; Anywhere: M-x cj/transcribe-audio +;; In dired: Press `T` on an audio OR video file to transcribe +;; (videos run through ffmpeg first to extract the audio) +;; Anywhere: M-x cj/transcribe-media (M-x cj/transcribe-audio still works) ;; View active: M-x cj/transcriptions-buffer ;; Switch backend: M-x cj/transcription-switch-backend ;; @@ -84,6 +85,17 @@ Status: running, complete, error") (when-let ((ext (file-name-extension file))) (member (downcase ext) cj/audio-file-extensions)))) +(defun cj/--video-file-p (file) + "Return non-nil if FILE is a video file based on extension." + (when (and file (stringp file)) + (when-let ((ext (file-name-extension file))) + (member (downcase ext) cj/video-file-extensions)))) + +(defun cj/--media-file-p (file) + "Return non-nil if FILE is an audio or video file." + (or (cj/--audio-file-p file) + (cj/--video-file-p file))) + (defun cj/--transcription-output-files (audio-file) "Return cons cell of (TXT-FILE . LOG-FILE) for AUDIO-FILE." (let ((base (file-name-sans-extension audio-file))) @@ -159,9 +171,13 @@ TITLE and MESSAGE are strings. URGENCY is normal or critical." :body message :urgency (or urgency 'normal)))) -(defun cj/--start-transcription-process (audio-file) +(defun cj/--start-transcription-process (audio-file &optional cleanup-file) "Start async transcription process for AUDIO-FILE. -Returns the process object." +Returns the process object. + +When CLEANUP-FILE is non-nil, delete that path once the transcription +sentinel fires (success or failure). Used by the video flow to drop +the temp audio file produced by ffmpeg after transcription completes." (unless (file-exists-p audio-file) (user-error "Audio file does not exist: %s" audio-file)) @@ -186,13 +202,57 @@ Returns the process object." :buffer (get-buffer-create buffer-name) :command (list script audio-file) :sentinel (lambda (proc event) - (cj/--transcription-sentinel proc event audio-file txt-file log-file)) + (cj/--transcription-sentinel proc event audio-file txt-file log-file) + (when cleanup-file + (ignore-errors (delete-file cleanup-file)))) :stderr log-file))) (cj/--track-transcription process audio-file) (cj/--notify "Transcription" (format "Started on %s" (file-name-nondirectory audio-file))) process))) +(defun cj/--video-extracted-audio-path (video-file) + "Return a temp .mp3 path to hold the extracted audio for VIDEO-FILE. +The basename hints at the source so a stuck file is easy to identify." + (make-temp-file (format "cj-tx-%s-" + (file-name-base video-file)) + nil ".mp3")) + +(defun cj/--extract-audio-from-video (video-file output-file on-success) + "Async-extract the audio track from VIDEO-FILE to OUTPUT-FILE via ffmpeg. + +On success, call ON-SUCCESS (no args). On failure, signal a +descriptive `user-error' via `cj/--notify'. Signals `user-error' +synchronously if ffmpeg isn't on PATH. + +Uses libmp3lame at quality 4 (~165kbps VBR) -- good for speech, +universally accepted by the transcription backends." + (let ((ffmpeg (cj/executable-find-or-warn + "ffmpeg" "video audio extraction" 'transcription-config))) + (unless ffmpeg + (user-error "ffmpeg not found on PATH -- install ffmpeg to transcribe videos")) + (let ((process-name (format "ffmpeg-extract-%s" + (file-name-nondirectory video-file)))) + (make-process + :name process-name + :buffer (get-buffer-create (format " *%s*" process-name)) + :command (list ffmpeg "-y" "-i" video-file + "-vn" "-acodec" "libmp3lame" "-q:a" "4" + output-file) + :sentinel (lambda (proc event) + (cond + ((and (string-match-p "finished" event) + (= 0 (process-exit-status proc))) + (let ((buf (process-buffer proc))) + (when (buffer-live-p buf) (kill-buffer buf))) + (funcall on-success)) + ((string-match-p "\\(?:exited\\|failed\\|signal\\)" event) + (cj/--notify "Transcription" + (format "ffmpeg failed on %s" + (file-name-nondirectory video-file)) + 'critical) + (ignore-errors (delete-file output-file))))))))) + (defun cj/--write-transcript-on-success (process-buffer success-p txt-file) "Write PROCESS-BUFFER contents to TXT-FILE when SUCCESS-P is non-nil. No-op if PROCESS-BUFFER is dead or SUCCESS-P is nil." @@ -284,25 +344,49 @@ associated output files." ;; --------------------------- Interactive Commands ---------------------------- ;;;###autoload -(defun cj/transcribe-audio (audio-file) - "Transcribe AUDIO-FILE asynchronously. -Creates AUDIO.txt with transcript and AUDIO.log with process logs. -Uses backend specified by `cj/transcribe-backend'." - (interactive (list (read-file-name "Audio file to transcribe: " +(defun cj/transcribe-media (file) + "Transcribe FILE asynchronously. Accepts audio or video. + +For audio: hands the file straight to the transcription pipeline. +For video: shells ffmpeg to extract the audio track to a temp .mp3, +then transcribes that. The temp audio is deleted after the +transcription sentinel fires. + +Creates FILE.txt with the transcript (alongside the source) and +FILE.log with process logs. Uses the backend in +`cj/transcribe-backend'." + (interactive (list (read-file-name "Media file to transcribe: " nil nil t nil - #'cj/--audio-file-p))) - (cj/--start-transcription-process (expand-file-name audio-file))) + #'cj/--media-file-p))) + (let ((path (expand-file-name file))) + (unless (cj/--media-file-p path) + (user-error "Not an audio or video file: %s" path)) + (cond + ((cj/--audio-file-p path) + (cj/--start-transcription-process path)) + ((cj/--video-file-p path) + (let ((extracted (cj/--video-extracted-audio-path path))) + (cj/--extract-audio-from-video + path extracted + (lambda () + (cj/--start-transcription-process extracted extracted)))))))) ;;;###autoload -(defun cj/transcribe-audio-at-point () - "Transcribe audio file at point in dired." +(defun cj/transcribe-media-at-point () + "Transcribe the audio or video file at point in dired/dirvish." (interactive) (unless (derived-mode-p 'dired-mode) (user-error "Not in dired-mode")) (let ((file (dired-get-filename nil t))) (unless file (user-error "No file at point")) - (cj/transcribe-audio file))) + (cj/transcribe-media file))) + +;; Backwards-compat aliases. The audio-only names predate the +;; video-extension work; keep them as drop-in synonyms for anyone +;; with muscle memory or external scripts. +(defalias 'cj/transcribe-audio 'cj/transcribe-media) +(defalias 'cj/transcribe-audio-at-point 'cj/transcribe-media-at-point) (defun cj/--format-transcription-entry (entry) "Return a display string for a transcription ENTRY. @@ -374,11 +458,11 @@ Prompts with completing-read to select from available backends." ;; ------------------------------- Dired Integration --------------------------- (with-eval-after-load 'dired - (define-key dired-mode-map (kbd "T") #'cj/transcribe-audio-at-point)) + (define-key dired-mode-map (kbd "T") #'cj/transcribe-media-at-point)) ;; Dirvish uses its own keymap, so bind T there too (with-eval-after-load 'dirvish - (define-key dirvish-mode-map (kbd "T") #'cj/transcribe-audio-at-point)) + (define-key dirvish-mode-map (kbd "T") #'cj/transcribe-media-at-point)) ;; Reach the transcription commands via M-x. The previous `C-; T' ;; menu was retired so the top-level slot could go to telega (which diff --git a/modules/user-constants.el b/modules/user-constants.el index b1f6016b..21e141a5 100644 --- a/modules/user-constants.el +++ b/modules/user-constants.el @@ -56,6 +56,12 @@ Used by cursor color, modeline, and other UI elements.") "File extensions recognized as audio files. Used by transcription module and other audio-related functionality.") +(defvar cj/video-file-extensions + '("mp4" "mkv" "mov" "webm" "avi" "m4v" "wmv" "flv" "mpg" "mpeg" "3gp" "ogv") + "File extensions recognized as video files. +Used by transcription to dispatch the audio-extract step in front of +the regular transcription pipeline.") + ;; ------------------------ Directory And File Constants ----------------------- ;; DIRECTORIES -- cgit v1.2.3