Media

How images, audio, video and narration enter a course, the canonical formats and quality presets, the encoder, and how media reach packages and previews. Part of the architecture, the contract every change follows.

Media is part of the package. The project keeps one master per media file, already in a web format at the high preset. The original that the user imported is never copied into the project. The pure part (canonical formats, presets, conformance(info), the plans that turn an input into a master or a master into a rendition, size estimates) is @elabora/core media/; probing, encoding and jobs are @elabora/node media/.

Import and optimisation

• elabora media import [dir] <file…> [--to assets/video] [--name intro] [--no-wait] (MCP elabora_media_import, and the app’s import) probes each file at once (a file that is not media fails then), reserves assets/<video|audio|images>/<slug>.<ext> under the project lock (a name never taken twice, even by a job still running) and queues a job; it prints the paths, then waits, showing progress on stderr. --no-wait leaves the jobs to a detached elabora media worker.
• What a job does with a file:
  • copy: SVG, and a conformant MP3, byte for byte.
  • remux (no quality loss): a conformant MP4 or M4A, or a file whose streams are already right (H.264 and AAC in a .mov), is rewritten with +faststart and without metadata; a conformant JPEG, PNG or WebP loses its metadata without re-encoding (EXIF, XMP, IPTC, comments, JPEG multi-picture previews and motion-photo videos after the image), keeping its orientation (as a minimal EXIF block) and its colour profile.
  • encode: only the streams that need it (a .mov with PCM audio keeps its H.264 video). Video: H.264 High yuv420p, AAC, downscale only (aspect kept, even sides, square pixels), rotation applied; HDR (PQ, HLG) is tone-mapped to SDR when ffmpeg has zscale or libplacebo, else converted and labelled BT.709 with a warning. Audio: AAC in M4A, stereo at most (mono at half the bitrate), no cover art. Images: WebP (transparency and animation kept); HEIF and AVIF photos (tile grids) included. Outputs never carry metadata (-map_metadata -1, +bitexact): phone videos and photos hold GPS positions.
• elabora media captions [dir] <block> <file.vtt|.srt> [--name <name>] (MCP elabora_set_captions, engine command set_captions: the app’s « Sous-titres » field and a file dropped on the video) gives a video block its captions: the text written under assets/captions/<block>.vtt (a SubRip file converted to WebVTT, the same text already there reused, another one numbered), the block’s captions naming it, in one journaled change (set_captions, undoable). It answers E_VIDEO_CAPTIONS_MISSING.
• A media file of assets/ that is not conformant gets W_MEDIA_NOT_OPTIMIZED (a GPS position is reported as a privacy matter). elabora media optimize [dir] [<path>…|--all] converts it next to itself and, when the extension changes, rewrites the references and removes the old file in one journaled change (optimize_media, undoable).
• Jobs are files in <data>/media/jobs/<id>.json (queued, running, done, failed, cancelled, with progress, error, warnings and the input and output hashes), claimed by a process with an exclusive lock file, one at a time by default; a job left running by a process that is gone goes back to the queue, cancel reaches a job run by another process. Outputs are written in <data>/media/tmp/ and moved into place when complete. elabora media status|cancel|worker, MCP elabora_media_status.
• While a job runs, references to its output get I_MEDIA_PROCESSING instead of E_ASSET_MISSING; the preview shows a placeholder; elabora build (and elabora_build) waits for the jobs, and --no-wait refuses to build.
• Backups skip non-conformant media: they are inputs waiting for conversion, not sources.

Narration (D24)

The voice of a narrated screen is one file per line and language, found by convention next to the script (screen.narration.lines): assets/narration/<language>/<screen>/<line>.m4a and its sidecar <line>.json (SPEC §4.7). They are media masters of assets/ (probed, hashed, backed up) that no asset prop names, so packages never ship them. A layer’s lines (layers[].narration.lines, D62), and a dialogue’s (D61: its lines with a speaker, and with learnerVoice the learner’s answers as <node>.<option>), are voice lines too: ids unique in the screen, every track counted, their audio at the same path.

