Acue

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 empty

Without --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 empty

Text 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 10

Two 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 coffees

A 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 dusk

A 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, Rome

How a file is read

Where your words go

DirectiveImage modelLanguage model, in a draftVoiceShown in the bookPicture metadata
--titlenoyesnoyesyes
--briefnoyesnonono
--sceneyesyesnonoyes
--styleyesnononoyes
--locationnoyesnoyesyes
--ratioyesnononoyes
--widthyesnononoyes
--heightyesnononoyes
--stepsyesnononoyes
--guidanceyesnononoyes
--seedyesnononoyes
--avoidyesnononoyes
--voicenonoyesnono
--speednonoyesnono
--imageyesyesnonoyes
--photonononoyesno
--cardnoyesnoyesyes
--videoyesyesnonono
--speaknoyesyesyesno
--animateyesnononono
--captionnoyesnoyesyes
--framesyesnononono
--fpsyesnononono

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.

DirectiveTakesWhat it doesIts text reaches
--titletext, on its line or as the lines under itThe 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.
--title Morning--image she steps out into the morning
a language model, in a draft, the book, picture metadata
--brieftext, on its line or as the lines under itWhat any language model working from this file is told: acue studio's system prompt for its text jobs, appended to acue's drafts.
--brief Write short, happy sentences for a child of six. Pip sat on a lily pad.
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.

DirectiveTakesWhat it doesIts text reaches
--scenetext, on its line or as the lines under itA 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.
--scene a café terrace in Paris, morning--image she reads the menu
the image model, a language model, in a draft, picture metadata
--styletext, on its line or as the lines under itThe look of every drawing and clip, leading its prompt. Read by the image and video models, never by a language model.
--stylesoft anime style, clean linework, warm light --image Pip on a lily pad
the image model, picture metadata
--locationtext, on its line or as the lines under itWhere 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.
--location Rome--photo day-1/IMG_0412.jpg--photo day-1/IMG_0440.jpg --location "Ostia Antica"
a language model, in a draft, the book, picture metadata
--paragraphsone or more of drawn, spoken, or "" for noneWhat plain paragraphs become: drawn (pictures), spoken, both, or "" for neither. The caller sets the default.
--paragraphs drawn spokenPip sat on a lily pad, waiting for the rain.
acue only
--ratioone of square, landscape, portrait, wide, tall, wallpaperA 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.
--ratio wide--image the whole pond at dusk--image Pip on a lily pad --ratio portrait
the image model, picture metadata
--widtha whole number, 1 or moreA drawing's width in pixels.
--width 1216 --height 832--image Pip on a lily pad
the image model, picture metadata
--heighta whole number, 1 or moreA drawing's height in pixels.
--width 1216 --height 832--image Pip on a lily pad
the image model, picture metadata
--stepsa whole number, 1 or moreSampling steps, for drawn pictures.the image model, picture metadata
--guidancea number from 0 to 100How closely the model follows the prompt (CFG scale), for drawn pictures.the image model, picture metadata
--seeda whole number, -1 or moreThe seed; -1 asks for a random one. No maximum: a backend with a narrower seed enforces its own.
--seed 7--image Pip on a lily pad--image Pip mid-leap --seed -1
the image model, picture metadata
--avoidtext, on its line or as the lines under itWhat a drawing or clip must not show: the negative prompt. Never joins the composed prompt, never reaches a language model.
--avoid blurry, lowres, extra fingers--image Pip on a lily pad --avoid people
the image model, picture metadata
--holda number from 2 to 15Seconds 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.
--hold 8--image the bridge at dusk--card Rome, evening --hold 4
acue only
--voiceone wordThe voice of the spoken words that follow. The caller's (a book's [narration] voice) stands until a file sets one.
--voice bf_emma --speed 1.05 --volume 6
the voice
--speeda number, above 0The voice's pace; 1 is its own.
--speed 1.1Pip held his breath.
the voice
--volumea level from 1 to 9The voice's level, 1 to 9: 5 is as recorded, each step 3 dB.
--volume 6Pip held his breath.
acue only
--ambienta file name, or "" for noneThe sound under the voice: a base name in the host's ambient folder, or "" to stop it. Mixed locally.
--ambient rain.wavRain drummed on the pond.--ambient ""
acue only
--ambient-volumea level from 1 to 9The ambient sound's level, 1 to 9.
--ambient rain.wav --ambient-volume 2Rain drummed on the pond.
acue only
--segment-fadea number, 0 or moreFades each segment of spoken words in and out over this many seconds; 0 is none.acue only
--join-pausea number, 0 or moreThe 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.

DirectiveTakesWhat it doesIts text reaches
--imagetext, 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.
--image --ratio portraitshe stops under a tall stone arch,looking up
the image model, a language model, in a draft, picture metadata
--photoa 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.
--location Rome--photo day-1/IMG_0412.jpg --caption "The Forum at noon"
the book
--cardtext, 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.
--image the Colosseum at dawn--card The city wakes --hold 6
a language model, in a draft, the book, picture metadata
--videotext, 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.
--video a harbour at dawn, gulls lifting off the water --width 832 --height 448
the image model, a language model, in a draft
--panelthe 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.
--panel --hold 6--image she reads the menu at a café table--card Paris was never the city on the map. --border bubble
acue only

Spoken words

What the voice says, and what belongs to its neighbours.

DirectiveTakesWhat it doesIts text reaches
--speaktext, on its line or as the lines under itWords 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.
--speak Amberlin stepped off the train into a grey morning.--image Amberlin on the platform, her satchel held tight
a language model, in a draft, the voice, the book
--pausea number, above 0Seconds of silence in the spoken words.
Pip held his breath. --pause 1.5Then he jumped.
acue only
--animatetext, 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.
--image her hand flat on a warm stone wall--animate sunlight slides down the wall onto her hand
the image model
--overlaya level from 1 to 9, or nothingThe next spoken words play over the ones before, at this level (2 when bare).
--speak The pond went quiet. --overlay 2--speak A frog croaked in the reeds.
acue only

Options on a page's line

These ride on a page's line and are for that page alone.

DirectiveTakesWhat it doesIts text reaches
--captiontextPublic words under this one entry: printed, shown, and written into the .acue and the page's metadata. Nothing in force becomes a caption.
--photo day-1/IMG_0412.jpg --caption "The Forum at noon"
a language model, in a draft, the book, picture metadata
--borderone of none, square, round, bubbleThe frame of a card's words: none, a ruled box, a rounded one, or a speech bubble pointing at the picture beside it.
--image she reads the menu--card Two coffees, please. --border bubble
acue only
--framesa whole number, 1 or moreA clip's length in frames; the host snaps it to what its animator accepts.
--video gulls lifting off the harbour --frames 97 --fps 24
the image model
--fpsa whole number, 1 or moreA clip's frame rate.the image model

Notes and reset

DirectiveTakesWhat it doesIts text reaches
--notetext, on its line or as the lines under itA 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.
--note check Pip's colours against chapter one--image Pip on a lily pad
nothing: only the book's copy of the story
--resetnothing, or the settings to put backPuts settings back to what the top of the file set: every setting when bare, or each one it names.
--reset --voice --ambient
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.