Metadata-Version: 2.4
Name: cuesplice
Version: 0.1.4
Summary: Timed transcript conversion and caption export.
Author: Eduard Germis
License: MIT
Project-URL: Repository, https://github.com/Talla/cuesplice
Project-URL: Issues, https://github.com/Talla/cuesplice/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: spacy<4.0,>=3.5.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Cuesplice

Cuesplice converts word-timed transcripts into Adobe-compatible transcript
JSON, speaker-aware plain text, and SRT captions.

It was extracted from the caption/export layer of Whisper Batch Processor. The
original workflow used AssemblyAI for word timings and speaker labels, then
converted that result into Adobe's transcript shape before producing text and
captions. Cuesplice contains those transformations only. It does not upload
media, call a transcription provider, transcribe audio, or combine separate
audio tracks.

## Requirements

- Python 3.10 or newer.
- spaCy is required. Cuesplice uses its dependency parser to keep captions from
  breaking inside grammatical units; it is not designed to run without it.
- Install the language model for every language you will caption. The current
  release supports German (`de-de`) and English (`en-us`, `en-gb`).

```bash
# Package, after the PyPI release
pip install cuesplice

# Required language models: install the one(s) you need
python -m spacy download de_core_news_sm
python -m spacy download en_core_web_sm
```

Install the public GitHub source before the PyPI release, or a checkout while
developing:

```bash
pip install "cuesplice @ git+https://github.com/Talla/cuesplice.git"
pip install -e .
```

If a required model is missing, caption generation stops with the exact
`python -m spacy download ...` command needed to install it. It does not fall
back to heuristic caption breaks.

## Input formats

`assemblyai_to_adobe_json()` accepts an AssemblyAI-style payload with
millisecond `start`/`end` values. It uses `utterances` when present and falls
back to a flat `words` list.

```python
from cuesplice import assemblyai_to_adobe_json

assemblyai_payload = {
    "language_code": "de",
    "utterances": [
        {
            "speaker": "A",
            "start": 0,
            "end": 1420,
            "words": [
                {"text": "Hallo", "start": 0, "end": 480, "confidence": 0.98},
                {"text": "Welt.", "start": 540, "end": 1420, "confidence": 0.97},
            ],
        },
    ],
}

adobe = assemblyai_to_adobe_json(
    assemblyai_payload,
    speaker_names={"A": "Presenter"},
)
```

The returned structure uses seconds, word durations, UUID speaker IDs, speaker
names, and Adobe language codes such as `de-de` or `en-us`. Pass an explicit
`language` argument when the source payload does not provide `language_code`.

The text and SRT functions take that Adobe-compatible structure directly. They
also work with other tools that emit the same `language`, `segments`,
`speakers`, and word-level timing fields.

## Plain text

```python
from cuesplice import adobe_json_to_text

text = adobe_json_to_text(adobe)
open("transcript.txt", "w", encoding="utf-8").write(text)
```

Text export groups words into paragraphs using speaker changes, sentence
punctuation, pauses, and a soft length limit. Multi-speaker transcripts receive
speaker labels.

## SRT captions

```python
from cuesplice import generate_srt_from_data

generate_srt_from_data(adobe, "captions.srt", preset="fast")
```

The named presets are:

| Preset | Intended use | Caption shape |
| --- | --- | --- |
| `ultra-fast` | Reels and short-form cuts | 1–3 words, short holds |
| `fast` | Talking heads and YouTube | About 4–5 words, one line |
| `medium` | Filmic or documentary work | Longer, single-line captions |
| `slow` | Documentary and slower-paced work | Longer, two-line captions |

You can also generate an SRT from an Adobe JSON file and override individual
caption settings:

```python
from cuesplice import generate_srt

generate_srt(
    "transcript.json",
    "captions.srt",
    preset="fast",
    max_chars=32,
    pause_threshold=0.35,
)
```

The module also provides a small command-line interface:

```bash
python -m cuesplice.srt transcript.json --preset fast --output captions.srt
```

## Track boundaries

Cuesplice treats the transcript it receives as one timeline. If a project has
one diarized transcript per microphone, call Cuesplice once per microphone.
That preserves the timing and speaker labels from each recorded track instead
of inventing a merged conversation.

## Public API

- `assemblyai_to_adobe_json(transcript, language=None, speaker_names=None)`
- `adobe_language_code(language)`
- `adobe_json_to_text(data, pause_after_eos=0.6, hard_pause=1.8, soft_max_chars=700)`
- `generate_srt(input_path, output_path=None, ..., preset=None)`
- `generate_srt_from_data(data, output_path, preset)`
- `load_presets()` and `get_preset(name)`

## License

MIT. See [LICENSE](LICENSE).
