|
| 1 | +<p align="center"> |
| 2 | + <img src="resources/icon.png" alt="Avatica" width="160" height="160"> |
| 3 | +</p> |
| 4 | + |
| 5 | +<h1 align="center">Avatica</h1> |
| 6 | + |
| 7 | +<p align="center"> |
| 8 | + A free, native creative studio for AI-generated media — image, video, music, and speech — that runs entirely on your machine. Bring your own provider keys; your projects live as plain folders on your disk. |
| 9 | +</p> |
| 10 | + |
| 11 | +## What it is |
| 12 | + |
| 13 | +Avatica talks to AI providers directly using keys you supply — generation costs go straight to your provider account and nothing else does. |
| 14 | + |
| 15 | +The studio is organized around **projects** (folders), **apps** (focused tools that read and write typed assets), and **sequences** (`.seq` files you build on a multi-track timeline). |
| 16 | + |
| 17 | +## Install |
| 18 | + |
| 19 | +Download the latest installer from the [Releases page](https://github.com/vahidk/avatica/releases), or get it from the Mac App Store on macOS. |
| 20 | + |
| 21 | +## First run |
| 22 | + |
| 23 | +1. **Pick a projects folder.** On first launch Avatica asks where to store projects. It creates an `Avatica/` subfolder in the location you choose (default: `~/Movies/Avatica/`). Each project is a folder inside it — open it in Finder/Explorer any time. |
| 24 | +2. **Add at least one API key.** Settings opens automatically if none are configured. Avatica supports three provider families, and you only need one: |
| 25 | + - **Google Gemini** — text, image (Imagen / Nano Banana), video (Veo), music (Lyria), speech. Get a key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey). |
| 26 | + - **xAI** — Grok for text, image, video, and TTS. Get a key at [console.x.ai](https://console.x.ai). |
| 27 | + - **OpenAI** — GPT Image 2. Get a key at [platform.openai.com/api-keys](https://platform.openai.com/api-keys). |
| 28 | + Keys are stored locally and never leave your machine except as calls to the provider you chose. |
| 29 | +3. **Create a project.** Click *New Project*, give it a name, and you land in the workspace. |
| 30 | + |
| 31 | +## The workspace |
| 32 | + |
| 33 | +Three modes across the top, panels on the sides: |
| 34 | + |
| 35 | +- **Create** — pick a built-in app from the dropdown and generate. Outputs land in the output grid and on disk in your project folder. |
| 36 | +- **Compose** — multi-track timeline. Drag assets onto tracks, trim, layer text overlays, scrub, and export an MP4. |
| 37 | +- **Develop** — build your own apps and asset types. |
| 38 | + |
| 39 | +Toggle the side panels from the top-right: |
| 40 | +- **Assets** (left) — file browser for the current project. Drag files onto app input slots; double-click a `.seq` to open it in Compose. |
| 41 | +- **Log** (bottom) — running output from app invocations. |
| 42 | +- **Chat** (right) — the assistant. It sees your project's files and built-in apps as tools and can chain them: generate a character, then a shot from that character, then drop the shot on the timeline. |
| 43 | + |
| 44 | +## Built-in apps |
| 45 | + |
| 46 | +### Image |
| 47 | + |
| 48 | +- **Image Generation** — text-to-image, or edit an existing image with a prompt. Optional reference images for style. |
| 49 | +- **Fashion Studio** — fashion photoshoot from a reference photo, with style, setting, and shot selections. |
| 50 | +- **Hair Stylist** — hairstyle visualizations from a reference photo, with style, color, and view selections. |
| 51 | +- **Makeup Artist** — makeup looks from a reference photo, with style, skin tone, and view selections. |
| 52 | + |
| 53 | +### Video |
| 54 | + |
| 55 | +- **Video Generation** — text-to-video, image-to-video, frame-to-frame interpolation, or extend an existing clip. |
| 56 | +- **Cinema Studio** — animate a `.shot` asset (pre-composed first frame with characters/scene/objects) into a cinematic clip with camera movement and action. |
| 57 | +- **Monologue Studio** — turn a shot plus monologue text into a full delivery video. Splits the script into chunks of the target duration, generates each in parallel from the shot's frame, and assembles a sequence. |
| 58 | + |
| 59 | +### Audio |
| 60 | + |
| 61 | +- **Song Generation** — music from a text prompt, with optional genre, mood, tempo, and instrument controls. |
| 62 | +- **Speech Generation** — speech audio from text with voice selection. |
| 63 | + |
| 64 | +### Entity (reusable building blocks) |
| 65 | + |
| 66 | +- **Character Creator** — a character with portrait, description, and attributes; saved as a `.character` asset other apps can consume. |
| 67 | +- **Object Creator** — an object or product from a reference image, description, and attributes; saved as a `.object` asset. |
| 68 | +- **Scene Creator** — a scene or location from a reference image, description, and attributes; saved as a `.scene` asset. |
| 69 | +- **Shot Creator** — a cinematic first frame from scene + characters + objects (*create* mode), or a new camera angle that continues a previous shot (*continue* mode). Output is a `.shot` asset that Cinema Studio animates. |
| 70 | + |
| 71 | +### Script |
| 72 | + |
| 73 | +- **Script Writer** — screenplays and scripts for short films, music videos, and AI video content. |
| 74 | +- **Monologue Writer** — standup, storytelling, TED talk, dramatic, pitch, vlog, spoken word, and more. |
| 75 | + |
| 76 | +Drag characters, objects, scenes, or shots from the asset browser onto another app's input slot to chain them together. |
| 77 | + |
| 78 | +## Supported models |
| 79 | + |
| 80 | +Every provider is enabled out of the box once its key is set. The app picks a sensible default per task; you can override the model from the app surface. |
| 81 | + |
| 82 | +### Google (Gemini API) |
| 83 | + |
| 84 | +| Model | What it does | |
| 85 | +|---|---| |
| 86 | +| **Gemini 3.1 Pro** | Text generation (scripts, monologues, reasoning) | |
| 87 | +| **Gemini 3.1 Flash Lite** | Faster/cheaper text generation | |
| 88 | +| **Nano Banana 2** (Gemini 3.1 Flash Image) | Image generation and edit, up to 4K, full range of aspect ratios | |
| 89 | +| **Gemini 3.1 TTS** | Speech in 18 languages, 30 voices (Zephyr, Puck, Charon, Kore, …) | |
| 90 | +| **Lyria 3 Clip** | Music generation (mp3/wav) | |
| 91 | +| **Lyria 3 Pro** | Higher-quality music generation (mp3/wav) | |
| 92 | +| **Veo 3.1 Lite** | Video generation and image-to-video up to 1080p | |
| 93 | +| **Veo 3.1 Fast** | Video generation, image-to-video, interpolation, and extend up to 4K | |
| 94 | +| **Veo 3.1** | Highest-quality Veo: generation, image-to-video, interpolation, and extend up to 4K | |
| 95 | + |
| 96 | +### xAI |
| 97 | + |
| 98 | +| Model | What it does | |
| 99 | +|---|---| |
| 100 | +| **Grok 4.2** | Text generation | |
| 101 | +| **Grok Imagine** | Image generation and edit, 1K/2K, full range of aspect ratios | |
| 102 | +| **Grok Imagine Pro** | Higher-quality image generation and edit | |
| 103 | +| **Grok Imagine** (video) | Video generation, image-to-video, extend, and edit at 480p/720p, 1–15s | |
| 104 | +| **Grok TTS** | Speech in 16 languages, 5 voices (Eve, Ara, Rex, Sal, Leo) | |
| 105 | + |
| 106 | +### OpenAI |
| 107 | + |
| 108 | +| Model | What it does | |
| 109 | +|---|---| |
| 110 | +| **GPT Image 2** | Image generation and edit, 1K/2K (4K at 16:9 / 9:16), wide aspect ratio range | |
| 111 | + |
| 112 | +## File handling |
| 113 | + |
| 114 | +- Projects are real folders. Move, back up, or sync them however you like. |
| 115 | +- Double-clicking a `.seq` file in Finder opens it in Compose. |
| 116 | +- Generated images, video, audio, and JSON assets are named based on the prompt that produced them. |
| 117 | + |
| 118 | +## Settings |
| 119 | + |
| 120 | +Open Settings from the navbar (gear icon): |
| 121 | + |
| 122 | +- **General** — API keys, projects root folder, light/dark theme. |
| 123 | +- **Usage** — running cost totals and per-app/per-provider breakdown, estimated from each provider's published pricing. |
0 commit comments