avialsync 0.1.0b5__tar.gz

avialsync-0.1.0b5/.flake8

@@ -0,0 +1,21 @@
+# Ruff is this project's linter and formatter (AGENTS.md "How to run things").
+# This file exists only so an editor-integrated flake8 agrees with it instead of
+# reporting a wall of E501 against its own 79-column default.
+[flake8]
+max-line-length = 100
+extend-ignore =
+    # Slice spacing and line breaks before binary operators are how the
+    # project's formatter writes code; flake8's defaults predate it.
+    E203,
+    W503,
+    # Ruff owns these, configured in pyproject.toml [tool.ruff.lint].
+    E501
+exclude =
+    .git,
+    __pycache__,
+    build,
+    dist,
+    graphify-out,
+    .mypy_cache,
+    .pytest_cache,
+    .ruff_cache

avialsync-0.1.0b5/.gitattributes

@@ -0,0 +1,5 @@
+# Generated developer visualisation; retain it in Git without affecting language statistics.
+graphify-out/graph.html linguist-generated
+
+# Shell packaging helpers are executed by Bash in Windows checkout tests too.
+*.sh text eol=lf

avialsync-0.1.0b5/.githooks/post-commit

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Local developer convenience only. It never stages, commits, pushes, or runs in CI.
+if command -v graphify >/dev/null 2>&1; then
+    graphify update . --no-cluster
+else
+    printf '%s\n' 'graphify is not installed; graph was not refreshed.' >&2
+fi

avialsync-0.1.0b5/.githooks/pre-commit

@@ -0,0 +1,25 @@
+#!/bin/sh
+# Refuse to commit raw recording data.
+#
+# These directories are gitignored, but an ignore rule is not a guarantee: a
+# `git stash` that happens to include .gitignore, or a `git add -f`, re-exposes
+# them. Field recordings are private research data and are large; once pushed
+# they are effectively permanent. This checks what is actually staged.
+
+staged=$(git diff --cached --name-only --diff-filter=A)
+[ -z "$staged" ] && exit 0
+
+offenders=$(printf '%s\n' "$staged" | grep -E '^([0-2][0-9]-[0-5][0-9]-[0-5][0-9]|TENSS26_Anzal)/' || true)
+
+if [ -n "$offenders" ]; then
+    printf '%s\n' 'pre-commit: refusing to commit raw recording data.' >&2
+    printf '%s\n' '' >&2
+    printf '%s\n' "$offenders" | head -20 >&2
+    count=$(printf '%s\n' "$offenders" | wc -l | tr -d ' ')
+    [ "$count" -gt 20 ] && printf '  ... and %s more\n' "$((count - 20))" >&2
+    printf '%s\n' '' >&2
+    printf '%s\n' 'Unstage them:  git reset HEAD -- <path>' >&2
+    printf '%s\n' 'If this is genuinely intended, commit with --no-verify.' >&2
+    exit 1
+fi
+exit 0

avialsync-0.1.0b5/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Something behaves incorrectly
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Please do not attach private research data. If the bug only reproduces
+        on your own recordings, describe their shape instead (rate, duration,
+        channel count, container) and we will try to build a matching fixture.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you did, what you expected, and what actually happened.
+      placeholder: |
+        1. Opened a session with 3 cameras and a 50 kHz CSV
+        2. Dragged the seek bar to ~00:04:12 and released
+        3. Expected the plots and video to land on the same instant
+        4. The middle camera stayed one frame behind until I paused
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: AvialSync version
+      placeholder: "0.1.0b4, or a commit SHA"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options: [Windows, macOS, Linux]
+    validations:
+      required: true
+
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics
+      description: >
+        Help → Diagnostics → "Copy diagnostics", pasted here. This carries your
+        Python and Qt versions, libmpv availability, hardware-decode support,
+        and disk speed — it answers most of the follow-up questions at once.
+      render: text
+
+  - type: textarea
+    id: sources
+    attributes:
+      label: Sources loaded (timing issues only)
+      description: >
+        For a synchronisation or timing problem: which sources were loaded, what
+        their offsets and drift were, and whether any accepted TTL alignment was
+        in effect. This is usually the whole answer.

avialsync-0.1.0b5/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or usage help
+    url: https://github.com/anzalks/avialsync/discussions
+    about: For "how do I…" questions, please use Discussions rather than an issue.

avialsync-0.1.0b5/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,37 @@
+name: Feature request
+description: Suggest a capability
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        AvialSync is a visual inspection tool. Acquisition and built-in
+        scientific analysis are deliberately out of scope — those belong in
+        plugins. See BLUEPRINT.md for the scope boundary.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What are you trying to do
+      description: >
+        Describe the research task, not the feature. "I need to check whether
+        the encoder and the cameras drifted apart over an hour" tells us more
+        than "add a drift graph".
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: How do you do it today
+      description: What you currently do instead, and why that is unsatisfying.
+
+  - type: dropdown
+    id: layer
+    attributes:
+      label: Does this belong in core or in a plugin?
+      description: Lab-specific formats and event semantics are plugin territory.
+      options:
+        - Not sure
+        - Core — every user needs it
+        - Plugin — specific to my lab's formats or workflow

avialsync-0.1.0b5/.github/pull_request_template.md

