Pinchflat

Pinchflat is a lightweight, self‑hosted media ingestion layer that orchestrates YouTube content downloads via yt‑dlp. From a developer’s viewpoint, the application exposes a minimal yet powerful HTTP API that accepts rules—JSON objects describing channel or playlist identifiers, download intervals, and output layouts. Once a rule is persisted to the underlying SQLite database, Pinchflat’s scheduler triggers yt‑dlp in a Docker container, streams the output to a configurable media folder, and emits webhook events for downstream pipelines. This design keeps Pinchflat stateless outside of its rule store, making it trivially containerized and suitable for micro‑service architectures.

Architecture & Technical Stack

• Language & Runtime: Pinchflat is written in Go 1.22, leveraging its concurrency primitives for parallel download orchestration and its robust standard library for HTTP handling.
• Frameworks: The web layer uses the lightweight Chi router, providing a clean, middleware‑driven routing structure. JSON schema validation is performed with go-playground/validator, ensuring rule payloads meet strict requirements before persistence.
• Persistence: A single SQLite3 file stores all rules, download history, and configuration flags. The ORM‑like layer is built on top of sqlc, generating type‑safe queries that eliminate runtime SQL errors.
• Download Engine: yt‑dlp is invoked as an external process; Pinchflat captures its stdout/stderr streams, parses JSON‑encoded progress updates, and forwards them to the client via Server‑Sent Events (SSE). This keeps the Go process lightweight while delegating heavy I/O to yt‑dlp’s efficient Python implementation.

Core Capabilities & Developer APIs

• Rule CRUD: POST /rules, GET /rules/{id}, PUT /rules/{id}, DELETE /rules/{id} – fully RESTful, returning JSON representations and HTTP status codes.
• Event Streaming: GET /events exposes an SSE endpoint that streams real‑time download progress, completion notifications, and error alerts. This can be consumed by front‑ends or CI pipelines.
• Webhook Hooks: Each rule can specify a postDownloadUrl; Pinchflat performs an HTTP POST with metadata upon successful download, enabling integration with Plex/Webhooks or custom media indexers.
• Health & Metrics: /healthz for liveness probes, /metrics exposing Prometheus counters (downloads started/completed/failed) and histograms of download duration.

Deployment & Infrastructure

Pinchflat is intentionally container‑first. A single Dockerfile builds a stateless image that mounts:

• /data – where the SQLite database and media files reside.
• /config – optional YAML for global settings (e.g., default download directory, concurrency limits).

The provided Docker Compose snippets demonstrate running Pinchflat behind a reverse proxy (Traefik/NGINX) with HTTPS termination, and the optional --env-file pattern for environment variables. For high‑availability, multiple instances can share a networked filesystem (e.g., NFS or SMB) for /data, allowing each instance to read/write the same rule set while isolating download processes.

Integration & Extensibility

• Plugin System: Pinchflat exposes a simple plugin hook interface. Developers can drop Go shared objects (*.so) into /plugins; the runtime loads them at startup, allowing custom rule validation or post‑processing logic without modifying core code.
• Webhooks & Callbacks: Beyond the built‑in postDownloadUrl, any HTTP endpoint can be registered per rule, facilitating integration with external services such as Jellyfin Webhooks, Slack notifications, or custom ingestion pipelines.
• CLI Tool: A companion CLI (pinchflat-cli) lets developers script rule creation, bulk deletion, or trigger ad‑hoc downloads from CI/CD pipelines.

Developer Experience

The repository follows modern Go conventions: all code is formatted with gofmt, linted via golangci-lint, and unit‑tested using Go’s testing framework. Documentation is split across the Wiki for high‑level concepts and inline comments for API details. Community support is active on Discord, where contributors can request features or report bugs in real time. Licensing under MIT ensures no commercial restrictions, and the open‑source nature encourages rapid iteration.

Use Cases

• Media Center Automation: A home server operator can define rules for favorite YouTube channels, automatically populating a Plex library with the latest videos.
• Archival & Backup: Researchers or archivists can schedule daily pulls from specific channels, storing metadata in a central database for future analysis.
• CI/CD Media Pipelines: Developers building video‑based tutorials can trigger Pinchflat downloads as part of a build step, ensuring consistent media assets across environments.

Advantages Over Alternatives