nocek 0.1.0__tar.gz

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

@@ -0,0 +1,49 @@
+# Builds Nocek and publishes it, with PyPI's trusted publishing (no passwords or tokens
+# kept anywhere):
+#   - pushing a tag v0.1.0, v0.2.0, ... publishes that version to PyPI;
+#   - running this workflow by hand (Actions, "Publish", Run workflow) publishes to
+#     TestPyPI, to try a release out first.
+# The tag must name the version in src/nocek/__init__.py.
+
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Build
+        run: uv build
+      - name: Check the tag names the version being published
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          version=$(python3 -c "import re; print(re.search(r'__version__ = \"(.+)\"', open('src/nocek/__init__.py').read())[1])")
+          test "${GITHUB_REF_NAME}" = "v${version}" || { echo "tag ${GITHUB_REF_NAME} but version ${version}"; exit 1; }
+      - name: Check the package's metadata
+        run: uvx twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    # A tag goes to PyPI, a run by hand to TestPyPI.
+    environment: ${{ startsWith(github.ref, 'refs/tags/') && 'pypi' || 'testpypi' }}
+    permissions:
+      id-token: write # what trusted publishing signs in with
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: ${{ startsWith(github.ref, 'refs/tags/') && 'https://upload.pypi.org/legacy/' || 'https://test.pypi.org/legacy/' }}

nocek-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors and OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Recordings never belong in the repository
+*.wav
+!tests/fixtures/**/*.wav

nocek-0.1.0/LICENSE