@@ -0,0 +1,35 @@
+## What and why
+
+<!-- What changed, and the problem it solves. Link the issue if there is one. -->
+
+## How it was verified
+
+<!-- The actual commands and their results, not "tests pass". If you fixed a
+     bug, say how you reproduced it first. -->
+
+```
+conda run -n avialsync ruff check .
+conda run -n avialsync mypy src/avialsync/core
+conda run -n avialsync mypy src/avialsync
+QT_QPA_PLATFORM=offscreen conda run -n avialsync pytest -q --ignore=tests/benchmarks
+```
+
+## Checklist
+
+- [ ] Tests ship with the code (`core/` logic → unit tests; UI behaviour →
+      pytest-qt; performance-relevant → benchmark)
+- [ ] All four gate commands pass locally
+- [ ] No test was weakened, skipped, or `# type: ignore`d to make this land
+- [ ] `tests/test_sync_golden.py` untouched and passing (required for any change
+      to `core/timeline.py`, the playback loop, or seek logic)
+- [ ] No performance budget regressed by more than 20 % on touched benchmarks
+- [ ] `HANDOUT.md` updated if this changes a module's public API, adds a trap,
+      or fixes a listed bug
+- [ ] `DECISIONS.md` entry added if this makes a choice future contributors
+      must not silently reverse
+- [ ] New dependency? Licence named here, and it is not GPL/AGPL
+
+## Anything reviewers should look at closely
+
+<!-- Trade-offs you made, things you were unsure about, or areas where you would
+     like a second opinion. Saying "I am not certain about X" is welcome. -->

avialsync-0.1.0b5/.github/workflows/ci.yml

@@ -0,0 +1,140 @@
+# Correctness on every push, on every branch: lint, types, and the full
+# OS x Python test matrix. Nothing here freezes a bundle or builds an
+# installer — that work belongs to a release tag and lives in release.yml,
+# which additionally refuses any tag not reachable from main.
+name: CI
+
+on:
+  push:
+    # Every branch, not just main. Work sat on a feature branch for weeks with
+    # no CI at all, so the first signal would have arrived at merge time.
+    branches: [ "**" ]
+  pull_request:
+    branches: [ "main" ]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  PYTHONUTF8: 1
+  QT_QPA_PLATFORM: offscreen
+
+jobs:
+  lint-type:
+    name: Lint & Type Check
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Ruff Check
+        run: ruff check .
+      - name: Ruff Format Check
+        run: ruff format --check .
+      - name: Mypy Core
+        run: mypy src/avialsync/core
+      - name: Mypy All (standard mode; pre-existing errors suppressed in pyproject.toml)
+        run: mypy src/avialsync
+
+  test:
+    name: Test ${{ matrix.os }} - Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    needs: lint-type
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-15, windows-2022]
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+      
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          
+      # --no-install-recommends is load-bearing, not tidiness: ffmpeg's
+      # recommends pull yt-dlp, pipewire and a 27 MB pocketsphinx speech model,
+      # none of which encode a fixture. A slow archive mirror spent twelve
+      # minutes on them and took the whole 15-minute job down with it. The
+      # codecs the fixtures need (libx264, libx265) are depends, not
+      # recommends, and the Make Fixtures step below proves they arrived.
+      - name: Install System Dependencies (Ubuntu)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends -o Acquire::Retries=3 ffmpeg libmpv2 libegl1
+        
+      - name: Install System Dependencies (macOS)
+        if: runner.os == 'macOS'
+        run: brew install ffmpeg mpv
+        
+      - name: Install System Dependencies (Windows)
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          choco install --no-progress ffmpeg
+          $archive = Join-Path $env:RUNNER_TEMP 'mpv-dev-x86_64-20260607-git-71ebd08.7z'
+          $destination = Join-Path $env:RUNNER_TEMP 'libmpv'
+          curl.exe --fail --location --silent --show-error --retry 5 --retry-all-errors --output $archive 'https://sourceforge.net/projects/mpv-player-windows/files/libmpv/mpv-dev-x86_64-20260607-git-71ebd08.7z/download'
+          if ((Get-FileHash -Algorithm SHA256 $archive).Hash -ne 'FAA0BE46643CD889A1D816696F60B9962D7BB70E9D9D6E619DA368D0B22211D6') {
+            throw 'Downloaded libmpv archive did not match its pinned SHA-256'
+          }
+          & "$env:ChocolateyInstall\tools\7z.exe" x $archive "-o$destination" -y | Out-Null
+          $libmpv = Get-ChildItem $destination -Filter 'libmpv-2.dll' -File -Recurse | Select-Object -First 1
+          if ($null -eq $libmpv) {
+            throw 'Pinned libmpv archive did not contain libmpv-2.dll'
+          }
+          $libmpv.DirectoryName | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+
+      - name: Install Project Dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Verify libmpv is importable (Windows)
+        if: runner.os == 'Windows'
+        run: python -c "import mpv; print('libmpv import succeeded')"
+        
+      - name: Make Fixtures
+        run: python tools/make_fixtures.py --small
+        
+      - name: Verify Determinism
+        run: |
+          cp -r tests/fixtures tests/fixtures_first_run
+          python tools/make_fixtures.py --small
+          python -c '
+          import pathlib, filecmp, sys
+          p1 = pathlib.Path("tests/fixtures")
+          p2 = pathlib.Path("tests/fixtures_first_run")
+          for f1 in p1.rglob("*.json"):
+              f2 = p2 / f1.relative_to(p1)
+              if not f2.exists() or not filecmp.cmp(f1, f2, shallow=False):
+                  print(f"Mismatch in {f1}")
+                  sys.exit(1)
+          print("Determinism check passed!")
+          '
+        
+      - name: Run Tests
+        # A Qt/platform deadlock must fail at the specific test instead of
+        # consuming the whole job timeout with no diagnostic evidence.
+        run: pytest --maxfail=5 -q --durations=20 --timeout=60 --timeout-method=thread --ignore=tests/benchmarks
+
+  docs:
+    name: Read the Docs build
+    runs-on: ubuntu-24.04
+    needs: lint-type
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - name: Install documentation dependencies
+        run: pip install -e ".[docs]"
+      - name: Build documentation with warnings as errors
+        run: sphinx-build -W --keep-going -b html docs docs/_build/html