Olenji functions at a glance

Function reference. Use the numbered groups to find an action, its choices, and its limits. Use Complete a workflow to connect those actions, then Check before sharing to review the result. Group headings open the detailed instructions in the handbook; the separate PDF keeps its own navigation.

A session is a saved transcript and its related work. A turn is one timed piece of source text. The workspace is the folder where Olenji saves its data. MCP lets an AI agent call Olenji tools; the local API lets another program send requests. You can also use terminal commands (the CLI).

Choose separately: how audio enters Olenji, which model recognizes it, who writes an optional translation, and where you view the result. Changing the view does not change the speech model or produce a translation.

1. Transcribe existing recordings

1.1 Submit a recording

One file: transcribe a local audio or video file with a terminal command. Relative paths start from the caller's current folder.
Several files: submit multiple paths together. Each file gets its own session and processing task; shared options apply to the batch.
Browser upload: select or drop one file per submission. The browser sends it to the paired Olenji service.
AI agent: ask a connected agent to submit a file on the computer running Olenji and check the returned task.
Local API: let another application submit a local path or upload the file's bytes through an authenticated request.

1.2 Set options and check the result

Recognition choices: choose a compatible model and the spoken language, or automatic language detection where supported. Processor and precision controls depend on the model.
Speaker labels and audio: request voice grouping, set a session title, and choose whether to retain audio for playback and later re-transcription.
Waiting and viewing: wait for completion or return task IDs without waiting; optionally open the browser. Batch submission does not mean unlimited parallel processing.
Saved result: inspect the recognized text, available timing, speaker assignments, and task status. An accepted task is not a finished transcript. Check each task in a batch; one successful file does not confirm the others.

Limits: video transcription uses the recording's audio, not its on-screen words or images. FFmpeg determines readable media formats. Timing may be per word, segment, or input clip. There is no general website-video downloader. Keep local input files available until processing ends. The browser upload form starts with your saved audio-retention preference. Change Source recording before submitting to override it for that file.

2. Transcribe live speech

2.1 Choose one live input

Computer microphone: use the default microphone or an available native input device returned by source discovery.
System audio: capture computer playback through the operating system's supported route.
Browser microphone: supply audio from a paired tab after granting microphone permission and starting its microphone control.
Global push-to-talk: ask your agent to bind a keyboard shortcut on the service computer. Hold to record a new transcript session; release to finish. OS approval may be needed. Explicit insertion can write completed words into the same supported focused field, without sending. Default output remains a saved transcript. macOS insertion requires an empty selection and confirms only the newly inserted Unicode range; interrupted shortcut delivery retains the transcript without insertion.

2.2 Control and monitor capture

Prepare: inspect available inputs, choose a ready speech model, and prepare the separate speaker model when voice labels are needed. Test actual speech before an important recording.
Start and retain: begin a session with the selected input, model, language, speaker option, and audio-retention choice.
Pause or resume: suspend new capture and continue in the same session.
Stop and finish: stop capture and allow accepted audio to finish processing. Wait for any returned finalization task before exporting the final result.
Read the status: see changing draft words, saved turns, available input levels, and reported gaps. Missing audio cannot be reconstructed.

Ownership: service-managed microphone or system capture can continue after a viewer closes. Browser-microphone capture needs its supplying tab. Starting a session does not grant permission. This build chooses one source per session; it does not promise combined microphone/system tracks, per-app capture, or arbitrary browser-tab audio. Live text uses buffered speech, so delay varies.

3. Choose and manage speech models

3.1 Find a suitable choice

Catalog search: list all entries, search by name, or show installed models. Choices come from Olenji's bundled, reviewed catalog, not an internet-wide search.
Compatibility: inspect spoken languages, computer requirements, supporting software, download information, terms, and readiness before choosing.
Coverage: the reviewed development catalog has 29 transcription entries and nine speaker choices, including the 17 FluidVoice speech selections in its dated comparison. Sizes and conversions count separately; this is not a promise about future FluidVoice releases.
Available families: Whisper and Faster Whisper, Parakeet, Fluid Speech Mini/Pico, Moonshine, Nemotron, Apple Speech, Qwen3 ASR, Cohere, and Voxtral. Speaker choices include WeSpeaker, Nemotron 3, Pyannote-style ONNX, Sortformer v2/v2.1, and four LS-EEND variants.

3.2 Plan and install

One model or a group: inspect a download plan, then install a model or a preset profile through the CLI, agent tools, or supported browser controls.
Preset profiles: use a named model list, such as the recommended pair or the FluidVoice comparison set. Profiles are not automatic accuracy rankings. Review skipped entries in a compatible-only plan.
Download sources: reviewed Hugging Face repositories, versioned GitHub releases or FluidVoice's model host supply exact artifacts. Apple manages its own speech assets.

