Transcript Organizer user manual — version 001

First transcription

Open PowerShell 7 in the project directory and pass the local media file as the first argument.

pwsh -File .\Invoke-TranscriptOrganizer.ps1 '.\recording.webm'

Inspect the complete plan without inference or an output folder:

pwsh -File .\Invoke-TranscriptOrganizer.ps1 '.\recording.webm' -DryRun

Requirements

The target machine uses an i7-8750H, 32 GB RAM, and a GTX 1050 Ti with 4 GB VRAM. The module runs one request at a time, prefers GPU device 0, and permits one classified CPU fallback by default.

Check readiness

The check inspects Windows, PowerShell, FFmpeg, FFprobe, the actual Whisper filter options, NVIDIA diagnostics, and the required model. It never starts transcription.

$manifest = '.\module\TranscriptOrganizer.psd1'
Import-Module $manifest -Force
$configuration = New-TranscriptOrganizerConfiguration -ProjectDirectory $PWD
Test-TranscriptOrganizerEnvironment -Configuration $configuration -IncludeModel

A general FFmpeg installation is insufficient. Confirm the selected binary directly:

ffmpeg -hide_banner -help filter=whisper

Model setup

The supplied English model is ggml-model-whisper-medium.en-q5_0.bin. Search order is an explicit WhisperModelPath, the project root name, the models directory name, then canonical ggml-medium.en-q5_0.bin locations. An explicit missing path fails without silent substitution.

Downloads are opt-in through DownloadMissingModels. Automatic download also requires a trusted SHA-256 in configuration, uses a temporary .download file, validates it, and moves it only after success. The shipped configuration has no asserted hash, so it safely refuses automatic download.

Output formats

There is no format selection: every run uses one internal JSON inference and derives text and SRT. Existing runs are preserved through new suffixed folders unless Overwrite is explicit.

Build a shared extraction corpus

A corpus performs Whisper inference once in JSON mode, then derives normalized segments, readable text, SRT, media metadata, bounded visual frames, validation evidence, and hashes. Downstream projects can reuse these source artifacts without another transcription run.

$configuration = New-TranscriptOrganizerConfiguration -ProjectDirectory $PWD
Export-TranscriptOrganizerCorpus -InputPath '.\talk.webm' -OutputFolder '.\talk-transcript' -Configuration $configuration

Use ReuseExistingTranscript when a validated transcript.raw.jsonl already exists. This protects the expensive source extraction from accidental repetition.

FFmpeg 8.1.2 can emit unescaped quotation marks when quoted speech occurs inside the JSON text field. Export preserves the raw JSONL unchanged, applies a narrow recovery only to the exact FFmpeg record shape, and reports strictly valid and recovered record counts separately.

Reusable coding-agent skills

Experiments 01, 02, and 10 produced workflows that generalize beyond the original talk. Their dated skill folders contain self-contained SKILL.md prompts: each repeats the extraction-folder layout, segment and frame schemas, expected outputs, review questions, and definition of done. Give an agent a validated Transcript Organizer corpus and an output directory; the skill does not need another experiment.

The skills are project knowledge artifacts, not application runtime files, so they remain outside the version 001 PowerShell distribution ZIP.

Common workflows

Choose an output folder

pwsh -File .\Invoke-TranscriptOrganizer.ps1 '.\talk.webm' -OutputFolder '.\results\talk'

Replace one known result

pwsh -File .\Invoke-TranscriptOrganizer.ps1 '.\talk.webm' -OutputFolder '.\results\talk' -Overwrite

CPU-only processing

Edit UseGpu = $false in the launcher’s user-editable defaults block. Set AllowCpuFallback = $false when no fallback distinction is needed.

GPU-preferred processing

The default attempts GPU device 0. CPU fallback occurs once only when FFmpeg reports a recognized GPU initialization failure; invalid models, output conflicts, missing filters, and malformed requests never trigger it.

VAD-enabled processing

Edit EnableVad = $true and provide VadModelPath in the defaults block. VAD remains completely inactive otherwise.

Sequential batch

Get-ChildItem '.\media' -Filter '*.webm' -File | ForEach-Object {
    pwsh -File .\Invoke-TranscriptOrganizer.ps1 $_.FullName
}

Module-level orchestration

$request = New-TranscriptOrganizerRequest -InputPath '.\talk.webm' -OutputFolder '.\talk-transcript'
$result = Invoke-TranscriptOrganizer -Request $request -Configuration $configuration
$requests | Invoke-TranscriptOrganizerBatch -Configuration $configuration

Dry run

pwsh -File .\Invoke-TranscriptOrganizer.ps1 '.\talk.webm' -DryRun

Configuration reference

All operational defaults are together near the beginning of Invoke-TranscriptOrganizer.ps1. The product accepts local media files only.

Logs and diagnostics

Each request writes JSON Lines to artifacts/logs/transcript-organizer-YYYYMMDD.jsonl. Every event includes request and operation identifiers. Process events record the resolved executable, native argument array, working directory, outcome, duration, exit code summary, execution mode, and a separately formatted diagnostic command.

URL credentials, sensitive query strings, password-like properties, and token-like properties are redacted. Transcript output content is not logged. If persistent logging fails, a warning is emitted and the original operation result remains authoritative.

Troubleshooting

Limitations

• Recognition is probabilistic; important transcripts require human review.
• The English quantized medium model is optimized for English, not multilingual accuracy.
• VAD detects speech and silence; it does not identify speakers.
• The project accepts local media files only; live devices and network input are not supported.
• The project does not summarize, correct, edit video, or provide a subtitle editor.
• The FFmpeg Whisper filter does not expose a documented Whisper thread-count setting.

Examples index

• First complete transcript corpus
• Readiness inspection
• Output folder, overwrite, CPU, GPU, VAD, batch, and dry-run workflows