THE BLACKCAT Image Motion Studio

# THE BLACKCAT Image Motion Studio

THE BLACKCAT Image Motion Studio converts one JPG/PNG photo into a short MP4 video using Higgsfield Seedance 2.0 image-to-video.

This Studio is a local dashboard plus a shell wrapper around a paid external API. It does not run local AI inference. Rendering only starts when the operator presses Render.

## Local Dashboard

- URL: `http://127.0.0.1:8771`
- Launcher: `scripts/open-image-motion-studio.command`
- Studio folder: `studios/image-motion-studio/`
- Input folder: `studios/image-motion-studio/input/`
- Output folder: `studios/image-motion-studio/output/`
- Logs: `studios/image-motion-studio/output/_logs/`

## What It Does

1. Reads a JPG/PNG from `input/`.
2. Sends it to `higgsfield generate create seedance_2_0`.
3. Uses a motion preset or a custom prompt.
4. Waits for the cloud render.
5. Downloads the MP4 to `output/`.
6. Creates a QC frame in `output/_logs/` when FFmpeg is available.

Default settings:

- Duration: 4 seconds.
- Resolution: 1080p.
- Aspect ratio: 16:9.
- Mode: `std`.
- Audio: disabled.

## One-Time Setup

```bash
export PATH="$HOME/.local/bin:$PATH"
higgsfield auth login
higgsfield account balance
```

Auth is browser device-login. The token lives at:

```text
~/.config/higgsfield/credentials.json
```

Never commit or print that file.

Install FFmpeg for QC frame extraction:

```bash
brew install ffmpeg
```

## How To Use

1. Open THE BLACKCAT Image Motion Studio from the portal.
2. Press `Abrir input`.
3. Put one or more JPG/PNG photos in that folder.
4. Press `Actualizar`.
5. Choose a photo, duration, resolution and motion preset.
6. Press `Render`.
7. Review the MP4 and QC frame in `output/`.

## Terminal Command

```bash
studios/image-motion-studio/image-motion-studio.sh \
  --image studios/image-motion-studio/input/photo.jpg \
  --out studios/image-motion-studio/output/photo.mp4 \
  --duration 4 \
  --resolution 1080p \
  --aspect 16:9 \
  --mode std \
  --prompt "Subtle push-in; person gestures naturally; faces realistic; no warping."
```

## Presets

Presets live in:

- `studios/image-motion-studio/presets.json`
- `studios/image-motion-studio/presets.sh`

Current presets:

- Subtle push-in.
- Subtle pan right.
- Subtle pan left.
- Subtle zoom-out.
- Subtle tilt down.
- Locked ambient life.

## Safety Notes

- Rendering uses real Higgsfield credits.
- A 1080p 4-second clip can cost about 36 credits.
- A 720p 4-second smoke test can cost about 18 credits.
- Higgsfield auth can expire and may require `higgsfield auth login` again.
- Keep concurrency low. Higgsfield can rate-limit around three jobs.
- Always review faces, hands and text for warping.
- Do not commit input photos, output MP4 files, JSON logs, error logs or credentials.