Format providers
Teach Atlas to index and preview file types it does not handle on its own. A provider supplies a thumbnail and details for its extensions, and the files then show up in the grid like anything else.
Declare a provider
formats[] lists the extensions, a media kind, and the service commands that produce the preview and the details. It needs format.register, and each command must be one your service block declares.
"formats": [{
"id": "myfmt", "extensions": [".myext"], "mediaKind": "text",
"previewCommand": "render-preview", "metadataCommand": "read-meta"
}]Extensions are normalised to lowercase with a leading dot, so MYEXT and .myext are the same entry. mediaKind is required.
Media kinds
mediaKind must be one of these 11. It decides which viewer your files open in and which media-kind filters they take part in, including the mediaKinds filters on context menus, inspectors, viewers, and item actions.
imageRaster images. Atlas indexes these with its built-in provider. Built-in extensions: .png, .jpg, .jpeg, .webp, .bmp, .tiff, .tif, .gif.videoVideo files, shown with a poster frame and a hover scrubber. Built-in extensions: .mp4, .webm, .mov, .m4v.audioAudio files, shown with a generated waveform. Built-in extensions: .mp3, .wav, .ogg, .oga, .flac, .m4a, .aac, .opus.textPlain-text and markdown documents, rendered as their own first page. Built-in extensions: .txt, .md, .markdown.htmlHTML documents, whose tile is a real render of the page. Built-in extensions: .html, .htm.fontFont files, shown as a glyph specimen. Built-in extensions: .ttf, .otf, .ttc, .otc, .woff, .woff2.model3D models, shown in an orbit viewer with geometry stats. Built-in extensions: .glb, .gltf, .fbx, .obj, .stl, .ply, .3mf, .dae, .pmx, .pmd.lottiedotLottie animations, shown as a poster frame with a looping player. Built-in extensions: .lottie.documentPaged documents. Atlas covers PDF with its built-in provider; supply a plugin for any other paged format. Built-in extensions: .pdf.archiveArchive files. Atlas has no built-in provider — supply one from a plugin.otherAnything that fits none of the above. Use it when no other kind describes the format.How a job runs
- 1The scanner finds a file whose extension your provider claims and writes a pending row for it.
- 2Atlas calls your
previewCommand, then yourmetadataCommand, and writes each result to a path it supplies. - 3The preview is packed into the folder atlas, so your file draws in the grid at the same speed as an image.
- 4If a command throws or times out, the row is marked failed and the error appears in your plugin's log.
What your preview command returns
Return an object carrying the image in one of three shapes. Atlas writes it to destPath for you — do not write the file yourself.
previewDataUrlA base64 image data URL. Must match data:image/<type>;base64,… or the job fails.previewBase64Bare base64 image bytes, no data-URL prefix.previewBytesAn array of integers from 0 to 255. Any value outside that range fails the job.metadataOptional. Any JSON-serialisable value, written to the metadata file. Lets one command return both.return {
previewDataUrl: canvas.toDataURL("image/webp", 0.92),
metadata: { title, author, tags }
};