dinnote 0.1.0__tar.gz

dinnote-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: dinnote
+Version: 0.1.0
+Summary: Audio denoising, VAD, speaker diarization, and transcription pipeline using Demucs, Silero VAD, pyannote, and Whisper
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: demucs>=4.0.0
+Requires-Dist: torchcodec
+Requires-Dist: torch
+Requires-Dist: torchaudio
+Requires-Dist: pydub
+Requires-Dist: packaging
+Requires-Dist: pyannote.audio>=3.1.0
+Requires-Dist: openai-whisper
+Requires-Dist: pyyaml
+
+## dinnote audio transcription
+Processes audio through a four-step pipeline to produce a transcription JSON with per-speaker diarization: denoising (Demucs), voice activity detection (Silero VAD), speaker diarization (pyannote), and transcription (Whisper).
+
+### Installation
+```bash
+pip install dinnote
+```
+
+On first run, dinnote copies default config files to your platform config directory:
+- **Windows:** `%APPDATA%\dinnote\`
+- **macOS:** `~/Library/Application Support/dinnote/`
+- **Linux:** `~/.config/dinnote/`
+
+Edit `config.yaml` and `vocab.txt` to customize settings.
+
+Speaker diarization requires a HuggingFace token with access to [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1). 
+Set it via `diarize.hf_token` in `config.yaml`.
+
+
+### CLI usage
+```bash
+dinnote input/audio.mp3            # single file
+dinnote input/                     # all audio files in a folder
+dinnote input/audio.mp3 -f         # force re-run all steps
+dinnote input/audio.mp3 -c path/to/config.yaml   # custom config
+dinnote input/audio.mp3 -o results/              # custom output dir
+```
+
+Each step checks whether its output already exists and skips it if so. Use `-f` to force all steps to re-run.
+
+Output is written to `output/<filename>/` and contains:
+- `<filename>_denoised.wav` (vocals isolated from background noise)
+- `<filename>_vad.json` (detected speech segment boundaries)
+- `<filename>_diarization.json` (per-speaker turn boundaries from pyannote)
+- `<filename>_transcription.json` (final transcription with timestamps and speaker labels)
+
+
+### Python API
+```python
+from pathlib import Path
+import dinnote
+from dinnote import PipelineConfig, VadConfig, DiarizeConfig, TranscribeConfig
+
+# Run the full pipeline with defaults
+dinnote.process_file(
+    input_path=Path("recording.wav"),
+    output_dir=Path("output"),
+)
+
+# Custom config
+config = PipelineConfig(
+    vad=VadConfig(threshold=0.4, max_segment_length_sec=20),
+    diarize=DiarizeConfig(num_speakers=2),
+    transcribe=TranscribeConfig(model="small", language="en"),
+)
+dinnote.process_file(Path("recording.wav"), Path("output"), config=config)
+
+# Or use individual stages
+from dinnote import denoise, vad, diarize, transcribe
+
+denoised      = denoise.run(Path("recording.wav"), Path("output/recording"), config={})
+vad_file      = vad.run(denoised, Path("output/recording"), config={})
+diarization   = diarize.run(denoised, Path("output/recording"), config={})
+result        = transcribe.run(denoised, Path("output/recording"), config={}, diarization_path=diarization)
+```
+
+
+### Configuration
+
+```yaml
+denoise:
+  model: htdemucs        # htdemucs | htdemucs_ft | mdx | mdx_extra | htdemucs_6s
+
+vad:
+  threshold: 0.5         # 0.0–1.0, higher = requires clearer speech
+  min_speech_duration_ms: 250
+  min_silence_duration_ms: 100
+  padding_ms: 500
+  max_segment_length_sec: 30
+  merge_within_sec: 1.0
+
+diarize:
+  # hf_token: hf_...
+  num_speakers: null     # fix speaker count or leave null to let pyannote estimate
+  min_speakers: null
+  max_speakers: null
+  min_turn_ms: 200       # turns shorter than this are discarded (ms)
+
+transcribe:
+  model: base            # tiny | base | small | medium | large
+  language: en           # set to null to auto-detect
+  temperature: null      # null = Whisper fallback sequence, 0 = greedy
+  no_speech_threshold: 0.6
+  logprob_threshold: -1.0
+  compression_ratio_threshold: 2.4
+  condition_on_previous_text: false
+  vocab_file: null       # path to domain-specific vocabulary, defaults to vocab.txt in config dir
+```
+
+Add domain-specific vocabulary to `vocab.txt` to improve transcription accuracy on unusual words and jargon. For noisy or technical audio, set `temperature: 0` to disable Whisper's fallback to higher-temperature decoding, and consider filtering out common hallucinations specific to your dataset.
+
+If `num_speakers` is known in advance, setting it gives more reliable diarization. Otherwise use `min_speakers`/`max_speakers` to constrain the range, or leave both null to let pyannote estimate freely.

dinnote-0.1.0/README.md

@@ -0,0 +1,102 @@
+## dinnote audio transcription
+Processes audio through a four-step pipeline to produce a transcription JSON with per-speaker diarization: denoising (Demucs), voice activity detection (Silero VAD), speaker diarization (pyannote), and transcription (Whisper).
+
+### Installation
+```bash
+pip install dinnote
+```
+
+On first run, dinnote copies default config files to your platform config directory:
+- **Windows:** `%APPDATA%\dinnote\`
+- **macOS:** `~/Library/Application Support/dinnote/`
+- **Linux:** `~/.config/dinnote/`
+
+Edit `config.yaml` and `vocab.txt` to customize settings.
+
+Speaker diarization requires a HuggingFace token with access to [pyannote/speaker-diarization-3.1](https://huggingface.co/pyannote/speaker-diarization-3.1). 
+Set it via `diarize.hf_token` in `config.yaml`.
+
+
+### CLI usage
+```bash
+dinnote input/audio.mp3            # single file
+dinnote input/                     # all audio files in a folder
+dinnote input/audio.mp3 -f         # force re-run all steps
+dinnote input/audio.mp3 -c path/to/config.yaml   # custom config
+dinnote input/audio.mp3 -o results/              # custom output dir
+```
+
+Each step checks whether its output already exists and skips it if so. Use `-f` to force all steps to re-run.
+
+Output is written to `output/<filename>/` and contains:
+- `<filename>_denoised.wav` (vocals isolated from background noise)
+- `<filename>_vad.json` (detected speech segment boundaries)
+- `<filename>_diarization.json` (per-speaker turn boundaries from pyannote)
+- `<filename>_transcription.json` (final transcription with timestamps and speaker labels)
+
+
+### Python API
+```python
+from pathlib import Path
+import dinnote
+from dinnote import PipelineConfig, VadConfig, DiarizeConfig, TranscribeConfig
+
+# Run the full pipeline with defaults
+dinnote.process_file(
+    input_path=Path("recording.wav"),
+    output_dir=Path("output"),
+)
+
+# Custom config
+config = PipelineConfig(
+    vad=VadConfig(threshold=0.4, max_segment_length_sec=20),
+    diarize=DiarizeConfig(num_speakers=2),
+    transcribe=TranscribeConfig(model="small", language="en"),
+)
+dinnote.process_file(Path("recording.wav"), Path("output"), config=config)
+
+# Or use individual stages
+from dinnote import denoise, vad, diarize, transcribe
+
+denoised      = denoise.run(Path("recording.wav"), Path("output/recording"), config={})
+vad_file      = vad.run(denoised, Path("output/recording"), config={})
+diarization   = diarize.run(denoised, Path("output/recording"), config={})
+result        = transcribe.run(denoised, Path("output/recording"), config={}, diarization_path=diarization)
+```
+
+
+### Configuration
+
+```yaml
+denoise:
+  model: htdemucs        # htdemucs | htdemucs_ft | mdx | mdx_extra | htdemucs_6s
+
+vad:
+  threshold: 0.5         # 0.0–1.0, higher = requires clearer speech
+  min_speech_duration_ms: 250
+  min_silence_duration_ms: 100
+  padding_ms: 500
+  max_segment_length_sec: 30
+  merge_within_sec: 1.0
+
+diarize:
+  # hf_token: hf_...
+  num_speakers: null     # fix speaker count or leave null to let pyannote estimate
+  min_speakers: null
+  max_speakers: null
+  min_turn_ms: 200       # turns shorter than this are discarded (ms)
+
+transcribe:
+  model: base            # tiny | base | small | medium | large
+  language: en           # set to null to auto-detect
+  temperature: null      # null = Whisper fallback sequence, 0 = greedy
+  no_speech_threshold: 0.6
+  logprob_threshold: -1.0
+  compression_ratio_threshold: 2.4
+  condition_on_previous_text: false
+  vocab_file: null       # path to domain-specific vocabulary, defaults to vocab.txt in config dir
+```
+
+Add domain-specific vocabulary to `vocab.txt` to improve transcription accuracy on unusual words and jargon. For noisy or technical audio, set `temperature: 0` to disable Whisper's fallback to higher-temperature decoding, and consider filtering out common hallucinations specific to your dataset.
+
+If `num_speakers` is known in advance, setting it gives more reliable diarization. Otherwise use `min_speakers`/`max_speakers` to constrain the range, or leave both null to let pyannote estimate freely.

dinnote-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dinnote"
+version = "0.1.0"
+description = "Audio denoising, VAD, speaker diarization, and transcription pipeline using Demucs, Silero VAD, pyannote, and Whisper"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "demucs>=4.0.0",
+    "torchcodec",
+    "torch",
+    "torchaudio",
+    "pydub",
+    "packaging",
+    "pyannote.audio>=3.1.0",
+    "openai-whisper",
+    "pyyaml",
+]
+
+[project.scripts]
+dinnote = "dinnote.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dinnote = ["config.yaml", "vocab.txt"]

dinnote-0.1.0/setup.cfg

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

dinnote-0.1.0/src/dinnote/__init__.py

@@ -0,0 +1,8 @@
+from . import denoise, vad, diarize, transcribe
+from .pipeline import process_file
+from .config import DenoiseConfig, VadConfig, DiarizeConfig, TranscribeConfig, PipelineConfig
+
+__all__ = [
+    "denoise", "vad", "diarize", "transcribe", "process_file",
+    "DenoiseConfig", "VadConfig", "DiarizeConfig", "TranscribeConfig", "PipelineConfig",
+]

dinnote-0.1.0/src/dinnote/cli.py

@@ -0,0 +1,80 @@
+import argparse
+import sys
+import time
+from pathlib import Path
+from .utils import AUDIO_EXTENSIONS, load_config, warn_if_no_cuda, setup_user_config, fmt_time
+from .pipeline import process_file
+from .config import PipelineConfig
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Denoise, VAD, diarize, and transcribe audio files"
+    )
+    parser.add_argument("input")
+    parser.add_argument("-o", "--output", default="output")
+    parser.add_argument("-c", "--config", default=None,
+                        help="Path to config.yaml (default: user config dir)")
+    parser.add_argument("-f", "--force", action="store_true")
+    args = parser.parse_args()
+
+    config_dir = setup_user_config()
+    config_path = args.config or str(config_dir / "config.yaml")
+    raw = load_config(config_path)
+
+    transcribe_raw = raw.setdefault("transcribe", {})
+    if not transcribe_raw.get("vocab_file"):
+        vocab_path = config_dir / "vocab.txt"
+        if vocab_path.exists():
+            transcribe_raw["vocab_file"] = str(vocab_path)
+
+    config = PipelineConfig.from_dict(raw)
+    input_path = Path(args.input)
+    output_dir = Path(args.output)
+
+    if input_path.is_file():
+        if input_path.suffix.lower() not in AUDIO_EXTENSIONS:
+            print(f"Unrecognized audio extension: {input_path.suffix}")
+            sys.exit(1)
+        files = [input_path]
+    elif input_path.is_dir():
+        files = sorted(
+            f for f in input_path.iterdir()
+            if f.is_file() and f.suffix.lower() in AUDIO_EXTENSIONS
+        )
+        if not files:
+            print(f"No audio files found in {input_path}/")
+            sys.exit(1)
+    else:
+        print(f"Not found: {input_path}")
+        sys.exit(1)
+
+    print(f"Files to process: {len(files)}")
+    print(f"Output directory: {output_dir}/")
+    warn_if_no_cuda()
+
+    success = 0
+    batch_start = time.monotonic()
+
+    for i, audio_file in enumerate(files, 1):
+        if len(files) > 1:
+            print(f"\n{'═' * 60}")
+            print(f"  File {i}/{len(files)}: {audio_file.name}")
+
+        if process_file(audio_file, output_dir, config, force=args.force):
+            success += 1
+
+    failed = len(files) - success
+
+    if len(files) > 1:
+        print(f"\n{'─' * 60}")
+        print(f"  Batch complete: {success} succeeded, {failed} failed")
+        print(f"  Total time: {fmt_time(time.monotonic() - batch_start)}")
+        print(f"\n{'─' * 60}")
+
+    if failed:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

dinnote-0.1.0/src/dinnote/config.py

@@ -0,0 +1,64 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class DenoiseConfig:
+    model: str = "htdemucs"
+
+
+@dataclass
+class VadConfig:
+    threshold: float = 0.5
+    min_speech_duration_ms: Optional[int] = 250
+    min_silence_duration_ms: Optional[int] = 100
+    padding_ms: int = 500
+    max_segment_length_sec: Optional[float] = 30.0
+    """Segments longer than this are discarded as likely noise or music. None keeps all."""
+    merge_within_sec: Optional[float] = 1.0
+    """Segments with less than this gap between them are merged. None disables merging."""
+
+
+@dataclass
+class DiarizeConfig:
+    hf_token: Optional[str] = None
+    num_speakers: Optional[int] = None
+    min_speakers: Optional[int] = None
+    max_speakers: Optional[int] = None
+    min_turn_ms: int = 200
+    """Turns less than this length are discarded."""
+
+
+@dataclass
+class TranscribeConfig:
+    model: str = "base"
+    language: str = "en"
+    temperature: Optional[float] = None
+    """0 for greedy decoding, None to use Whisper's fallback sequence."""
+    no_speech_threshold: Optional[float] = 0.6
+    logprob_threshold: Optional[float] = -1.0
+    compression_ratio_threshold: Optional[float] = 2.4
+    condition_on_previous_text: bool = False
+    """Use previous segment output as context. Improves coherence but can propagate errors."""
+    vocab_file: Optional[str] = None
+
+
+@dataclass
+class PipelineConfig:
+    denoise: DenoiseConfig = field(default_factory=DenoiseConfig)
+    vad: VadConfig = field(default_factory=VadConfig)
+    diarize: DiarizeConfig = field(default_factory=DiarizeConfig)
+    transcribe: TranscribeConfig = field(default_factory=TranscribeConfig)
+
+    @staticmethod
+    def from_dict(d: dict) -> "PipelineConfig":
+        def _build(cls, section):
+            fields = {f.name for f in cls.__dataclass_fields__.values()}
+            return cls(**{k: v for k, v in section.items() if k in fields})
+
+        return PipelineConfig(
+            denoise=_build(DenoiseConfig, d.get("denoise", {})),
+            vad=_build(VadConfig, d.get("vad", {})),
+            diarize=_build(DiarizeConfig, d.get("diarize", {})),
+            transcribe=_build(TranscribeConfig, d.get("transcribe", {})),
+        )

dinnote-0.1.0/src/dinnote/config.yaml

@@ -0,0 +1,81 @@
+denoise:
+  # Demucs model used for vocal isolation.
+  # Options: htdemucs, htdemucs_ft, mdx, mdx_extra, htdemucs_6s
+  # See: https://github.com/facebookresearch/demucs
+  model: htdemucs
+
+vad:
+  # Detection sensitivity (0.0–1.0). Higher values require clearer speech to trigger.
+  # See: https://github.com/snakers4/silero-vad
+  threshold: 0.5
+
+  # Minimum duration of a detected speech region to keep (milliseconds).
+  # Set to null to use Silero's default (250ms).
+  min_speech_duration_ms: 250
+
+  # Minimum silence gap required before a new segment begins (milliseconds).
+  # Set to null to use Silero's default (100ms).
+  min_silence_duration_ms: 100
+
+  # Padding added before and after each detected segment (milliseconds).
+  # Set to null to disable padding.
+  padding_ms: 500
+
+  # Segments longer than this are discarded as likely noise or music (seconds).
+  # Set to null to keep all segments regardless of length.
+  max_segment_length_sec: 30
+
+  # Segments with less than this gap between them are merged into one (seconds).
+  # Set to null to disable merging of neighboring segments.
+  merge_within_sec: 1.0
+
+diarize:
+  # HuggingFace token with access to pyannote/speaker-diarization-3.1.
+  # hf_token: hf_...
+
+  # Fix the number of speakers if known. Set to null to let pyannote estimate.
+  num_speakers: null
+
+  # Alternatively constrain the range and let pyannote pick within it.
+  min_speakers: null
+  max_speakers: null
+
+  # Turns shorter than this are discarded (milliseconds).
+  min_turn_ms: 200
+
+transcribe:
+  # Whisper model size. Larger models are slower but more accurate.
+  # Options: tiny, base, small, medium, large
+  # See: https://github.com/openai/whisper
+  model: base
+
+  # Language code for transcription.
+  # Examples: en, fr, de, es, ja. Set to null to auto-detect.
+  language: en
+
+  # Decoding temperature.
+  # Set to 0 for single-pass greedy decoding with no fallback.
+  # Set to null to use Whisper's default fallback sequence (0.0, 0.2, …, 1.0),
+  # retrying at higher temperatures when output quality metrics look poor.
+  temperature: null
+
+  # Segments where Whisper's no-speech probability exceeds this are discarded.
+  # Set to null to use Whisper's default (0.6).
+  no_speech_threshold: 0.6
+
+  # Segments with average log-probability below this are discarded as likely low-quality audio.
+  # Set to null to use Whisper's default (-1.0).
+  logprob_threshold: -1.0
+
+  # Segments with compression ratio above this are discarded as likely hallucinations.
+  # Set to null to use Whisper's default (2.4).
+  compression_ratio_threshold: 2.4
+
+  # Whether Whisper should use the previous segment's output as context for the next.
+  # Improves coherence across segments but can propagate errors.
+  # Default: false.
+  condition_on_previous_text: false
+
+  # Path to a file containing domain-specific vocabulary to guide transcription.
+  # Set to null to disable.
+  vocab_file: vocab.txt

dinnote-0.1.0/src/dinnote/denoise.py

@@ -0,0 +1,59 @@
+"""
+Uses Demucs to isolate vocals in audio.
+"""
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from .utils import cuda_available
+
+
+def _ffmpeg_env():
+    """Return env with FFmpeg bin dir on PATH so subprocess can load torchcodec DLLs."""
+    import glob as g
+    env = dict(os.environ)
+    if sys.platform != "win32":
+        return env
+    local_appdata = env.get("LOCALAPPDATA", "")
+    winget_packages = os.path.join(local_appdata, "Microsoft", "WinGet", "Packages")
+    for bin_dir in g.glob(os.path.join(winget_packages, "Gyan.FFmpeg.Shared*", "**", "bin"), recursive=True):
+        if any(g.glob(os.path.join(bin_dir, "avcodec-*.dll"))):
+            env["PATH"] = bin_dir + os.pathsep + env.get("PATH", "")
+            break
+    return env
+
+
+def _run_demucs(input_file: Path, output_file: Path, model: str = "htdemucs", device: str = "cpu"):
+    """Run Demucs and copy the vocals stem to the destination path."""
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        tmp_path = Path(tmp_dir)
+
+        result = subprocess.run(
+            [sys.executable, "-m", "demucs", "-n", model, "--two-stems=vocals",
+             "--device", device, "-o", str(tmp_path), str(input_file)],
+            env=_ffmpeg_env(),
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"demucs exited with code {result.returncode}")
+
+        vocals_path = tmp_path / model / input_file.stem / "vocals.wav"
+        if not vocals_path.exists():
+            raise FileNotFoundError(f"Demucs output not found: {vocals_path}")
+
+        shutil.copy2(vocals_path, output_file)
+
+
+def run(input_path: Path, output_dir: Path, config: dict, force: bool = False) -> Path:
+    """Denoise a single audio file using Demucs vocal isolation. Returns path to denoised .wav."""
+    output_file = output_dir / f"{output_dir.name}_denoised.wav"
+    if not force and output_file.exists():
+        return output_file
+
+    model = config.get("model", "htdemucs")
+    device = "cuda" if cuda_available() else "cpu"
+    output_dir.mkdir(parents=True, exist_ok=True)
+    _run_demucs(input_path, output_file, model=model, device=device)
+    return output_file