• Every voice line of a screen (D62): @elabora/core narration/voice-lines.ts screenVoiceLines(project, screen) gives each line with its track (screen, layer, dialogue: dialogueLineSource), its translation unit and its JSON pointer; VOICE_LINE_SOURCES is the one place a new holder of lines is added. narrationLines, the voice tools, alignment, recordings and transcription, translation units and anchors, the report and the engine read lines through it.
• @elabora/core narration/: paths, narrationTextHash, narrationLines(project, screen, language) (each line’s text in that language, from the screen or its translation, its files and whether they are ok, missing, stale or untranslated, with why), screenTiming (the timeline from the lines’ durations: the file’s probe, else its sidecar, else an estimate from the text), narrationTiming, captionCues, narrationVtt, and report.ts for elabora timeline. Its check is a project check (narration-audio): the files are not named in the screen, and the engine runs project checks again when a file of assets/ changes.
• Writing a line’s audio is one journaled change (set_narration_audio): @elabora/node narration/audio.ts setNarrationAudio keeps an M4A in AAC mono with its index first as it is, converts anything else (AAC mono 96 kb/s, +faststart, no metadata), measures it, and the core command writes the file and its sidecar (the text hash in that language, the duration, the audio hash, the voice); importNarration is a recording (provider: "recording", not generated, silence at both ends trimmed to 0.1 s). CLI elabora narration import, MCP elabora_import_narration; the voice tools call the same.
• The mouth’s envelope (D61): @elabora/core narration/mouth.ts mouthEnvelope(samples, rate, words), pure and deterministic, gives one letter per 1/30 s (c, s, o, w) from the line’s samples and words; @elabora/node narration/mouth.ts decodes the audio with ffmpeg (mono, 16 kHz, decodeSamples of narration/tracks.ts, which peaks.ts uses too) and passes it the words (aligned, else placed along the text). setNarrationAudio writes it into the sidecar (mouth) with the audio, alignNarration again with the words it timed (set_narration_words takes mouth).
• A dialogue’s lines in a package (D61): build asks narration/dialogue-audio.ts for each line of a dialogue whose audio is there: the master at high, else its rendition at the package’s preset (ensureRendition, as any media), shipped as narration/<screen>.<block>/<line>.m4a (narration/<language>/… for another language); its envelope from the sidecar, else measured and cached in <data>/cache/narration/<hash>.mouth. compileCourseData takes them (dialogueAudio) and gives each line its voice (@elabora/core dialogue/voices.ts: the audio’s path, its duration, its words, its envelope; without audio, the estimate of @elabora/player character/ textVoice). The build id includes them, the report’s narration.lines lists them, and a generated voice in a dialogue is in generatedMedia.
• Tracks. build asks narration/tracks.ts for one track per narrated screen, and one per narrated layer (narration/<screen>.<layer>.m4a and .vtt, D62), whose lines all have their audio in the course’s language: each line decoded to PCM (mono, 48 kHz, 16 bits) by ffmpeg, the pauses written as silence, the whole encoded once (AAC-LC, 64 kb/s, +bitexact, +faststart) into <data>/cache/narration/<inputs hash>.m4a with the lines’ measured durations next to it (.json). The package ships it as narration/<screen>.m4a (from the cache, like a media master: streamed into the ZIP, served by the preview, cloned into folders) with narration/<screen>.vtt, and the course data gets the cue times from the decoded samples (compileCourseData option narration). The build id includes the tracks’ keys. Package limits count the tracks (their seconds in the heaviest files); the report’s narration gives bytes, seconds, tracks and silent screens. A track that cannot be made is E_NARRATION_TRACK.
• Optional model versions (D55). Desired releases and exact compatible descriptors live in each model manifest. models/versions.ts selects checked installations, stages upgrades beside active files, gives inference calls directory leases and removes old releases only after use. A family lease coordinates installation/removal across app, CLI and MCP; update-only intent cannot reinstall an absent element. Workers switch when their directory changes and provenance records the selected model. Automatic network-cost policy and the shared app/update/quota panel belong to the desktop app, not the core.
• Local AI platform policy (D54). Mac Intel keeps editing, existing audio and word timings, recordings, FFmpeg processing and online services. Local voice generation, forced word alignment and local transcription are unavailable on darwin/x64: downloaded models stay listed for removal, but installation and inference are refused by the core as well as the app. The release carries no Intel ONNX Runtime binding. The Intel prebuilt FFmpeg remains pinned independently.
• Generated voices (D25). @elabora/node voice/: a VoiceProvider lists its voices, says whether its model is on this computer (status), installs it and says a text (synthesize: mono PCM, the model, the credit, failed parts said again). The local one, voice/pocket/, runs Kyutai’s Pocket TTS with ONNX Runtime (onnxruntime-node, optional, required when a voice speaks), its model downloaded once per language into <local app data>/voices/pocket-tts/<bundle>/ (models.ts: pinned files, SHA-256, resumed, one download across processes; removed on request, never while a generation holds it, D37), its voices from packages/node/voices/pocket-tts/ (embeddings made once by scripts/pocket-voices.ts). voice/generate.ts generateNarration takes a screen’s lines (missing or out of date, all, or some), says each with its speaker’s voice (speakers[].voices[<language>]; the text after the pronunciations, the settings with the line’s delivery: spokenText), keeps the result as a take in <data>/voice-takes/<language>/<screen>/<line>/take-<n>.wav (and .json), and writes it through set_narration_audio with its take, credit and model; a writer (VoiceWriter) lets the engine send that through its session. The Pocket model speaks in a worker thread (voice/pocket/thread.ts, worker.ts): the process that asks (the engine, the MCP server) goes on answering while it speaks, and a signal stops it between two of its steps (a stopped generation keeps the lines said so far, cancelled). voiceSample says a few words with a voice, written nowhere. CLI elabora voice …, MCP elabora_voice_*, engine requests voices, installVoices, setSpeakerVoice, generateVoice, voiceTakes, cancelVoice, voiceSample. The sidecar keeps the text the audio says (text).
• Optional downloads (D38). @elabora/node downloads/: the registry of what Elabora downloads once per computer and keeps out of every course (the local voices’ models, the word aligners, the transcriber), by kind and language, with what each serves, what happens without it, its state (size on disk or to download, a download under way in any process, in use) and its install and removal. A kind registers there and uses models/download.ts for its files (pinned, checked, resumed; a lock beside the folder; holds while in use; removal refused while held). CLI elabora downloads, MCP elabora_downloads, elabora_download_install, elabora_download_uninstall; the app lists them in Elabora settings.
• ElevenLabs (D29). voice/elevenlabs/: a paid provider (VoiceProvider.paid, with search, lookup, account, estimate, synthesizeDialogue). key.ts finds the author’s key (the app’s when the author keeps it in the keychain, given in memory by setSessionKey or setVoiceKey once the author first calls the service, D40; ELEVENLABS_API_KEY; the 0600 file elabora voice key set writes in the local data, where the app keeps it when the author’s AI may use it) and masks it everywhere; api.ts calls the API (ELABORA_ELEVENLABS_URL elsewhere), maps its refusals to codes (E_VOICE_KEY_MISSING, _INVALID, _PERMISSION, E_VOICE_CREDITS, E_VOICE_BUSY…) and keeps every generation’s answer in <local data>/elevenlabs/cache/ keyed by the request, so the same request is never paid twice. generateNarration plans first (planNarration, estimateNarration): the lines, the takes given back free, the dialogue runs, the credits about and at most, and their share of the month’s quota (costs.ts: the share of its list price a model is charged on the author’s plan, from the cost ledger’s averages for the current price period (@elabora/core ai/costs.ts and ai/cost-ledger.generated.ts, generated from ai-costs/, D36) and the author’s own requests, whose character-cost header is kept in <cache>/charges.json, a library voice’s own rate in <cache>/voice-rates.json; the quota read from /v1/user (its subscription, in 0.25 s where /v1/user/subscription, which adds the invoices, takes 1.3 to 1.9 s) with what this process spent added until the account’s count catches up). Under 1 % of the quota it runs; from 1 % it needs approvedPercent (@elabora/core ai/quota.ts, D30), and it stops (overBudget) once the service charged half as much again as it was allowed. A dialogue is one text-to-dialogue request cut into lines at its turns, the silences before each written as the lines’ pauseBefore (VoiceWriter.updateLinePause). Stage directions (@elabora/core narration/directions.ts) stay in the line’s text; words, captions, the player’s text, durations and pronunciations skip them; XLIFF wraps them in <mrk type="elabora:direction">; a voice that cannot play them gets the text without them. CLI elabora voice search|estimate|account|key, MCP elabora_voice_search, elabora_voice_estimate, elabora_voice_account, engine requests setVoiceKey, voiceAccount, voiceSearch, voiceEstimate.
• Word times (D27). @elabora/node align/: forced alignment of a line’s text with its audio. spoken.ts turns the words of narrationWords into what a voice says (numbers, times and symbols spelt out in French and English, elisions run on) and the model’s characters; wav2vec2.ts runs a wav2vec2 CTC character model (ONNX Runtime, 16 kHz mono from ffmpeg) for the probabilities of each character every 20 ms; ctc.ts finds the text in them (Viterbi, forcedAlign); align.ts gives each word its start, end and score (the model’s measured lateness of starts and earliness of ends corrected). The model runs in a process of its own (process.ts, on models/process.ts, starts it with the program that runs the engine, ELECTRON_RUN_AS_NODE; worker.ts is what it serves) that keeps it and ends after two idle minutes: an allocation ONNX Runtime cannot make aborts that process and fails the line (E_ALIGN_CRASHED), not the engine; wav2vec2.ts reads audio in windows of 10 s (the outer 2 s of each overlap given up) with ONNX Runtime’s memory arena off, a recording of 90 s peaking at 1.1 GB instead of 2.4; models.ts pins one model per language, downloaded once into <local app data>/aligners/<model>/ by models/download.ts (shared with the voices), held while it aligns and removable like every optional download (downloads/, D38). setNarrationAudio times a new line’s audio in the same change when its language’s aligner is installed (ELABORA_ALIGN=0 turns it off); alignNarration times the others through the command set_narration_words (words, aligner, text into the sidecar), downloading the aligner first, with an AlignWriter for the engine’s session. CLI elabora narration align, MCP elabora_align_narration, engine requests aligners, alignNarration (alignProgress events). A word scored under 0.25 is one the voice may have swallowed (W_NARRATION_WORD_SWALLOWED).
• What a recording says (D46). @elabora/node transcribe/: parakeet.ts runs NVIDIA’s Parakeet TDT 0.6B v3 (ONNX Runtime: NeMo’s mel features, the encoder, the decoder and joint network decoded greedily, a token and how many 80 ms frames to move on), in windows of 30 s at most cut in the quietest moment; text.ts makes its pieces a text (punctuation, capitals, French spaces) and words; worker.ts and process.ts run it in a process of its own on models/process.ts (E_TRANSCRIBE_CRASHED); models.ts pins the model, one download for 25 languages (transcriber, D38); elevenlabs.ts asks ElevenLabs’ Scribe v2 when the author chooses it, its share of the quota told first and its transcript deleted after; index.ts gives transcribeAudio, transcribers and estimateTranscription. narration/from-audio.ts makes a line from a recording (add_narration_line_with_audio: the line and its audio in one change, @elabora/core addNarrationLineWithAudio) and gives a recorded line the text its recording says (set_narration_text_from_audio: the text through update_narration_line, the sidecar through keep_narration_audio, the words through set_narration_words, in one change), each timed by the aligner when it is here. CLI elabora narration transcribe | add-from-audio | retranscribe, MCP elabora_transcribe, elabora_narration_line_from_audio, elabora_narration_text_from_audio, engine requests transcribers, transcribeRecording, transcriptionEstimate, transcribeLine (transcribeProgress events).
• The timeline of a timed screen (D28): @elabora/core narration/timeline.ts lays out a screen’s steps, its lines and their words (narration/words.ts: one tokenizer for anchors, the aligner and the editor; a line’s word times from its sidecar’s words, followed through a changed text by a word diff, placed in proportion to the text without them) and resolves every anchor (timing.in/out of blocks, event cues, seek-timeline) to seconds: screenTimeline, blockTimings, anchorTime. A step’s stretch ends when its last line or its last effect anchored there ends, so the stop at its end never cuts an effect; the build lays the track’s silences from it (TimelineLayout.gaps) and the course data’s times follow those silences. Screens without narration but with blocks or cues in seconds have a timeline too (no track). A layer has a timeline of its own (D62: screenTimeline(…, { layer }), timedLayers): its lines from its opening in one stretch, its blocks and the cues on its lines (or with the trigger’s layer); an anchor on a line of another timeline falls back with a problem of kind track (E_TIMELINE_ANCHOR_TRACK). timelineView, screenAt, timelineMarks, narrationView, resolveAt and timelineReport take layer. narration/view.ts gives editors timelineView (lines, words and their offsets in the text, timed blocks, cues) and screenAt (what is seen at a time); narration/anchor-text.ts reads and writes anchors as tools type them (l2:imprimante+0.3s). Commands: set_block_timing; update_narration_line takes word anchors along (reanchorLine); split_step cuts a step at a line (later steps, their blocks, settings, anchors and reveal-step actions move one on); narration_from_plan writes the script from the plan items’ voiceover; duplicate_screen copies the lines’ audio; keep_narration_audio keeps the audio of a line whose text was only corrected; set_plan_voiceover writes a plan item’s voice-over; write_plan writes the plan (D52), and takes the screens of the items it moves along (project/plan-order.ts, D50), as revert_plan_change does. The canvas takes at and ghost from the app’s own elabora/view messages and reports BlockLayout.timed (state and progress of each timed block); the timeline’s findings carry details. timelineMarks lists a timed screen’s marks (its start, each block that comes or goes, each cue, each step’s end) with the time to show each: elabora look --sheet captures one per mark on a contact sheet (look.ts). Checks: validate/timeline.ts (a screen check on what is written, a project check on the times).
• The player’s timeline.ts reads the narration’s <audio> as its clock (docs/decisions.md D24); timed-blocks.ts sets the timed blocks of the screen shown to its time at every move (Web Animations created paused, currentTime from the playhead; data-t-timed and inert before and after), and the cues the compiler resolved fire when playback crosses them (a seek-timeline jump crosses nothing). Previews and captures (elabora screenshot, elabora fit) and the LMS emulator set window.ELABORA_TEST = { virtualTime: true } before the player starts: nothing plays by itself, captures show a time (__elabora.timeline.at(line)), the emulator plays a screen to its end (__elabora.timeline.toEnd(), closing the dialogs its cues open; a dialog’s close event comes with the next frame). The editor canvas shows a line’s moment (RenderView.at, on the timeline of the layer shown when it has one) and never plays. A layer’s timeline is another createTimeline with a compact bar in the layer (.t-layer-timeline), started at 0 when it opens and disposed when it closes; while it speaks the screen’s timeline is held (hold('layer:<id>') for a dialog, hold('voice:<id>') for a panel until its narration ends); tests drive it with __elabora.timeline.layer(id).

