webinar-transcriber 1.3.0__tar.gz

webinar_transcriber-1.3.0/.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*.md]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+max_line_length = 100
+trim_trailing_whitespace = false
+
+[*.sh]
+indent_style = space
+indent_size = 4
+
+[*.json]
+indent_style = space
+indent_size = 4

webinar_transcriber-1.3.0/.gitattributes

@@ -0,0 +1,6 @@
+* text=auto
+*.md text eol=lf
+*.py text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf

webinar_transcriber-1.3.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      github-actions:
+        patterns:
+          - "*"

webinar_transcriber-1.3.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint-test:
+    name: lint-test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Sync dependencies
+        run: uv sync --extra llm --group dev
+      - name: Smoke CLI help
+        run: uv run webinar-transcriber --help
+      - name: Smoke whisper runtime
+        run: uv run python -c "from pywhispercpp.model import Model; assert Model.system_info().strip()"
+      - name: Lint
+        run: make lint
+      - name: Test
+        run: make test-all

webinar_transcriber-1.3.0/.github/workflows/codeql.yml

@@ -0,0 +1,40 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "24 5 * * 2"
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [actions, python]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

webinar_transcriber-1.3.0/.github/workflows/release.yml

@@ -0,0 +1,122 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+jobs:
+  validate:
+    name: validate (${{ matrix.os }})
+    permissions:
+      contents: read
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Sync dependencies
+        run: uv sync --extra llm --group dev
+
+      - name: Smoke CLI help
+        run: uv run webinar-transcriber --help
+
+      - name: Smoke whisper runtime
+        run: uv run python -c "from pywhispercpp.model import Model; assert Model.system_info().strip()"
+
+      - name: Lint
+        run: make lint
+
+      - name: Test
+        run: make test-all
+
+  release:
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Sync dependencies
+        run: uv sync --extra llm --group dev
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+
+      - name: Create GitHub Release
+        if: github.event_name == 'push'
+        uses: softprops/action-gh-release@v3
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+
+  publish-testpypi:
+    needs: release
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/webinar-transcriber
+    permissions:
+      id-token: write
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          skip-existing: true
+
+  publish-pypi:
+    needs: release
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/webinar-transcriber
+    permissions:
+      id-token: write
+    steps:
+      - name: Download built distributions
+        uses: actions/download-artifact@v7
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

webinar_transcriber-1.3.0/.gitignore

