Directives
A story file is a story you already have, as plain text, with a few lines added that start with two dashes. Those lines are directives: they tell acue what to draw and what to speak. Everything else stays your story.
The quickest start is one line. Put --paragraphs drawn at the top of a poem, a story or a chapter, and every paragraph gets a picture:
--paragraphs drawn The fog came in over the harbour before the boats were back. By noon the lighthouse was the only thing still standing in it.That gives you a first set of pictures to look at. Then refine it: --style sets the look of every picture, --scene says where the story is set, and an --image line describes a picture in your own words. Put it on the line under a paragraph, with no blank line between, and it replaces that paragraph's picture; after a blank line it adds a picture of its own. This file makes two pictures:
--paragraphs drawn--style soft watercolour, muted greys and blues--scene a small harbour town, early morning The fog came in over the harbour before the boats were back.--image the lighthouse alone in the fog, a single lamp lit --image the harbour from above, every mooring emptyWithout --paragraphs, a file makes pictures only where you write an --image line, and the rest stays text. A story that needs two or three pictures you choose does it this way. This makes one picture:
The fog came in over the harbour before the boats were back.--image the lighthouse alone in the fog, a single lamp lit By noon the lighthouse was the only thing still standing in it. The boats came home one by one in the evening.Then bring a picture to life. An --animate line under a picture turns it into a short video clip: say what moves, and what the camera does. The clip starts from your picture and keeps its look, and in the book's video it plays in the picture's place. Ending with what the camera does matters: left to itself, the camera may wander.
--style soft watercolour, muted greys and blues--scene a small harbour town, early morning --image the lighthouse alone in the fog, a single lamp lit--animate the fog drifts past the tower and the lamp turns, the camera holds still --image the harbour from above, every mooring emptyText can be a page of the book too. A --card line draws its words. Right under a picture, with no blank line, the picture blurs and the words fade in over it; after a blank line, the card is plain, on the paper colour. --hold says how long a page stays on screen, in seconds: on a line of its own for everything after it, or on one page's line for that page only.
--hold 7 --card The Harbour --image the lighthouse alone in the fog, a single lamp lit--card By noon it was the only thing still standing. --hold 10Two to four pages can share one comic page. A --panel line takes the picture and card lines under it, and a card can be a speech bubble:
--style four panel colour comic book, clean ink lines, flat colours --panel --hold 6 --caption Paris, the first morning--image she reads the menu at a café table--card Paris was never the city on the map. --border bubble--image the waiter sets down two coffeesA book can be read aloud. A --speak line is spoken over the pictures after it, up to the next words spoken. A voice speaks it, and the music eases down under it:
--style soft watercolour, muted greys and blues--scene a small harbour town, early morning --speak Morning fog lay over the harbour, and the lighthouse lamp glowed warm through it, waiting for the boats.--image the lighthouse alone in the fog, a single lamp lit--image the harbour from above, every mooring empty --scene the harbour at dusk--speak By evening the boats came home one by one, and the whole town came down to meet them.--image fishing boats sliding into the harbour at duskA story told in paragraphs can be read as it is: --paragraphs drawn spoken draws every paragraph and speaks it too. A --speak line right under a paragraph says that paragraph another way, the way an --image line there draws it another way:
--paragraphs drawn spoken The fog lay soft over the harbour as the boats set out. By noon the sun had burned it away, and the lighthouse shone white.--speak By noon the whole harbour sparkled in the sun.Your own photos work the same way. Each --photo line is a page, and its --caption is printed under it. A --note is for you alone:
--title 14 July--location Rome--note Captions checked by hand; IMG_0420 left out on purpose. --scene the Forum at noon--photo day-1/IMG_0412.jpg --caption The Forum at noon--photo "day-1/IMG 0413.jpg" --caption Lunch in Trastevere --location Trastevere, RomeHow a file is read
- Only a line that starts with two dashes is a directive, and it may be indented. Dashes inside a sentence, as in “twenty--thirty boats”, stay part of your story.
- Lines with no blank line between them belong together: a paragraph and the
--imageor--speakunder it, a picture and the card or--animateunder it, a panel and its pages. A blank line ends that. - Short text goes on the directive's line. Longer text goes on the lines under a directive written on its own, up to the first blank line. Both of these set the same look:
--style soft watercolour, muted greys and blues --stylesoft watercolour,muted greys and blues --image the boats coming in - A setting such as the look, the place, the size or the voice holds until you change it. Here the first two pictures are set in the harbour, and the third at the lighthouse:
To go back to what the top of the file set, write--scene a small harbour town, early morning--image the boats coming in--image the fish market opening--scene the lighthouse at night--image the lamp turning--resetwith the setting's name, such as--reset --hold;--reseton its own puts back every setting. - A mistake never stops the file. A line that cannot be read is skipped, with a warning that gives its line and column. A misspelt directive gets a suggestion: “--ratoi is not a directive; did you mean --ratio?”. The rest of the file still makes its pictures.
acue checkreads a file and lists every warning without drawing anything.
Where your words go
- Everything runs on machines you choose. The tables below say, for each directive, which of them its text can reach: the image model, the voice, the book, or a picture's metadata.
- A language model reads your story only when you ask for a draft:
acue draft narration,draft lyricsordraft captions. Every line except a--notemay reach it then. - A
--notenever reaches any model and is never written into a picture's metadata. - A book carries its whole story file, notes included, so it can be made again from itself. Anyone you give the book to can read every line of it.
| Directive | Image model | Language model, in a draft | Voice | Shown in the book | Picture metadata |
|---|---|---|---|---|---|
--title | no | yes | no | yes | yes |
--brief | no | yes | no | no | no |
--scene | yes | yes | no | no | yes |
--style | yes | no | no | no | yes |
--location | no | yes | no | yes | yes |
--ratio | yes | no | no | no | yes |
--width | yes | no | no | no | yes |
--height | yes | no | no | no | yes |
--steps | yes | no | no | no | yes |
--guidance | yes | no | no | no | yes |
--seed | yes | no | no | no | yes |
--avoid | yes | no | no | no | yes |
--voice | no | no | yes | no | no |
--speed | no | no | yes | no | no |
--image | yes | yes | no | no | yes |
--photo | no | no | no | yes | no |
--card | no | yes | no | yes | yes |
--video | yes | yes | no | no | no |
--speak | no | yes | yes | yes | no |
--animate | yes | no | no | no | no |
--caption | no | yes | no | yes | yes |
--frames | yes | no | no | no | no |
--fps | yes | no | no | no | no |
Every other directive, --note among them, reaches nothing outside acue but the book's copy of the story.
The part
At the top of the file, before the first paragraph, picture or spoken words. They hold for the whole file.
| Directive | Takes | What it does | Its text reaches |
|---|---|---|---|
--title | text, on its line or as the lines under it | The part's title: the chapter head, the .acue chapter's title, and with the book's title each page's metadata title, Book · Part. Without one, the caller's. | a language model, in a draft, the book, picture metadata |
--brief | text, on its line or as the lines under it | What any language model working from this file is told: acue studio's system prompt for its text jobs, appended to acue's drafts. | a language model, in a draft |
Scenes and settings
A setting holds until you change it or write --reset. Several settings can share one line: --ratio wide --hold 6.
| Directive | Takes | What it does | Its text reaches |
|---|---|---|---|
--scene | text, on its line or as the lines under it | A new scene starts here, set in its text. The setting joins every drawn prompt in the scene; the drafts group by scene. --scene "" starts one with no setting. | the image model, a language model, in a draft, picture metadata |
--style | text, on its line or as the lines under it | The look of every drawing and clip, leading its prompt. Read by the image and video models, never by a language model. | the image model, picture metadata |
--location | text, on its line or as the lines under it | Where the entries are. Holds until changed; on an entry or panel line, that one's place alone. Printed under the entry and written into its metadata. | a language model, in a draft, the book, picture metadata |
--paragraphs | one or more of drawn, spoken, or "" for none | What plain paragraphs become: drawn (pictures), spoken, both, or "" for neither. The caller sets the default. | acue only |
--ratio | one of square, landscape, portrait, wide, tall, wallpaper | A drawing's shape: square (1:1), landscape (3:2), portrait (2:3), wide (16:9), tall (9:16), or wallpaper, 16:9 upscaled to 3840x2160. The host draws it at its model's size for that shape; a --width and --height beside it win, one alone keeps its side. | the image model, picture metadata |
--width | a whole number, 1 or more | A drawing's width in pixels. | the image model, picture metadata |
--height | a whole number, 1 or more | A drawing's height in pixels. | the image model, picture metadata |
--steps | a whole number, 1 or more | Sampling steps, for drawn pictures. | the image model, picture metadata |
--guidance | a number from 0 to 100 | How closely the model follows the prompt (CFG scale), for drawn pictures. | the image model, picture metadata |
--seed | a whole number, -1 or more | The seed; -1 asks for a random one. No maximum: a backend with a narrower seed enforces its own. | the image model, picture metadata |
--avoid | text, on its line or as the lines under it | What a drawing or clip must not show: the negative prompt. Never joins the composed prompt, never reaches a language model. | the image model, picture metadata |
--hold | a number from 2 to 15 | Seconds on screen, 2 to 15. On an entry or panel line, for that one; on a clip line, the clip's length. Without it, the host's time. | acue only |
--voice | one word | The voice of the spoken words that follow. The caller's (a book's [narration] voice) stands until a file sets one. | the voice |
--speed | a number, above 0 | The voice's pace; 1 is its own. | the voice |
--volume | a level from 1 to 9 | The voice's level, 1 to 9: 5 is as recorded, each step 3 dB. | acue only |
--ambient | a file name, or "" for none | The sound under the voice: a base name in the host's ambient folder, or "" to stop it. Mixed locally. | acue only |
--ambient-volume | a level from 1 to 9 | The ambient sound's level, 1 to 9. | acue only |
--segment-fade | a number, 0 or more | Fades each segment of spoken words in and out over this many seconds; 0 is none. | acue only |
--join-pause | a number, 0 or more | The silence before each segment where it joins the one before. | acue only |
Pages
Each line is one page or moment of the book. The options listed after it are for that page only.
| Directive | Takes | What it does | Its text reaches |
|---|---|---|---|
--image | text, on its line or as the lines under it on its line: --ratio --width --height --steps --guidance --seed --avoid --hold --location --caption | A drawn picture; its value, on the line or as a bare paragraph, is the prompt, composed as look, entry, setting. | the image model, a language model, in a draft, picture metadata |
--photo | a file path, relative to the story file on its line: --hold --location --caption | Your photo, a JPEG or PNG used as it is: its path relative to the story file. Never drawn, never animated; the parse never opens it. | the book |
--card | text, on its line or as the lines under it on its line: --hold --border | Words drawn as a page, kept as written. Over the last picture above it in its block, blurred; with none, on the paper colour. | a language model, in a draft, the book, picture metadata |
--video | text, on its line or as the lines under it on its line: --ratio --width --height --seed --avoid --hold --frames --fps --location --caption | A clip from its text alone, composed with the look and the setting. | the image model, a language model, in a draft |
--panel | the picture and card lines under it, two to four on its line: --ratio --width --height --hold --location --caption | The two to four --image and --card lines under it are one comic page: two side by side, three as one tall slot beside two stacked, four as a grid. Its line holds the page's shape, hold, location and caption. | acue only |
Spoken words
What the voice says, and what belongs to its neighbours.
| Directive | Takes | What it does | Its text reaches |
|---|---|---|---|
--speak | text, on its line or as the lines under it | Words to speak over the entries after them. In a block with a paragraph, that paragraph's words; otherwise words of their own. --speak "" is silence. | a language model, in a draft, the voice, the book |
--pause | a number, above 0 | Seconds of silence in the spoken words. | acue only |
--animate | text, on its line or as the lines under it on its line: --seed --avoid --hold --frames --fps | Puts the last picture above it in its block into motion; its text is the motion. | the image model |
--overlay | a level from 1 to 9, or nothing | The next spoken words play over the ones before, at this level (2 when bare). | acue only |
Options on a page's line
These ride on a page's line and are for that page alone.
| Directive | Takes | What it does | Its text reaches |
|---|---|---|---|
--caption | text | Public words under this one entry: printed, shown, and written into the .acue and the page's metadata. Nothing in force becomes a caption. | a language model, in a draft, the book, picture metadata |
--border | one of none, square, round, bubble | The frame of a card's words: none, a ruled box, a rounded one, or a speech bubble pointing at the picture beside it. | acue only |
--frames | a whole number, 1 or more | A clip's length in frames; the host snaps it to what its animator accepts. | the image model |
--fps | a whole number, 1 or more | A clip's frame rate. | the image model |
Notes and reset
| Directive | Takes | What it does | Its text reaches |
|---|---|---|---|
--note | text, on its line or as the lines under it | A private note. Never reaches a model, never written into metadata. It stays in the story, and the book carries the story: anyone given the book can read it. | nothing: only the book's copy of the story |
--reset | nothing, or the settings to put back | Puts settings back to what the top of the file set: every setting when bare, or each one it names. | acue only |
Next: run your file
With a story file written, Commands shows how to check it, draw it into a book and add a soundtrack.