Local images and video
Mercury's bundled local media extension generates images and video with models on your own computer. It is off by default. Generation uses your disk, memory and time, with no paid media-generation API.
The bundled runtime needs Apple Silicon macOS, curl and unzip. Video posters also need ffmpeg on PATH.
Turn it on
Open /config, find Local media, switch it on and save with Enter. Enabling the extension connects it in the current session without downloading the runtime or weights. Switching it off in the same place disconnects it.
Open /imagesetup to choose and download the runtime and models. Completing a model download turns Local media on and connects it in the current session.
Download a model
- Read the table. The top line shows the media folder, memory and free disk space. Each model row names its kind, licence and default slot, followed by its remaining download size, total disk size, memory requirement, available seconds per image and whether it fits. Disk uses decimal GB; memory uses GiB. Shared components already installed do not need downloading again.
- Select the runtime with the arrow keys and press
p. The download card shows the size, destination, source and licence. Pressyto download ornto go back. The runtime archive is 37.6 MB. - Select a model and press
p. Read its download card before confirming. Progress shows the file and downloaded bytes. Pressescto pause and keep the partial files; select the row and presspagain to resume. - Press
don a model to make it the default. Image and video have separate slots. This changes a saved choice without loading weights or downloading files. - Press
ton an installed image model to try it. With Local media on and the runtime installed, Mercury requests a 256×256 image of a red apple through the normal permission card, then shows the image and its saved path. Pressescto cancel a running test, return from a preview or close the table.
The fit calculation leaves 8 GiB for the operating system and other work, and checks accelerator memory too. The table's timings describe catalogue image runs; dimensions, steps, video length and other applications affect the time and memory a request needs. There is no download-time estimate.
Choose the defaults
In /config, Default image model and Default video model change the same slots as d in /imagesetup.
Omit model to use the default; name a model only when the user asks for a specific one. Asking for another model changes that call alone and leaves the saved slot unchanged. Changing a slot does not restrict which models can be requested later. Installed models and saved defaults are available on the next media-tool call without reconnecting.
For example, “Generate an image of a lighthouse at dusk” uses the image default. Asking to use a particular installed model selects it for that request. Asking to make it the default saves it for future requests.
The catalogue and download card show each model's licence. Some weights permit commercial use under Apache-2.0; others are non-commercial or have territorial and commercial-use restrictions. Read the terms before downloading. The extension's licence does not replace the weights' terms.
Ask the agent
| Tool | What it does |
|---|---|
media_models |
Lists models, licences, installed sizes and defaults without loading weights. |
media_status |
Reads the image and video engines, their models, state and memory without starting them. |
media_set_default |
Changes an image or video slot without loading a model. |
image_generate |
Generates a PNG from a prompt, with a reference image when the selected model supports editing. |
video_generate |
Generates video from a prompt and optional starting image. Specify frames or seconds, never both. |
media_jobs |
Lists jobs and their progress. |
media_result |
Reads a job's result, saved file and image or video poster, with an optional wait. |
Generation returns a job id by default. wait: true waits for completion. A result wait expiring does not cancel the render. Closing the submitting client cancels its unfinished jobs; completed files remain available. Image previews are at most 1024 pixels on their long side; the full image stays on disk. Video returns WebM when the runtime supports it, otherwise AVI, with a PNG poster.
The Local image or Local video permission card names the effective model, dimensions, steps and output folder, plus the prompt and any reference. Video details include length and fps. When the call names no model, the card marks the effective model as the default for its kind.
Find the files
Media folder in /config sets media.root, normally ~/.mercury/media under Mercury's config home. It holds the runtime, model files, media configuration and logs. Choose another absolute path if needed; changing it does not move existing weights.
Generated files normally go into the project's media/ folder. In <media.root>/config.json, outputs selects another destination, relative to the media folder or absolute. MEDIA_OUTPUT_DIR overrides it. Without an output setting or project, files go to ~/Desktop/mercury-media.
The default slots live in that media config as imageModel and videoModel. The /config row ids media.imageModel and media.videoModel edit them there; they are not Mercury settings keys. Explicit MEDIA_IMAGE_MODEL and MEDIA_VIDEO_MODEL environment variables override the saved slots, and media.serverPath in user settings optionally overrides the path to a development server.js.
In /health, Local media shows whether it is off, the media folder, or a missing folder or runtime with /imagesetup as the next step. It also points out slot keys stored in Mercury's settings instead of the media config.
Limits and other models
Images and video have separate engines, each processing one render at a time. The server checks available memory before loading weights. When a video job fits, the image model can stay loaded; otherwise the server waits for the other work to finish and unloads idle weights. Engines unload after five idle minutes.
Video models have minimum dimensions and frame-count rules. Requests below a model's size floor return its requirement without rendering. Catalogue sizes and times do not guarantee that every resolution or video length will fit. One video entry has an estimated memory budget and no measured clip time. On Metal, video uses CPU VAE decoding by default while diffusion remains on the GPU.
Add supported local models in <media.root>/catalog.json, then reconnect the extension. Entries need an id, kind, licence, engine recipe, generation defaults and component slots, with paths under models/, byte sizes and memory budgets. Place the weights at those paths yourself. Adding an entry does not download weights or make an unsupported architecture work; the installed engine must support its architecture and format. The model then appears in setup and the default pickers and can be selected by id.