Skip to content

Preserve raw transcript text and timestamps #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alozowski merged 1 commit into from
Aug 24, 2026
Merged

Preserve raw transcript text and timestamps #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 39 additions & 147 deletions CONFIGURATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,24 @@
# Configuration

The defaults are a good starting point for most recordings. If this is your first time using `textplease`, try them before changing anything.
The web interface is the easiest way to use TextPlease:

You can run the app in two ways:

- Web interface: `textplease --gradio`
- Command line: `textplease --config path/to/config.yaml`
```bash
textplease --gradio
```

The web interface is the easiest option. Upload a file, choose a language, and start the transcription. Each run stores
its transcript, configuration, and log in a private job directory under `output/`. Clear deletes that job directory.
Upload a file, choose its language, and start the transcription. The app chooses the best available device. Each job
stores its transcript, configuration, and log in a private directory under `output/`. Clear deletes that directory.

## Quick start from the command line
## Command line

Create a YAML file, for example `my_config.yaml`:
Create a YAML file such as `my_config.yaml`:

```yaml
input_path: "input/recording.mp3"
output_path: "output/recording_transcript.csv"
model_name: "openai/whisper-large-v3"

device: "cpu"
device: "auto"
language: "en"

pause_threshold: 2.0
similarity_threshold: 0.75
min_segment_words: 3
min_segment_chars: 15
max_segment_words: 100
```

