Skip to content

Configuration ​

Formercial is configured in three places:

  • Environment variables (or .env): where things are, and how the app runs.
  • src/formercial.config.ts: extra render drivers and voice providers.
  • Each project's project.json: everything about one commercial. See project.json.

Environment variables ​

Put them in .env at the repository root (copy .env.example), or set them in your shell. A bad value stops startup, and the error names the variable.

Formercial ​

VariableDefault
FORMERCIAL_PROJECTSprojectsThe projects folder, relative to the repository or absolute.
FORMERCIAL_TRUST_FILE~/.config/formercial/trust.jsonWhere trust for custom scenes is kept. Keep it outside the projects folder.
FORMERCIAL_HISTORY_FILEa file under .formercial/Where project history is kept.
FORMERCIAL_VOICEen-US-AvaNeuralVoice for new projects. Each project then keeps its own in project.json.
FORMERCIAL_FPS30Render frame rate unless a render asks for another: a whole number from 1 to 60.
FORMERCIAL_DRIVERchromium-ffmpegRender driver unless a render asks for another. Set it to chromium-nvenc to use an NVIDIA GPU.
XDG_CONFIG_HOME~/.configMoves the default trust file to $XDG_CONFIG_HOME/formercial/trust.json.
CHROMEthe newest Playwright headless shellThe Chromium (or Chrome) binary renders use.
FORMERCIAL_RENDERunsetSet by kick formercial render on the server it starts: turns hot reload off. You don't normally set it yourself.

The app ​

VariableDefault
PORT3000Port for pnpm dev and pnpm start.
NODE_ENVdevelopmentdevelopment, production or test.
LOG_LEVELinfoServer log level.
SESSION_SECRETa public dev-only valueRequired (32+ characters) when NODE_ENV isn't development or test.
APP_URLhttp://localhost:3000Required when NODE_ENV isn't development or test.

Formercial is a local tool. Run it with pnpm dev. If you build it (pnpm build, pnpm start), set SESSION_SECRET and APP_URL, and still keep it on your own machine: see Security.

Keeping projects in a bucket (experimental) ​

Projects are read and written through @forinda/kickjs-storage. Setting S3_BUCKET moves them into an S3-compatible bucket (AWS S3, Cloudflare R2, MinIO):

Variable
S3_BUCKETBucket name. Setting it switches storage to the bucket.
S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEYCredentials (or neither, for an IAM role).
S3_REGIONDefault us-east-1; auto for R2.
S3_ENDPOINTFor R2 or MinIO; unset for AWS.
S3_SESSION_TOKEN, S3_FORCE_PATH_STYLEAs your provider needs.

With a bucket, the editor doesn't notice outside changes to project.json, and the command line still reads projects from a folder. Local folders are the supported setup.

src/formercial.config.ts ​

Adds render drivers and voice providers next to the built-in ones (chromium-ffmpeg and edge-tts). The editor and the command line both read it.

ts
import { defineConfig } from './core/render/registry'
import { gpuDriver } from './drivers/gpu'

export default defineConfig({
  drivers: [gpuDriver],
  voices: [],
})

Names must be unique, and a duplicate stops startup. See Render drivers and voice providers for how to write one.

kick.config.ts ​

The kick formercial commands are registered here as a kick CLI plugin:

ts
plugins: [formercialCliPlugin(formercialConfig)],

Add your own commands with another plugin. See Command line → Your own commands.

Files and folders ​

PathIn git
projects/<name>/project.jsonyesThe commercial
projects/<name>/media/yesLogo, music, fonts
projects/<name>/voice/*.rec.webmyesYour recordings
projects/<name>/voice/*.tts.mp3, voice/.made.jsonnoGenerated lines; remade when needed
projects/<name>/renders/noRendered MP4s and .srt files
~/.config/formercial/trust.json(outside the repo)Which projects' custom scenes may run here

Released under the Apache License 2.0.