Olenji handbook

Recordings, live speech, translations, and your AI agent · 29 October 2026 · Speaker integrity and translation memory review

Start with the task you need. This guide explains the choices, steps, saved files, and recovery actions. Exact commands, model IDs, and agent requests are collected in the command and model reference.

About this edition: Local follow-up to the recovered olenji-bugfix-update.zip and preceding Linux review. Includes verification of speaker-model files before native startup, explicit corruption recovery, and reduced retention of saved provider output. Earlier privacy, live model ownership and browser language fixes remain included. Source, installed-artifact and native-host results retain their separate recorded scopes.

Start hereContents

Olenji turns recordings and live speech into saved text. Use terminal commands or your existing AI agent to start the work. Open a local browser tab to read, translate, and review it.

The usual path: install Olenji, prepare a speech model, transcribe a recording, review the result, and export a copy. Translation and speaker grouping are optional, separate steps. Complete a workflow connects the features for files, batches, live captions, later corrections, and supplied text.

The computer doing the work: models, the service, and saved sessions belong to the computer running Olenji. A browser or agent is another way to control and view that work. For a local-path request, the service must be able to read that path. For a browser upload, the browser sends the file to the paired service.

Choose what to do

Read help without starting the app

The handbook ships with Olenji. You do not need a downloaded model, an internet connection, or a running service to read it.

1. In your terminal, open the installed guide:

   olenji docs --open
   

2. To find a particular topic, list the available section IDs:

   olenji docs --list
   

3. Open a section directly. For example, read about saved files:

   olenji docs --section understand-your-files-and-privacy --open
   

Without --open, the command prints a local file link and does not launch a browser. Add --json for an agent-readable result. It never creates a workspace or starts recording. A browser launch request does not prove that the browser is visible; use the printed link if no page appears.

In an already open Olenji browser view, select Help and handbook. This opens the same guide in a separate tab without closing the capture view. Browser behavior can vary. Help contains no session data and does not start transcription.

Five terms you will see

Model: downloaded files that help a speech engine recognize words. Language and computer requirements vary.

Session: one saved transcript with its speakers, translations, notes, and optional recording. Each input file creates a separate session.

Turn: a timed piece of transcript text, called a segment in commands. It is not necessarily one sentence.

Job: a piece of work, such as a download or transcription. A job ID means accepted, not necessarily finished.

Service: Olenji's background process. It can keep working after a command or viewer closes.

Read command examples

Run commands in a terminal on the computer running Olenji. Replace SESSION_ID, MODEL_ID, JOB_ID, and similar uppercase names with real values returned by the app. Keep the model IDs written in lowercase exactly as shown.

Quote file paths that contain spaces. Copy commands without their Markdown backticks. The JSON example files avoid shell-quoting differences between operating systems.

Add --json when an agent needs a machine-readable response. Omit it for normal terminal output. Use olenji COMMAND --help to see options in your installed build; for example, replace COMMAND with transcribe.

@automatic.json means read automatic.json from your current folder. Create the file from the example, or copy it from the editable bundle's examples/ folder. Replace its placeholders before use.

Build scope: these instructions describe the inspected 1.0.0 development archive. Later changes are not automatically covered. The technical reference records the exact archive and verification limits.

Install or update OlenjiContents

Choose the route that matches your download: a source update, a built Python package, or a built npm package. They use the same application engine. The handbook alone is not an installer. Installing the app does not install every speech model.

Before you start

Prepare the tools for the route you choose:

A Python virtual environment is a separate folder for an application's Python packages. Use one for the pip route rather than installing into your system Python. Your AI agent can help install these prerequisites; the commands below assume they are already available.

The commands here use files from the extracted Olenji release. Public PyPI and npm publication was not established for this build. Do not assume a package with the same name on a public registry is this project.

Run from a source update

A download labeled source update contains application code, but may not contain new wheel or npm installers. The dist commands in the next sections apply only when those built files are supplied. Do not substitute an older installer and expect it to include newer source changes.

From the extracted application folder, prepare and run the source version:

uv sync --frozen --python 3.12
uv run --frozen python -m olenji doctor --json

