SHOTBUDDY v3

Your AI Filmmaking Asset Manager.
An open-source tool designed to manage, organize, and streamline your entire AI-driven image-to-video workflow.

---

Shotbuddy takes the chaos out of AI filmmaking. Instead of juggling countless generated files in messy folders, Shotbuddy provides a structured, visual, and intuitive interface to build your stories shot by shot. This fork supercharges the original with powerful project management, advanced version control, and a modern user experience tailored for today's creative workflows.

✨ Key Features (v3 Enhancements)

This version of Shotbuddy is packed with features designed to make your workflow faster and more organized.

🚀 Streamlined Project Management

• Comprehensive Project Dashboard: Get a bird's-eye view of your entire project with the responsive Table of Shots (TOC) panel. Filter, navigate, and see active vs. archived shots at a glance.
• Effortless Shot Reordering: Simply drag and drop shots to rearrange your sequence. Your story's flow is always just a move away.
• Flexible Archiving & Naming: Keep your main workspace clean by archiving inactive shots. Give shots human-readable names like "Opening Scene" instead of just SH010 for better clarity.
• Detailed Project Info: Manage metadata for each project, including title, version, description, and tags, all from an intuitive modal.

🖼️ Powerful Asset & Version Control

• First & Last Frame Variants: Manage distinct opening and closing frames for each shot, complete with their own versions, prompts, and thumbnails.
• Instant Prompt Previews: No more digging for prompt details. Simply hover over a thumbnail to see the exact prompt used to generate it.
• Automatic File Organization: Drag and drop your generated images or videos. Shotbuddy automatically versions them, archives old iterations in a wip folder, and keeps the latest version ready for your pipeline.

💡 Enhanced User Experience

• Advanced Export Options: Precisely select what you want to export. Choose between images, videos, or both, and even include metadata summaries for a complete project handoff.
• Seamless Light/Dark Theme: Switch between light and dark modes with a single click. Your preference is saved automatically for your next session.
• And much more: Enjoy features like dynamic note fields that expand as you type, integrated asset captions, and quick access to recent projects.

🔧 Installation

Get started with Shotbuddy in just a few steps. Using uv is recommended for its speed and efficiency.

1. Clone the Repository (We use a shallow clone to download faster)

   git clone --depth 1 https://github.com/taruma/shotbuddy.git
   cd shotbuddy

2. Install Dependencies

   • (Recommended) Using uv:

     # Install uv if you haven't: https://docs.astral.sh/uv/
     uv sync

   • Using venv and pip:

     python -m venv .venv
     source .venv/bin/activate  # On Windows: .venv\Scripts\activate
     pip install -r requirements.txt

3. Run the Server

   # If using uv
   uv run run.py
   
   # If using venv and pip
   python run.py

4. Open Your Browser Navigate to http://127.0.0.1:5001 to start using Shotbuddy!

📁 How It Works: Project Folder Structure

Shotbuddy automatically creates and maintains a clean, predictable folder structure for every project. This ensures your assets are always organized and easy to find.

project_folder/
├── shots/
│   ├── latest_images/    # The current, "promoted" image for each shot (e.g., SH010.png)
│   ├── latest_videos/    # The current, "promoted" video for each shot (e.g., SH010.mp4)
│   └── wip/              # Work-in-progress and old versions are archived here
│       └── SH010/
│           ├── images/   # e.g., SH010_v001.png, SH010_v002.png
│           └── videos/   # e.g., SH010_v001.mp4
└── project_info.json     # Metadata like title, version, and notes

📜 Attribution and License

This project is a fork that significantly extends and modernizes the original work.

• Forked from Shotbuddy by Albert Bozesan (@albozes).
• Maintained and extended by Taruma Sakti.
• This project is licensed under the MIT License.

This project is developed with AI assistance. For detailed attribution, see the CHANGELOG.md.