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
| Method | Result / 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
| Method | Result / 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 withnameandisDefault;GetCurrentAudioInputDevice()returns the selected name;SetAudioInputDevice(name)changes it.IsOnboardingCompleted()andSetOnboardingCompleted(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 asdarwin,windows, orlinux.CheckAccessibilityPermission()/RequestAccessibilityPermission()return booleans.CheckMicrophonePermission()/RequestMicrophonePermission()return status strings.ReregisterHotkey()retries registration after permission recovery.GetLogsDir()returns the logs directory.ShowWindow(),Hide(),Minimize(),Quit(), andQuitApp()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.0 | Payload |
|---|---|
stateChanged | Application state snapshot |
historyChanged | Updated history array |
modelDownloadState | Download 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.