3.3 Keep, reuse, and remove files

Local weights: downloaded speech and speaker files remain on the service computer under models/MODEL_ID/ in the workspace and are reused for later recordings.
Supporting software: the engines that run those files stay separately in runtimes/. Installing the app alone does not install every model.
Verification: check installed files and readiness, then try a short recording in the language you need. A catalog entry, downloaded files, and an engine that runs are different checks.
Removal: remove unused managed weights without deleting transcripts. A model in use cannot be removed; supporting engines may remain. Apple controls its own asset lifecycle.

3.4 Find the workspace

Linux: ~/.local/share/olenji, or the olenji folder under a valid absolute XDG_DATA_HOME.
macOS: ~/Library/Application Support/Olenji.
Windows: %LOCALAPPDATA%\Olenji, with a user AppData fallback.

A custom workspace changes this base folder. Model licenses are separate from the app's; Pico's weight-license metadata is unresolved in this reference. Translation text models are configured separately, not downloaded from this catalog.

4. Identify and name speakers

4.1 Create and organize voice labels

Group recurring voices: request speaker processing when transcribing, recording, or re-transcribing retained audio. The speaker model is separate from speech recognition.
Choose a backend and preset: inspect olenji_speaker_models or the catalog, then select a compatible speaker model for file transcription or refinement. New timeline backends are offline-only and capped at one hour; live capture uses WeSpeaker. Presets tune one model rather than download another model.
Recover changed weights: if speaker startup reports model_corrupt, verify and reinstall the speaker model before retrying. See the speaker recovery steps.
Create labels: use generated anonymous labels or add a label yourself before assigning turns.
Names and colors: rename labels and choose their display colors. A name comes from you or your agent, not verified identification by Olenji.

4.2 Correct the attribution

Reassign a turn: choose another speaker or mark the turn Unassigned.
Merge duplicates: move a source label's assignments into a surviving target label. This changes saved assignments and can require translation review.

Limits: labels belong to a session, not a verified identity across recordings. Similar voices, short turns, noise, and overlap can remain uncertain. Installing the speaker model alone does not label old transcripts. There is no one-command unmerge.

5. Manage sessions and edit transcripts

5.1 Find and organize work

Session organization: create, list, rename, and tag sessions. Search session titles and source text.
Transcript reading: inspect the whole saved result or a smaller window. Within a session, search source and translated text; filter by speaker or navigate through turns.
Safe deletion: permanently delete an inactive session and its managed data after active work ends. Original external inputs and separate exports are not the same data.

5.2 Correct or supply text

Edit a turn: change its words, timing, or speaker. Read the current version first; conflicting edits are rejected rather than silently replacing newer work.
Review history: inspect earlier saved versions. History is not an automatic undo command.
Split: divide a turn using a split time and the text for both pieces. Linked notes follow both pieces.
Merge: combine 2–100 adjacent source turns assigned to the same speaker. Linked notes move to the surviving turn. Neighboring visible rows under a filter are not necessarily adjacent in the source.
Add supplied text: create a session and add timed turns directly, yourself or through an agent, without running recognition.

Result: original text, edits, labels, and related records remain in the session. A source change can mark translations outdated; it does not silently rewrite every language. Supplied text is not proof that Olenji heard the words. Session deletion has no Trash or built-in restore.

6. Replay and refine recordings

6.1 Review the retained recording

Keep audio: request retention when importing or recording. Text can remain after temporary audio is removed.
Play and seek: listen to the managed audio copy and move to a relevant point. A browser may require a click before playback.

6.2 Run recognition again

Choose another model: re-transcribe retained audio with a prepared model and supported settings; optionally request speaker grouping.
Preserve human work: protect human-edited regions. Conflicting regions can remain unchanged and are reported; failed refinement preserves the earlier transcript.
Review changed results: check new wording, timing, speaker assignments, and translations that now need updating.

6.3 Remove only the audio

Keep the words: after active work ends, disable retention to remove the managed recording while retaining transcript text. If cleanup fails, resolve the access problem and retry.

Limits: playback is audio, not an original-video editor. Enabling retention later cannot recover deleted samples. Import the original again when needed; removing Olenji's audio copy does not delete that external original.

7. Translate transcripts

7.1 Choose who writes the translation

Existing agent: ask your connected agent to translate selected or completed turns into Turkish or another language, then save the result against the exact source versions. An answer only in the agent chat is not a saved Olenji translation.
One-time request: request a translation from a configured text-model service and follow its task to completion.
Automatic translation: enable a provider and target language for a session so newly completed source can be translated as work continues.

7.2 Configure processing and control work