Automatic word alignment announces its work through NarrationAudioArgs.onAlign; voice generation forwards it as voiceProgress phase align, including when selecting an earlier take. If alignment fails, the audio is still written and alignmentError is returned with the line’s generation result. Editors must tell the author that the words remain estimated and offer another alignment attempt.

Sounds (D67)

• The engine. @elabora/player sounds.ts: one AudioContext for the page, made at the learner’s first pointer or key press (never at load, so that no browser keeps it suspended), its master gain the player’s volume and mute (the narration’s controls: TimelineOptions.onVolume says when they change). Interface sounds are decoded once and played at once or not at all. __elabora.sounds.state() gives the context’s state and what was played, for tests.
• Interface sounds. @elabora/core sounds/sounds.ts: interfaceSounds(project) (when, whether they sound, the volume, each role’s source: the player’s file, a sound of the course, or none), courseHasSound, compileSounds (the course data’s sounds.interface: the volume and each role’s file; nothing when they do not sound). The player’s own files are packages/player/src/interface-sounds/<role>.m4a, made by pnpm run sounds from the originals sources.json names (pinned by SHA-256); build ships those the course data names as elabora/sounds/<role>.m4a (playerSoundFile), and the sound of the course a role plays instead as any asset.
• Sounds of the course. @elabora/core sounds/sounds.ts: soundAssets (the files of assets/sounds/ by id), soundSidecar, soundUses (every place the course names a sound: an interface role, an action, a sound line, a background track; a narration’s sound line is inTrack), compileSounds (the course data’s sounds: files by id, background with their screens, music), backgroundTracks, soundCreditsText (the package’s CREDITS.txt); sounds/licences.ts: classifyLicence, soundCredit. fileMedia(info, path) takes a sound of assets/sounds/ kept as FLAC or as its lossy original as a master; renditionPath and packageMedia give audio that is neither AAC nor MP3 an M4A rendition at high too. A narration’s sound lines are laid among its voice lines by @elabora/core narration/narration.ts timelineLines (the timeline and the track read them through it; screenVoiceLines never gives them: no voice says them), decoded into the track at their volume.
• The engine’s other layers. sounds.ts plays sounds of the story once (play, stop; a request before the first gesture is dropped after 1.5 s), loops ambiences and background tracks with a crossfade on the context’s clock (enterScreen stops the screen’s sounds and starts or keeps the tracks of the screen’s range), and lowers music and ambiences by 20 dB while a voice speaks (voice: player.ts reports every media element of the page that plays).
• Adding sounds. @elabora/node sounds/: library.ts (« Sons courants »: the core’s packages/node/sounds/, then each folder ELABORA_SOUND_LIBRARIES names, as PATH does, with its own catalogue.json and files/: the desktop app’s, whose CC BY sounds carry their credit), openverse.ts, search.ts (searchSounds: the library or Openverse in one shape, SoundFound, with what add_sound takes; soundPreview: a sound’s bytes to hear it before adding it), add.ts (addSound, the change add_sound), generate.ts (generateSound, or generateSoundWith and a writer of its own), types.ts (the types that leave the process, without Node). The narration’s commands take sound lines: add_narration_line with { sound, caption?, volume? }, update_narration_line with sound, caption (empty: none), volume, step and pauseBefore, and move_narration_line and remove_narration_line as for a voice’s; update_course writes sounds whole. Engine requests soundSearch, soundPreview (soundProgress events while an Openverse sound downloads), courseSounds (the module’s sounds with their sidecars: licence, credit, source, author, suggested caption, uses), soundEstimate, generateSound (session-sounds.ts: its add_sound goes through the session’s queue); Openverse’s refusals are E_SOUND_OPENVERSE and E_SOUND_OPENVERSE_LIMIT.

