first commit

Author: Repulsiveprogress

.env.example

@@ -0,0 +1,8 @@
+MATRIX_HS_URL=https://matrix.example.org
+MATRIX_USER_ID=@transcriptbot:example.org
+MATRIX_ACCESS_TOKEN=syt_...
+
+# Optional
+LOCALE=en
+ASR_MODEL_NAME=nvidia/parakeet-tdt-0.6b-v2
+MAX_AUDIO_BYTES=26214400

.github/workflows/lint.yml

@@ -0,0 +1,78 @@
+name: Lint & Security
+
+on:
+  push:
+    branches: ["main", "master"]
+  pull_request:
+    branches: ["main", "master"]
+
+jobs:
+  ruff:
+    name: Ruff (lint + format)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Lint
+        run: ruff check src/
+
+      - name: Format check
+        run: ruff format --check src/
+
+  bandit:
+    name: Bandit (security)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install bandit
+        run: pip install "bandit[toml]"
+
+      - name: Run bandit
+        run: bandit -r src/ -c pyproject.toml --format json -o bandit-report.json --exit-zero
+
+      - name: Print bandit report
+        if: always()
+        run: |
+          if [ -f bandit-report.json ]; then
+            python - <<'EOF'
+          import json, sys
+          with open("bandit-report.json") as f:
+              r = json.load(f)
+          issues = r.get("results", [])
+          if not issues:
+              print("No security issues found.")
+              sys.exit(0)
+          for i in issues:
+              sev = i["issue_severity"]
+              conf = i["issue_confidence"]
+              text = i["issue_text"]
+              loc = f"{i['filename']}:{i['line_number']}"
+              print(f"[{sev}/{conf}] {loc}: {text}")
+          high = [i for i in issues if i["issue_severity"] == "HIGH"]
+          if high:
+              print(f"\n{len(high)} HIGH severity issue(s) found — failing.")
+              sys.exit(1)
+          EOF
+          fi
+
+      - name: Upload bandit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: bandit-report
+          path: bandit-report.json
+          if-no-files-found: ignore

Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.11-slim
+
+# ffmpeg is required by pydub for audio decoding/conversion
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install CPU-only PyTorch first as a separate layer — saves ~2 GB vs CUDA wheels
+RUN pip install --no-cache-dir \
+    torch \
+    torchaudio \
+    --extra-index-url https://download.pytorch.org/whl/cpu
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY src ./src
+
+# Mount a volume here to cache the 2.4 GB Parakeet checkpoint across container restarts
+ENV NEMO_CACHE_DIR=/models
+ENV PYTHONUNBUFFERED=1
+
+CMD ["python", "-m", "src.main"]

docker-compose.yml

@@ -0,0 +1,7 @@
+services:
+  bot:
+    build: .
+    restart: unless-stopped
+    env_file: .env
+    volumes:
+      - ./models:/models

pyproject.toml

