Acue

Commands

acue is run from a terminal. You write a story as a text file, and one command turns it into a book: the pictures, the soundtrack and a video. This page goes through it task by task.

Rather not use a terminal? acue studio does much of the same in your browser: drop a story file on its page and it comes back as a book. acue on its own opens a full-screen interface in the terminal. Everything below runs without it, so it also works from a script.man acue lists every option. To install acue first, see Setup; to write a story file, see Directives.

Where your files go

acue keeps what you write and what it makes in your own folders, named as your desktop names them, so a German desktop has ~/Bilder/Acue:

  • stories and photo book drafts in ~/Documents/Amber/Acue/
  • books in ~/Pictures/Amber/Acue/, in a folder named after the model that drew them
  • their videos in ~/Videos/Amber/Acue/
  • music auditions in ~/Music/Amber/Acue/auditions/

Your settings stay in ~/.config/acue/. acue reads every text file in the stories folder, subfolders included, in sorted order, and never removes anything it made.

See which models are installed and ready:

acue --list

Check a file

Before a long run, check the file. acue reads it without starting a model or going online, and warns about every line it cannot use, with the line and column. This file has two mistakes on purpose: a seed that is not a number, and --ratio misspelt:

--seed nope--image the lighthouse alone in the fog--ratoi wide--image the harbour from above
$ acue check harbour.txt
harbour.txt:1:8: warning: --seed takes a whole number, -1 or more
harbour.txt:3:1: warning: --ratoi is not a directive; did you mean --ratio?
1 file, 2 pictures, 2 warnings, 0 errors

A warning never stops a file. acue --print-stories lists every picture a run would draw, numbered, so you can see how your story was split before anything is made.

Draw a story into a book

Name the model, and add --book to bundle each story file with its pictures into one .acue book:

$ acue --run zimage --book
story1: 28 image(s) in 9m14s
story2: 28 image(s) in 9m41s
wrote 2 book(s) to /home/you/Pictures/Amber/Acue/zimage

Each book is named after the file that made it, with a .sha256 beside it so a book you publish can be checked after download. --seed 42 repeats a run exactly.

A --card line draws a title or a few words as a panel of its own, and --hold sets how long a panel stays on screen. Both are on the Directives page.

--ratio sets the shape of the pictures: square, landscape, portrait, wide, tall or wallpaper. Each model draws at its own size for that shape, and landscape (3:2) is the default. Wide (16:9) fills a video frame, and the city books use it. Wallpaper is 16:9 upscaled to 3840 × 2160, for a desktop background. A --width or --height beside it wins, and with one side given the other follows the shape.

A book with a soundtrack

A book in several parts, like a day in a city, is a set of story files and one book file beside them: paris.book.toml with paris-morning.txt, paris-lunch.txt and so on. The book file holds the title, the pace of the video and the music: one track per part, each described in a sentence or two.

Hear the music before drawing a single picture. This makes four takes of every track in seconds, each the length its part will need, in ~/Music/Amber/Acue/auditions/:

acue --audition --takes 4

Each take is printed with its seed. Write the seed of the one you like into that track as seed = N, and every build makes exactly that piece. Then acue --run zimage --book makes the whole book, one .acue with the soundtrack under it, and its video as an .mp4 in ~/Videos/Amber/Acue/.

acue --print-soundtrack shows how long each track will be, and flags a part that would play in silence.

A book that sings

A book's soundtrack can be a short song for each part, sung in the book's language, in place of music alone. In the book file, kind = "song" says so, language is what it is sung in, singer is who sings it, and each track's style describes its song. ACE-Step, an open music model, sings it:

[soundtrack]
kind     = "song"
language = "fr"
singer   = "Amberlin, a young woman in her mid twenties with copper-red hair in a short plait"

  [[soundtrack.track]]
  segment = "morning"
  style   = "chanson française, café accordion, upright bass, brushed drums, a young woman's clear vocal singing in French, romantic and light"

First the words:

acue draft lyrics

For each part, a chat model reads the story's words, never a --note, and sums them up in a few sentences, in the song's language. From that summary it writes short lyrics, sung in the first person, with an instrumental intro and outro and a chorus that repeats. A reply in the wrong language is asked for again. Ours is Qwen, on our own server.

Each part's lyrics go into a file beside the book, paris-morning.lyrics, with an English translation under them that is never sung. Edit them as you like: a lyrics file that is there is kept, unless you add --force. Lyrics you write yourself need no chat model at all.

Then listen. This makes two takes of every song:

acue --audition

A sung take cannot be made again from its seed, so the one you like is kept as a file. It is copied beside the book, and every build uses it as it is:

acue --keep ~/Music/Amber/Acue/auditions/paris/paris-morning-seed-1234.wav

