Create AI-Directed Films with Cinecode: Installation, Workflow, and Rendering

What Is Cinecode?

Cinecode is an open-source filmmaking kit for AI coding agents. You describe a film, commercial, explainer, documentary, or music video, and an agent helps write the script, construct every frame in code, design the soundtrack, render drafts, and deliver a finished MP4.

The kit runs locally through Claude Code or Cursor. Its rendering workflow uses browser graphics such as Canvas 2D and three.js/WebGL, headless Chrome, and ffmpeg. A paid video-generation service is not required. Voice-over can use your own Gemini or ElevenLabs access, an optional Turkish voice engine, or a temporary system voice.

Cinecode can produce projects ranging from 15-second vertical advertisements to documentaries and video essays longer than ten minutes. Short projects can be built in one working session, while longer productions use a staged approval process.

Key Capabilities

• Code-built short films: Choose realistic 3D, 2D animation, paint, ink, paper, clay, motion graphics, or pixel-inspired treatments.
• Long-form videos: Film mode supports researched scripts, acts, chapters, narration, archive material, maps, diagrams, and reconstructed spaces.
• Commercials and product films: Provide brand colors, fonts, logos, product details, and a call to action. Advertising projects can be prepared for 9:16, 1:1, and 16:9 delivery with safe areas.
• Vertical explainers: Create 30–60 second videos with an immediate question, kinetic typography, diagrams, and phone-readable text.
• Music videos: Cinecode can measure a song’s beat grid, place cuts on measures, align accents to beats, and associate visuals with lyric lines.
• Footage editing: Talking-head recordings and screen captures can be cut from word-timed transcripts, with pauses removed and graphics attached to spoken words. This optional workflow requires Whisper.
• Reusable formats: Save a film’s format and use it as the basis for later episodes.
• Designed audio: The workflow supports ambience, effects, narration processing, music, shared reverb, and −14 LUFS mastering.

How the Workflow Operates

1. Describe the idea. One sentence is enough, although a complete brief can reduce the number of follow-up questions.
2. Answer creative questions. The agent asks about interpretation, visual medium, duration, aspect ratio, appearance, narration, and music. Recommended answers are marked with a star.
3. Review the plan. You receive timed beats and an editable director card. Before the complete film is built, the agent presents frames from two contrasting scenes.
4. Review the draft. Cinecode renders a draft and checks motion from the opening frame, loudness, readability, and repetition. An independent viewer pass is also part of the documented process.
5. Request focused revisions. Feedback should change only the areas it addresses rather than rebuilding unrelated approved work.
6. Render the final film. The result is exported at full size, mastered to −14 LUFS, and accompanied by credits information for the video description.

Choose Quick Mode or Film Mode

Quick Mode

Quick mode is intended for work under roughly three minutes, especially social clips, advertisements, narrated videos, and first drafts of short films. The entire visual timeline lives in one self-contained film.html file. Scenes are functions of time and can use Canvas 2D or three.js/WebGL.

The normal sequence is a short interview, optional research, a written plan, two preview frames, a half-size draft, up to two revision rounds, and the full-size render. Audio is designed from the first version and can include ambience, synchronized effects, generated sounds, music, and reverb.

Film Mode

Film mode is designed for longer, multi-scene, researched, narrated, or archive-based productions. It starts with six questions across three short rounds, followed by a roadmap, the complete script, a final-quality style frame, and an animatic. Production can proceed stage by stage with approvals or continue from the approved script to a complete draft.

Film mode includes eight documented visual presets: cinematic realism, anime or cel animation, pastel storybook, claymation, paper cutout or collage, retro or synthwave or VHS, polished advertising, and handmade ink. It can also derive a custom direction from reference images.

Start in Quick mode when you need speed or want to test an idea. Its timed beats can later become the roadmap for a Film mode production.

Choose the Project Purpose

Mode controls how deeply the production process goes. Purpose controls what kind of result it is trying to create.

• Cinematic film: Prioritizes story, feeling, photographic camera language, lens character, depth of field, grain, operator inertia, and environment-led sound. Optional finishing effects such as motion blur, film color, and gate weave are disabled by default.
• Advertising and product: Prioritizes a specific subject, brand identity, a clear next action, competitor and specificity checks, interface hero shots for software, name labels, brand typography, and a call-to-action ending.

System Requirements

Before installation, confirm that your computer can run an AI coding agent and local command-line tools.

• Claude Code in the desktop application, VS Code extension, or terminal; alternatively, Cursor Agent
• Node.js 22 or newer
• Python 3.9 or newer
• ffmpeg
• Google Chrome, Chromium, or Edge
• A GPU usable by Chrome
• A few hundred megabytes of free space for Quick mode, or several gigabytes per Film mode render

If a dependency is missing, the agent can inspect the computer and propose installing it. Cinecode’s scripts use built-in modules, while pinned three.js library versions are loaded from a CDN. The agent should ask before installing anything.

Claude’s normal web chat cannot run ffmpeg, Chrome, and local scripts on your computer. Use Claude Code, not a standard claude.ai conversation.

Install Cinecode

Option 1: Ask Claude Code to Install It

Open Claude Code and ask it to install the Cinecode skill from the repository:

Install the cinecode skill from https://github.com/sarpstar/cinecode

The repository is cloned into ~/.claude/skills/cinecode. On Windows, the equivalent location is %USERPROFILE%\.claude\skills\cinecode. After installation, start a new conversation so the skill is detected cleanly.

Option 2: Clone It Manually for Claude Code

git clone https://github.com/sarpstar/cinecode.git ~/.claude/skills/cinecode

Install only one copy. Multiple copies can make it unclear which version the agent should use. To retrieve a newer version later, ask Claude Code to update Cinecode.

