Share a graphic

A .fjgraphic file, called a package on this page, carries one graphic with the fonts and pictures it uses, so you can move it to another project or give it to someone else with Frame Job. Finder calls the file a Frame Job Graphic.

Menu: Insert ▸ Graphic…
Where: Export… and From File… in the Insert Graphic sheetA .fjgraphic opened from the Finder
Agent tools: export_graphicimport_graphic

Export a graphic

Choose Insert ▸ Graphic… and pick the graphic in the Insert Graphic sheet. It can be a bundled template or one from This Project.
Choose Export…. It’s dimmed when the chosen graphic doesn’t compile, and while another export is running.
A save panel slides down over the sheet, with the file already named after the module, such as lower-third.fjgraphic. Choose where to put it and save.

The Insert Graphic sheet stays open. The line under its lists says Exporting <title>…, then Exported <title> to <file>: followed by the files the package holds, or says why it couldn’t.

Saving over an existing file replaces it whole. If the export fails, the file already there is left as it was.

Exporting changes nothing in the project and isn’t an undo step.

What a package packs

A package holds the module, which is the script that draws the graphic, and only the project fonts and pictures the graphic uses. To find those, Frame Job draws the graphic and packs what it saw used:

Every frame with the default properties. A graphic longer than 900 frames has 900 frames spread evenly over it.
Then each other choice of each Enum property and the other value of each Boolean property, one at a time, over up to 30 frames each. It tries at most 32 of these.

A font is packed when the graphic drew or measured text with it, or fell back to it for a character its own font lacks. A picture is packed when the graphic’s asset(name) drew it. The app’s own fonts are never packed, because every copy of Frame Job has them, so a bundled template’s package holds its module and nothing else.

A frame that fails to draw is skipped.

The .fjgraphic file

A package is a zip with nothing compressed. It holds manifest.json, the module, and the fonts/ and assets/ folders. The manifest gives the package’s format, the module, its title, category and description, the Frame Job version that wrote it, and each file’s path, name, size and SHA-256.

Exporting the same graphic twice with the same version of Frame Job gives byte-identical files.

A file name a zip path can’t hold is stored under a tidied name. That covers a : or \, a control character and a leading ., so a:b.ttf is stored as a-b.ttf. The manifest keeps the original, so a font is still found by its family and asset(name) still finds its picture.

A package can hold at most about 4 GiB and 65,535 files.

Open from the Finder

Frame Job is the app macOS uses for these files. Double-click a .fjgraphic, open it with Open With, drop it on Frame Job’s Dock icon, or open it from a browser’s downloads. Frame Job checks the package, then puts up the Import Graphic sheet.

The package goes into the front project, the one whose window is in front. With no project open, it goes into a new untitled project. A package that fails its checks before the sheet appears shows an alert and opens no project.

If Frame Job wasn’t running, it opens first and the package waits until any projects it reopens are back, so it lands once, in one project, with no Welcome window.

File ▸ Open… doesn’t list .fjgraphic files, and there’s no menu item for importing one.

Import with From File…

Choose Insert ▸ Graphic…, then From File…. The Insert Graphic sheet closes and a file panel opens.
Choose a .fjgraphic. The Import Graphic sheet appears for that same project.

The panel also takes a .js module, which goes straight onto the timeline. See Insert a graphic.

The Import Graphic sheet

Before anything is copied, the sheet shows the graphic’s title and description, then what will happen to each file:

Line	What it can read
Module	`Module: lower-third`, `Module: lower-third (already in this project)`, or `Module: lower-third-2 (lower-third is taken)`
Fonts	The font files, each plain, marked `(already here)`, or marked `(as Inter-2.ttf)`. With none, `Fonts: none`.
Pictures	The picture files, each plain or marked `(already here)`. With none, `Pictures: none`.

Under them it says “Importing copies these files into this project’s graphics. It is not an Undo step.”

Choose Import to copy the files, or Cancel to copy nothing.

If the project’s graphics folder changed while the sheet was up and the import can’t go ahead, Frame Job beeps, the sheet stays open and it says why.

Name clashes

An import never replaces a file. Each file keeps the name the package gives it, unless that name is taken:

The project already has	What happens
A file of that name with the same contents	It’s used as it is, and the sheet says “already here”, or “already in this project” for the module.
A different module of that name	The module is copied under a new name with `-2`, `-3` and so on: `Module: lower-third-2 (lower-third is taken)`.
A different font of that name	The font is copied under a new name, such as `as Inter-2.ttf`. A font is found by its family, so its file name changes nothing.
A different picture of that name	The import stops, because the module asks for its pictures by name. An alert says so. Rename or remove the project’s file and import again.

A name that differs only in case counts as taken. A module name also counts as taken while any clip still uses it, even when its file is gone.

To find the project’s pictures, see Fonts and pictures in graphics.

After an import

Import copies the files into the project’s graphics folder and opens the Insert Graphic sheet on This Project with the graphic chosen, ready to insert. The line under the lists says what happened:

Imported Lower third as lower-third. Added: lower-third.js, fonts/Inter.ttf. Already here: assets/logo.png.

An import only copies files. It places no clip, so choose Insert when you want one on the timeline.

Importing isn’t an undo step and doesn’t mark the project as edited. An untitled project keeps the files when it’s first saved. If a copy fails part-way, what it had copied is removed.

Package checks

Frame Job checks a package before it copies anything. If a check fails, nothing is copied, and the message reads <file> cannot be imported: followed by the reason.

What’s wrong	What the reason says
The file is empty	`it is empty (0 bytes)`
It isn’t a zip, or it’s damaged	For example `the package is not a zip: no end of central directory record`
It was compressed, for example by zipping it again	`<entry> is compressed (method 8); a .fjgraphic holds stored entries only`
It was changed after it was written	The entry that differs from the manifest by path, size or SHA-256, such as `<entry> is 2048 bytes, but the manifest says 1024`
A newer Frame Job wrote it	`the package is format 2; this Frame Job reads format 1 — a newer Frame Job wrote it`
A font is bad	`the font "<name>" is not a .ttf or .otf file`, or why it doesn’t load
A picture is bad	`the picture "<name>"` and why: it isn’t a PNG, JPEG, GIF, WebP, SVG or SVGZ file, its name can’t be used, or it’s empty

A module that doesn’t compile passes these checks and is imported. It’s listed on This Project with Export… dimmed, and Insert places nothing and shows the first error. Fix it the way you’d fix any module. See Edit a module.

With an agent

export_graphic is Export…, writing to a path instead of through a save panel, and it also says how many frames it drew and how many failed. It writes nothing for an unknown graphic, a module that doesn’t compile or a folder that doesn’t exist. The Assistant asks you before it runs, because it can replace a file.

import_graphic is Import without the sheet, so nothing asks first. See Tools: graphic fonts, pictures and packages.