Our Paris songs are in French, Berlin's in German, London's in English, Rome's in Italian and Kyiv's in Ukrainian, all sung by Amberlin. A song book is not narrated: a voice would talk over the singing.

A book read aloud

A book can be narrated: a voice speaks a line or two over each scene, and the music eases down under it. Each line is a --speak line in the story, or a story's own paragraphs under --paragraphs spoken, as the Directives page shows. acue --paragraphs spoken, or paragraphs = "spoken" under [stories] in acue.toml, reads every story that way. acue can draft the lines for you:

acue draft narration

A chat model writes one line a scene, from one --scene to the next, in the book's language, from the story's words, never a --note, and puts it into the story for you to edit. A --brief at the top of the story steers it. A scene that already has a line keeps it; --force drafts over every scene, and never over your paragraphs. Read the drafts: now and then the model invents a detail.

The book file's [narration] table sets how it sounds:

[narration]
voice    = "ff_siwis"
language = "fr"
speed    = 0.92
duck     = 12

voice is a Kokoro voice, and its first letter is its language: f French, i Italian, b British English. language is what the lines are written in, speed is the pace, and duck is how many decibels the music drops while the voice speaks. Before each line the music glides down over 1.5 seconds, and after it the music comes back up.

A line longer than its scene keeps the scene's pictures on screen longer, and the music is made to the new length. The .acue holds the narration with its subtitles, and the music beside it; the video plays the two mixed.

Our voices: ff_siwis reads Paris in French, if_sara reads Rome in Italian, and bf_emma reads London, Berlin and Kyiv in English, since Kokoro has no German or Ukrainian voice. Kokoro runs on our own server. Narration is optional: without a speech server, the book is made without it, and acue says so.

acue finds its servers in servers.toml, in ~/.config/acue/. Besides Forge Neo for the pictures, it names Stable Audio for the music, a chat server for lyrics, photo captions and narration drafts (it can read pictures), and a speech server for the narration. These three are optional: without music or narration a book is still a book, and lyrics and narration you write yourself need no chat server.

Make a photo book

A folder of your own photos becomes a book the same way, with a soundtrack and a video, and no pictures drawn. On Linux Mint, Pinax does it from a folder with Make a book…; in a terminal, acue first writes a draft into ~/Documents/Amber/Acue/, and nothing into your photo folder:

$ acue photos ~/Pictures/Naples
wrote /home/you/Documents/Amber/Acue/naples/naples.book.toml
wrote /home/you/Documents/Amber/Acue/naples/naples-2026-10-05.txt
3 photo(s) in 1 part(s)
next: write the captions, or draft them with acue draft captions --stories-dir /home/you/Documents/Amber/Acue/naples, then make the book with acue --stories-dir /home/you/Documents/Amber/Acue/naples --book

The photos are put in the order they were taken and cut into parts by day, and at gaps of more than three hours. Each part gets music in a mood: holiday, family, travel or calm. Each photo gets a line of its own, ready for a caption, and a place if you want one:

--photo IMG_0412.jpg --caption the harbour at dawn --location Naples

acue draft captions drafts the empty captions with a vision model on your own server, for you to check and edit. Each photo is sent to that server only, scaled down and with no metadata, and the captions name no one and describe no face. Without that server, the captions stay empty for you to write.

Then make the book. This starts no image model:

acue --stories-dir ~/Documents/Amber/Acue/naples --book

Inside the book every photo is turned upright, scaled to at most 2560 pixels and saved with no metadata at all: no GPS position, camera, serial number or owner. A place appears only where you wrote one. Your originals are never changed.

To print it, one photo to a page with its caption, inside a 15 mm margin and with the fonts embedded, on A4 or a 210 mm square:

acue --print ~/Pictures/Amber/Acue/naples.acue --page square --out naples.pdf

Add --for screen for a smaller file to share, each picture a JPEG at 150 dpi.

Compare models

Name two or more models to draw the same stories with each, on the same seed, so the model is the only difference:

acue --run ernie,klein --book --seed 42

Then lay two to four of the books side by side in one PDF, every model's take on each picture on one page:

acue --proof ernie/paris.acue klein/paris.acue --out paris-proof.pdf

Change a finished book

A book carries its own story files, so it can be changed later without the folder it came from. This unpacks it beside itself, once, and the original is never written:

acue --rebuild paris.acue

Edit the files in the new folder, then make what changed:

acue --rebuild paris.acue --images     # redraw the pictures whose lines you edited
acue --rebuild paris.acue --audio      # the soundtrack and video, from the book as edited
acue --rebuild paris.acue --audition   # takes of the music to choose from

Changing the pace changes how long every track must be, so --audio remakes the music and video in minutes without redrawing a picture.

Read it on paper

acue --guide renders markdown files into one printable PDF. The full guide is made that way, and you can download it from Downloads.