94 lines
3.1 KiB
Markdown
94 lines
3.1 KiB
Markdown
# 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:**
|
|
```bash
|
|
go build -o glimbus .
|
|
```
|
|
|
|
**Run (development with logging):**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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.
|