Local provider: connect a text-model service already installed and running on your computer. Olenji does not download or start that text model for you.
Online provider: configure its address, model, and required credentials; explicitly allow the session to send text. Your separate agent has its own data policy.
Observe and recover: inspect waiting, translating, retrying, blocked, or canceled work. Temporary failures have limited retries; blocked work needs attention.
Stop deliberately: disable future automatic requests or cancel the exact current task. A one-time request owns a separate task.

7.3 Keep languages and corrections intact

Separate tracks: retain original wording and multiple translated languages. Changing the target does not delete earlier languages.
Sentence groups: attach a translation to one or several source turns, preserving their IDs and versions. One speech-recognition turn is not necessarily a whole sentence.
Human corrections: protect human edits from automatic replacement. Mark translations outdated when the source changes; review them before use or export.

Check the result: verify that current target-language text exists beside the intended source. A bilingual view does not create it. Turkish recognition and translation into Turkish are different model requirements. Use an explicit translation language, not auto.

8. Read in a browser or terminal

8.1 Open and control browser views

Local browser view: open or reuse a paired viewer; request another tab when needed. The browser decides actual tab/window behavior and focus.
Text and layout: change theme, overall scale, separate original/translation sizes, source visibility, speaker filters, search, and live following.
Agent-directed display: ask the agent to configure a view and check its acknowledgment. Applied does not necessarily mean visible, focused, or playing audio.

8.2 Pick one of six layouts

Conversation: read timed turns with speaker labels.
Bilingual: compare original wording with an available translation.
Captions: show large, recent text with fewer controls.
Review: read and correct words while playing retained audio.
Timeline: examine timing and speaker turns.
Operations: inspect tasks, processing state, and reported problems.

8.3 Follow the terminal view

Terminal view: follow recent turns, speaker colors, available translations, draft words, capture state, and available input levels within the terminal's size.
Machine-readable result: return one recent snapshot as JSON. Use the events interface for a continuing stream of saved changes.
Detach or reconnect: leave the viewer without stopping service-owned recording; retain the last committed display during a limited reconnect attempt.

Display only: filters, text sizes, and hiding the original do not edit or delete saved content or restrict exports. Old text is not proof that capture is active. Keep pairing links private. Terminal instructions.

9. Add notes and markers

9.1 Record useful context

Written notes: save notes, highlights, or summaries supplied by you or your agent.
Follow-up items: store actions, decisions, or tasks as text.
Navigation markers: add chapters or bookmarks to help organize the discussion.

9.2 Attach and manage items

Source links: connect an item to one or several turns, or keep it as a session-level item.
Read or remove: list stored items and delete an item without deleting transcript text.

Limits: choosing a summary label does not generate a summary. A task label does not execute work or create an external task-manager entry. These are stored annotations, not an independent assistant.

10. Export results

10.1 Choose a format

TXT: share a readable plain-text transcript.
Markdown: keep readable text and notes in an editable document format.
HTML: open a standalone transcript report without running the Olenji service.
SRT: save a subtitle track for tools that accept SRT files.
VTT: save subtitles in VTT format. Both subtitle formats depend on the timing produced by recognition.
JSON: save structured session data for another application or agent.
JSONL: save structured records one per line for line-by-line processing.

10.2 Choose language and check completeness

Original, translated, or bilingual: select the language presentation for readable exports and, where needed, the target language.
Missing or outdated translation: bilingual output retains source where a current translation is missing. Translation-only readable output omits turns without a current translation; review omissions before sharing.
Finish first: wait for transcription and required translations before making a final export. Choose the destination file through the supported export route.

Privacy and reuse: JSON/JSONL retain source text and translation records; a language option does not turn them into filtered private copies. An export is independent of later edits. HTML does not bundle playable audio. No export is a full workspace backup or a promise of matching import/restore support.

11. Work through agents and other applications

11.1 Connect and discover

Environment advice: inspect passive process facts and optional task/context suggestions before choosing a route. This command and tool, available from 1.1.0, do not start a service, probe devices or grant user-side access. See the agent instructions for a concise local-app handoff when live audio is unavailable.
Terminal commands: call Olenji directly, using JSON for structured results and JSONL where a saved-event stream is needed.
MCP connection: expose version 1.2.1's 46 tools to an existing compatible agent. The agent launches the local tool process; Olenji needs no built-in chatbot.
Local API: use authenticated requests from another program. Inspect command schemas and tool definitions instead of guessing fields or treating every route as identical.

11.2 Coordinate longer work

Tasks: list, inspect, wait for, or cancel background jobs. Keep their IDs so later calls inspect the same work.
Read a smaller portion: retrieve a limited transcript window with related translation context rather than repeatedly reading everything.
Saved events: follow saved changes or resume from a recorded position after reconnecting.
Safe retries and edits: reuse the same supported request label when retrying to avoid starting the same work twice. For an edit or translation, include the source versions you read so newer work is not silently overwritten.