Then run:
Expand All @@ -35,160 +27,60 @@ Then run:
textplease --config my_config.yaml
```

Paths are read from the directory where you run the command. The input file must already exist. The output folder is created automatically.

Only `input_path`, `output_path`, and `model_name` are required. Everything else has a default value.

> The output file has a `.csv` extension, but its columns are separated by tabs. This makes transcript text containing commas safe to open and process.

## The settings you are most likely to change

### `pause_threshold`

Default: `2.0` seconds

This is the pause threshold used for ordinary grouping of recognized pieces into transcript segments.

- Use a **lower** value to keep more recognized pieces separate.
- Use a **higher** value to allow more joining across pauses.

This setting does not change Silero VAD, the audio sent to Whisper, decoder text, or raw timestamps. Speech detection is
automatic.

### `similarity_threshold`

Default: `0.75`

This controls whether nearby pieces of text are similar enough to join together.

- Use a **higher** value to keep more segments separate.
- Use a **lower** value to allow more merging.

| Value | What to expect |
|-------|----------------|
| `0.0` | Very permissive; many segments may merge |
| `0.75` | A balanced default |
| `0.9` | Keeps more topic and sentence boundaries |
| `1.0` | Effectively turns off similarity-based merging |

`0.0` does **not** turn merging off. Short fragments may still be joined to a neighbour even when this is set to `1.0`.
At `1.0`, the embedding model is not loaded because semantic similarity cannot affect the result.

### Segment length

These three settings keep the transcript from becoming too fragmented or too dense:

```yaml
min_segment_words: 3
min_segment_chars: 15
max_segment_words: 100
```

- A segment below either minimum is treated as a fragment and is usually joined to a neighbour.
- A segment above the maximum is split into smaller pieces.
- A fragment is kept when it cannot be merged without exceeding the maximum.

Set both minimums to `1` if short replies such as “Yes” or “No” should stay on their own.

## Keep Whisper's segments mostly unchanged

```yaml
similarity_threshold: 1.0
min_segment_words: 1
min_segment_chars: 1
max_segment_words: 100000
```

This turns off the normal segmentation rules as far as practical. The result is not completely raw Whisper output: `textplease` still splits sentences, removes repeated overlap and known false phrases, and drops empty segments.

## Input and model settings
Paths are resolved from the directory where you run the command. The input must exist. The output directory is
created automatically.

| Setting | Default | Notes |
|---------|---------|-------|
| `input_path` | Required | An existing audio or video file |
| `output_path` | Required | Replaced if it already exists |
| `model_name` | Required | A Hugging Face model ID downloaded on first use, or a local directory; the web interface uses `openai/whisper-large-v3` |
| `device` | `cpu` | Use `auto` for the best available device, `cuda` for NVIDIA, or `mps` for Apple Silicon |
| `language` | `en` | Language code passed to Whisper; use `null` for automatic detection with multilingual models |
| `embedding_model` | `all-MiniLM-L6-v2` | Model used to compare segment meaning |
| `log_level` | `INFO` | Also accepts `DEBUG`, `WARNING`, and `ERROR` |

`auto` prefers CUDA, then MPS, then CPU. An unavailable explicit accelerator uses the same fallback order. The web
interface automatically chooses the best available device. It currently offers these languages:
| `model_name` | Required | A Hugging Face model ID downloaded on first use, or a local model directory |
| `device` | `cpu` | `auto`, `cpu`, `cuda`, or `mps` |
| `language` | `en` | A Whisper language code, or `null` for automatic detection |
| `log_level` | `INFO` | `DEBUG`, `INFO`, `WARNING`, or `ERROR` |

- English (`en`), Russian (`ru`), Spanish (`es`), French (`fr`), Italian (`it`)
- German (`de`), Turkish (`tr`), Chinese (`zh`), Korean (`ko`), Japanese (`ja`)
`auto` prefers CUDA, then MPS, then CPU. An unavailable accelerator falls back in the same order. The web interface
offers English, Russian, Spanish, French, Italian, German, Turkish, Chinese, Korean, and Japanese. YAML files can use
other language codes supported by the selected Whisper model.

The command line can use other language codes supported by the selected Whisper model.
The transcript preserves each retained, nonblank Whisper span and its timestamp. TextPlease does not merge, split,
deduplicate, or rewrite that text.

## Performance settings
## Performance

Most users can leave these alone.
Most users should keep the default:

```yaml
performance:
whisper_batch_size: 1
similarity_batch_size: 32
chunk_size: 1000
```

`whisper_batch_size` controls how many VAD speech chunks Whisper transcribes together. The default is `1` on every
device because output parity for larger real-model batches is not yet established. An explicitly configured batch that
exhausts accelerator memory automatically retries one chunk at a time.
This controls how many detected speech chunks Whisper processes together. The default is `1` because parity for larger
real-model batches is not established. If an explicitly configured accelerator batch runs out of memory, TextPlease
retries one chunk at a time.

`similarity_batch_size` controls how many text embeddings are created at once. Lower it if the embedding step runs out of memory.
The web interface keeps its loaded Whisper model after a successful job. Cancelling or failing a job discards the worker
and model. Changing the model or device also starts a new worker. Cancel removes temporary PCM. Clear also deletes the
job's transcript, configuration, and log.

`chunk_size` controls how many pieces of the Whisper transcript are handled at once during merging. Set it to `0` to turn chunked merging off. Embeddings are created before this stage, so lowering `chunk_size` does not reduce the memory used to create them.
## Privacy and model downloads

The web interface keeps its loaded Whisper and embedding models after a successful transcription so later jobs can
reuse them. Cancelling or failing a job discards the worker and its models; changing the model or device also starts a
fresh worker. Cancel removes temporary PCM, while Clear also deletes that job's transcript, configuration, and log.
Audio and transcripts stay on the machine. Hugging Face receives model and metadata requests when a required model is
not cached. Models download automatically and later runs reuse the local cache.

## Environment variables

Configuration files do not change the process environment. Set required environment variables in your shell or
operating system before starting `textplease`; this keeps credentials and machine-specific settings out of saved YAML
files and logs.

## What the web interface exposes

The web interface lets you change:

- device and language
- transcript-grouping pause and similarity thresholds
- minimum words, minimum characters, and maximum words

It chooses the input and output paths for you and uses the default Whisper and embedding models. Performance and logging settings are available only in a CLI YAML file.

## How merging works

In the usual case, two neighbouring segments are joined only when:

1. The pause is no longer than `pause_threshold`.
2. Their similarity is greater than `similarity_threshold`.
3. Their combined length is no more than `max_segment_words`.

Short fragments get an extra cleanup pass. They may be joined without passing the similarity check, but a merge is never allowed to create a segment longer than `max_segment_words`. If no suitable neighbour is available, the fragment is left as it is.

Speech detection is automatic. Changing transcript grouping does not change the audio sent to Whisper.
Configuration files do not set environment variables. Set machine-specific values in the shell before starting
TextPlease so they are not copied into saved job configurations or logs.

## Troubleshooting

| If you see this | Try this |
|-----------------|----------|
| Too many tiny segments | Raise `min_segment_words` or `min_segment_chars` |
| Segments are too long | Lower `max_segment_words` |
| Not enough transcript breaks | Lower `pause_threshold` or raise `similarity_threshold` |
| Too many transcript breaks | Raise `pause_threshold` or lower `similarity_threshold` |
| Unrelated sentences are joined | Raise `similarity_threshold` to about `0.85` |
| Short replies disappear into nearby text | Set both minimums to `1` |
| Whisper runs out of memory | Lower `performance.whisper_batch_size` |
| Embedding runs out of memory | Lower `performance.similarity_batch_size` |
| GPU transcription runs out of memory | Use `device: "cpu"` or a smaller compatible Whisper model |
| Whisper runs out of memory | Keep `performance.whisper_batch_size: 1`, select `cpu`, or use a smaller compatible Whisper model |
| A model download fails | Check the network connection and Hugging Face access, then try again |
| Speech is missing | Confirm the language and review the quality baseline before changing code |
| Music produces text | Record the file and expected silence as a new credited evaluation case |

## A note about CLI values

The command line checks that the required fields are present and that the input file exists, but it does not validate every numeric value. Use non-negative thresholds and positive length and batch values. Keep `min_segment_words` lower than or equal to `max_segment_words`. Unknown settings are ignored.
The output uses tab-separated columns even when its name ends in `.csv`. This preserves commas in spoken text. Unknown
settings produce an error so misspellings and removed options cannot silently change expectations.

For a complete example with every supported option, see [`examples/config_example.yaml`](examples/config_example.yaml).
See [`examples/config_example.yaml`](examples/config_example.yaml) for a complete example.
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ The [baseline](evaluation/BASELINE.md) has all results and audio credits. The [p

## How it works

FFmpeg makes mono 16 kHz PCM for Whisper. Silero VAD finds likely speech. A local AudioSet model suppresses output that it rates as music without speech. Whisper transcribes what remains. The app groups the text by pauses, meaning, and length, then writes the tab-separated file.
FFmpeg makes mono 16 kHz PCM for Whisper. Silero VAD finds likely speech. A local AudioSet model suppresses output that it rates as music without speech. Whisper transcribes what remains. The app writes each retained, nonblank Whisper span and timestamp without rewriting its text.

## License

Expand Down
Loading
Loading