This step can download the reviewed application dependencies. It does not download speech models or upgrade another separately installed Olenji command. Use uv run --frozen before subsequent commands to keep using this source environment.

To read the included guide before installing dependencies, run python -m olenji docs --open from the same folder. Preparing new wheel and npm installers is a maintainer task described in docs/RELEASING.md in the source archive.

Install through Python

From the extracted application folder:

uv tool install ./dist/olenji-1.0.0-py3-none-any.whl
olenji --version
olenji doctor --json

If you do not use uv, activate a Python virtual environment, then run:

python -m pip install ./dist/olenji-1.0.0-py3-none-any.whl

doctor lists what is ready and what needs attention. A missing model is normal before you download one. It is not a reason to delete your workspace.

Install through npm

Use Node.js 22.14 or later and uv for the explicit setup step. From the extracted application folder:

1. Install the supplied npm package:

   npm install --global ./dist/olenji-1.0.0.tgz --ignore-scripts
   

2. Prepare its separate Python environment:

   olenji-bootstrap setup --python 3.12 --json
   

3. Check the result:

   olenji-bootstrap status --json
   olenji doctor --json
   

Setup can download Python and application dependencies. It does not download speech models. Keep the prepared interpreter available. Bun is optional; it is not required by these instructions.

Update without losing transcripts

1. Stop any recording normally. Wait for important jobs to finish, or cancel them deliberately.

2. Stop the old service:

   olenji service stop
   

3. Back up the workspace before an important upgrade. Then replace the application. For uv:

   uv tool install --force ./dist/olenji-1.0.0-py3-none-any.whl
   

4. Run olenji doctor --json again. For npm, reinstall the local package and rerun olenji-bootstrap setup.

Keep the same workspace location to retain your transcripts and models. Stop the service first even when both development builds say 1.0.0. That version string does not identify every unpublished archive. See Back up or move your workspace.

Choose, download, and remove modelsContents

Where the choices come from

Olenji searches a reviewed catalog included in the application. It does not search every model on the internet or accept any arbitrary model repository.

The inspected catalog has 29 speech-recognition entries and one speaker-recognition entry. It includes the 17 selectable FluidVoice speech entries in the pinned 25 October 2026 comparison. This is a dated comparison, not a promise that future FluidVoice updates are already included.

A different size or conversion can be a separate entry in the same family. The count does not mean 29 unrelated recognition methods.

olenji models list
olenji models search whisper
olenji models list --installed
olenji models inspect MODEL_ID --json

Use inspect to check supported languages, computer requirements, download information, model terms, and readiness. Choose by these requirements rather than the model's name alone:

1. Check the spoken language. A Turkish recording needs Turkish recognition; English speech translated into Turkish does not.
2. Check the computer and engine requirements. An Apple-only entry cannot run locally on Windows or Linux.
3. Check the planned download and available storage. Model weights and the software that runs them are separate parts of installation.
4. Try a short representative recording before processing a large batch or relying on a live session. Compare important words and the delay you observe.

A profile is a convenience list, not an accuracy ranking. No model is guaranteed to be best for every recording.

What gets downloaded

Downloaded speech models stay in models/MODEL_ID/ inside the local workspace on the computer running Olenji. They are not stored only in a browser tab. Supporting engines are stored separately under runtimes/. The storage section gives each operating system's default workspace.

Olenji reuses installed files for later recordings. Installation needs a network connection unless the required files are already available locally. Installing a local speech model does not install a text model for translation; that is a separate service choice.

Model licenses are separate from Olenji's application license. The inspected catalog leaves Pico's weight-license metadata unresolved. Check the actual model terms before sharing or redistributing its files.

Install one model or a preset group

Inspect the plan before starting a large download:

olenji models plan-install MODEL_ID --json
olenji models install MODEL_ID
olenji models verify MODEL_ID --json

A profile is a preset list of model IDs. It does not choose the best model automatically while someone speaks. The recommended profile includes Faster Whisper Tiny and the speaker model. The full profile list is in the reference.

To inspect the FluidVoice comparison set for this computer:

olenji models plan-install --profile fluidvoice-parity --compatible-only --json