Check outcomes: a task ID means the request was accepted, not that it finished. Ending a wait does not cancel its task. A requested view is not proof that it opened. Model downloads, capture permission, online processing, and permanent deletion are separate actions to authorize deliberately.

12. Manage settings, files, and the service

12.1 Install and maintain the application

Offline help: open the bundled handbook with olenji docs --open, list topics with olenji docs --list, or select Help and handbook in the browser. No service, model download, or internet access is needed for the terminal route.
Python route: install the supplied wheel with uv or pip in a separate environment.
npm route: install the supplied package, then explicitly prepare its Python environment. It runs the same engine; setup does not install all speech models. Bun is optional.
Update safely: finish or cancel active work, stop the service, back up needed data, replace the app, and check readiness. Registry publication is not established for this build.

12.2 Set preferences and choose storage

Saved defaults: choose model, spoken language, audio retention, translation target, and view preferences. Explicit operation choices take priority; changing a default does not install a model or replace a running task.
Translation services: add, inspect, or remove provider addresses and model settings; use the documented credential inputs rather than typing a key directly into a command.
Workspace: use the same data folder for the service, CLI, and agent. Text, edits, translations, labels, notes, and jobs stay in its database; session folders contain managed audio and temporary files.

12.3 Diagnose, protect, and clean up

Service controls: start, inspect, stop, and read logs from the background service; use diagnostics to check model, platform, and capture readiness.
Processing privacy: restrict Olenji-managed processing to local execution or explicitly allow online text processing. This setting is not a firewall for downloads, an external agent, or a separate local provider.
Private files: protect recordings, transcript databases, provider keys, access tokens, and pairing links. Olenji does not encrypt workspace files by default.
Selective cleanup: remove unused weights, managed audio, inactive sessions, or separate exports deliberately. These actions remove different data; uninstalling the app does not necessarily remove any workspace data.
Manual backup: stop work and the service before copying the full workspace. Moving it to another path or OS can break audio and engine paths; there is no built-in backup/restore or automatic repair command.

Initial defaults: Faster Whisper Tiny, automatic recognition-language selection, Turkish as the translation target, and audio retention off at workspace level. No text provider is configured and automatic translation is off. The file-upload exception is stated in section 1. Installation · Storage and privacy.

Complete a workflow

These combinations use the functions above. They are multi-step tasks, not extra commands or automatic promises.

Recording to a bilingual report: Transcribe the file, correct important wording, create and review a translation, then export both languages. Finished when: the saved export contains the intended source and current translation.
Several recordings to separate transcripts: choose shared options and submit the batch. Keep each session and task ID, check each result, and export the sessions you need. Finished when: every input has a checked result or a known failure; this does not create one combined report.
Live speech with Turkish captions: prepare and test one input, choose who will translate saved turns, and open a bilingual or captions view. Finished when: capture has been stopped, accepted audio has finished processing, and the required translations are present. A closed view is not proof of any of these.
Improve an existing transcript: reopen the session and review it. Correct text directly, or re-transcribe retained audio when appropriate. Review affected translations and create a new export. Finished when: the saved copy reflects the reviewed changes; an earlier export does not update itself.
Work from text you already have: create a session and add timed turns. Translate, annotate, and export that text as needed. Finished when: the supplied words and intended additions are saved. This route does not perform speech recognition or imply a general subtitle-file import.

Completion: check the relevant task results and any finalization work. Saved partial text can exist after a failed or canceled task.
Accuracy: review names, dates, numbers, speaker assignments, and reported gaps against the recording when available. A completed task is not a guarantee of correct wording.
Translation coverage: confirm the required language is present and current. Translation-only readable exports can omit turns without a current translation.
The actual file: open the export and inspect its content and timing. Display filters and hiding the original do not remove it from stored data or structured exports.
Privacy and reuse: check what you are sharing, where it will go, and whether you still need the audio. Exported text is not a full backup of the workspace.

Scope of this list

This reference describes 1.2.1, including environment advice, global push-to-talk and selectable speaker backends. Python, npm and direct downloads use the same application engine and features at that version; previous releases remain separate recovery material. A source or registry change is not a new hardware or inference test. Application features still depend on the selected model, OS, permissions, and device. The historical application archive is separate from this working documentation bundle.

Version 1.2.1 provides 73 CLI commands, 46 agent tools and 38 model identities. Earlier selected Linux results do not establish native Windows/macOS, Apple-model, GPU, or physical-capture success on your machine. Multilingual and overlapping-speaker accuracy needs representative testing. Read platform support and the handbook's exact reference before relying on a particular environment.