Fuuga.Image.cpu 1.0.12

Fuuga.Image

This is image generation MCP client for Fuuga (or other agents) to make the agent capable of producing images via other (Stable Diffusion) models from for example HuggingFace.

Standalone CLI tool for image generation and captioning, built on stable-diffusion.cpp and Phi-3.5-vision.

Commands

fuuga-image txt2img     Generate an image from a text prompt
fuuga-image img2img     Transform an image guided by a text prompt
fuuga-image txt2video   Generate a video from a text prompt (video models only)
fuuga-image img2video   Animate a still image into a video (video models only)
fuuga-image vid2vid     Edit/continue a video guided by text (VACE; video models only)
fuuga-image caption     Generate a text description of an image
fuuga-image info        Display model metadata

Quick Start

dotnet build

# Text-to-image
dotnet run -- txt2img --model path/to/model.ckpt --prompt "a cat sitting on a windowsill" --steps 20

# Image-to-image
dotnet run -- img2img --model path/to/model.ckpt --source input.png --prompt "in watercolor style" --strength 0.75

# Text-to-video (requires a video model, e.g. a Wan2.1/2.2 T2V GGUF)
dotnet run -- txt2video --model path/to/wan-t2v.gguf --prompt "a wave crashing on rocks" --frames 16 --fps 8 --format mp4

# Image-to-video (animate a still)
dotnet run -- img2video --model path/to/wan-i2v.gguf --source photo.png --prompt "gentle zoom" --frames 24 --format gif

# Video-to-video (edit/continue a video guided by text; --source is a video file or a frames dir)
dotnet run -- vid2vid --model path/to/wan-vace.gguf --source clip.mp4 --prompt "make it snowy" --format mp4

# Attach an audio track to a generated mp4 (models don't make audio; this muxes a provided file)
dotnet run -- txt2video --model path/to/wan-t2v.gguf --prompt "a marching band" --format mp4 --audio track.mp3

# Caption an image
dotnet run -- caption --model path/to/vision-model/ --image photo.jpg --detail standard

# Caption a video (samples frames and describes them; --video is a file or a frames dir)
dotnet run -- caption --model path/to/vision-model/ --video clip.mp4 --frame-samples 8 --detail detailed

# Transcribe/describe audio (needs an audio-capable model, e.g. Phi-4-multimodal — same runtime)
dotnet run -- caption --model path/to/phi-4-multimodal/ --audio speech.wav

# Model info
dotnet run -- info --model path/to/model.ckpt

Common Options

txt2img Options

img2img Options

Same as txt2img, plus:

caption Options

Captioning uses whatever multimodal model directory you pass to --model. Provide one of --image (a still), --video (a video file decoded via ffmpeg, or a directory of frames, sampled to --frame-samples), or --audio (transcribe/describe an audio clip). Audio needs an audio-capable model such as Phi-4-multimodal — it runs on the same ONNX-Runtime-GenAI runtime already bundled (no extra dependency), you just point --model at it.

txt2video / img2video / vid2vid Options

Video is generated only when the loaded model supports it (e.g. Wan2.1/2.2 text-to-video, image-to-video, or VACE GGUF models); the tool checks the model's capability and errors clearly otherwise. img2video additionally takes --source <path> (the starting image); vid2vid takes --source <path> (a video file or a directory of frame images) plus --vace-strength <f>.

Video models produce no audio. --audio <path> muxes a user-provided audio file into an mp4/webp output via ffmpeg (ignored for gif / image sequences).

Output formats. png writes an image sequence (frame_0000.png …) into a per-run subdirectory — this is dependency-free and always available. mp4, gif, and webp are encoded from those frames with ffmpeg, which is an optional external tool (see below). If a single-file format is requested but ffmpeg is not found, the tool falls back to an image sequence and prints a note.

Optional: ffmpeg for mp4 / gif / webp

ffmpeg is not a .NET dependency and is not bundled. To enable single-file video output, install it and make sure it is on PATH (or point FUUGA_FFMPEG at the executable):

• Windows: winget install Gyan.FFmpeg (or choco install ffmpeg), or download from https://ffmpeg.org/download.html and add the bin folder to PATH.
• macOS: brew install ffmpeg
• Linux: sudo apt install ffmpeg (Debian/Ubuntu) or your distro's package manager.
• Explicit path: set FUUGA_FFMPEG=/full/path/to/ffmpeg to use a specific build.

Without ffmpeg, --format png (image sequence) still works and can be turned into a video later with any tool.

MCP Server Mode

Fuuga.Image can run as an MCP tool server over stdio, enabling integration with Fuuga LLM via the MCP protocol:

dotnet run -- --mcp-server

This exposes these tools via JSON-RPC 2.0 over stdin/stdout:

• fuuga_image_txt2img -- text-to-image generation
• fuuga_image_img2img -- image-to-image transformation
• fuuga_image_txt2video -- text-to-video generation (video models only)
• fuuga_image_img2video -- image-to-video animation (video models only)
• fuuga_image_caption -- image captioning

See architecture.md Section 18 for the full integration design.

F# Script Demo

An interactive demo script shows how to use Fuuga.Image as an F# library — calling the modules directly with record-based configuration, validation, and I/O:

dotnet build Fuuga.Image
dotnet fsi examples/image-demo.fsx

The script runs without models (dry-run mode), exercising types, validation, image I/O, and prompt templates. Uncomment Section 5 and set your model paths for actual generation. See examples/image-demo.fsx for the full source.

Project Structure

Fuuga.Image/
  Types.fs        Layer 0: Domain types, error handling (ImageError DU)
  Config.fs       Layer 1: CLI argument parsing
  ImageIO.fs      Layer 2: Image load/save, format conversion, validation
  Diffusion.fs    Layer 3: Stable Diffusion model wrapper (txt2img, img2img)
  Caption.fs      Layer 4: Phi-3.5-vision captioning (ONNX Runtime GenAI)
  McpServer.fs    Layer 5: MCP JSON-RPC 2.0 server over stdio
  Program.fs      Layer 6: Entry point, subcommand routing, error handling

Architecture

• Image Extension Architecture -- standalone design
• Main Architecture Section 18 -- Fuuga LLM integration