scribeio 0.1.4__tar.gz

scribeio-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artur Marchewicz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scribeio-0.1.4/MANIFEST.in

@@ -0,0 +1,4 @@
+# sdist: the whole test suite with its helpers and data, never the local-only tests
+graft tests
+prune tests/local
+global-exclude __pycache__ *.py[co]

scribeio-0.1.4/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: scribeio
+Version: 0.1.4
+Summary: Balanced audio and transcripts from Craig (Discord) recordings of TTRPG sessions
+Author: Artur Marchewicz
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/00apm/scribeio
+Project-URL: Documentation, https://github.com/00apm/scribeio/blob/main/docs/README.md
+Project-URL: Issues, https://github.com/00apm/scribeio/issues
+Keywords: ttrpg,transcription,whisper,discord,craig
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.2
+Requires-Dist: rich>=13
+Requires-Dist: pyyaml>=6
+Requires-Dist: numpy>=1.24
+Requires-Dist: colorama>=0.4.6; sys_platform == "win32"
+Provides-Extra: transcribe
+Requires-Dist: whisperx<3.9,>=3.8.6; extra == "transcribe"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/00apm/scribeio/main/docs/images/scribeio-logo-dark.svg">
+    <img alt="scribeio logo" src="https://raw.githubusercontent.com/00apm/scribeio/main/docs/images/scribeio-logo-light.svg" width="360">
+  </picture>
+</p>
+
+# scribeio
+
+Turn [Craig](https://craig.chat) (Discord) recordings of your TTRPG
+sessions into balanced audio and a transcript ready for your session
+notes.
+
+Craig records one track per person. scribeio works on those tracks:
+
+- **Audio mastering:** each voice is evened out and brought to the same
+  level as the others, the music is kept quieter than the voices so it
+  never drowns them out, and everything is mixed into one file.
+- **Transcript:** each track is transcribed by Whisper, a speech-to-text
+  model that runs on your own computer
+  (through [WhisperX](https://github.com/m-bain/whisperX)), and the lines
+  are put together in time order with each person's name.
+
+What you get from working per track, locally:
+
+- Every line has the right speaker, even when people talk over each
+  other.
+- Lines Whisper made up (hallucinations, e.g. "thanks for watching" in a
+  silence) are found and removed; a report lists each one.
+- The names of your world are taught to Whisper in a glossary; a misheard
+  name is fixed with one line and a rebuild that takes seconds.
+- Your recordings never leave your computer: your players' voices and
+  words stay private, and no online service can keep them or use them to
+  train its AI models.
+
+**Not a TTRPG session, or not Craig?** A podcast or a meeting recorded on
+Discord with Craig works the same way, and so does any other recording
+with one track per person
+([input recordings](https://github.com/00apm/scribeio/blob/main/docs/recordings.md#not-using-craig)).
+
+## Requirements
+
+- Windows, macOS or Linux.
+- [ffmpeg](https://ffmpeg.org) 6.1 or newer.
+- For transcription: an NVIDIA GPU, GTX 16xx / RTX 20xx or newer, 6 GB or
+  more (8 GB recommended). Without one it runs on the CPU, very slowly
+  (`transcribe.whisper.device: cpu` in `scribe.yaml`). Audio mastering needs no GPU.
+- Disk: up to about 12 GB with transcription (the install and the speech
+  models); audio mastering alone needs well under 1 GB.
+
+## Install
+
+- [Quick install](https://github.com/00apm/scribeio/blob/main/docs/install.md):
+  a few commands, no Python knowledge needed.
+- [Install into your own Python environment](https://github.com/00apm/scribeio/blob/main/docs/install-own-env.md):
+  pip, Python 3.10–3.13.
+
+## Quick start
+
+In the folder with the Craig download:
+
+```
+scribe init "craig-session-7.zip"
+```
+
+This creates scribeio's settings for this recording: `scribe.yaml`, with
+the Discord accounts from the recording already listed, and `glossary.txt`
+for the names of your world. Write each person's name next to their
+account in `scribe.yaml`, then make the session audio and the transcript:
+
+```
+scribe master "craig-session-7.zip"
+scribe transcribe "craig-session-7.zip"
+```
+
+`scribe check` shows what is installed and what is missing.
+
+The files land next to the recording, named by the session date:
+
+| File | What it is |
+|---|---|
+| `2026-09-22_master.mp3` | the session audio, every voice at the same level |
+| `2026-09-22_transcript.md` | the transcript, one line per utterance |
+| `2026-09-22_transcript.json` | everything Whisper found, for rebuilding the transcript without the GPU |
+| `2026-09-22_transcript-report.md` | the quality report: what was removed and why |
+
+A piece of the transcript:
+
+```
+[01:12:05] Alice (GM): The stairs end at a heavy door. Cold air seeps through the cracks, and from somewhere below comes a slow
+[01:12:11] Sam: Please don't say scratching.
+[01:12:12] Alice (GM): scratching. Something is scratching at the wood.
+[01:12:16] Robin: I put my ear to the door.
+[01:12:17] Sam: We are not opening that door.
+[01:12:19] Alice (GM): The scratching stops. Then, very quietly, something knocks. Three times.
+[01:12:25] Sam: Nope. I'm going back up.
+[01:12:25] Robin: I open the door.
+```
+
+The quick start runs everything on its defaults. The guides below show
+how to make the result your own.
+
+## Usage guide
+
+Each guide covers one part; go to the one you need.
+
+- **[Input recordings](https://github.com/00apm/scribeio/blob/main/docs/recordings.md):**
+  which Craig downloads work, where scribeio puts its files, and how to
+  use tracks that did not come from Craig.
+- **[Audio mastering](https://github.com/00apm/scribeio/blob/main/docs/usage/audio.md):**
+  listen to a short preview after each step, change how the voices and
+  the music sound, adjust one player only, and choose the file format.
+- **[Transcribing a recording](https://github.com/00apm/scribeio/blob/main/docs/usage/transcribe.md):**
+  set names and the language, download the models, read the transcript
+  and the report, and teach Whisper the names of your world with a
+  glossary.
+
+All documentation pages, install included:
+[docs](https://github.com/00apm/scribeio/blob/main/docs/README.md).
+
+## Development
+
+```
+git clone https://github.com/00apm/scribeio.git
+cd scribeio
+pip install -e ".[dev]"
+pytest -m "not gpu"
+mypy
+ruff format src tests && ruff check src tests
+```
+
+The tests need ffmpeg 6.1 or newer with the mp3 encoder on PATH, but not
+WhisperX, PyTorch or a GPU: transcription is tested with stand-ins. Tests
+use synthetic data only; no real recordings are in the repository (the
+`gpu` tests need a local recording; `-m "not gpu"` leaves them out).
+
+To run real transcriptions from the checkout, install PyTorch with CUDA
+first
+([Install into your own Python environment](https://github.com/00apm/scribeio/blob/main/docs/install-own-env.md#install)),
+then `pip install -e ".[transcribe,dev]"`.
+
+## License
+
+scribeio is free and open source under the
+[MIT License](https://github.com/00apm/scribeio/blob/main/LICENSE): you
+may use, change and share it, also commercially, as long as the licence
+text stays with it.
+
+WhisperX, ffmpeg and the speech models are installed separately and come
+with their own licences.

scribeio-0.1.4/README.md

@@ -0,0 +1,150 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/00apm/scribeio/main/docs/images/scribeio-logo-dark.svg">
+    <img alt="scribeio logo" src="https://raw.githubusercontent.com/00apm/scribeio/main/docs/images/scribeio-logo-light.svg" width="360">
+  </picture>
+</p>
+
+# scribeio
+
+Turn [Craig](https://craig.chat) (Discord) recordings of your TTRPG
+sessions into balanced audio and a transcript ready for your session
+notes.
+
+Craig records one track per person. scribeio works on those tracks:
+
+- **Audio mastering:** each voice is evened out and brought to the same
+  level as the others, the music is kept quieter than the voices so it
+  never drowns them out, and everything is mixed into one file.
+- **Transcript:** each track is transcribed by Whisper, a speech-to-text
+  model that runs on your own computer
+  (through [WhisperX](https://github.com/m-bain/whisperX)), and the lines
+  are put together in time order with each person's name.
+
+What you get from working per track, locally:
+
+- Every line has the right speaker, even when people talk over each
+  other.
+- Lines Whisper made up (hallucinations, e.g. "thanks for watching" in a
+  silence) are found and removed; a report lists each one.
+- The names of your world are taught to Whisper in a glossary; a misheard
+  name is fixed with one line and a rebuild that takes seconds.
+- Your recordings never leave your computer: your players' voices and
+  words stay private, and no online service can keep them or use them to
+  train its AI models.
+
+**Not a TTRPG session, or not Craig?** A podcast or a meeting recorded on
+Discord with Craig works the same way, and so does any other recording
+with one track per person
+([input recordings](https://github.com/00apm/scribeio/blob/main/docs/recordings.md#not-using-craig)).
+
+## Requirements
+
+- Windows, macOS or Linux.
+- [ffmpeg](https://ffmpeg.org) 6.1 or newer.
+- For transcription: an NVIDIA GPU, GTX 16xx / RTX 20xx or newer, 6 GB or
+  more (8 GB recommended). Without one it runs on the CPU, very slowly
+  (`transcribe.whisper.device: cpu` in `scribe.yaml`). Audio mastering needs no GPU.
+- Disk: up to about 12 GB with transcription (the install and the speech
+  models); audio mastering alone needs well under 1 GB.
+
+## Install
+
+- [Quick install](https://github.com/00apm/scribeio/blob/main/docs/install.md):
+  a few commands, no Python knowledge needed.
+- [Install into your own Python environment](https://github.com/00apm/scribeio/blob/main/docs/install-own-env.md):
+  pip, Python 3.10–3.13.
+
+## Quick start
+
+In the folder with the Craig download:
+
+```
+scribe init "craig-session-7.zip"
+```
+
+This creates scribeio's settings for this recording: `scribe.yaml`, with
+the Discord accounts from the recording already listed, and `glossary.txt`
+for the names of your world. Write each person's name next to their
+account in `scribe.yaml`, then make the session audio and the transcript:
+
+```
+scribe master "craig-session-7.zip"
+scribe transcribe "craig-session-7.zip"
+```
+
+`scribe check` shows what is installed and what is missing.
+
+The files land next to the recording, named by the session date:
+
+| File | What it is |
+|---|---|
+| `2026-09-22_master.mp3` | the session audio, every voice at the same level |
+| `2026-09-22_transcript.md` | the transcript, one line per utterance |
+| `2026-09-22_transcript.json` | everything Whisper found, for rebuilding the transcript without the GPU |
+| `2026-09-22_transcript-report.md` | the quality report: what was removed and why |
+
+A piece of the transcript:
+
+```
+[01:12:05] Alice (GM): The stairs end at a heavy door. Cold air seeps through the cracks, and from somewhere below comes a slow
+[01:12:11] Sam: Please don't say scratching.
+[01:12:12] Alice (GM): scratching. Something is scratching at the wood.
+[01:12:16] Robin: I put my ear to the door.
+[01:12:17] Sam: We are not opening that door.
+[01:12:19] Alice (GM): The scratching stops. Then, very quietly, something knocks. Three times.
+[01:12:25] Sam: Nope. I'm going back up.
+[01:12:25] Robin: I open the door.
+```
+
+The quick start runs everything on its defaults. The guides below show
+how to make the result your own.
+
+## Usage guide
+
+Each guide covers one part; go to the one you need.
+
+- **[Input recordings](https://github.com/00apm/scribeio/blob/main/docs/recordings.md):**
+  which Craig downloads work, where scribeio puts its files, and how to
+  use tracks that did not come from Craig.
+- **[Audio mastering](https://github.com/00apm/scribeio/blob/main/docs/usage/audio.md):**
+  listen to a short preview after each step, change how the voices and
+  the music sound, adjust one player only, and choose the file format.
+- **[Transcribing a recording](https://github.com/00apm/scribeio/blob/main/docs/usage/transcribe.md):**
+  set names and the language, download the models, read the transcript
+  and the report, and teach Whisper the names of your world with a
+  glossary.
+
+All documentation pages, install included:
+[docs](https://github.com/00apm/scribeio/blob/main/docs/README.md).
+
+## Development
+
+```
+git clone https://github.com/00apm/scribeio.git
+cd scribeio
+pip install -e ".[dev]"
+pytest -m "not gpu"
+mypy
+ruff format src tests && ruff check src tests
+```
+
+The tests need ffmpeg 6.1 or newer with the mp3 encoder on PATH, but not
+WhisperX, PyTorch or a GPU: transcription is tested with stand-ins. Tests
+use synthetic data only; no real recordings are in the repository (the
+`gpu` tests need a local recording; `-m "not gpu"` leaves them out).
+
+To run real transcriptions from the checkout, install PyTorch with CUDA
+first
+([Install into your own Python environment](https://github.com/00apm/scribeio/blob/main/docs/install-own-env.md#install)),
+then `pip install -e ".[transcribe,dev]"`.
+
+## License
+
+scribeio is free and open source under the
+[MIT License](https://github.com/00apm/scribeio/blob/main/LICENSE): you
+may use, change and share it, also commercially, as long as the licence
+text stays with it.
+
+WhisperX, ffmpeg and the speech models are installed separately and come
+with their own licences.

scribeio-0.1.4/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scribeio"
+version = "0.1.4"
+description = "Balanced audio and transcripts from Craig (Discord) recordings of TTRPG sessions"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Artur Marchewicz" }]
+keywords = ["ttrpg", "transcription", "whisper", "discord", "craig"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+]
+dependencies = [
+    "click>=8.2",
+    "rich>=13",
+    "pyyaml>=6",
+    "numpy>=1.24",
+    "colorama>=0.4.6; sys_platform == 'win32'",
+]
+
+[project.urls]
+Homepage = "https://github.com/00apm/scribeio"
+Documentation = "https://github.com/00apm/scribeio/blob/main/docs/README.md"
+Issues = "https://github.com/00apm/scribeio/issues"
+
+[project.optional-dependencies]
+# Install torch with CUDA first (docs/install-own-env.md), so pip keeps the GPU build.
+transcribe = ["whisperx>=3.8.6,<3.9"]
+dev = ["pytest>=8", "mypy>=1.10", "types-PyYAML", "ruff>=0.6"]
+
+[project.scripts]
+scribe = "scribeio.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+scribeio = ["defaults.yaml", "templates/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# tests in subfolders import the shared tests/helpers.py
+pythonpath = ["tests"]
+addopts = "-ra"
+markers = [
+    "gpu: needs CUDA + WhisperX + the local excerpt in tests/local/ (deselect with -m 'not gpu')",
+    "ffmpeg: needs ffmpeg in PATH",
+]
+
+[tool.ruff]
+# PEP 8 via ruff: Black-compatible formatting, 88-character lines.
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+# pycodestyle, pyflakes, import order, pyupgrade, bugbear
+select = ["E", "W", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["scribeio"]
+known-local-folder = ["helpers"]
+
+[tool.mypy]
+python_version = "3.10"     # oldest supported Python: flags newer-only APIs
+files = ["src"]
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+# these ship no type information, or are absent without the transcribe extra
+module = ["whisperx", "whisperx.*", "faster_whisper", "faster_whisper.*", "torchaudio", "torchaudio.*", "colorama", "torch", "torch.*", "huggingface_hub", "huggingface_hub.*"]
+ignore_missing_imports = true

scribeio-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scribeio-0.1.4/src/scribeio/__init__.py

@@ -0,0 +1,8 @@
+"""scribe — transcripts of TTRPG sessions recorded with Craig (Discord)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("scribeio")
+except PackageNotFoundError:  # source tree without `pip install -e .`
+    __version__ = "0.0.0"