CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Glimbus is a Go-based web service that processes images and videos using DeepDanbooru or Stable Diffusion WebUI for image tagging. The service accepts uploaded media files and returns tags by analyzing frames.

Core Architecture:

Two-file Go web server (main.go, video.go)
Uses chi router with standard library net/http
Listens on 0.0.0.0:6679
Accepts multipart file uploads via POST to /
For videos: extracts frames at variable intervals, sends each frame to upstream tagger, aggregates tags
For images: sends directly to upstream tagger
Supports two upstream runners (configured via env vars):
- DeepDanbooru (via DD_ADDRESS)
- StableDiffusionWebUI (via SD_ADDRESS)

Build and Run Commands

Build:

go build -o glimbus .

Run (development with logging):

# Set environment variables first (see .envrc for example)
export LOG_LEVEL=debug  # or RUST_LOG=debug for compatibility
export SD_ADDRESS=http://your-server:port
export SD_MODEL=vitv3  # or wd14-vit-v2-git (default)

./glimbus

Run tests:

go test ./...

Environment Variables

Required (one of):

DD_ADDRESS: DeepDanbooru server URL (checked first)
SD_ADDRESS: Stable Diffusion WebUI server URL

Optional:

SD_MODEL: Model name for SD WebUI (default: wd14-vit-v2-git)
LOG_LEVEL: Log level (debug for verbose logging)
RUST_LOG: Also supported for compatibility (debug enables debug logging)

Video Processing Logic

The service adaptively samples video frames based on duration: look at getFrameSkipSeconds to find the mapping, but its kind of like this (as an example):

0-10s: every 2 seconds
11-60s: every 10 seconds
61-120s: every 15 seconds
121-300s: every 20 seconds
301-1000s: every 30 seconds
1001-1200s: every 40 seconds
1201s+: every 60 seconds

Frame extraction uses ffmpeg with fast seeking (-ss before input), extracting one frame per interval. All tags from all frames are collected into a deduplicated set.

Key Implementation Details

Frame Rate Calculation (video.go): The service attempts to get frame rate from stream metadata, falls back to calling ffprobe directly if the metadata returns 0/0.

Frame Count Calculation (video.go): Tries stream metadata first, then format duration x frame rate, finally falls back to full decode with ffprobe -count_frames.

Upstream Runner Detection (main.go): Checks DD_ADDRESS first, then SD_ADDRESS. Exits with error if neither is set.

Response Format:

Returns JSON array of tags: ["tag1", "tag2", ...]
On error: returns JSON string: "error message"

Dependencies

Core (Go standard library + chi):

github.com/go-chi/chi/v5: HTTP router
net/http: HTTP server
os/exec: ffmpeg/ffprobe execution
encoding/json: JSON serialization
log/slog: Structured logging

External tools required:

ffmpeg: Frame extraction
ffprobe: Video metadata

The service has an 8GB body size limit for file uploads.

3.1 KiB Raw Permalink Blame History