The production bible#

Applies to v0.10Last reviewed

In short

The production bible records what "the same" means for each recurring character, place, prop or look, with the reference images that define it, and whether you have the right to use each. The Bible tab is where you build it; CODA can add to it and draft its rights, and only you affirm them.

A twenty-minute film is hundreds of shots, and what makes them feel like one film is that the same character has the same face in every one of them. The production bible is where you record what "the same" means: one entry for each recurring character, place, prop or look, with the reference images that define it, and a record of why you may use each.

Those references are then supplied to every generation that involves that entry. The bible is not documentation about your production — it is the input your production runs on.

The Bible tab#

The Bible tab sits in the middle of the workspace, between Script and ViewportThe tabs above the work areaA map of the Zymcos workspace. The five tabs above the work area, marked 1 to 5, are Home, Script, Bible, Viewport and Files.1Home is the first tab: the production at a glance.2Script is the Production Book, where the writing lives.3Bible sits between Script and Viewport: a list on the left and the entry you choose on the right.4Viewport is the stage, where the take you chose is shown.5Files is the last tab: every file in the production.A map of the Zymcos workspace, drawn from its layout. Your screen has more on it.. It is a list on the left and the entry you choose on the right.

The list has four sections, one for each kind of entry:

SectionWhat it is for
CharactersPeople you want to look the same in every shot. The entry whose face has to hold.
PlacesSets and locations that scenes return to and that should stay recognisable.
PropsObjects that have to match every time they appear.
LooksA look supplied as conditioning to hold across the production. Not an identity, and never scored as one.

A new production's Bible is empty, and each section says what it is for and offers a button to make the first one ("New character", "New place", "New prop", "New look"). The API and the glossary call each entry an entity; on screen it is always a character, a place, a prop or a look.

Across the top of the tab is the lock strip: where the Bible's lock is, the Lock version N button and History (see Locking). Each row shows its name and up to three small labels: where its lock is, where its identity checks are (once it has been locked) and where its rights are (all explained below). Choose a row and its details open beside the list, in the order you need them: its name, its rights, its references, and what has been locked.

  • Make one. Choose the section's "New …" button, type a name (1 to 200 characters) and create it. A name is unique within its kind in a production, so "which Maya?" is never a guess; if the name is taken the tab says so and nothing is made. The pack starts empty.
  • Rename it in place with the pencil beside the name. Enter saves and Escape leaves it as it was. A rename does not need the rights re-affirming.
  • Delete it, while it has never been locked. A confirmation names what goes. Once an entry has been locked into the Bible, shots may have been made from it, so the tab shows no Delete and says why in one line; the lock is the record of what your finished shots were made from.
  • Its kind does not change. If you made a place that should have been a prop, delete it (while it has never been locked) and make the prop.
  • A voice a character has is shown ("Has a voice") and cannot be changed from the tab.

Anything you have started typing in the tab (a new name, a rename, a rights form) counts as unsaved work: the workspace will not switch to another tab on its own (for example when a take finishes generating) while it is open, and shows a small marker on the Viewport instead.

What the small labels mean#

Where the lock is. Locking the Bible takes a numbered snapshot (see below), and each row says how its entry stands against the newest one:

  • Not locked yet. It has never been in a snapshot.
  • In version 3. It was snapshotted in version 3 of the Bible and has not changed since. The number is the Bible's, the same one on the Lock version button, not a count of how often this entry has changed.
  • Edited since version 3. It has changed since that snapshot, so locking again would make a new version of it.

"Edited since" is worked out by Zymcos, with the rule the lock itself uses, not by the screen.

Where the identity checks are. After a lock, Zymcos measures each locked character, place and prop from its pictures, so that shots can be checked against how it looks (see The continuity gate). It does this by itself, a few minutes after the lock, and the row says where it has got to. A look has no identity checks and shows no label.

  • Identity checks: preparing. The measuring has not finished. Nothing is wrong; give it a few minutes. Until it is ready, nothing says shots are being held to this entry.
  • Identity checks: ready. Shots made with this entry are checked against its pictures.
  • Identity checks: can't be measured. Zymcos looked at the pictures and could not find what it measures: no clear face in a character's pictures, or no usable picture of a place or prop. The label's hover text and the details beside the list say which. Shots can still use the entry, but how well a shot matches it is reported as not measured, never as a pass. The fix is better pictures (a clear, front-on face for a character), then a new lock; the same pictures will not measure differently later.
  • Identity checks: unavailable. The checks could not run for the moment, because of a fault on Zymcos's side, and Zymcos tries again by itself. Nothing is wrong with your pictures.

