av1dae/AGENTS.md

AGENTS.md

This file provides guidance for agents operating in the videnc-vibe repository.

Project Overview

Go-based CLI tool for transcoding DVD/Blu-ray to SVT-AV1 with automatic metadata fetching from OMDb and TVmaze.

Build Commands

# Build binary
go build -o videnc-vibe ./cmd/videnc/

# Run binary
./videnc-vibe

# With flags
./videnc-vibe -d              # Delete original after encode
./videnc-vibe -c /path/to/config.yaml

Code Style Guidelines

General

• Use Go standard library; minimize external dependencies
• Use gopkg.in/yaml.v3 for YAML config parsing (already in go.mod)
• Run go fmt and go vet before commits

Imports

• Group imports: standard library, external packages, internal packages
• Use aliases for packages: "videnc-vibe/pkg/types"

import (
    "fmt"
    "os"

    "gopkg.in/yaml.v3"
    "videnc-vibe/pkg/types"
)

Naming

• Packages: lowercase, single word (e.g., encoder, metadata)
• Types: PascalCase (e.g., Encoder, Job)
• Functions: PascalCase exported, camelCase unexported
• Variables: camelCase
• Constants: PascalCase for exported, camelCase for unexported
• Acronyms: all caps for 2 letters (e.g., IMDBID), mixed for 3+ (e.g., jpegImage)

Error Handling

• Return errors with context: fmt.Errorf("parsing config: %w", err)
• Use sentinel errors for known conditions
• Check errors explicitly, don't ignore with _

Types

• Use specific types where appropriate (e.g., MediaType string type)
• Define types in pkg/types/types.go

Functions

• Keep functions small and focused
• Prefer multiple small functions over large ones
• Use receivers for methods: func (e *Encoder) Transcode(...)

Concurrency

• Use channels for communication
• Handle shutdown with context or done channels

Testing

• Write tests in *_test.go files alongside implementation
• Use table-driven tests for multiple cases
• Test external dependencies with mocks

Commit Messages

Follow Conventional Commits:

• add: new features
• fix: bug fixes
• refactor: code restructuring
• chore: maintenance

Example: add: add command line argument support

Project Structure

cmd/videnc/main.go       # CLI entrypoint
internal/
  config/                # Config loading
  watcher/               # Folder polling
  encoder/               # FFmpeg wrapper
  metadata/              # OMDb/TVmaze client
  mover/                 # File operations
  logger/                # Logging
pkg/types/types.go       # Shared types

Key Dependencies

• ffmpeg - video encoding
• opusenc - audio encoding
• gopkg.in/yaml.v3 - config parsing