Review skipped entries. --compatible-only does not make Apple-only models work on Windows or Linux. An installation that completes with skipped entries is not complete FluidVoice coverage on that computer.

Understand readiness and remove a model

Listed means the catalog knows the model. Installed means its local files are present. Runtime-ready means the engine is prepared. Successful recognition on your actual computer is a further check. These are not interchangeable promises.

Remove an unused model with:

olenji models remove MODEL_ID --json

Removal is refused while a worker is using the model or a live session still owns it, including silence, pause, and final recognition after stop. Finish the recording and wait for its finalization job before retrying removal. It removes managed weights, not your transcripts. Supporting runtimes can remain. Apple controls the lifecycle of its own speech assets. See Where files are stored before removing any folders yourself.

Transcribe files in different waysContents

All five routes create saved sessions, but they differ in how the file reaches Olenji.

Submit several files

olenji transcribe interview.mp4 lecture.wav call.m4a --model faster-whisper.tiny

The usual waiting mode processes submissions in order. Add --no-wait --json to return job IDs while the service works through them. This is not unlimited parallel processing.

Keep the session and job ID for each file. Review each result separately: one successful transcript does not establish that the whole batch finished. Check any existing job before retrying a submission. Export the sessions you need individually; batch input is not a single merged transcript.

Upload in the browser

1. Run olenji ui open, then choose Transcribe a file.
2. Choose a recording and review Recognition model and Input language.
3. Set Source recording to Keep for playback and refinement or Temporary processing only.
4. Optional: select Identify speaker turns.
5. Click Transcribe recording and check the processing state.

The browser can install the selected speech model and speaker model first if needed. This can contact the model and package hosts. The file upload itself goes to the paired local service.

Audio preference: the file-upload form starts with your saved retain_audio choice. Select a different Source recording value to override it for this upload. The file is still sent to Olenji for processing; choosing temporary processing means the recording is not kept for later playback or refinement.

Choose options deliberately

Omitted CLI model, language, and audio-retention choices use the saved preferences. Explicit choices win. Advanced processor and precision settings are in the reference.

Treat video transcription as a transcript of its audio, not a description of what appears on screen. FFmpeg determines which media formats can be decoded. Olenji does not provide a general website-video or URL downloader in this build. Recognition can return word, segment, or whole-clip timings depending on the model; exact word alignment is not universal.

Transcribe live audioContents

Before you start: prepare a speech model that runs on this computer. Prepare the speaker model as well if you need separate voice labels. Test the input and permissions before an important conversation.

Discover the available inputs:

olenji live sources --json

System audio is audio played by your computer. It is not the same as your microphone. The reviewed start command selects one source; it does not promise simultaneous microphone-and-system tracks, per-app capture, or arbitrary browser-tab audio capture.

Start and monitor a recording

For your computer microphone:

olenji live start --source microphone --retain-audio --open

For a microphone supplied by the browser:

olenji live start --source browser --retain-audio --open

Use the tab's microphone control and approve the browser's permission request. Starting a session does not itself grant permission or send audio. Check the input meter and the arrival of transcript text before relying on the recording.

The saved model preference is used unless you specify --model. Add --diarize after preparing the speaker model. Keep the returned session ID.

Pause, resume, and stop

olenji live pause SESSION_ID
olenji live resume SESSION_ID
olenji live stop SESSION_ID
olenji live status SESSION_ID --json

Pause stops new capture temporarily. Stop finishes the session and flushes accepted audio. If stop returns a finalization job, wait for that job before exporting the final transcript.

Closing a viewer or detaching the terminal does not stop service-owned recording. Closing the tab supplying browser-microphone audio removes that audio source. Use live stop to end work deliberately rather than killing the service.

What to expect from live text

Draft words can change. Completed turns are saved, but later corrections can still revise them. Text appears after buffered speech is processed; this build does not promise instantaneous captions or the same delay on every model.

A reported audio gap means some audio was missing. Olenji records the gap; it cannot recreate words it never received. A model with “streaming” in its name does not by itself establish a continuous decoder inside this app.

