Dropper

Drop files

Development

Install the pinned Python, uv, Node.js, pnpm, just, and FFmpeg tools with mise:

mise trust
mise install
mise exec -- just install
mise exec -- just dev

With mise activated in your shell, you can run just directly. Tool versions and shared environment variables live in mise.toml; keep credentials and personal overrides in the ignored mise.local.toml.

Update a tool and its project pin with mise use --pin TOOL@VERSION, then verify the relevant project commands before committing mise.toml. Python and JavaScript package dependencies remain managed by uv and npm. Podman/Docker and the Cairo system library require OS installation. Kubernetes and local Ollama workflows also require their respective tools and services.

ChatGPT library metadata

To use your ChatGPT plan for library metadata, install the project dependencies and start the local companion on the computer where Dropper is open:

uv sync
uv run dropper-chatgpt

In Dropper, choose Continue with ChatGPT, select a model, and run Describe library. The default model is the first account model whose name contains luna, when available. The companion listens on 127.0.0.1:8765; OAuth tokens are stored in ~/.config/dropper/chatgpt.json with private file permissions. They are used locally and are never sent to Dropper. The production hosts dropper.wayl.one and dropper.waylonwalker.com, dev hosts, and localhost origins are allowed by default. Add any additional origin with the comma-separated DROPPER_CHATGPT_ALLOWED_ORIGINS setting before starting the companion.

ChatGPT results are kept in media_chatgpt_metadata, separate from the existing current metadata. Worker and media JSON include chatgpt_metadata and a best_metadata object that prefers non-empty ChatGPT values and falls back to the existing metadata. Gaming items include category: "gaming", gaming: true, and a game title when identifiable. Apply database migrations with uv run alembic upgrade head before using the ChatGPT analysis workflow.

Game event profiles and timestamped clip annotations are managed at /metadata/game-events. Add a game's gameplay context and event enum definitions there; Describe library then asks Luna for matching clip events as it analyzes tagged videos. The page includes a synchronized video player and event timeline, and agents can read or add clip events through the authenticated /api/media/{media_id}/timeline-events endpoints.

The library runner spaces ChatGPT requests at least 500 ms apart and allows up to eight in flight when responses take longer. OpenAI does not publish a fixed parallel-request limit for this ChatGPT plan flow; usage depends on the task and the account's app limit. Review it under ChatGPT Settings → Usage. The metadata page shows active previews and estimates remaining time from recent batch completion rates.

Automated agents can fetch /llms.txt for instructions tailored to the current request's authentication state. /changelog serves the shipped Markdown release notes.

Python development and the runtime container use CPython 3.15.0. See the upgrade validation and timings.

License

dropper is distributed under the terms of the MIT license.

Type checking

Run just typecheck after changes. ty checks all Python files in dropper/, scripts/, tests/, and alembic/, including standalone scripts and ignored files inside those directories. Every ty diagnostic is an error; strict equality and generic narrowing are enabled. Type-ignore comments cannot suppress errors, and there are no source exclusions.

The optional Whisper transcription proof of concept requires Python 3.10–3.14 because its native ctranslate2 dependency has no Python 3.15 wheel. It remains included in type checking through an explicit engine protocol.