@@ -0,0 +1,214 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+webinar_transcriber/_version.py
+runs/
+models/.DS_Store
+models/whisper-cpp/*.bin
+models/whisper-cpp/*.wav
+models/whisper-cpp/*.json
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+.DS_Store
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

webinar_transcriber-1.3.0/.markdownlint.json

@@ -0,0 +1,5 @@
+{
+    "MD013": {
+        "line_length": 100
+    }
+}

webinar_transcriber-1.3.0/.mdformat.toml

@@ -0,0 +1 @@
+wrap = 100

webinar_transcriber-1.3.0/.prettierrc.json

@@ -0,0 +1,11 @@
+{
+    "overrides": [
+        {
+            "files": "*.md",
+            "options": {
+                "printWidth": 100,
+                "proseWrap": "preserve"
+            }
+        }
+    ]
+}

webinar_transcriber-1.3.0/.python-version

@@ -0,0 +1 @@
+3.12

webinar_transcriber-1.3.0/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+    "recommendations": [
+        "charliermarsh.ruff",
+        "ms-python.python"
+    ]
+}

webinar_transcriber-1.3.0/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+    "python.testing.pytestArgs": [
+        "--no-cov",
+        "webinar_transcriber/tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

webinar_transcriber-1.3.0/AGENTS.md

@@ -0,0 +1,188 @@
+# AGENTS
+
+This file is the contributor and coding-agent guide for this repository.
+
+## Scope
+
+Documentation is organized by [Diátaxis](https://diataxis.fr) mode. Decide where content goes by
+what it serves, not by which file is nearest:
+
+- `README.md`: the entry point. A how-to quick start, user-facing reference (CLI flags, environment
+  variables, output layout), and a brief explanation of what the tool is.
+- `docs/pipeline.md`: explanation. How and why the stages work; no step-by-step instructions and no
+  flag tables.
+- `docs/troubleshooting.md`: how-to. Error-indexed fixes.
+- `docs/development.md`: how-to and reference. Checkout setup, running from source, and the
+  make-target and quality-gate reference.
+- `docs/releasing.md`: how-to. The release process.
+- `AGENTS.md`: contributor and coding-agent process the user docs do not need.
+
+When unsure, place content by Diátaxis axis: action for someone working is how-to, information for
+someone working is reference, understanding is explanation. Keep modes separate within a file: do
+not fold explanation into a how-to, or a flag table into the pipeline explanation.
+
+Prefer extending `README.md` first. Add a new file under `docs/` only when a section is long enough
+to obscure the user-facing flow and self-contained enough to read on its own.
+
+Repository-visible assets stay under `docs/assets/`. The README preview uses GitHub's theme
+suffixes: `social-preview.png#gh-light-mode-only` and `social-preview-dark.png#gh-dark-mode-only`.
+Keep `social-preview-dark.png` suitable for the repository social-preview setting.
+
+## Tooling
+
+Keep setup docs and Makefile targets in sync. If you add, rename, or remove a `make install*`
+target, update README in the same change. If you add, rename, or remove a `make sync*` target or
+quality-gate target, update `docs/development.md` in the same change.
+
+Use `make test` for quick iteration (fast subset, skips slow tests, no coverage gate). Run
+`make format` then `make check` before committing — `make check` is the full coverage-gated gate.
+
+GitHub Actions runs `make lint` and `make test-all` so CI mirrors the local quality gate. CI runs on
+`ubuntu-latest` and `macos-latest`; Windows is not part of the CI matrix and is treated as
+best-effort.
+
+In sandboxed Codex runs, prefer `UV_CACHE_DIR=/tmp/uv-cache` for `uv` and `make` commands to avoid
+cache-permission failures.
+
+## Definition of Done
+
+A change is ready to merge when all of the following hold:
+
+- **Quality gates pass.** `make format && make check` runs cleanly — the full coverage-gated test
+  suite, `ruff`, `ty`, and the markdown linters.
+- **100% coverage stays.** Add `# pragma: no cover` to genuinely unreachable defensive branches
+  rather than lowering the threshold.
+- **Docs stay in sync.** If the change affects CLI flags, output artifacts, install targets, package
+  layout, or runtime contracts, update `README.md` and `AGENTS.md` in the same PR.
+- **No dead code.** Remove unused imports, helpers with no callers, fields that are written or
+  serialized but never read back, and `# TODO` comments that will not be addressed in this PR.
+- **PR has a summary and a test plan.** Each pull request description includes a brief summary and
+  an explicit test-plan checklist.
+- **Commits follow Conventional Commits.** Prefix commit messages with `refactor:`, `docs:`, `ci:`,
+  `style:`, `feat:`, `fix:`, `test:`, `build:`, or `chore:`. Use an optional scope when it adds
+  clarity, for example `build(deps):`.
+
+## Package Layout
+
+The package is deliberately flat: shallow subpackages by domain (`asr`, `diarization`, `llm`,
+`transcript`, `video`, `export`) with leaf modules at the root. Read the tree directly rather than
+maintaining a copy here, and avoid adding deep nesting.
+
+## Runtime Contracts
+
+- Successful default CLI runs write the report artifact set described in `README.md`.
+- `--diarize` runs locally and adds `diarization.json` plus speaker fields on transcript segments.
+- Successful runs write `diagnostics.json`; failed runs also write it once the run directory exists,
+  though early failures can still leave only partial intermediate artifacts and no final report
+  outputs.
+- Temporary WAV audio extracted for transcription should stay outside the run directory;
+  `--keep-audio` may write the compressed `transcription-audio.mp3` artifact described in
+  `README.md`.
+
+## Testing Notes
+
+- Keep tests under `webinar_transcriber/tests/`, mirroring the package hierarchy in filenames and
+  grouping where it helps scanability. Split a test file into a sibling when it crosses roughly 800
+  lines or when the production-side module it covers has already split — for example, `llm/utils.py`
+  and `llm/processor.py` map to `test_llm_utils.py` and `test_llm.py`.
+- Prefer tiny deterministic fixtures committed to the repo.
+- Prefer `pytest` `monkeypatch` for simple state replacement and `unittest.mock.patch` when a test
+  needs mock semantics such as `side_effect`, `return_value`, or call assertions.
+- Group related tests by behavior using `class Test...` when it improves scanability; keep helpers
+  and fakes scoped to the narrowest test class that uses them, and leave them module-level only when
+  they are intentionally shared across multiple test classes or fixtures.
+- CLI tests should generally monkeypatch the reporter and heavy runtime seams instead of invoking
+  real media-processing work.
+- Use `pytest.mark.parametrize` when cases share the same setup and assertions and the test
+  naturally becomes a clear input/output table; avoid it when cases need materially different
+  fixtures, monkeypatching, or fake-object wiring.
+- Prefer asserting current observable behavior over asserting that recently removed options, fields,
+  dependencies, import paths, or artifacts are absent. Deletion-based assertions are usually shallow
+  and brittle.
+- Avoid tests that only prove one function forwards fields into another helper unless that wiring is
+  itself a meaningful behavioral contract.
+- For predicate-style tests, prefer `assert expr` / `assert not expr`. Reserve `is True` /
+  `is False` for cases where exact boolean identity matters.
+
+## Implementation Notes
+
+- When an earlier pipeline stage already guarantees an invariant, prefer enforcing that invariant
+  directly instead of carrying defensive conversion logic downstream. For example, transcription
+  audio is normalized to `16000 Hz`, so the `sherpa-onnx` Silero VAD integration should assert that
+  contract rather than silently resample.
+- Let genuine errors propagate. Reserve warnings for recoverable, user-actionable conditions; do not
+  downgrade a real failure (a failed image write, a missing required stream) into a warning that the
+  run then has to thread around.
+- The Silero VAD ONNX model is vendored under `webinar_transcriber/assets/` so default speech-region
+  detection does not require PyTorch or a first-run network download.
+- Speaker diarization uses `sherpa-onnx` with downloaded ONNX models cached under
+  `~/.cache/webinar-transcriber/diarization`; keep those model artifacts out of the wheel.
+
+## Simplification and Refactoring Notes
+
+This repo has improved repeatedly by making complexity justify itself, not the reverse. In review
+the maintainer keeps pushing past a first "this is load-bearing" reading and is usually right. Carry
+that prior: an abstraction must earn its keep, the default answer to "can this be simpler" is yes
+until the code proves otherwise, and a challenge to a conservative answer is a request for evidence.
+Grep the real readers and callers, then produce a verified cleanup or give the precise structural
+reason it can't be done and act rather than re-explain. A small flag-free helper is fine when a
+linter genuinely forces extraction; a state flag or multi-helper split to dodge one is
+over-engineering.
+
+Recurring smells to check for:
+
+- **Test-only knobs** — a param/field whose only non-default caller is a test; delete it and let
+  tests monkeypatch the constant or exercise the real contract.
+- **1:1 wrappers / single-caller helpers** that only rename one shape or forward one call; inline at
+  the call site.
+- **Write-only fields** serialized or assigned but never read back; delete unless an external
+  artifact contract consumes them.
+- **Duplicated diagnostics or serialization** — one value under two keys or two artifacts; pick the
+  single owner.
+- **Wrapper / result-object chains** threading one value through re-keying passes, or a plan/spec
+  wrapping a `min()`/`len()`; collapse to one shape or a function.
+- **Re-export / lazy-import surfaces with no production consumer**; import from the defining leaf
+  module, keeping a package re-export only to isolate an optional extra or a real public boundary.
+- **Protocols for a single in-tree implementation**; type the collaborator concretely and let tests
+  use duck-typed fakes. A Protocol earns its place only at a third-party or polymorphic seam.
+- **Fakes re-implementing production logic**; replace with a Mock-based double that runs the real
+  policy or object, so the test proves production behavior.
+- **Defensive branches guarding states an earlier stage forbids** (a guard on a positive constant, a
+  `getattr` default masking a missing attribute); assert the invariant or delete the branch.
+- **Errors downgraded to warnings** the run then threads around; let them propagate, reserving
+  warnings for recoverable, user-actionable conditions.
+- **Config bags between exactly two callers**; inline as kwargs or fields.
+- **Stale suppressions** — ruff ignores with zero hits, `type: ignore` / `cast()` that narrow away
+  with `isinstance`; re-enable or narrow, keeping only documented stub gaps.
+
+When acting: put ownership at the boundary that already knows the value (the CLI builds
+collaborators, stages record their own diagnostics, ASR owns window policy, export/report models
+carry no diagnostics-only data); prefer the narrowest cohesive cleanup with a clear before/after
+story; verify with a byte-identical fixture-artifact diff where possible over tests that only prove
+one helper forwarded to another; and make any user-visible contract change (CLI flags, artifact
+paths, JSON shapes, diagnostics or stage keys) explicit in the PR with `README.md` and `AGENTS.md`
+updated in the same change.
+
+## Style Notes
+
+- `cast()` is a runtime no-op and a smell when used purely to satisfy the type checker. Prefer
+  `isinstance()` checks for narrowing. Reserve `cast()` for genuine third-party stub gaps and always
+  add a comment explaining which stub is missing and why.
+- `# type: ignore` is the same smell. Only use it for genuine stub gaps, bare (no bracket error
+  codes — `ty` does not use mypy's `[attr-defined]` syntax), with a comment on the same or preceding
+  line.
+- When adapting third-party types that don't stub well, define a private `Protocol`. If `Any` is
+  unavoidable in a Protocol method signature due to stub-level invariance constraints, suppress ruff
+  with `# noqa: ANN401` and add a comment.
+- Bind caught exceptions as `ex` — `except SomeError as ex:` — never `as error:` or `as exc:`. The
+  same applies to `pytest.raises(...) as ex` in tests.
+- Replace `assert x is not None` guards in production code with explicit `if x is None: raise`.
+  `assert` is stripped by optimised builds and banned by ruff S101.
+- Use the walrus operator selectively when it removes repeated work without making the code harder
+  to read.
+- Prefer short loop and comprehension variable names when the surrounding context already makes the
+  meaning obvious.
+- In ASR code and artifacts, use `speech region` for VAD/planning inputs and `window` for Whisper
+  decode units; avoid `chunk` for ASR concepts.
+- Treat acronyms as words in PascalCase identifiers: `LlmProcessor`, `AsrPipelineDiagnostics`,
+  `WhisperCppTranscriber`. Constants stay SCREAMING_SNAKE: `ASR_BACKEND_NAME`, `LLM_PROVIDER_ENV`.