Linux system capture requires a supported PulseAudio/PipeWire setup and tools. Windows uses its WASAPI loopback route. macOS uses a ScreenCaptureKit helper and recording permission. See Check platform support for the remaining hardware checks.

olenji models install diarization.wespeaker.en
olenji transcribe interview.wav --diarize --retain-audio

olenji models verify diarization.wespeaker.en --json

olenji models install diarization.wespeaker.en

olenji speakers list SESSION_ID --json
olenji speakers rename SESSION_ID SPEAKER_ID "Ada"
olenji speakers color SESSION_ID SPEAKER_ID "#1565C0"

olenji speakers merge SESSION_ID SOURCE_SPEAKER_ID TARGET_SPEAKER_ID

Review, correct, and organize transcriptsContents

Find the session and the words

olenji sessions list
olenji sessions search "planning"
olenji ui open SESSION_ID

Session search checks titles and source text. Within a session, the browser can also search translated text. It shows a page of turns rather than loading every turn into the display at once. Speaker filters and search change what you see, not the saved transcript.

Correct a turn

1. Open the turn's edit control in the browser.
2. Change Transcript text or Speaker.
3. Click Save correction.

Revision history shows previous versions. The current version number is called a revision. If an agent or another viewer changed the turn first, Olenji asks you to reread it rather than overwrite newer work.

For a command-line correction, read the current turn and its revision number first:

olenji segments list SESSION_ID --limit 50 --json
olenji segments edit SESSION_ID SEGMENT_ID --revision 1 --text "We meet on Tuesday."

The 1 in the example is only a sample revision. Use the actual number returned for that turn. History is available; an automatic undo command is not.

Split, combine, or supply text

The editor offers Split turn and Merge with next. Splitting requires a time and the text for both pieces. Merging combines 2–100 adjacent source turns assigned to the same speaker, not simply neighboring rows in a filtered view.

Notes linked to a whole turn follow both pieces after a split. After a merge, links to the combined turns point to the surviving turn once. The note itself is preserved.

Source edits can mark old translations as needing review. They do not silently rewrite every translated language.

You or an agent can also create a session and add timed text without recognizing audio:

olenji sessions create --title "Imported transcript" --language en --json
olenji segments add SESSION_ID --start 0 --end 3.5 --text "Hello, everyone."

This is supplied text, not evidence that Olenji heard those words. Advanced edit examples are in the reference.

olenji sessions rename SESSION_ID "Team planning"

olenji models install faster-whisper.small
olenji sessions refine SESSION_ID --model faster-whisper.small

Translate a transcriptContents

Speech recognition writes down the spoken words. Translation creates another language's text from those words. English audio can be recognized with an English-capable model and then translated into Turkish. Those are two separate stages.

Olenji keeps the original wording and translations separate. Choosing a bilingual layout only changes the display; it does not create translations.

Choose a translation route

A provider is the configured text-model service. It may run on your computer or online. Adding one does not download a language model through Olenji's speech-model catalog.

Ask your agent to translate

Give your agent a request such as:

Translate the completed turns in Olenji session SESSION_ID into Turkish. Keep the original wording. Preserve names and technical terms. Save the translations against the exact source versions, and show both languages in the browser.

Replace the session ID first. The agent must be connected to Olenji; merely pasting the prompt does not connect it. The browser's agent-translation dialog can help prepare a request. Your agent's own data policy applies when it reads the transcript. A translation displayed only in the agent's chat is not yet saved in Olenji; ask the agent to submit it and confirm it appears in the intended session.

One translated sentence can refer to several source turns. The reference includes the exact submission format for agent builders.

Use a configured text-model service

The following address is an example of a local service. Use the address and model you have actually installed and started:

olenji providers add local --base-url http://127.0.0.1:11434/v1 --model TEXT_MODEL_ID
olenji translate SESSION_ID --provider local --to tr

Olenji does not start that service for you. Test a short transcript before enabling automatic translation on a long session.

Online services require their actual HTTPS address, credentials when required, and your permission for that session to send text. Keep API keys out of command-line literals; use --api-key-env or --api-key-stdin. The reference shows the privacy setting and credential options.