Where the rights are. One of the four choices below, in plain words; Rights not set when none has been affirmed; or Rights withdrawn when the permission behind the newest locked version was withdrawn.

Recording the rights#

A person's likeness, a place or an object is someone's property, and the first question a studio's counsel asks about an AI-assisted production is whether every character in it has a documented basis. The Rights form in an entry's details is where you record it. There are four choices:

ChoiceWhat it says
I made itYou or your team made it, so the production may use it as its own.
I have a licenceA licence covers this use. Say what it covers.
The person agreedA real person agreed to be shown. Record who agreed and how.
AI-made, no real personMade with AI and not based on a real person.

Beside the choice there is one line, What does this cover? (up to 200 characters): "all uses in this production", "licensed to 2027, film and trailer".

For "The person agreed" you also record who agreed and how it was recorded ("signed release, filed 12 March"). Both are required, and Zymcos refuses the save without them, naming the missing one beside its field: a consent with nothing recorded is worse than no basis at all, because it reads as permission and shows nothing a person could be asked for.

You can also attach the file that evidences the consent, such as a photo of the signed release. Under Evidence (optional), Choose or upload a file opens the same dialog the reference pack uses, for one file: pick one of the production's pictures, or upload one from your computer. The chosen file's name is shown with a Clear, and it is kept with the consent record. An attached file is evidence and nothing more: it does not make the consent true, and attaching one grants no rights. A file already attached is kept when you affirm again.

Affirm rights is the one button, and the click is the attestation: you are saying it is true. It stays dimmed while the form matches what is already saved, and wakes when you change something. Nothing else records a basis. In particular CODA never does (see below).

Two things to know about how it behaves:

  • No basis is not an error. A draft legitimately exists before the paperwork does. The form says so, and also says what it costs: a shot cannot be cast with an entry until a basis is affirmed. Zymcos records your basis; it does not judge whether it is enough. What it does enforce is that an entry with no basis, or whose rights have been withdrawn, never reaches a shot, so nothing you pay to generate is conditioned on an undocumented likeness.
  • Re-curating a pack clears the rights. Consent names specific images, so changing which images an entry uses invalidates the permission that described the old ones. After you save a changed pack the entry reads Rights not set again, and you affirm it again in this tab, unless you chose to keep the rights when you saved (see the next section).

When someone else changed it while you were editing#

If a teammate (or CODA) changed the entry after you opened it, your save is refused rather than overwriting theirs, and the tab says so: "Maya changed while you were editing. This is what it says now." What the entry says now is shown above the form, what you typed is kept in the fields, and nothing is merged for you. Look at it, change what you need to, and affirm again: that save is against the version you have now seen.

Asking CODA#

CODA can work on the Bible with you, and it always knows which entry you mean when you have one selected in the tab:

  • Add, rename and delete. "Make a character called Mara" and "rename her to Maya" are done at once, and CODA's reply shows what it did with an Undo (a made entry is undone by deleting it, a rename by putting the old name back). If you ask in your own words, "delete the prop Mug", and the entry holds no pictures and no rights, CODA deletes it and says so. If CODA suggested the deletion and you answered "ok", or the entry holds pictures or rights, you get a confirmation card instead, and nothing is deleted until you click Delete on it. CODA will not offer to delete an entry that has been locked.

  • Stage a rights draft. "She signed a release on 12 March" gets a card in CODA with the basis, what it covers and who agreed, in your words, and one button: Open in the Bible. That selects the entry, switches to the tab and fills the form with the draft. Nothing is saved until you click Affirm rights. CODA cannot set a basis, a scope or a consent itself, and it cannot change an entry's kind, voice or pack from here: an attestation is a click, not an inference from a sentence.

  • Add a still. The Viewport's Add to Bible (or "put this in Mara's pack" to CODA) puts a still into an entry's reference pack. If you ask CODA in your own words ("add that picture to Mara's references"), it adds it and says so, with the note that her rights need affirming again. If adding it was CODA's idea and you answer "ok", the card reads Add this picture to Mara's references (or the picture's name, when it has one) over an Add to references button, and nothing changes until you press it. When it is done the note offers Open in the Bible. With no entry yet, the dialog sends you to the tab to make one first. A pack that already holds twelve pictures is marked full in that dialog and cannot be chosen.

  • Take one out, or make one the main reference. "Take the hat photo out of Mara's references" and "make the side view her main reference" are done at once when you ask for them, and CODA's reply says what it did with an Undo, which puts the earlier pictures back (when it was CODA's own idea and you answered "ok", you get a card first). Like any change to a pack, it clears the entry's rights, and CODA says so; Undo clears them again. CODA can only take pictures out and reorder the ones already there (to add a picture it uses Add to Bible, and uploading is yours to do in the tab), and it never keeps the rights for you: only you can tick that box.

  • Lock the Bible. Ask for it in your own words ("lock version 1", "ok go ahead and lock it", "freeze it") and CODA runs the lock's check and puts the lock card in the conversation, the same card the Bible tab's strip opens, with what is still open and the Lock version N button. CODA never locks for you, even when you ask: a lock is one-way, so nothing is locked until you click, and on autopilot she does not lock either. The lock needs the same permission as the Bible tab's own button, and CODA never affirms rights for you: that click is yours. If a lock would be refused (the Bible is empty, entries have no references, nothing has changed), CODA says what is missing. A card left in the conversation goes quiet once its version has been locked.