In the snapshot

readProjectFiles gives every media file of assets/ its probe and verdict (BinaryFile.media: MediaInfo with conformant and reasons), from <data>/media/probe-cache.json keyed by path, size and modification time: only new or changed files go through ffprobe, synchronously (unreadable files are cached with their error, E_MEDIA_UNREADABLE). Without ffprobe cached verdicts stay, new files have none, and the validator says I_MEDIA_TOOLS_MISSING. The snapshot also gives MediaStatus (Project.media): the outputs of unfinished jobs (read only when an asset is missing), unreadable files, tools missing. Hashes of binary files come from the snapshot’s hash cache (<data>/cache/hashes.json), shared with the jobs and the renditions.

Canonical formats

Kind	Master format	Conformant when
Video	MP4 (+faststart), H.264, yuv420p, AAC	MP4 container with the index first, H.264 Constrained Baseline, Main or High (8-bit 4:2:0: what browsers play; the encoder writes High), yuv420p, no HDR, long side ≤ 1920, bitrate ≤ 10 Mb/s, AAC audio, no GPS position
Audio	M4A, AAC	AAC (or MP3) ≤ 192 kb/s, no cover art, no GPS position
Raster image	WebP (JPEG and PNG also accepted)	WebP, JPEG or PNG, long side ≤ 3840, ≤ 8 MB, no GPS position
Vector image	SVG, unchanged	always