Use the service's API address, not a website login link. Do not include a username, password, spaces, or extra parts starting with ? or #. Local addresses such as localhost, 127.0.0.1, and [::1] can use HTTP. Other addresses require HTTPS. A saved label cannot make an online address local: Olenji checks the address again when choosing the service.

Providers must honor requests for uncompressed JSON. Olenji rejects a compressed response before reading it, so response compression cannot bypass its size limit. If this happens, configure the service or its proxy to disable response compression, then retry the translation.

Repair an invalid saved provider: run providers add again with the same provider ID and a valid address, or use providers remove to delete that provider. Other entries are preserved. Correcting an address does not reuse its previous API key unless the address is unchanged; supply a new key when needed. If the entire settings file is unreadable rather than just one entry, preserve a private copy and repair the file before retrying. Do not share it in an issue report.

Translate new text automatically

In the browser, open the translation controls, choose the language and provider, then enable automatic translation. Keep local processing selected unless you intend to send the transcript to an online provider.

Or create automatic.json:

{
  "auto_translate": true,
  "translation_language": "tr",
  "translation_provider": "local"
}

Apply it:

olenji sessions configure SESSION_ID --metadata @automatic.json --json

The status distinguishes waiting, translating, retrying, blocked, and canceled work. Temporary failures have limited automatic retries. A blocked status needs attention; silence from the provider does not mean translation finished.

Check the result: confirm that the target-language text appears beside the intended source turns and is not marked stale. Review important wording. A successful provider request or a bilingual layout alone does not prove the translation is complete or accurate.

Turn automatic translation off to prevent future automatic requests. Cancel the reported job to stop current owned work. A separate one-time translation request has its own job.

Keep corrections and languages separate

When source text changes, a previous translation can become stale: it no longer matches the current source version. It stays inspectable but is left out of readable exports until corrected.

Human translation corrections receive extra protection from automatic replacement. An agent should not label its output as a human correction. Changing the target language does not delete earlier language tracks. Use an explicit target such as tr; auto is not a translation target.

Choose a browser viewContents

Open a session in a normal local tab:

olenji ui open SESSION_ID

Olenji tries to reuse a connected viewer. Use --new-tab for a separate one. It can request a browser launch; your browser and operating system decide whether that appears in a new tab or window and whether it receives focus.

If the computer cannot launch a browser, the command returns the created view and a temporary pairing link instead of losing the result. Open that link in a browser on the same computer. You can also ask for the link without a launch:

olenji ui open SESSION_ID --print-url --json

Keep the link private. A requested launch or a returned link does not mean a viewer has connected.

Pick the layout

For Turkish beside the original:

olenji ui open SESSION_ID --layout bilingual --translation tr

For large captions:

olenji ui open SESSION_ID --layout captions --font-scale 1.4

Change the presentation

View settings include theme, text scale, separate original and translation sizes, source visibility, speaker filters, and whether to follow new speech. Scrolling back can pause following so the page does not pull you away from older text.

These choices change a view, not the saved words. Search highlighting leaves the original spelling, punctuation, and translation unchanged, including text that looks like markup. Hiding original text does not delete it. A speaker filter does not remove other speakers from an export.

Source and translation text carry their known language for assistive technology, and each text block determines its own reading direction. This helps screen readers and mixed Arabic, Hebrew, and Latin text. If recognition has not identified a source language, the view uses the session language when available.

Your agent can request a layout and check whether the connected viewer applied it. Applied does not necessarily mean the tab is visible or focused. A successful command is not proof that browser permission or playback succeeded.

Close or disconnect a viewer

Closing a tab or detaching a view does not cancel a file job or service-owned microphone capture. The exception is the tab supplying browser-microphone audio: closing it removes that source.

Pairing links grant access to the local workspace. Open the link returned by Olenji, and keep it private. Use olenji ui open again when pairing expires. Do not share an old pairing link as a public transcript link; use an export instead.

olenji tui SESSION_ID --translation tr

olenji tui SESSION_ID --translation tr --json

Add notes and export resultsContents

Add notes, decisions, or markers

You or your agent can attach a note, action, highlight, chapter, bookmark, summary, decision, or task. A stored summary is supplied text; Olenji does not automatically produce one merely because the annotation type is summary.

