FilmOpen Software Specification
The application — on Windows, Linux, Android, macOS and iOS — that reads, browses and edits FilmOpen projects: how it is built, and the rules that must stay true when adding to it.
| Version | 7.9 |
| Date | 10 November 2026 |
| Status | Describes the application as of the date above. Updated in the same change as the code it describes. |
| Companion documents | The FilmOpen Project Specification defines the file format this software reads and writes; the FilmOpen MCP Specification describes the agent layer as an agent uses it. |
| Repository | filmopen-app (filmopen-ai/filmopen-app on GitHub). This specification is the folder docs/software/ there; the pages under packages/ are generated from the code. |
The specification is in parts. Section numbers are kept across them, since the code and the other documents cite them (§6.11, §9.3).
| Part | Sections |
|---|---|
| Purpose | 1 |
| Design principles | 2 |
| Technology | 3 |
| Architecture: the packages, the data flow, the agent layer | 4 |
| The packages, one page each (generated from the code) | — |
| The model layer | 5 |
| Services: files, the writer and the log | 6.1–6.5, 6.16 |
| The account, the device and provider keys | 6.6–6.7 |
| The issue recorder, and sending a recording | 6.8 |
| Media and Google Drive | 6.9–6.10 |
| Plug-ins | 6.11 |
| Jobs, bringing media in, sync, renders and comparisons | 6.12–6.15, 6.17 |
| Exchanging a film | 6.18 |
| State and the tree | 7–8 |
| The user interface | 9 |
| Localisation, and the sample project | 10–11 |
| Testing | 12 |
| Conventions for contributors, and third-party code | 13, 15 |
| Known limitations, and points to address | 14, 16 |
| Glossary of code names | Appendix B |
| The timeline engine | 19 |
1. Purpose
Section titled “1. Purpose”A FilmOpen project is a folder of plain JSON files describing a film completely: characters, outfits, locations, props, styles, documents; the script as folders and scenes, nested as in a file system, a scene holding the blocks; shots and cues; models, platforms and plugins; render batches; commentary; and official pointers. Every entity file is versioned per author (ch_main-hero_30yo_john123_v2.json), forking copies a file into a new author’s name, and a small _official.json pointer names the version the project has chosen. The intent is that a film is developed the way software is developed: many people, many versions, comparison, and a deliberate choice of what is official.
FilmOpen the application is the reader and editor for such folders. It is a reader: open a folder, see the whole project as a tree, inspect any object, see every version of it side by side, see the media rendered for it and what people said about it, and be warned about everything the format’s rules say a reader should warn about. It is an application that lives on a machine: it reads a project’s documents from data/ and its media from media/ (§4 of the format), where the shared library of models, platforms and plugins is, where its own preferences and log are, which projects the user has opened, and it can create a project folder. It is a writer: a new project comes with its creator’s first project file, the project file is edited in a form that saves as you type, any version can be forked, a director sets official with a star, anyone picks the version they work from with a check, and a version can be labelled.
The application is not the format. The Project Specification is authoritative about what files mean; this document is authoritative about how the application is built. Where the application simplifies the format’s rules, this document says so.
1.1 Audience of this document
Section titled “1.1 Audience of this document”A developer, or an AI coding agent, who has read the Project Specification and needs to continue the code without re-deriving its structure. It explains what exists, the reasons behind the shape of it, and the rules that must stay true when adding to it.