@@ -0,0 +1,30 @@
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "UP", "B", "C4", "SIM", "S", "T20", "RUF",
+]
+ignore = [
+    "S101",
+    "S104",
+    "S311",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/__init__.py" = ["F401"]
+"src/strings.py" = ["RUF001"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.bandit]
+targets = ["src"]
+severity = "medium"
+confidence = "medium"
+skips = ["B101", "B311"]

requirements-dev.txt

@@ -0,0 +1,2 @@
+ruff>=0.4.0
+bandit[toml]>=1.7.0

requirements.txt

@@ -0,0 +1,8 @@
+matrix-nio>=0.24.0,<0.26
+pydantic-settings>=2.2.0
+aiohttp>=3.9.0
+nemo_toolkit[asr]>=2.0.0
+torch>=2.0.0
+torchaudio>=2.0.0
+pydub>=0.25.1
+soundfile>=0.12.1

src/__init__.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import io
+import logging
+import tempfile
+from urllib.parse import quote
+
+import aiohttp
+from nio import AsyncClient
+
+logger = logging.getLogger(__name__)
+
+_MIME_TO_PYDUB: dict[str, str] = {
+    "audio/ogg": "ogg",
+    "audio/opus": "ogg",
+    "application/ogg": "ogg",
+    "audio/webm": "webm",
+    "audio/mp4": "mp4",
+    "audio/m4a": "mp4",
+    "audio/x-m4a": "mp4",
+    "audio/aac": "aac",
+    "audio/flac": "flac",
+    "audio/x-flac": "flac",
+    "audio/mpeg": "mp3",
+    "audio/mp3": "mp3",
+    "audio/wav": "wav",
+    "audio/x-wav": "wav",
+    "audio/wave": "wav",
+}
+
+
+def _pydub_format(mime: str) -> str:
+    return _MIME_TO_PYDUB.get(mime.lower().split(";")[0].strip(), "ogg")
+
+
+def _parse_mxc(mxc_url: str) -> tuple[str, str] | None:
+    if not mxc_url.startswith("mxc://"):
+        return None
+    parts = mxc_url[len("mxc://"):].split("/", 1)
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        return None
+    return parts[0], parts[1]
+
+
+class AudioConverter:
+    """Downloads Matrix audio content and converts it to 16 kHz mono WAV."""
+
+    def __init__(self, matrix: AsyncClient, max_bytes: int) -> None:
+        self._matrix = matrix
+        self._max_bytes = max_bytes
+
+    async def download_mxc(self, mxc_url: str) -> bytes | None:
+        """Download mxc:// URL via authenticated v1 endpoint with legacy fallback."""
+        parsed = _parse_mxc(mxc_url)
+        if parsed is None:
+            logger.warning("Invalid mxc URL: %s", mxc_url)
+            return None
+        server, media_id = parsed
+
+        homeserver = self._matrix.homeserver.rstrip("/")
+        token = self._matrix.access_token
+
+        urls = [
+            f"{homeserver}/_matrix/client/v1/media/download/{quote(server)}/{quote(media_id)}",
+            f"{homeserver}/_matrix/media/v3/download/{quote(server)}/{quote(media_id)}",
+            f"{homeserver}/_matrix/media/r0/download/{quote(server)}/{quote(media_id)}",
+        ]
+
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+
+        async with aiohttp.ClientSession() as session:
+            for url in urls:
+                try:
+                    async with session.get(url, headers=headers) as resp:
+                        if resp.status != 200:
+                            continue
+                        content_length = resp.content_length
+                        if content_length and content_length > self._max_bytes:
+                            logger.warning("Audio too large: %d bytes", content_length)
+                            return None
+                        data = await resp.content.read(self._max_bytes + 1)
+                        if len(data) > self._max_bytes:
+                            logger.warning("Audio exceeds max bytes after download")
+                            return None
+                        return data
+                except aiohttp.ClientError:
+                    logger.exception("Download failed for %s", url)
+                    continue
+
+        logger.error("All download URLs failed for mxc: %s", mxc_url)
+        return None
+
+    def convert_to_wav(self, audio_bytes: bytes, mime: str) -> str | None:
+        """Convert raw audio bytes to a temporary 16 kHz mono WAV file.
+
+        Returns the temp file path, or None on failure.
+        Caller must delete the file (e.g. via os.unlink in a finally block).
+        Blocking — must be called via run_in_executor.
+        """
+        from pydub import AudioSegment  # noqa: PLC0415
+
+        fmt = _pydub_format(mime)
+        try:
+            seg = AudioSegment.from_file(io.BytesIO(audio_bytes), format=fmt)
+            seg = seg.set_frame_rate(16000).set_channels(1).set_sample_width(2)
+            tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)
+            seg.export(tmp.name, format="wav")
+            tmp.close()
+            return tmp.name
+        except Exception:
+            logger.exception("Audio conversion failed (mime=%s)", mime)
+            return None