Skip to content

CLAUDE.md

Latest commit

 

History

History
97 lines (71 loc) · 5.56 KB

CLAUDE.md

File metadata and controls

97 lines (71 loc) · 5.56 KB
Raw

mpv-photo-frame

Linux digital picture frame: plays a photo/video library as a fullscreen mpv slideshow with fade transitions and an EXIF date/filename overlay. Bash orchestration scripts + Lua mpv scripts. Configured via a gitignored slideshow.conf (see slideshow.conf.example).

Key Config Files

File Purpose
.claude/settings.json Permissions and environment variables
.claude/skills/release/SKILL.md Cuts a new release: bumps version, updates changelog, tags, and pushes
.github/workflows/claude-code-review.yml Auto-reviews every pull request
.github/workflows/claude.yml Runs Claude on @claude mentions in issues/PRs
.github/workflows/release.yml Publishes GitHub Releases from pushed version tags
.gitignore Git ignore patterns

Commands

bash install.sh                       # copy Lua scripts to ~/.config/mpv/scripts/
./generate-slideshow-playlist.sh      # convert TIFFs + build shuffled playlist
./slideshow.sh                        # start the fullscreen slideshow

No build step. Verify loop (install with apt install shellcheck / go install mvdan.cc/sh/v3/cmd/shfmt@latest / luarocks install luacheck):

shellcheck *.sh tests/*.sh            # lint Bash scripts (incl. tests/)
shfmt -i 2 -d .                       # check Bash formatting (2-space indent)
luacheck mpv-scripts/                 # lint Lua mpv scripts
for f in tests/*.test.sh; do bash "$f"; done   # run all unit tests

Structure

  • *.sh — Bash entrypoints (install, playlist generation, slideshow launch)
  • mpv-scripts/ — Lua mpv scripts: crossfade.lua (fade transitions), photo-info.lua (overlay), blurred-background.lua (letterbox/pillarbox fill)
  • slideshows/<name>.conf — one file per slideshow (sources + per-slideshow overrides); every slideshow is equal, there's no default
  • systemd/ — user service for playlist pre-generation on login
  • slideshow.conf.example — documented config template (app-wide settings); real slideshow.conf is gitignored

Local git config (not tracked, set once per clone): git config core.hooksPath .githooks — wires up scripts/sync-config-table.sh, which keeps the Key Config Files table above in sync on commit.

Conventions

  • All runtime config comes from slideshow.conf — never hardcode paths; add new options to slideshow.conf.example with a default and a doc-table row in README.md.
  • Lua overlay options are exposed via mpv script-opts so users override without editing scripts.
  • Keep scripts POSIX-friendly Bash with set-guarded variable expansion (: "${VAR:?...}").

Don't

  • Don't commit secrets or credentials to git — slideshow.conf stays untracked.
  • Don't use --force flags — fix the underlying issue instead.
  • Don't put private/absolute photo paths in committed files.

Learnings

When the user corrects a mistake or points out a recurring issue, append a one-line summary to .claude/learnings.md. Don't modify CLAUDE.md directly.

Compact Instructions

When compacting, preserve: list of modified files, current test/lint status, open TODOs, and key decisions made.

Headroom Learned Patterns

Auto-generated by headroom learn on 2026-06-26 — do not edit manually

Permissions & Denied Files

~900 tokens/session saved

  • .env.example and .env are denied by .claude/settings.json by default; the user must explicitly remove the deny entry before agents can read them. When only searching, use git show HEAD:.env.example | grep ... as a workaround.
  • rm -rf on any path (including /tmp/) is denied by project permissions. Clean up temp files individually with rm -f file1 file2 and directories with rmdir, never rm -rf.

GPG Signing

~600 tokens/session saved

  • Commits require interactive GPG passphrase input (TTY). Subagents launched without the claude fish function (which unlocks the key via Headroom) will fail on git commit with a PINENTRY_LAUNCHED error. Stage changes and ask the user to confirm they can enter the passphrase before committing from a subagent.

Tool Availability

~400 tokens/session saved

  • shellcheck, shfmt, and luacheck are NOT installed. Use bash -n for shell syntax checks.
  • luajit IS available for Lua testing; lua, luac, lua5.x are NOT.
  • exiftool IS available for EXIF inspection. PIL/Pillow is NOT (No module named 'PIL').
  • sudo requires a password; sudo -n always fails — do not attempt passwordless sudo.

Edit Tool Protocol

~350 tokens/session saved

  • Always Read a file before Editing it — the Edit tool fails with File has not been read yet if skipped. This applies even after a Write to the same file: re-read before the next Edit.

Project Layout

~300 tokens/session saved

  • Two copies of photo-info.lua must be kept in sync: ~/Slideshow/mpv-scripts/photo-info.lua (repo) and ~/.config/mpv/scripts/photo-info.lua (live). Always edit both.
  • Photo library path contains spaces: /home/familie/OneDrive/Familie/Fotos, Videos — always quote it in shell commands.
  • Desktop folder is ~/Schreibtisch (German locale), not ~/Desktop.

Bash Gotchas

~150 tokens/session saved

  • Backticks inside grep patterns are interpreted by bash as command substitution. To count/match markdown fences, use grep -nc '^\``'(single-quoted) orgrep -nc $'^```'`.