Type @ in the message box to insert a character, place, prop or look by its exact name, once it has been locked into the Bible. CODA's cards say what the locked Bible contributed to a proposal, or why it could not.

Reference packs, and why they matter#

An entry's reference pack is the list of pictures that define it. The References section of its details is where you build it: the pictures are shown as a row, in order, with a count against the limit ("6 of 12").

Today's generation models hold identity from references rather than from a description. Give them the same three photographs of a character in shot after shot and the character stays recognisable; describe her in words instead and she drifts. Everything else here (versions, locking, the continuity check) exists to make sure the right references reach the right shot.

The first four are the ones shots use#

Order is meaning. A shot is offered the first four pictures of an entry's pack, in order, and the first of them is the one the others support. Each of the first four says Counts as a reference. Any after the fourth are drawn quieter and say Kept, not used: they are spares you can bring forward, and the section says so in one line ("Shots are held to the first four. Drag, or use Move earlier and Move later, to change which."). When you drag a picture a line shows where it will land (before the one you are over), and a Last in the pack box appears at the end.

A pack holds 12 pictures at most: four are used, the rest are spares, and a limit stops the fingerprint of an entry drifting toward whatever was added last. When a pack is full, Add references waits and says why.

Changing a pack#

Everything you do in the section is a draft. Nothing is saved until you choose Save references (or throw the draft away with Discard), so a drag, a removal and an addition are one decision. A draft counts as unsaved work, so the workspace will not switch tabs on its own while you have one.

  • Reorder by dragging a picture to a new place, or with the keyboard: each picture has Move earlier and Move later buttons. Moves are announced to a screen reader ("Side moved to position 3 of 6").
  • Remove takes a picture out of the pack. The picture itself stays in Files.
  • Add references opens a dialog with two ways in:
    • From your files lists this production's pictures. Tick as many as you like; ones already in the pack are marked and cannot be added twice, and the dialog stops at the room the pack has left. The filter above the list searches the pictures that are loaded, which it says; Load more widens it. Withdrawn and erased files are not offered.
    • Upload takes one or more pictures from your computer (JPEG, PNG or WebP, up to 20 MB each). Each is sent in turn, shows its own state, and is refused in plain words if it cannot be used: a HEIC photo, a file that is too large, a full workspace, too many uploads at once. A file that finishes is added to your choice.

What an upload is. An uploaded picture becomes a file of this production, in Files. It stays there even if you discard the draft or never save it. Uploading records that the file was put here; it does not grant any right to use what is in it. The rights of an entry are the entry's own, and you affirm them.

Only pictures can be references. Zymcos refuses, and says why, a file that is not an image, a file that is withdrawn or erased when it is being added, and a thirteenth picture.

Withdrawn and erased pictures#

A picture already in a pack can later be withdrawn or erased in Files. It is not dropped: a pack that changed behind your back would be worse. It stays in the row, marked Withdrawn: not used in shots or Erased, each with its Remove, and neither is ever counted among the pictures shots use. A picture the production no longer returns reads Not found, and can be removed the same way.

Saving a changed pack clears the rights, and the section says so first#

When an entry has a rights basis and you have a draft, the section says: "Changing the references clears this entry's rights. You will affirm them again." Above Save there is one choice, off by default: Keep the current rights (I confirm they cover these references). Leave it off and the rights are cleared when you save, and you affirm them again. Tick it and the current basis, scope and consent are sent in the same save, which is you saying they still cover the new pictures. The tick is your attestation, as Affirm rights is; CODA can never tick it. An entry with no basis has nothing to clear, so it shows neither the sentence nor the box.