@@ -0,0 +1,75 @@
+Required Notice: Copyright 2026 kazek (https://github.com/kazek)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

nocek-0.1.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.5
+Name: nocek
+Version: 0.1.0
+Summary: Identify bats from ultrasonic recordings, in your browser.
+Project-URL: Homepage, https://github.com/kazek/nocek
+Project-URL: Source, https://github.com/kazek/nocek
+Project-URL: Issues, https://github.com/kazek/nocek/issues
+Author: kazek
+License-Expression: PolyForm-Noncommercial-1.0.0
+License-File: LICENSE
+Keywords: bat detector,bats,bioacoustics,echolocation,pippyg,ultrasound
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Natural Language :: German
+Classifier: Natural Language :: Polish
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: ai-edge-litert>=2.1.2
+Requires-Dist: audioread>=3.0
+Requires-Dist: batdetect2==1.3.1
+Requires-Dist: fastapi>=0.115
+Requires-Dist: numpy>=1.26
+Requires-Dist: platformdirs>=4
+Requires-Dist: soundfile>=0.12
+Requires-Dist: soxr>=0.5
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx2>=2.13; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Nocek
+
+Identify bats from ultrasonic recordings, in your browser.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kazek/nocek/main/docs/screenshot-dark.png">
+  <img alt="Nocek's main page: three sites, a calendar of nights, one night's recordings from sunset to sunrise, and a recording with two bats in its spectrogram" src="https://raw.githubusercontent.com/kazek/nocek/main/docs/screenshot-light.png">
+</picture>
+
+Bring in the recordings from your recorder's card, and Nocek copies the new
+ones, finds the echolocation calls, names the bats and shows you what has been
+flying past, night by night. It runs on your own computer and your recordings
+never leave it.
+
+> **Status:** an early version, in use by its authors. Expect rough edges, and
+> please report them.
+
+## What you need
+
+- A computer with one of:
+  - macOS 12 or newer on Apple Silicon (M1 or later)
+  - Windows 10 or 11, 64-bit
+  - Linux, x86-64 or ARM64
+- About 1.5 GB of disk space for Nocek itself, most of it PyTorch, and room for
+  your recordings.
+- A pippyg recorder. It is the only recorder Nocek reads for now.
+- An internet connection to install Nocek, and once more on its first start, to
+  download one of its models (about 52 MB).
+
+## Install
+
+On **macOS or Linux**, open a terminal and paste:
+
+```
+curl -LsSf https://raw.githubusercontent.com/kazek/nocek/main/install.sh | sh
+```
+
+On **Windows**, open PowerShell and paste:
+
+```
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/kazek/nocek/main/install.ps1 | iex"
+```
+
+That is all. The script installs [uv](https://docs.astral.sh/uv/), which brings
+the Python Nocek needs (so you do not need Python already), then Nocek itself with
+the build of PyTorch that suits your computer, puts Nocek in your system's menu
+(Applications on macOS, the Start menu on Windows, the applications menu on
+Linux), and starts it. The first time it downloads about 1 GB.
+
+### Installing by hand
+
+If you would rather see each step, or already use uv or pipx:
+
+```
+uv tool install --torch-backend auto nocek
+nocek shortcut
+```
+
+`--torch-backend auto` picks the build of PyTorch that suits your computer: with
+an NVIDIA graphics card, one that uses it; without one, the much smaller build for
+the processor alone. uv still calls the option experimental; should it ever fail,
+leave it out. With pipx, `pipx install nocek` works too. If the terminal does not
+find `nocek`, run `uv tool update-shell` and open a new terminal.
+
+## First start
+
+Start Nocek from its shortcut, or with `nocek` in a terminal. It opens in your
+browser at `http://127.0.0.1:6475`. Starting it again while it runs just opens
+the page once more.
+
+The first time, it asks for two things:
+
+- **A library**: one folder where Nocek keeps the recordings it copies and what
+  it found in them. It offers `Documents/Nocek`. A library can be backed up or
+  moved as a whole, as one folder.
+- **The models**: one of the three ways Nocek tells bats apart needs about 52 MB
+  of files, downloaded once.
+
+To stop Nocek, use **Quit** in the page's top right corner.
+
+## Using Nocek
+
+**Load new recordings.** Choose the folder with the recorder's files: the
+memory card, a copy of it, or one of its `bats_dev000`-style folders; the
+folders inside are searched too. Nothing on the card is changed, and recordings
+already in the library are skipped, so the same card can be loaded again
+safely. Recordings made in the recorder's bird mode are left out.
+
+**Sites.** A pippyg can be set to a number, which also names its files
+(`DEV_000_…`). Nocek takes each number to stand for a place, a site. The first
+time a number turns up, Nocek asks which site it stands for and suggests a new
+one named after it, such as `dev000`, placed where the recorder's GPS put it;
+after that, its recordings go there by themselves. In the **⋯** menu by the
+sites you can rename sites, move a number to another site, and say which bats
+are expected at each.
+
+**Nights.** The calendar shades each night by how many of its recordings named a
+bat. Pick a night to see it.
+
+**The night.** One bar from sunset to sunrise, with a mark for every recording:
+coloured by the bat, as tall as what it holds (a named bat, calls with the name
+withheld, or no calls). Point at a mark to see what it is, click it to open it.
+The legend counts each kind; point at an entry, or click it, to pick out its
+marks. On a busy night, zoom in with the magnifiers (or Ctrl and the scroll
+wheel, or a pinch on a trackpad) and drag the bar sideways.
+
+**The recording.** Its spectrogram, with each animal's calls boxed and
+numbered; drag across it to look closer. Playback is slowed (10 times by
+default) so that the calls fall where you can hear them. Under it, what was
+heard; **Details** shows how each method saw it. The arrow keys step through the
+night, the space bar plays and pauses.
+
+**How a bat gets its name.** [BatDetect2](https://github.com/macaodha/batdetect2)
+names the animals in a recording. Two other methods check it: a field key that
+measures the calls, and [BattyBirdNET](https://github.com/rdz-oss/BattyBirdNET-Analyzer).
+When both of them agree on something else, the name is withheld. So are names
+of bats not expected at the site, while bats marked rare need strong evidence.
+Bats that cannot be told apart by their calls are named as a group, such as
+*Pipistrellus kuhlii / P. nathusii*.
+
+The language, the light or dark theme, and the settings are in the top right
+corner. Nocek speaks English, Polish and German.
+
+## Update
+
+Run the install command again, or `uv tool upgrade nocek`. Your library and
+settings are kept. If Nocek was running, quit it and start it again.
+
+## Uninstall
+
+```
+nocek shortcut --remove
+uv tool uninstall nocek
+```
+
+This leaves your library, and the files below, in place; delete them yourself if
+you want them gone.
+
+## Where Nocek keeps its files
+
+| | macOS | Windows | Linux |
+| --- | --- | --- | --- |
+| Library | `~/Documents/Nocek`, unless you chose another folder | `Documents\Nocek`, unless you chose another folder | `~/Documents/Nocek`, unless you chose another folder |
+| Settings | `~/Library/Application Support/Nocek` | `%LOCALAPPDATA%\Nocek` | `~/.config/Nocek` |
+| Models | `~/Library/Application Support/Nocek/models` | `%LOCALAPPDATA%\Nocek\models` | `~/.local/share/Nocek/models` |
+| Log | `~/Library/Logs/Nocek/nocek.log` | `%LOCALAPPDATA%\Nocek\Logs\nocek.log` | `~/.local/state/Nocek/log/nocek.log` |
+
+The log is the file to send along when reporting a problem.
+
+## Privacy
+
+Nocek works on your computer only. It goes online for one thing: to download
+BattyBirdNET's model files, once. Your recordings, and what Nocek finds in
+them, stay where you put them.
+
+## Licence
+
+Nocek may be used for non-commercial purposes only, under the
+[PolyForm Noncommercial License 1.0.0](https://github.com/kazek/nocek/blob/main/LICENSE): by individuals, for research,
+teaching and conservation, and by charities and public bodies. For any other
+use, please ask.
+
+Nocek uses the work of others, under their own licences:
+
+- [BatDetect2](https://github.com/macaodha/batdetect2), Mac Aodha, O. et al.
+  (2022): CC BY-NC 4.0, non-commercial.
+- [BattyBirdNET](https://github.com/rdz-oss/BattyBirdNET-Analyzer), Zinck, R.D.
+  (2023), built on BirdNET by Kahl, S. et al.: CC BY-NC-SA 4.0,
+  non-commercial. Downloaded by Nocek, not part of it.
+- [Web Awesome](https://webawesome.com): MIT. Included in
+  `src/nocek/web/static/vendor/webawesome`.
+- [Lucide](https://lucide.dev) icons: ISC. Included in
+  `src/nocek/web/static/vendor/lucide`.
+
+## Development
+
+Requires Python 3.11 or newer.
+
+```
+git clone https://github.com/kazek/nocek
+cd nocek
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+
+.venv/bin/pytest
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+```
+
+On Windows, use `.venv\Scripts\` instead of `.venv/bin/`. The interface is plain
+JavaScript modules with no build step: change a file under
+`src/nocek/web/static` and reload the page. See
+[docs/roadmap.md](https://github.com/kazek/nocek/blob/main/docs/roadmap.md) for how Nocek came about.

nocek-0.1.0/README.md

@@ -0,0 +1,194 @@
+# Nocek
+
+Identify bats from ultrasonic recordings, in your browser.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kazek/nocek/main/docs/screenshot-dark.png">
+  <img alt="Nocek's main page: three sites, a calendar of nights, one night's recordings from sunset to sunrise, and a recording with two bats in its spectrogram" src="https://raw.githubusercontent.com/kazek/nocek/main/docs/screenshot-light.png">
+</picture>
+
+Bring in the recordings from your recorder's card, and Nocek copies the new
+ones, finds the echolocation calls, names the bats and shows you what has been
+flying past, night by night. It runs on your own computer and your recordings
+never leave it.
+
+> **Status:** an early version, in use by its authors. Expect rough edges, and
+> please report them.
+
+## What you need
+
+- A computer with one of:
+  - macOS 12 or newer on Apple Silicon (M1 or later)
+  - Windows 10 or 11, 64-bit
+  - Linux, x86-64 or ARM64
+- About 1.5 GB of disk space for Nocek itself, most of it PyTorch, and room for
+  your recordings.
+- A pippyg recorder. It is the only recorder Nocek reads for now.
+- An internet connection to install Nocek, and once more on its first start, to
+  download one of its models (about 52 MB).
+
+## Install
+
+On **macOS or Linux**, open a terminal and paste:
+
+```
+curl -LsSf https://raw.githubusercontent.com/kazek/nocek/main/install.sh | sh
+```
+
+On **Windows**, open PowerShell and paste:
+
+```
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/kazek/nocek/main/install.ps1 | iex"
+```
+
+That is all. The script installs [uv](https://docs.astral.sh/uv/), which brings
+the Python Nocek needs (so you do not need Python already), then Nocek itself with
+the build of PyTorch that suits your computer, puts Nocek in your system's menu
+(Applications on macOS, the Start menu on Windows, the applications menu on
+Linux), and starts it. The first time it downloads about 1 GB.
+
+### Installing by hand
+
+If you would rather see each step, or already use uv or pipx:
+
+```
+uv tool install --torch-backend auto nocek
+nocek shortcut
+```
+
+`--torch-backend auto` picks the build of PyTorch that suits your computer: with
+an NVIDIA graphics card, one that uses it; without one, the much smaller build for
+the processor alone. uv still calls the option experimental; should it ever fail,
+leave it out. With pipx, `pipx install nocek` works too. If the terminal does not
+find `nocek`, run `uv tool update-shell` and open a new terminal.
+
+## First start
+
+Start Nocek from its shortcut, or with `nocek` in a terminal. It opens in your
+browser at `http://127.0.0.1:6475`. Starting it again while it runs just opens
+the page once more.
+
+The first time, it asks for two things:
+
+- **A library**: one folder where Nocek keeps the recordings it copies and what
+  it found in them. It offers `Documents/Nocek`. A library can be backed up or
+  moved as a whole, as one folder.
+- **The models**: one of the three ways Nocek tells bats apart needs about 52 MB
+  of files, downloaded once.
+
+To stop Nocek, use **Quit** in the page's top right corner.
+
+## Using Nocek
+
+**Load new recordings.** Choose the folder with the recorder's files: the
+memory card, a copy of it, or one of its `bats_dev000`-style folders; the
+folders inside are searched too. Nothing on the card is changed, and recordings
+already in the library are skipped, so the same card can be loaded again
+safely. Recordings made in the recorder's bird mode are left out.
+
+**Sites.** A pippyg can be set to a number, which also names its files
+(`DEV_000_…`). Nocek takes each number to stand for a place, a site. The first
+time a number turns up, Nocek asks which site it stands for and suggests a new
+one named after it, such as `dev000`, placed where the recorder's GPS put it;
+after that, its recordings go there by themselves. In the **⋯** menu by the
+sites you can rename sites, move a number to another site, and say which bats
+are expected at each.
+
+**Nights.** The calendar shades each night by how many of its recordings named a
+bat. Pick a night to see it.
+
+**The night.** One bar from sunset to sunrise, with a mark for every recording:
+coloured by the bat, as tall as what it holds (a named bat, calls with the name
+withheld, or no calls). Point at a mark to see what it is, click it to open it.
+The legend counts each kind; point at an entry, or click it, to pick out its
+marks. On a busy night, zoom in with the magnifiers (or Ctrl and the scroll
+wheel, or a pinch on a trackpad) and drag the bar sideways.
+
+**The recording.** Its spectrogram, with each animal's calls boxed and
+numbered; drag across it to look closer. Playback is slowed (10 times by
+default) so that the calls fall where you can hear them. Under it, what was
+heard; **Details** shows how each method saw it. The arrow keys step through the
+night, the space bar plays and pauses.
+
+**How a bat gets its name.** [BatDetect2](https://github.com/macaodha/batdetect2)
+names the animals in a recording. Two other methods check it: a field key that
+measures the calls, and [BattyBirdNET](https://github.com/rdz-oss/BattyBirdNET-Analyzer).
+When both of them agree on something else, the name is withheld. So are names
+of bats not expected at the site, while bats marked rare need strong evidence.
+Bats that cannot be told apart by their calls are named as a group, such as
+*Pipistrellus kuhlii / P. nathusii*.
+
+The language, the light or dark theme, and the settings are in the top right
+corner. Nocek speaks English, Polish and German.
+
+## Update
+
+Run the install command again, or `uv tool upgrade nocek`. Your library and
+settings are kept. If Nocek was running, quit it and start it again.
+
+## Uninstall
+
+```
+nocek shortcut --remove
+uv tool uninstall nocek
+```
+
+This leaves your library, and the files below, in place; delete them yourself if
+you want them gone.
+
+## Where Nocek keeps its files
+
+| | macOS | Windows | Linux |
+| --- | --- | --- | --- |
+| Library | `~/Documents/Nocek`, unless you chose another folder | `Documents\Nocek`, unless you chose another folder | `~/Documents/Nocek`, unless you chose another folder |
+| Settings | `~/Library/Application Support/Nocek` | `%LOCALAPPDATA%\Nocek` | `~/.config/Nocek` |
+| Models | `~/Library/Application Support/Nocek/models` | `%LOCALAPPDATA%\Nocek\models` | `~/.local/share/Nocek/models` |
+| Log | `~/Library/Logs/Nocek/nocek.log` | `%LOCALAPPDATA%\Nocek\Logs\nocek.log` | `~/.local/state/Nocek/log/nocek.log` |
+
+The log is the file to send along when reporting a problem.
+
+## Privacy
+
+Nocek works on your computer only. It goes online for one thing: to download
+BattyBirdNET's model files, once. Your recordings, and what Nocek finds in
+them, stay where you put them.
+
+## Licence
+
+Nocek may be used for non-commercial purposes only, under the
+[PolyForm Noncommercial License 1.0.0](https://github.com/kazek/nocek/blob/main/LICENSE): by individuals, for research,
+teaching and conservation, and by charities and public bodies. For any other
+use, please ask.
+
+Nocek uses the work of others, under their own licences:
+
+- [BatDetect2](https://github.com/macaodha/batdetect2), Mac Aodha, O. et al.
+  (2022): CC BY-NC 4.0, non-commercial.
+- [BattyBirdNET](https://github.com/rdz-oss/BattyBirdNET-Analyzer), Zinck, R.D.
+  (2023), built on BirdNET by Kahl, S. et al.: CC BY-NC-SA 4.0,
+  non-commercial. Downloaded by Nocek, not part of it.
+- [Web Awesome](https://webawesome.com): MIT. Included in
+  `src/nocek/web/static/vendor/webawesome`.
+- [Lucide](https://lucide.dev) icons: ISC. Included in
+  `src/nocek/web/static/vendor/lucide`.
+
+## Development
+
+Requires Python 3.11 or newer.
+
+```
+git clone https://github.com/kazek/nocek
+cd nocek
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+
+.venv/bin/pytest
+.venv/bin/ruff check .
+.venv/bin/ruff format --check .
+.venv/bin/mypy
+```
+
+On Windows, use `.venv\Scripts\` instead of `.venv/bin/`. The interface is plain
+JavaScript modules with no build step: change a file under
+`src/nocek/web/static` and reload the page. See
+[docs/roadmap.md](https://github.com/kazek/nocek/blob/main/docs/roadmap.md) for how Nocek came about.

nocek-0.1.0/docs/releasing.md

@@ -0,0 +1,44 @@
+# Releasing
+
+Nocek is published on [PyPI](https://pypi.org/project/nocek/) by the `Publish`
+workflow (`.github/workflows/publish.yml`), through PyPI's trusted publishing: no
+password or token is kept anywhere.
+
+## Once: set up publishing
+
+1. Make accounts on [PyPI](https://pypi.org/account/register/) and
+   [TestPyPI](https://test.pypi.org/account/register/) (two separate sites), with
+   two-factor authentication.
+2. On each, add a pending trusted publisher (Account settings, Publishing, "Add a
+   new pending publisher", GitHub):
+   - PyPI project name: `nocek`
+   - Owner: `kazek`, repository: `nocek`
+   - Workflow name: `publish.yml`
+   - Environment name: `pypi` on PyPI, `testpypi` on TestPyPI
+
+## Each release
+
+1. Set the version in `src/nocek/__init__.py` (`0.1.0`, `0.1.1`, `0.2.0`, ...) and
+   commit it.
+2. Try it on TestPyPI: on GitHub, Actions, "Publish", "Run workflow" on `main`. Then,
+   on a computer with uv:
+
+   ```
+   uv tool install --torch-backend auto --index-url https://test.pypi.org/simple/ \
+     --extra-index-url https://pypi.org/simple/ --index-strategy unsafe-best-match nocek
+   ```
+
+   TestPyPI takes each version once too, so a second try needs a new version, such
+   as `0.1.1rc1`.
+3. Publish it: tag the commit and push the tag.
+
+   ```
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+   The workflow checks that the tag names the version in the code, builds Nocek,
+   and publishes it. Users then get it with the install script or
+   `uv tool upgrade nocek`.
+
+A version once on PyPI cannot be replaced, only followed by a newer one.

nocek-0.1.0/docs/roadmap.md

@@ -0,0 +1,28 @@
+# Roadmap
+
+Nocek is a rewrite of a single-station research setup as an application
+anyone with a recorder can install and use. Work proceeds in stages; each
+stage is small enough to review in one sitting.
+
+| # | Stage | Content | Done |
+| --- | --- | --- | --- |
+| 0 | Skeleton | Package layout, tooling, tests, licence | ✓ |
+| 1 | Core library | Pulse detection, the three classifiers behind one interface, cross-checking between them, tested against reference calls | ✓ |
+| 2 | Storage | SQLite model: site, device, import, night, recording, per-classifier result. Species identified by scientific name | ✓ |
+| 3 | Recorders | Safe, read-only import from a folder the user picks. Device adapters, starting with pippyg: device number, location, schedule and settings read from the card and respected | ✓ |
+| 4 | Web backend | HTTP API, background jobs with progress, first-run model download, localisation plumbing | ✓ |
+| 5 | Interface | One page: import, sites by recorder number, a calendar of nights, the night as one bar from sunset to sunrise, the recording with its spectrogram and slowed playback. Web Awesome components, light and dark themes | ✓ |
+| 6 | Translations | English, Polish, German. Local species names, always shown with the scientific name | ✓ |
+| 7 | Distribution | Published on PyPI; a one-line install script for each system, a shortcut in the system's menu, the browser opens on start | ✓ |
+| 8 | Documentation | User guide, translator guide, architecture notes | |
+
+Later: manual verification of identifications; other recorders (AudioMoth).
+
+## Decisions
+
+- Python 3.11+, macOS, Windows and Linux.
+- Backend: FastAPI. Frontend: plain JavaScript modules, no build step.
+- Storage: one SQLite database inside the library, the folder the user chose.
+- Web interface only; the command line just starts it and makes its shortcut.
+- Translations: JSON files, one per language.
+- Recordings and their metadata are kept as the recorder wrote them.