Skip to content

API Reference

Integrate with Yap's Wails bindings for recording, models, downloads, configuration, history, permissions, and frontend events.

This reference covers v0.5.0, not a public HTTP API. The generated frontend/wailsjs/go/main/App.d.ts is the authoritative method list; frontend/wailsjs/go/models.ts defines returned structures. Regenerate bindings when backend signatures change.

Stable 0.4.2 predates the Models Library download-state API. Use bindings from the same checkout as your backend.

Startup and state

import { WaitForStartup, GetState } from '../wailsjs/go/main/App';

await WaitForStartup();
const state = await GetState();

StartupGate.tsx waits before mounting frontend effects. GetState() returns recording state (ready, recording, transcribing, or error), recordingTime, lastTranscript, error, transcriptionOutputError, currentModel, currentProvider, modelReady, and hotkeyEnabled.

transcriptionOutputError is separate from the recording/transcription error: a failed text-file write does not change a successful transcription into an error state. Read it from the initial snapshot and stateChanged events; there is no dedicated output-error event. It clears after a successful file write, a successfully saved output-folder change, or a successful SetSaveTranscriptions call.

Recording

MethodResult / behavior
ToggleRecording()Start or stop based on state
StartRecording()Start after readiness checks
StopRecording()Stop and start transcription
CancelRecording()Discard active recording

These return Promise<void> in generated bindings. Handle rejections; do not assume a resolved startup gate means a model or API key is ready.

Models and downloads

MethodResult / behavior
GetModels()ModelInfo[] from the canonical catalog plus current file/favorite state
IsModelDownloaded(name)boolean
DownloadModel(name)Start an asynchronous managed download
GetModelDownloadState()Initial/recovered download snapshot
CancelModelDownload(name)Request cancellation
SetModel(name)Select a downloaded model
DeleteModel(name)Delete an allowed, inactive model
SetModelFavorite(name, favorite)Persist its favorite state

ModelInfo includes name, displayName, size, sizeBytes, downloaded, englishOnly, provider, speed, accuracy, useCase, recommendation, and favorite. Speed/accuracy are relative catalog ratings, not measured timings.

interface ModelDownloadState {
  model: string;
  status: 'idle' | 'downloading' | 'cancelling' |
          'completed' | 'failed' | 'cancelled';
  downloaded: number;
  total: number;
  progress: number;
  error: string;
}

Only one download runs at a time. Resolution of DownloadModel() does not mean the file has finished downloading. Observe modelDownloadState. Downloads do not auto-select models except in the onboarding flow. Use useModelDownload.ts as the reference for subscribing before fetching initial state without overwriting a newer event.

Settings and audio

GetConfig() returns the configuration structure. Setters return Promise<void>:

  • SetProvider('local' | 'openai'), SetOpenAIKey(key), SetAutoPaste(enabled), SetSoundEnabled(enabled).
  • ChooseTranscriptionOutputDir(): Promise<string> opens the native folder picker, checks write access, and persists the selected absolute path. Cancellation resolves to '' without changing settings. SetSaveTranscriptions(enabled): Promise<void> toggles saving future successful transcripts; enabling requires a writable folder. Neither operation exports old history or retries a failed write. Handle rejected calls. See Settings.
  • GetRecordingHotkey(), SetRecordingHotkey(key), GetRecordingHotkeyDisplayName().
  • GetCancelHotkey(), SetCancelHotkey(key), GetCancelHotkeyDisplayName().
  • GetAudioInputDevices() returns objects with name and isDefault; GetCurrentAudioInputDevice() returns the selected name; SetAudioInputDevice(name) changes it.
  • IsOnboardingCompleted() and SetOnboardingCompleted(completed) control setup state.

Hotkey identifiers are lowercase single-key names, such as rightoption, rightalt, and escape. Do not use the obsolete camelCase preset examples.

History and statistics

GetHistory() returns items with id, text, timestamp, duration, audioPath, and hasAudio. CopyHistoryItem(id) copies text; GetAudioData(id) returns base64 WAV data; ShowInFolder(id) reveals saved audio. These APIs take a history ID, not an arbitrary path.

DeleteHistoryItem(id) removes an entry and attempts audio-file deletion. ClearHistory() clears the list without removing all recordings. Neither deletes independently saved transcription .txt files; history items do not expose a text-file path. See History before describing either action as a full data wipe.

GetStats() returns averageWPM, wordsThisWeek, recordingsThisWeek, timeSavedThisWeek, totalRecordings, and totalWords.

Permissions and window methods

  • GetPlatform() returns the Go platform name, such as darwin, windows, or linux.
  • CheckAccessibilityPermission() / RequestAccessibilityPermission() return booleans.
  • CheckMicrophonePermission() / RequestMicrophonePermission() return status strings.
  • ReregisterHotkey() retries registration after permission recovery.
  • GetLogsDir() returns the logs directory.
  • ShowWindow(), Hide(), Minimize(), Quit(), and QuitApp() expose window/lifecycle actions.

SetTray also appears in generated bindings but is backend wiring, not a frontend feature to invoke.

Events

Import the real runtime helper, and unsubscribe when the component unmounts:

import { EventsOn } from '../wailsjs/runtime/runtime';

const unsubscribe = EventsOn('modelDownloadState', (state) => {
  console.log(state.status, state.progress);
});

// In effect cleanup:
unsubscribe();
Event in v0.5.0Payload
stateChangedApplication state snapshot
historyChangedUpdated history array
modelDownloadStateDownload lifecycle snapshot

The old Events.On / @wailsjs/runtime examples are not this project’s imports. Old downloadProgress, downloadComplete, and downloadError examples should not be used for the current Models Library.