The limits are looser than the high preset on purpose: a file a little above it is kept rather than re-encoded with generation loss.

Quality presets

course.json delivery.mediaQuality (high by default), elabora build --media-quality and elabora_build mediaQuality choose the preset of the package. high ships the masters. medium and low ship renditions encoded from the masters and cached in <data>/cache/media/<master hash>-<preset>-<parameters hash>.<ext> (the parameters of the preset for that kind of media, and a pipeline version). Streams already within the preset are copied (a 720p master at medium only gets its audio re-encoded), a master entirely within it ships as is, and a rendition that would be larger than its master is the master. A rendition under another extension (an MP3 shipped as M4A, a PNG as WebP) takes that name in the package (assets/audio/voice.m4a) and the compiled course data points at it. pruneProjectData removes renditions no package can use (their master was replaced or deleted, or the preset’s parameters changed) once they are a week old: a deletion undone meanwhile finds its rendition again.

Preset	Video	Audio	Raster images
high	long side ≤ 1920, CRF 21, ≤ 8 Mb/s, AAC 160 kb/s	AAC 160 kb/s	long side ≤ 3200, WebP q 88
medium	≤ 1280, CRF 24, ≤ 4 Mb/s, AAC 128 kb/s	AAC 128 kb/s	≤ 2400, q 80
low	≤ 854, CRF 27, ≤ 1.5 Mb/s, ≤ 30 fps, AAC 96 kb/s	AAC 96 kb/s	≤ 1600, q 72

