The command line tool
buhayin-cli: check, render, export, run a script and import from a terminal.
buhayin-cli works on scene files from a terminal, with no window. It uses the same code the editor does, so a frame it renders or a movie it exports comes out as it does from the editor. Use it to render and export many scenes in one go, to check scenes for problems, and to run a script over a folder of them.
It is inside the app, at Buhayin.app/Contents/MacOS/buhayin-cli. With Buhayin in Applications that is:
/Applications/Buhayin.app/Contents/MacOS/buhayin-cliTo run it by its name from any folder, link it onto your PATH once, or add the folder to your PATH in ~/.zshrc:
sudo ln -s /Applications/Buhayin.app/Contents/MacOS/buhayin-cli /usr/local/bin/buhayin-cli
export PATH="$PATH:/Applications/Buhayin.app/Contents/MacOS"Use one of the two. The commands below are written as buhayin-cli, which assumes it is on your PATH.
buhayin-cli <command> [options] <scene files>
buhayin-cli <command> --helpA scene file ends in .bhy. --help lists the options of any command. A file it cannot open is refused in plain words: it does not exist, is a folder, is empty, is not text or not a scene.
The commands
| Command | What it does |
|---|---|
info | Prints a scene's name, length, frame rate, size, layers and render targets. |
check | Runs the editor's scene check. |
render | Renders one frame to a PNG. |
export | Exports frames, movies, sprite sheets and storyboard PDFs. |
edit-list | Writes a storyboard's shots as an edit list. |
xsheet | Writes the scene's Xsheet as a PDF. |
script | Runs a script on scene files. |
import-vector | Brings an SVG, PDF or AI file into a scene. |
import-harmony | Converts a Harmony scene folder into a scene file. |
production, playback, cache | Tools for timing the editor, described at the end. |
info
buhayin-cli info scene.bhyPrints the scene's name, length, frame rate, size, layers and render targets. A storyboard whose dissolves share frames also says how many frames play, such as 18 frames, 14 played.
check
buhayin-cli check scene.bhy
buhayin-cli check --fix scene.bhyThe same check as Scene > Check Scene…. Problems that change the picture come first, then notes that may be meant. A file it cannot read is reported and passed over.
| Flag | What it does |
|---|---|
--fix | Puts right what can be put right in one step. It writes each file back first, and says what it fixed and every file and folder it wrote. |
The exit status is 1 while any file has problems, and 2 at the end when a file could not be read.
render
buhayin-cli render scene.bhy --frame 12 --size half --out frame12.pngRenders one frame as the finished shot: white paper, through the camera, straight at the size.
| Flag | What it does |
|---|---|
--frame N | The frame, from 1. Frame 0 is refused. |
--size | full, threeQuarters, twoThirds, half, third or quarter of the scene's size. Anything else is full. |
--draft | Taken and ignored. Every frame is painted at its size either way. |
--out file.png | Where to write it. By default <title>-<frame>.png in the current folder. |
It also takes the four render script flags below. Anything a frame leaves undrawn is named on standard error.
export
buhayin-cli export scene.bhy --format mp4 --frames 1-48 --out scene.mp4
buhayin-cli export --targets project-folder --out renders.zipExports as File > Export… does, into a zip, a folder, or a movie file. It takes scene files, or with --targets scene files or project folders.
| Flag | What it sets |
|---|---|
--format | png (the default), jpeg, psd (layered, one file a frame), tiff, exr (8 bit pictures written as half floats), sheet (a sprite sheet and its JSON), skeleton (an image for each attachment, with its data and a README), gif, mp4 (H.264), webm (VP9) or mov (ProRes). |
--codec | For a MOV: prores422proxy, prores422lt, prores422, prores422hq (the default) or prores4444, which keeps the alpha of --transparent. |
--from, --to, --frames | The first and last frame. --frames 1-24 sets both and wins over the other two. A first frame after the last, or outside the scene, is refused with exit 2. A last frame past the scene's is held to it, with a line saying so. |
--size, --draft | The size, as for render. |
--transparent | Leaves the paper out, for a PNG, PSD, sheet or a MOV in ProRes 4444. |
--separation | line, colour or matte in place of the whole picture, for any format but a skeleton. |
--layers | Only these layers, named and split by commas, anywhere in the scene's tree. |
--dither | A GIF's dithering: none, diffusion, pattern or noise. |
--no-loop | A GIF that plays once. |
--sheet | A sprite sheet's layout: grid (the default), easel, paper2d or xml. |
--trim, --drop-empty, --drop-duplicates | What a packed sheet cuts down, leaves out or draws once. |
--sheet-width, --sheet-height | The widest and tallest a packed sheet may be, 128 to 16384 pixels, 8192 by default. |
--jpeg-quality | A JPEG's quality in percent, 50 to 100, 92 by default. Another value is refused. |
--target | Renders the scene's render target of that name, as it is set up. |
--targets | A batch render: every render target each scene keeps, or every scene of a project folder, into one zip or folder. Targets turned off are passed over. |
--pdf, --profile | The storyboard's boards as a PDF, laid out by a profile that ships with Buhayin or one the board keeps. |
--out | A .zip, a folder, the movie's own file, or the PDF. By default <name>.zip, <name>.mp4 (or .webm, .mov) or <name>.pdf in the current folder. |
A storyboard's frames are numbered as it plays, and the last line counts the frames written, such as Frames 1 to 18, the 14 that play. A movie format this build cannot write is refused with the reason, or left out of a batch.
The render script flags
render and export can run a script round a render.
| Flag | What it does |
|---|---|
--pre-render-script file.js | Runs a script file on each scene as it is read. |
--pre-render-inline-script "code" | The same, with the code on the command line. |
--post-render-script file.js | Runs a script file on each scene after its render is written. |
--post-render-inline-script "code" | The same, with the code on the command line. |
The edits of a pre render script show in the render and are never written to the file. A post render script sees hook.output. A script that fails stops the command with exit 2.
edit-list
buhayin-cli edit-list board.bhy --format otio --out board.otioWrites a storyboard's shots as an edit list for a video editor.
| Flag | What it does |
|---|---|
--format | edl (CMX 3600), otio, xml or aaf. |
--out | Where to write it. |
xsheet
buhayin-cli xsheet scene.bhy --pdf xsheet.pdfWrites the scene's Xsheet as a PDF, laid out in the pages the Xsheet prints, with hidden columns left out. --pdf is required, and --out means the same.
script
buhayin-cli script cleanup.js a.bhy b.bhy --out cleanedRuns a script on scenes as the Script view runs it, each scene in a sandbox of its own, stopped at 10 seconds. The script comes first, then the scene files.
| Flag | What it does |
|---|---|
--out | Where the changed scene goes. For several scenes it is a folder. |
--frame N | The frame the script starts on, 1 by default. A frame outside the scene is refused with exit 2. |
--layer name | The current layer for the script. A layer the scene does not have is refused with exit 2. |
The script sees buhayin, print and console. It also sees hook, with hook.event set to batch. The scene's pictures are loaded first, so the script can paint a canvas it has, and with --out the canvases it painted are written beside the scene it leaves. A script file exported from the Script view loses its first line, the name.
There is no window, so calls that need the editor throw NO_EDITOR, and buhayin.ask throws NO_WINDOW.
import-vector
buhayin-cli import-vector --scene scene.bhy --out with-art.bhy art.svgBrings an SVG, PDF or AI file into a scene file. Each page becomes a drawing on a frame of one drawing layer, with its fills, pencil lines and their colours in the palette. Nothing in the file is fetched from anywhere else. What the file held that is not read is listed in the answer.
| Flag | What it does |
|---|---|
--scene, --out | The scene to add to, and where to write the result. Both are required. |
--layer | The layer to draw on. |
--frame | The first frame to put a page on. |
--first-page, --last-page | Which pages of a PDF to bring in. |
import-harmony
buhayin-cli import-harmony scene-folder --out imported.bhyConverts a Harmony scene folder into a scene file and its assets. A file of several scenes makes a scene file for each, the others named for their scenes beside the first. What has no place in Buhayin is named on standard error. A file already at --out is refused. The Harmony files are only read.
| Flag | What it does |
|---|---|
--out | Where to write the scene file. |
Tools for timing the editor
production <folder>writes a large scene into the folder to time the editor against, with its pictures and sound inassets.--layerssets how big, 987 by default.playbacktimes frames painted as the player paints them ahead.--frames,--size,--threads,--card,--layers,--preview,--autoand--compare FOLDERchoose how, with--max-mean,--max-over-8and--max-over-32as limits for--compare.cachereads the file of finished frames beside a scene, and--clearempties it first.
Exit status
| Status | Meaning |
|---|---|
| 0 | It worked. |
| 1 | check found problems, or playback --compare went past a limit. |
| 2 | A bad argument, such as a frame outside the scene, a file it could not read, or a render script that failed. |