echovault-flac-enhancer 0.1.0__tar.gz

echovault_flac_enhancer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+        include:
+          - os: windows-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev]
+      - run: ruff check .
+      - run: black --check .
+      - run: pytest -m "not slow"

echovault_flac_enhancer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

echovault_flac_enhancer-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/
+venv/

echovault_flac_enhancer-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Initial release: `--setup`, `--check`, `--file-name`, `--folder`
+  (`--recursive`, `--skip-existing`, `--output-dir`) CLI commands.
+- Model download/verification against a GitHub Release asset, ported from
+  EchoVault's own `downloader.js`.

echovault_flac_enhancer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EchoVault contributors
+
+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.

echovault_flac_enhancer-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: echovault-flac-enhancer
+Version: 0.1.0
+Summary: Standalone CLI for batch-enhancing lossy audio to FLAC via EchoVault's ONNX model
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mutagen>=1.47
+Requires-Dist: numpy>=1.26
+Requires-Dist: onnxruntime==1.20.1
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: scipy>=1.11
+Requires-Dist: soundfile>=0.13.1
+Requires-Dist: tqdm>=4.66
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# echovault-flac-enhancer
+
+Standalone CLI for bulk-enhancing lossy audio (MP3/AAC/OGG/WMA) to FLAC using
+the same ONNX model EchoVault's desktop app uses, independent of Electron.
+
+## Install
+
+```bash
+pip install echovault-flac-enhancer
+```
+
+## Usage
+
+```bash
+# One-time: download the model and verify everything works
+echovault-flac-enhancer --setup
+
+# Check runtime/deps/model status
+echovault-flac-enhancer --check
+
+# Enhance a single file
+echovault-flac-enhancer --file-name path/to/track.mp3
+
+# Enhance every lossy track in a folder
+echovault-flac-enhancer --folder path/to/music [--recursive] [--skip-existing] [--output-dir DIR]
+```
+
+Outputs are written as `<original-stem>.enhanced.flac` alongside the source
+(or under `--output-dir`, mirroring the source's relative subpath).
+
+The model (~107MB) is cached at:
+
+- Linux/macOS: `~/.cache/echovault-flac-enhancer/model/`
+- Windows: `%LOCALAPPDATA%\echovault-flac-enhancer\model\`
+
+## Non-goals (v1)
+
+- No GUI — CLI only.
+- No parallel/multi-worker inference (`--workers` must be `1`).
+- No mid-batch resume — re-run with `--skip-existing` to pick up where a
+  killed batch left off.
+- `.m4a` files are not auto-globbed by `--folder` (ambiguous AAC vs. ALAC
+  codec-in-container — pass an `.m4a` explicitly via `--file-name` if you're
+  sure it's lossy AAC).
+
+## Releasing
+
+Before `--setup` works for end users, a maintainer must create a GitHub
+Release on this repo and upload `model.onnx` + `config.json` as release
+assets, matching the URL/hashes pinned in
+`echovault_flac_enhancer/data/manifest.json`.

echovault_flac_enhancer-0.1.0/README.md

@@ -0,0 +1,51 @@
+# echovault-flac-enhancer
+
+Standalone CLI for bulk-enhancing lossy audio (MP3/AAC/OGG/WMA) to FLAC using
+the same ONNX model EchoVault's desktop app uses, independent of Electron.
+
+## Install
+
+```bash
+pip install echovault-flac-enhancer
+```
+
+## Usage
+
+```bash
+# One-time: download the model and verify everything works
+echovault-flac-enhancer --setup
+
+# Check runtime/deps/model status
+echovault-flac-enhancer --check
+
+# Enhance a single file
+echovault-flac-enhancer --file-name path/to/track.mp3
+
+# Enhance every lossy track in a folder
+echovault-flac-enhancer --folder path/to/music [--recursive] [--skip-existing] [--output-dir DIR]
+```
+
+Outputs are written as `<original-stem>.enhanced.flac` alongside the source
+(or under `--output-dir`, mirroring the source's relative subpath).
+
+The model (~107MB) is cached at:
+
+- Linux/macOS: `~/.cache/echovault-flac-enhancer/model/`
+- Windows: `%LOCALAPPDATA%\echovault-flac-enhancer\model\`
+
+## Non-goals (v1)
+
+- No GUI — CLI only.
+- No parallel/multi-worker inference (`--workers` must be `1`).
+- No mid-batch resume — re-run with `--skip-existing` to pick up where a
+  killed batch left off.
+- `.m4a` files are not auto-globbed by `--folder` (ambiguous AAC vs. ALAC
+  codec-in-container — pass an `.m4a` explicitly via `--file-name` if you're
+  sure it's lossy AAC).
+
+## Releasing
+
+Before `--setup` works for end users, a maintainer must create a GitHub
+Release on this repo and upload `model.onnx` + `config.json` as release
+assets, matching the URL/hashes pinned in
+`echovault_flac_enhancer/data/manifest.json`.

echovault_flac_enhancer-0.1.0/echovault_flac_enhancer/__init__.py

@@ -0,0 +1,3 @@
+"""echovault-flac-enhancer: standalone CLI wrapper around EchoVault's ONNX FLAC enhancer."""
+
+__version__ = "0.1.0"

echovault_flac_enhancer-0.1.0/echovault_flac_enhancer/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

echovault_flac_enhancer-0.1.0/echovault_flac_enhancer/batch.py

@@ -0,0 +1,181 @@
+"""Single-file and batch enhancement: spawns inference.py, parses its stdout/stderr
+contract, and drives sequential batch processing over a folder of tracks."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from typing import Callable, NamedTuple
+
+LOSSY_EXTENSIONS = {
+    ".mp3",
+    ".aac",
+    ".ogg",
+    ".wma",
+}  # .m4a excluded: ambiguous AAC-vs-ALAC codec-in-container
+
+PROGRESS_RE = re.compile(r"^PROGRESS\s+(\d+)$")
+DONE_RE = re.compile(r"^DONE\s+(.+)$")
+ERROR_RE = re.compile(r"ERROR\s+(\w+)\s*(.*)")
+
+EXIT_CODE_FALLBACK = {
+    1: "GENERIC",
+    2: "INPUT_READ_FAILED",
+    3: "MODEL_NOT_FOUND",
+    4: "ORT_INIT_FAILED",
+}
+
+
+class InferenceResult(NamedTuple):
+    success: bool
+    output_path: Path | None
+    error_code: str | None
+    error_message: str | None
+
+
+def run_single_file(
+    inference_script: Path,
+    model_path: Path,
+    config_path: Path,
+    input_path: Path,
+    output_path: Path,
+    on_progress: Callable[[int], None] = lambda pct: None,
+) -> InferenceResult:
+    proc = subprocess.Popen(
+        [
+            sys.executable,
+            str(inference_script),
+            "--model",
+            str(model_path),
+            "--config",
+            str(config_path),
+            "--input",
+            str(input_path),
+            "--output",
+            str(output_path),
+            "--provider",
+            "auto",
+        ],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+    stderr_lines: list[str] = []
+
+    def drain_stderr() -> None:
+        for line in proc.stderr:
+            stderr_lines.append(line.rstrip("\n"))
+
+    stderr_thread = threading.Thread(target=drain_stderr, daemon=True)
+    stderr_thread.start()
+
+    done_path: Path | None = None
+    for line in proc.stdout:
+        line = line.strip()
+        if m := PROGRESS_RE.match(line):
+            on_progress(int(m.group(1)))
+        elif m := DONE_RE.match(line):
+            done_path = Path(m.group(1))
+
+    returncode = proc.wait()
+    stderr_thread.join()
+
+    if returncode == 0:
+        if done_path is not None and done_path != output_path:
+            print(
+                f"WARN inference reported DONE {done_path}, expected {output_path}",
+                file=sys.stderr,
+            )
+        return InferenceResult(
+            success=True, output_path=output_path, error_code=None, error_message=None
+        )
+
+    error_code = None
+    error_message = None
+    for line in stderr_lines:
+        if m := ERROR_RE.search(line):
+            error_code = m.group(1)
+            error_message = m.group(2).strip() or None
+            break
+    if error_code is None:
+        error_code = EXIT_CODE_FALLBACK.get(returncode, "GENERIC")
+
+    return InferenceResult(
+        success=False,
+        output_path=None,
+        error_code=error_code,
+        error_message=error_message,
+    )
+
+
+def resolve_files(folder: Path, recursive: bool) -> list[Path]:
+    candidates = folder.rglob("*") if recursive else folder.glob("*")
+    return sorted(
+        p for p in candidates if p.is_file() and p.suffix.lower() in LOSSY_EXTENSIONS
+    )
+
+
+def output_path_for(
+    input_path: Path, source_root: Path, output_dir: Path | None
+) -> Path:
+    stem_name = f"{input_path.stem}.enhanced.flac"
+    if output_dir is None:
+        return input_path.with_name(stem_name)
+    rel_parent = input_path.parent.relative_to(source_root)
+    dest_dir = output_dir / rel_parent
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    return dest_dir / stem_name
+
+
+def should_skip(output_path: Path) -> bool:
+    return output_path.exists()
+
+
+class BatchSummary(NamedTuple):
+    succeeded: list[Path]
+    skipped: list[Path]
+    failed: list[tuple[Path, str, str]]  # (input_path, error_code, message)
+
+
+def run_batch(
+    files: list[Path],
+    source_root: Path,
+    model_path: Path,
+    config_path: Path,
+    inference_script: Path,
+    output_dir: Path | None,
+    skip_existing: bool,
+    on_file_progress: Callable[[Path, int, int, int], None] = lambda *a: None,
+) -> BatchSummary:
+    succeeded: list[Path] = []
+    skipped: list[Path] = []
+    failed: list[tuple[Path, str, str]] = []
+
+    for i, input_path in enumerate(files, start=1):
+        out_path = output_path_for(input_path, source_root, output_dir)
+        if skip_existing and should_skip(out_path):
+            skipped.append(input_path)
+            continue
+
+        result = run_single_file(
+            inference_script,
+            model_path,
+            config_path,
+            input_path,
+            out_path,
+            on_progress=lambda pct, idx=i, total=len(
+                files
+            ), p=input_path: on_file_progress(p, idx, total, pct),
+        )
+        if result.success:
+            succeeded.append(input_path)
+        else:
+            failed.append(
+                (input_path, result.error_code or "GENERIC", result.error_message or "")
+            )
+
+    return BatchSummary(succeeded=succeeded, skipped=skipped, failed=failed)

echovault_flac_enhancer-0.1.0/echovault_flac_enhancer/cli.py

@@ -0,0 +1,181 @@
+"""argparse CLI surface: --folder/--file-name/--setup/--check."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from tqdm import tqdm
+
+from . import batch, model_manager
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="echovault-flac-enhancer")
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument(
+        "--folder", type=Path, help="Enhance all lossy tracks in a folder"
+    )
+    mode.add_argument("--file-name", type=Path, help="Enhance a single track")
+    mode.add_argument(
+        "--setup",
+        action="store_true",
+        help="Download/verify the model and run a self-test",
+    )
+    mode.add_argument(
+        "--check",
+        action="store_true",
+        help="Report runtime/deps/model/self-test status",
+    )
+
+    parser.add_argument(
+        "--recursive", action="store_true", help="Walk subfolders (only with --folder)"
+    )
+    parser.add_argument(
+        "--workers", type=int, default=1, help="Parallel workers (v1: must be 1)"
+    )
+    parser.add_argument(
+        "--skip-existing",
+        action="store_true",
+        help="Skip files with an existing enhanced output",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=Path,
+        default=None,
+        help="Write outputs here instead of alongside sources",
+    )
+    return parser
+
+
+def _cmd_setup() -> int:
+    def on_progress(name: str, done: int, total: int) -> None:
+        pct = round(done / total * 100) if total else 0
+        print(f"Downloading {name}: {pct}%", end="\r")
+
+    print("Downloading model assets...")
+    paths = model_manager.ensure_model_assets(on_progress)
+    print("\nRunning self-test...")
+    inference_script = model_manager.inference_script_path()
+    if model_manager.run_self_test(
+        inference_script, paths.model_path, paths.config_path
+    ):
+        print("SELF-TEST PASS")
+        return 0
+    print("SELF-TEST FAILED", file=sys.stderr)
+    return 1
+
+
+def _cmd_check() -> int:
+    status = model_manager.check_status()
+    print("Dependencies:")
+    for name, version in status["deps"].items():
+        print(f"  {name}: {version if version else 'MISSING'}")
+    print(
+        f"Model:  ok={status['model']['ok']}  ({status['model']['reason']})  {status['model']['path']}"
+    )
+    print(
+        f"Config: ok={status['config']['ok']}  ({status['config']['reason']})  {status['config']['path']}"
+    )
+    return (
+        0
+        if status["model"]["ok"]
+        and status["config"]["ok"]
+        and all(status["deps"].values())
+        else 1
+    )
+
+
+def _print_summary(summary: batch.BatchSummary) -> None:
+    print(
+        f"\nSucceeded: {len(summary.succeeded)}  Skipped: {len(summary.skipped)}  Failed: {len(summary.failed)}"
+    )
+    for path, code, message in summary.failed:
+        print(f"  FAILED {path}: {code} {message}")
+
+
+def _cmd_file(args: argparse.Namespace) -> int:
+    paths = model_manager.ensure_model_assets()
+    inference_script = model_manager.inference_script_path()
+    input_path: Path = args.file_name
+    output_path = batch.output_path_for(input_path, input_path.parent, args.output_dir)
+
+    with tqdm(total=100, desc=input_path.name) as bar:
+
+        def on_progress(pct: int) -> None:
+            bar.n = pct
+            bar.refresh()
+
+        result = batch.run_single_file(
+            inference_script,
+            paths.model_path,
+            paths.config_path,
+            input_path,
+            output_path,
+            on_progress,
+        )
+
+    if result.success:
+        print(f"DONE {result.output_path}")
+        return 0
+    print(f"ERROR {result.error_code} {result.error_message}", file=sys.stderr)
+    return {"MODEL_NOT_FOUND": 3, "INPUT_READ_FAILED": 2, "ORT_INIT_FAILED": 4}.get(
+        result.error_code, 1
+    )
+
+
+def _cmd_folder(args: argparse.Namespace) -> int:
+    if args.workers > 1:
+        print(
+            "ERROR: parallel workers not implemented yet — v2. Use --workers 1.",
+            file=sys.stderr,
+        )
+        return 1
+
+    folder: Path = args.folder
+    files = batch.resolve_files(folder, args.recursive)
+    if not files:
+        print("No lossy tracks found.")
+        return 0
+
+    paths = model_manager.ensure_model_assets()
+    inference_script = model_manager.inference_script_path()
+
+    outer = tqdm(total=len(files), position=0, desc="Batch")
+    inner = tqdm(total=100, position=1, leave=False)
+
+    def on_file_progress(path: Path, idx: int, total: int, pct: int) -> None:
+        outer.set_postfix_str(f"Track {idx}/{total}")
+        inner.n = pct
+        inner.refresh()
+
+    summary = batch.run_batch(
+        files,
+        folder,
+        paths.model_path,
+        paths.config_path,
+        inference_script,
+        args.output_dir,
+        args.skip_existing,
+        on_file_progress=on_file_progress,
+    )
+    for _ in files:
+        outer.update(1)
+        inner.reset()
+    outer.close()
+    inner.close()
+
+    _print_summary(summary)
+    return 0 if not summary.failed else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.setup:
+        return _cmd_setup()
+    if args.check:
+        return _cmd_check()
+    if args.file_name:
+        return _cmd_file(args)
+    return _cmd_folder(args)

echovault_flac_enhancer-0.1.0/echovault_flac_enhancer/data/manifest.json

@@ -0,0 +1,14 @@
+{
+  "version": "1.0.0",
+  "baseUrl": "https://github.com/EchoVaultHQ/EchoVault-FLAC-Enhancer/releases/download/v0.1.0",
+  "model": {
+    "file": "model.onnx",
+    "sha256": "b08db07825ebb164a927e9ef50dc5e566d1c13c0515af039fc2350b7a523c379",
+    "bytes": 112608277
+  },
+  "config": {
+    "file": "config.json",
+    "sha256": "5368dceb6297a20fb1ea3768ffc132585776a2edc173c0e164d8ce1bc871425a",
+    "bytes": 280
+  }
+}

echovault_flac_enhancer-0.1.0/echovault_flac_enhancer/data/requirements-onnx.txt

@@ -0,0 +1,5 @@
+onnxruntime==1.20.1
+soundfile>=0.13.1
+numpy>=1.26
+scipy>=1.11
+mutagen>=1.47