A package’s weight before it is built (@elabora/node packaging/weights.ts, the engine’s packageWeights, the app’s « Publier »): what one learner loads to go through the module in its own language, at each preset, with nothing encoded, compiled or written. The assets it ships (packaging/assets.ts, the list the build ships), each media at the preset as a cached rendition, else estimated from its bitrates (estimateBytes); the narration tracks as cached, else their duration at 64 kb/s; the dialogue lines as media; the player’s runtime deflated, the interface sounds it plays, three.js for 3D objects, the fonts of theme/, the free objects’ files and the course’s texts deflated. It stays within about 2 % of the ZIP the build writes (its headers and the compiled course data); estimated says some part comes from bitrates.

Package limits (checklist item 8, @elabora/core lms/package-limits.ts): the size of the ZIP, its size once extracted, its number of files and its compression ratio, against the LMSs the course targets (--profile, else course.json delivery.lms, else the unknown LMS). The limit of a chosen LMS stops the build (E_PACKAGE_TOO_LARGE, E_PACKAGE_TOO_MANY_FILES, E_COMPRESSION_RATIO). The unknown LMS assumes no package limit: they range from 100 MB (Teach Up) to 4 GB extracted (360Learning), too far apart to stop a course on a guess. The build warns instead with the documented LMSs that would refuse the package (W_PACKAGE_TOO_LARGE_FOR_SOME_LMS, W_PACKAGE_TOO_MANY_FILES_FOR_SOME_LMS, W_COMPRESSION_RATIO_FOR_SOME_LMS) until the course names its LMS. A finding’s details (PackageLimitDetails) give the measure, its value, the lowest limit passed, the LMSs that set it (id, name, limit) and whether they were chosen, the media quality, the package’s size at each preset (measured when renditions exist, estimated from bitrates otherwise, never above the masters), the best other preset under the limit (fits; null: none) and the heaviest files (path, asset, size, kind, duration). The message says the same in English, and what to do when no preset is enough: shorten the video, host it on a video platform and link to it, or split the course. A rendition that cannot be made (no ffmpeg) is E_MEDIA_RENDITION.