olenji annotations add SESSION_ID "Review the launch date." --kind note
olenji annotations list SESSION_ID --json

Use --segment SEGMENT_ID to link a note to a turn. Use it more than once to link several turns. Splitting a linked turn keeps the note attached to both pieces; merging linked turns removes duplicate links. Notes without a turn link stay attached to the session. Deleting an annotation removes that note, not the transcript.

Choose an export format

Save the original text:

olenji export SESSION_ID --format txt --out transcript.txt

Save original and Turkish subtitles together:

olenji export SESSION_ID --format srt --language bilingual --to tr --out bilingual.srt

Save Turkish text only:

olenji export SESSION_ID --format txt --language tr --out turkish.txt

SRT and VTT record times to the nearest thousandth of a second. If rounding would give a subtitle the same start and end time, Olenji moves its exported end forward by one thousandth of a second. This does not change the saved transcript timing.

Wait for transcription and required translations before exporting a final result. Bilingual readable exports keep original text where a current translation is missing. Translation-only readable exports omit turns without a current translation. Review omissions before sharing.

JSON and JSONL retain the structured session data, including translation records. Language display options do not turn them into translation-only or privacy-filtered files. Inspect them before sharing.

An export is a separate copy, not a live link. Later edits do not update it. The standalone HTML report is a transcript, not a bundled playable recording. Export formats do not imply that the app has an import or one-click restore for the same format.

Review the exported copy

Open the file you actually plan to share. Confirm the session, language, expected beginning and end, and any intended notes. For subtitles, also check timing in the target player. An export can be created before the session is complete, so file creation alone is not a completeness check.

Check important names, numbers, speaker labels, and passages without a current translation. Correct the session and export again when needed. Keep the earlier copy only if you mean to preserve that version; later session edits cannot update it automatically.

Use Check before sharing as the final review. A presentation choice in the browser is not a promise that the exported copy hides the same content.

Work with your agentContents

Your existing AI agent can use Olenji through terminal commands or MCP, a standard connection that exposes tools to the agent. Olenji does not require a built-in chatbot.

Connect an MCP-capable agent

In your agent's configuration, add Olenji as a local MCP server. In this connection mode, called stdio, the agent launches olenji mcp serve and exchanges messages with that process:

{
  "mcpServers": {
    "olenji": {
      "command": "olenji",
      "args": ["mcp", "serve"]
    }
  }
}

This is a common configuration shape, not a promise that every agent uses the same settings screen or file. The agent must be able to find the olenji executable. When using a separate workspace, give the agent the same --data-dir setting.

The inspected build exposes 41 MCP tools. The technical reference lists every name. Other operations can use the CLI or local API.

Ask for a complete outcome

For a file:

Inspect the installed Olenji models and choose one suitable for this recording's language and this computer. Transcribe FILE_PATH, distinguish the speakers, retain audio for review, and open the session. Report any missing model or permission before claiming success.

For live speech:

Start microphone transcription. Show recent speaker turns in a local browser tab. Translate completed turns into Turkish without changing the original words. Tell me whether the translation would leave this computer before using an online service.

For review:

Find the session about the launch. Show the part discussing dates, preserve my existing corrections, and export a bilingual text copy after all selected translations are current.

Replace example file paths and session descriptions with your own. A model download, microphone permission, online text processing, and permanent deletion are different actions; the agent should not treat one approval as permission for all of them.

What a reliable agent should check

The agent should check available models, wait for the correct job, preserve source versions when translating or editing, and report missing permissions honestly. It should not report a transcript complete merely because it received a job ID or report a view visible merely because a tab was requested.

Long tasks belong to the service. The agent can return later and read new saved changes. Advanced examples for bounded reads, safe retries, and event positions are in the reference.

Manage work and saved preferencesContents

Find out whether work finished

olenji jobs list --json
olenji jobs get JOB_ID --json
olenji jobs wait JOB_ID --json

A job can be waiting, running, completed, failed, or canceled. A transcript may be partly visible while its job is still running. Look at the job's final result before telling someone the task is complete.

To cancel deliberately:

olenji jobs cancel JOB_ID --json