Practical guidance:

  • Several references beat one. The identity fingerprint is built from the whole pack, not from whichever image happens to be first, so a varied pack is more robust than a single hero image.
  • Duplicates are dropped, order is kept. Sending the same image twice does not weight it twice.
  • Show the thing you want measured. A character whose pack is only back-of-head shots has no face to compare against, and her identity simply cannot be checked. That is reported honestly rather than passed silently, but it is easier to fix in the pack than in a shot.
  • A reference must belong to the same project. An image id from anywhere else is rejected.

When two people edit one pack#

Each entry carries a pack revision, a number that goes up every time its pack, its voice or its rights change. The Bible tab sends back the revision it was looking at when you affirm rights, and so does anything you build against the API (expected_pack_revision, required whenever a request sets reference_asset_ids, voice or a rights field; renaming needs none). A request that omits it is answered with 428 Precondition Required, and the revision may instead be sent as the standard header If-Match: "<revision>".

If someone else changed the pack after you read it, your change is refused rather than overwriting theirs: the answer is a 409 stale_pack carrying the pack as it stands now, so you can look at it and decide whether your change is still wanted. In the Bible tab the section says the entry changed while you were editing, keeps your draft in the order you left it, and shows the pictures the pack holds now; Save references again to replace them, or Discard to see them. Nothing is merged for you, and nothing of yours is saved. Adding a take to a pack from the Files tab, or asking CODA to, follows the same rule: if the pack moved in between, you are told and nothing is added.

Locking: a snapshot, not a state#

A locked version's pictures are not edited in place. In an entry's References, while the pictures are exactly what a version locked, a line says These are the references locked in version 3. Changing them starts a new version; version 3 stays as it is until you lock again.

Locking the bible takes a numbered snapshot of the whole registry. Every entity in the project gets a fresh, immutable version carrying the pack and the rights it had at that moment, and the snapshot itself is recorded as version 1, 2, 3 and so on. Shots you make from then on are held to those versions as they were on that day.

The word "lock" is film vocabulary, and it can mislead here, so it is worth being precise:

  • Nothing is frozen. Your entities stay editable after a lock. That is deliberate — a production keeps developing, and only the version a finished shot was made from must not move.
  • There is no unlock, because there is no state to leave. Correcting a mistake means editing the entities and locking again. Versions accumulate, which is intended and costs nothing.
  • A version, once minted, never changes. That is what makes a retake reproducible: a shot redone six weeks later uses exactly the references it used the first time, even if the entity has moved on since. It is also what makes drift attributable — you can point at a specific locked reference rather than at a moving target.

The lock strip#

The strip across the top of the Bible tab says where the Bible's lock is, in one line: Version 3 locked 2 October, or Not locked yet. Beside it are History and the Lock version 4 button, which always names the version the next lock would make. The strip is drawn from what Zymcos reports about the Bible now, so it never offers a lock that would be refused:

  • Lock version 4 is available when a lock would do something new.
  • Nothing has changed since version 3. The button waits. A lock where nothing differs would only repeat the last one. (Renaming an entry on its own is not a change to what shots are held to: a name is not part of a locked version.)
  • 2 entries need references. The button opens the card, which names them (see below).
  • The Bible has no entries yet. The button waits.

History opens a list of every lock so far, newest first: its version, its date and how many entries it took. It is a list to read; there is no comparing two versions and no going back to one.

The lock card: check, then one click#

Pressing Lock version 4 opens the lock card right there, under the strip. Nothing is locked yet. Its first line says what it would do: Lock version 4: 12 entries, 3 changed since version 3, 2 without rights. Under it is the lock's check, one row for each thing a lock cares about, each with a word (fine, open or stops it) and, where something is open, the names with a Show me link that opens the place:

  • Entries, Pictures (entries with no pictures stop the lock), Rights (entries without a basis, which can still be locked, and a shot cannot be cast with them until one is affirmed) and Changes since the last lock;
  • a line at the end of the check: Nothing is open. You can lock. or These are still open. You can lock anyway.;
  • what a lock means: Shots you make from now on are held to these as they are today. You can keep editing and lock again; a lock is never undone.

The check is a compact box tinted by its verdict, green when nothing is open, amber when something is and red when the lock would be refused. On a wide panel each row's detail sits to the right of its label, so the whole check fits without scrolling. The lock buttons carry a padlock, and a locked script's Unlock button an open one.

When the check found things open the button says Lock anyway; when nothing is open it says Lock version 4. It is the second step, and the only one that locks. Cancel closes the card and puts you back on the strip's button; nothing was saved. Afterwards the strip says Version 4 locked, and the rows' labels change by themselves.