Encoder

The node package finds ffmpeg and ffprobe through ELABORA_FFMPEG / ELABORA_FFPROBE, then PATH, and reads their encoders and filters once. It prefers libx264 (CRF), then the hardware encoders (h264_videotoolbox on macOS, h264_mf on Windows; an average bitrate under the preset’s cap), then libopenh264; an encoder that fails on the machine passes to the next. WebP needs ffmpeg’s libwebp: without it, images become JPEG, or PNG (APNG) when they have transparency or animation, both accepted masters. The desktop app bundles a GPL build with libx264, libwebp and zimg, run as a separate program (D21); CI uses the same builds (BtbN/FFmpeg-Builds) on Linux and Windows.

Packaging and preview

• Packages are written as streams (packaging/zip-writer.ts): media read from disk are stored without compression, entries in memory (generated files, text, fonts read by the design layer and the licence files found next to them, which every packaged font carries) are deflated at level 9 unless that does not help, entries keep sorted names and fixed timestamps, so builds stay byte-identical (D8), and a package without media keeps the bytes of the in-memory writer. The ZIP is planned first, so its exact size is known before anything is written; each file is read twice (sizes and CRC, then the data, checked against the first pass). No ZIP64: archives of 4 GB or more are refused. Nothing loads a whole media file into memory; folder builds clone media (copy-on-write where the file system can).
• The preview never zips and never copies media: it serves the generated files from its folder and the media from the project folder, through http/files.ts (streams, single range requests, content types), with a placeholder for media a job is still writing; its pages reload after each rebuild. The emulator serves packages the same way.