diff --git a/aur/PKGBUILD b/aur/PKGBUILD
new file mode 100644
index 0000000..291aa2a
--- /dev/null
+++ b/aur/PKGBUILD
@@ -0,0 +1,59 @@
+# Maintainer: beefy-player contributors <beefcarver@tilde.club>
+
+pkgname=beefy-player
+pkgver=1.2.2
+pkgrel=1
+pkgdesc="Flashy terminal player for internet radio with a live spectrum analyser"
+arch=('any')
+url="https://tildeforge.dev/beefcarver/beefy-player"
+license=('WTFPL')
+depends=(
+  'python'
+  'python-dbus-next'
+  'python-httpx'
+  'python-numpy'
+  'python-pillow'
+  'python-rich'
+  'python-textual'
+)
+makedepends=(
+  'python-build'
+  'python-hatchling'
+  'python-installer'
+  'python-wheel'
+)
+checkdepends=(
+  'python-pytest'
+  'python-pytest-asyncio'
+)
+optdepends=(
+  'ffmpeg: decode the stream for the spectrum analyser, and ffplay as the audio fallback'
+  'libpulse: capture the output monitor so the analyser follows what you hear (parec/pactl)'
+  'mpv: preferred audio backend'
+  'tmux: detect the outer terminal for kitty graphics passthrough inside tmux'
+)
+
+# Upstream does not tag releases yet, so the source is the archive of the
+# commit that carries this version.  Once a `v$pkgver` tag exists, switch to
+#
+#   source=("$pkgname-$pkgver.tar.gz::$url/archive/v$pkgver.tar.gz")
+#
+_commit=941c7446384bf346e40d1438a7ce67939d9615df
+source=("$pkgname-$pkgver.tar.gz::$url/archive/$_commit.tar.gz")
+sha256sums=('8ac568676ef5ef8345441c28e4f8f5d61fb06d5225e566ac578acae18672c778')
+
+build() {
+  cd "$pkgname"
+  python -m build --wheel --no-isolation
+}
+
+check() {
+  cd "$pkgname"
+  # The suite is offline: catalogues are fixtures, mpv/parec are faked.
+  python -m pytest -q
+}
+
+package() {
+  cd "$pkgname"
+  python -m installer --destdir="$pkgdir" dist/*.whl
+}
diff --git a/aur/README.md b/aur/README.md
new file mode 100644
index 0000000..b095b30
--- /dev/null
+++ b/aur/README.md
@@ -0,0 +1,81 @@
+# AUR packaging for beefy-player
+
+An AUR repository holds exactly two tracked files, `PKGBUILD` and `.SRCINFO`.
+This directory is the staging area for both; the rest of the project is
+irrelevant to the AUR.
+
+## Build it locally
+
+```bash
+cd aur
+makepkg -si          # build, run the test suite, install
+```
+
+`makepkg -o && makepkg -e` skips the download/checksum phase, and
+`extra-x86_64-build` (devtools) builds in a clean chroot. The package builds
+with `base-devel` plus the `makedepends`/`checkdepends` listed in the
+`PKGBUILD`; every dependency comes from the official repositories, none from
+the AUR.
+
+## Publish to the AUR
+
+```bash
+git clone ssh://aur@aur.archlinux.org/beefy-player.git /tmp/aur-beefy-player
+cp PKGBUILD .SRCINFO /tmp/aur-beefy-player/
+cd /tmp/aur-beefy-player
+git add PKGBUILD .SRCINFO
+git commit -m "Initial import: beefy-player 1.2.2-1"
+git push
+```
+
+## Releasing a new version
+
+1. Set `pkgver` in `PKGBUILD` and `pyproject.toml`, and reset `pkgrel=1`.
+2. Point `_commit` at the commit carrying that version:
+
+   ```bash
+   git rev-parse HEAD          # or the tag, once one exists
+   ```
+
+3. Refresh the checksum:
+
+   ```bash
+   curl -fsSL "https://tildeforge.dev/beefcarver/beefy-player/archive/$_commit.tar.gz" | sha256sum
+   ```
+
+4. Regenerate the metadata (on Arch, or inside a chroot):
+
+   ```bash
+   makepkg --printsrcinfo > .SRCINFO
+   ```
+
+5. Push to the AUR with the conventional commit message:
+
+   ```bash
+   git commit -am "upgpkg: beefy-player <pkgver>-<pkgrel>"
+   ```
+
+## Why the source is a commit archive
+
+Upstream publishes no tags or releases, so the checksum in `sha256sums`
+belongs to the archive of a specific commit rather than of a `v$pkgver` tag.
+Forge archives of a commit are deterministic, so the checksum stays stable.
+Once `v$pkgver` is tagged, replace the `source` line with
+
+```bash
+source=("$pkgname-$pkgver.tar.gz::$url/archive/v$pkgver.tar.gz")
+```
+
+## Packaging notes
+
+- The wheel is built with `hatchling`; `theme.tcss` is force-included by
+  `pyproject.toml`, so it ends up in `site-packages/beefy_player/`.
+- `check()` runs the real test suite. It is offline by design (station
+  catalogues are fixtures and `mpv`/`parec` are faked), which makes it safe in
+  a build chroot with no network.
+- `mpv`, `ffmpeg`, `libpulse` (`parec`/`pactl`) and `tmux` are `optdepends`,
+  not `depends`: the player degrades gracefully without them and says so in
+  the UI. Users who want sound need `mpv` (or `ffmpeg` for `ffplay`) and, for
+  the output-synced spectrum, `libpulse`.
+- `license=('WTFPL')` is an SPDX identifier shipped by Arch's `licenses`
+  package.