If the card says a lock cannot go ahead, it says why. When the reason is that entries have no references, each is listed with Add references, which selects that entry and takes you to its References section, where you add pictures; then come back and lock.

If someone else locks version 4 while you are looking, the card says Version 4 was locked while you were looking; this is the new state. and shows what a lock would take now. Nothing is lost and nothing was locked twice.

A member who can only view the production sees the strip, the card and History, and the card's lock button waits with a sentence saying locking is for members who can curate.

What an entry shows of its locks#

What has been locked, in an entry's details, lists the versions a lock took of that entry, newest first: the Bible's version it was in, the date, the rights it was locked with (or that it had none, or that they were withdrawn), where its identity checks were, and its pictures. The newest version shows its pictures at once; Show pictures opens the others. An entry with a long history shows the latest 50 and says how many there are.

When a lock is refused#

A snapshot covers the whole registry, so it refuses rather than quietly skipping. The strip and card say each of these before you press, and again if one arrives after:

  • An entity with an empty reference pack. The card names the unfinished entities. An entity with no references cannot condition a generation and cannot be checked for continuity; the lock is the cheapest moment to notice that.
  • A project with no entities at all. There is nothing to snapshot.
  • Nothing has changed. No entry differs from the last lock and none was added.
  • A version someone else just took. Two people locking at the same moment is resolved by refusing the second rather than silently creating two near-identical snapshots. The card shows the new state; lock again if there is still something to lock.

What a lock reports rather than refuses#

A lock tells you how many entities it snapshotted and how many of them have no rights basis yet — "12 entries, 2 without rights". It is a report, not a blocker. Drafts legitimately exist before the paperwork does, and a bible you cannot snapshot until every release form is signed would stop all creative work on a legal dependency.

The refusal that protects you arrives later and more precisely: a shot cannot commit to a version with no basis, so nothing is generated from it.

Casting a character into a shot#

A shot is held to the entries you cast in it: the pictures of each are what a generation of that shot is made from, and what its continuity is measured against. You cast from the shot editor (the Edit button on a shot in the Script tab), in its Cast section: one row for each entry of the Bible, grouped as Characters, Places, Props and Looks, each saying where it stands for this shot.

  • Not in this shot has a Cast button. It casts the entry's newest locked version, at once, and an Undo follows.
  • In this shot says which version of the Bible it was cast from ("As locked in version 3") and has Take out.
  • In this shot, with a newer version in the Bible says both numbers and offers Update. A shot never moves to a newer version by itself: a shot with takes made against version 2 is a different shot once it is held to version 3, so that is your click. Update swaps the two in one step, so the shot is never left uncast between them.
  • Not locked into the Bible yet offers Lock first, which opens the Bible on that entry. The editor never locks anything for you.
  • A shot cannot be cast with this until a basis is affirmed offers Rights, which opens the Bible. An entry whose rights were withdrawn cannot be cast, and the editor offers no way round it.

A cast shot is held: a take made for it is made on a model that takes character pictures, and its card says Holds Mara's look from Bible v2. If no model on your plan can hold a cast character, no card is made and nothing is spent (see Create).

Under the section a line says what the cast does to a generation: "Held to 7 pictures; 2 did not travel", and for each picture that did not, why (withdrawn, erased, or beyond the first four a shot is held to). Changing the cast does not change takes already made: each score keeps the version it was measured against.

You can ask CODA in words: "put Maya in shots 2 and 3" or "take Maya out of shot 2". It casts the newest locked version into each shot you name (at most twelve at a time), says which shots it changed and which it did not, and offers Undo. Casting never locks the Bible and never sets rights to make a cast possible: if an entry cannot be cast it says why, and you ask for the lock or do the rights yourself.

Withdrawing rights#

If a permission is withdrawn, the affected version is marked as revoked. This is the one change that is ever made to a locked version, and it is not retroactive:

  • shots that already committed to it stand — they are the record of what happened, and rewriting history would destroy the provenance the record exists to give you;
  • new commitments to that version are refused from that moment on.

What happens after a lock#

Locking is also what makes continuity measurable. After a lock, Zymcos reduces each version's reference pack to a compact fingerprint by itself, one for a character's face, one for a figure or prop, one for a set, and the continuity check compares generated frames against those. The row's Identity checks label says where that has got to (see "What the small labels mean"). A pack that yields nothing usable leaves that fingerprint absent, and the check says so rather than inventing a result.

That side of the system is described in The continuity gate.