Ending a waiting command or reaching its wait timeout does not cancel the service's job. Stop live capture with the live command so pending audio can finish normally.

Close a view, stop recording, or cancel work

These actions have different effects:

For removal rather than stopping, see Know what removal means. Closing a view does not delete a transcript.

Change defaults

olenji config get --json
olenji config set default_translation_language tr
olenji config set ui_layout bilingual

The initial workspace model is Faster Whisper Tiny, recognition language is automatic, and the translation target is Turkish. No translation service is configured automatically. Automatic translation is off. The workspace audio-retention preference is off, with the browser upload exception described under File uploads.

Changing a default model does not install it. A default generally applies to a later operation that omits a choice; it does not replace a running session's model. Explicit choices override defaults.

The reference lists every setting, including upload limits and the number of ordinary jobs that can run at once.

Manage the local service

olenji service status --json
olenji service logs --lines 50
olenji service stop

Normal operations can start the service when needed. Stop capture and important work normally before stopping the service. Read logs to investigate an error, but inspect them for private paths or transcript content before sharing them publicly.

Understand your files and privacyContents

Where files are stored

The workspace is a folder on the computer running Olenji. The browser does not hold the only copy.

~ means your home folder. You can choose another workspace with --data-dir or OLENJI_DATA_DIR. Use the same location in the CLI, service, and agent; otherwise you will see different saved sessions.

The npm application environment is stored separately; olenji-bootstrap status --json shows it. Apple manages its own speech assets. Uninstalling an application package is not the same as deleting your workspace or exports.

What can leave the computer

Local recognition uses downloaded model files after installation. Installing models and runtimes contacts download hosts. An online translation provider receives transcript text when the session permits it. Your existing hosted AI agent can also receive text when you ask it to read the transcript.

local_only restricts Olenji-managed processing. For Apple Legacy recognition, it requires on-device recognition; an unsupported device or language can fail rather than use the network. Turning this setting off can allow Apple's network recognition as well as online text services.

Changing a session's local_only setting applies to subsequent recognition calls, including later chunks of an active recording. A request already sent cannot be recalled by changing the setting. Stop active work before changing privacy settings if you need a clear boundary with no request in progress.

The setting is not a firewall for your external agent, model downloads, a separate text-model service, or all network traffic. A local provider can have its own network behavior.

Workspace files are not encrypted by Olenji by default. Keep the computer and backups secure. Do not publish provider keys, access tokens, pairing links, private recordings, or transcript databases.

Back up or move your workspace

There is no built-in backup, migration, or restore command. For a manual backup:

1. Stop active recordings normally and finish or cancel jobs.
2. Stop the service.
3. Copy the complete workspace folder to a private backup location. Include database sidecar files if present.
4. Keep the original until you have checked the copy.

Moving is not fully portable: retained-media records and prepared runtimes can contain absolute paths. Copying the folder to a different location or OS can leave playback or runtimes pointing at the old location. This build has no automatic path-repair command. Keep original recordings and the old workspace.

To evaluate a move on the same computer, stop the service, copy rather than move, and start Olenji with --data-dir pointing to the copy. The CLI and agent must use that same folder. Check playback and model readiness before using it for new work. Reinstall compatible models or reimport originals when needed.

Know what removal means

Export or back up anything you need before permanent deletion. An error during cleanup is not confirmation that the files were removed.

Solve common problemsContents

Start with the error message and the relevant job or session. Do not delete the entire workspace as a first troubleshooting step.

For an issue report, include the build identity, OS, Python or Node route, model ID, command without secrets, error code, and a small permitted reproduction. Do not include a confidential recording or key just to make the report complete. The developer package contains the project's reporting guidance.

Check platform supportContents

The application has Linux, macOS, and Windows paths. That is not a claim that every capture device, model conversion, processor, or GPU was tested on every OS.

The app does not claim perfect speaker identity, universal word-level timing, instant live captions, automatic summarization, direct website-video import, or automatic repair of relocated workspaces.

For exact commands, all model entries, API examples, and the source fingerprint, use the technical reference. For how this documentation is maintained, see the bundle's maintenance guide.

Small glossary