Option 3: Install It for Cursor

git clone https://github.com/sarpstar/cinecode.git ~/.cursor/skills/cinecode

Open an empty project folder in Cursor and begin from its Agent chat. Cinecode’s make.py and qc.py checks still work in Cursor. However, Claude Code-specific guard hooks that immediately stop certain workflow mistakes are not available there.

Create Your First Film

1. Open an Empty Project Folder

In the Claude desktop application, select the Code section and choose an empty folder. In VS Code or Cursor, open an empty folder before starting the agent chat.

For a terminal-based Claude Code session, run:

mkdir my-film
cd my-film
claude

2. Submit a Brief

The only required information is the idea. A practical first prompt is:

Let’s make a film with Cinecode.

Idea: A forgotten lighthouse remembers every ship it guided home.
Duration: 60 seconds
Destination: YouTube, 16:9
Sound: No narration; music and effects only
Appearance: Handmade ink, or suggest a better direction

Do not select a mode in advance unless you have a reason to override the recommendation. The agent evaluates the project’s size and suggests Quick or Film mode.

If you do not know the duration, format, sound approach, or visual treatment, omit those fields. Cinecode will ask. Conversely, a complete brief containing timed beats, text, duration, and format can move directly toward a draft.

3. Select the Mode and Purpose

For the lighthouse example, Quick mode is suitable because the film is only one minute long. Choose cinematic film if the focus is atmosphere and story. For a product launch or branded explainer, choose advertising and product.

4. Approve the Plan

Read the one-sentence summary, turn, timed beat list, dialogue or screen text, camera directions, and director card. Camera instructions use a concise vocabulary, such as:

dolly in, 3 s, slow ease-in-out, toward the figure

Change individual lines rather than giving vague approval when an important decision is wrong. You can also request different references or additional research.

5. Inspect the Two Preview Scenes

Quick mode shows the opening and another visually different scene before constructing the rest of the film. Check the composition, palette, typography, subject design, lighting, and whether the chosen medium is recognizable.

6. Review and Revise the Draft

The first draft is rendered at half size with optional finishing effects disabled. Watch it with sound and collect related notes into one response. Quick mode supports up to two targeted draft revision rounds.

A useful revision request is specific and time-based:

At 00:08–00:12, slow the camera move and keep the lighthouse centered.
Make the title larger for phone viewing.
Lower the music under the final sound effect.
Do not change the approved ink texture or ending.

7. Render the Final MP4

After approval, Cinecode renders at full size, enables any finishing effects you selected, reruns its checks, and writes the finished file to the top level of the film folder as <title>.mp4.

Working with References and Existing Media

Place reference material in the project’s refs/ directory. Cinecode can measure qualities such as shot duration, editing pace, palette, lighting, BPM, and the relationship between cuts and beats. It then builds a new film around that formal structure without taking frames or music from the reference.

You can also add typography screenshots to refs/type/. The kit documents licensed open fonts, Turkish character checks, phone-size readability, contrast checks, and font pairing proposals.

If you bring your own song, tell the agent where the file is located. Cinecode can estimate tempo across the track, align cuts to measures, place accents on beats, create visuals for lyric lines, and reduce music automatically beneath narration.

Voice-Over Options

Voice-over is optional. Cinecode processes narration so it belongs to the film rather than exporting an untouched engine voice. It can characterize the voice as close, recorded on tape, transmitted by radio, underwater, choral, or mechanical, and place it within an acoustic space.

The README lists several optional Turkish voice systems. These are not installed automatically:

• EMA Lightning: A single offline Turkish voice that can run on a CPU. Install support with python3 tools/tts.py --install ema, then select the ema engine.
• VoxCPM2 Turkish voice design: Offers describable voices and seven prepared narrator styles. It requires Apple Silicon or an NVIDIA GPU and approximately 3.7 GB.
• Ahenk: Supports features such as question intonation and emotion. Its model weights use CC BY 4.0, so films using them must credit Ahenk.

Without one of these local options, narration can use your Gemini TTS key or temporarily fall back to a system voice.

Advanced Workflow Tips

• Begin with the smallest useful brief. A one-sentence idea lets the agent propose interpretations you may not have considered. A detailed brief is better when timing, copy, and brand rules are already fixed.
• Approve structure before polish. Correct the turn, beat order, hook, and ending in the plan. Do not wait until the final render to solve a script problem.
• Use references for form, not imitation. Ask Cinecode to preserve pacing, lighting logic, or editing rhythm while changing the subject and visual material.
• Give consolidated revision notes. Quick mode allows at most two draft revision rounds, so group timing, typography, audio, and composition notes into a single response.
• Design for the destination. Mention whether the film is for vertical Instagram viewing, square delivery, or horizontal YouTube playback. Phone-readable wording is especially important for explainers.
• Keep optional finishing effects intentional. Motion blur, film color treatment, and gate weave are off by default. Enable them only when they support the selected direction.
• Move promising tests into Film mode. A successful Quick mode beat sheet can become a longer production roadmap.
• Budget disk space for long renders. Quick mode streams frames directly into MP4 and normally needs only a few hundred megabytes. Film mode may require several gigabytes for each project during rendering.
• Use current Claude Code builds. The documented guard hooks require support for exec-style hooks and onFailure. Older builds may still render films, but the guard may not activate.

Conclusion

Cinecode turns an AI coding agent into a guided local filmmaking workflow rather than a simple text-to-video prompt. Install the skill, open an empty folder, describe the film, approve its plan and preview frames, then refine the audiovisual draft before rendering the final MP4. Start with a short Quick mode project, learn the approval stages, and move to Film mode when the story requires research, narration, archives, or a longer structure.

Source and installation updates are available from the Cinecode GitHub repository.