IP Inlay for FileMaker

Inlay › Function Reference › Transcription

Transcription

Whisper transcription of audio and video files. 8 functions.

Inlay_INSTALL_WHISPER

Transcription macOS only Returns JSON

Installs the whisper-cli binary (and on macOS the ggml-metal.metallib shader) into the Inlay helper data dir.

Required once per workstation before Inlay_TRANSCRIBE can run. Downloads are SHA-256-verified, installed atomically, and progress is shown in a native window. See the Inlay TechBlog for build/hosting guidance.

Declaration

Inlay_INSTALL_WHISPER ( UrlsJson )

Parameters

UrlsJson Required
JSON object describing the artifacts to install. Required keys: `whisper_cli` (https URL of the whisper-cli binary), `sha256_whisper_cli` (64-char lowercase hex). On macOS also required: `metal_shaders` (https URL of ggml-metal.metallib) and `sha256_metal_shaders`. Optional: `force` (boolean, defaults to false; when true, reinstalls even if the SHA already matches the on-disk file).

Returns

JSON string `{"ok":true,"status":"installed"|"already_installed","paths":{"whisper_cli":"...","metal_shaders":"..."}}` on success. On failure, `{"ok":false,"error_code":"...","message":"..."}` with codes including `download_failed` (hash mismatch or HTTP error), `invalid_args`, and `internal_error`.

Use Cases

  • Provision a workstation for offline transcription before any Inlay_TRANSCRIBE call.
  • Re-install with `force:true` to upgrade to a new whisper-cli build after re-hosting the binary.

Notes

  • macOS only. Calls from unsupported platforms return an error response.
  • The whisper-cli binary should be Mach-O universal (arm64+x86_64) for cross-architecture macOS support.
  • Models are installed separately via Inlay_WHISPER_MODEL_INSTALL.

See Also

Inlay_WHISPER_MODEL_INSTALL Inlay_TRANSCRIBE Inlay_INSTALL_FFMPEG

Inlay_WHISPER_MODEL_INSTALL

Transcription macOS only Returns JSON

Downloads a GGML whisper.cpp model into the Inlay helper data dir.

Required once per model before Inlay_TRANSCRIBE can use it. URLs and SHA-256s are baked into the plugin source (trust boundary; arbitrary URLs are not accepted). Models range from 75 MB to 3 GB depending on the variant; a native progress window shows the download.

Declaration

Inlay_WHISPER_MODEL_INSTALL ( ModelNameOrJson )

Parameters

ModelNameOrJson Required
either a bare model-name string (one of `tiny`, `tiny.en`, `base`, `base.en`, `small`, `small.en`, `medium`, `medium.en`, `large-v3`, `large-v3-turbo`) or a JSON object `{"model":"<name>","force":false}`. When `force` is true, the model is re-downloaded even if the SHA already matches the on-disk file.

Returns

JSON string `{"ok":true,"status":"installed"|"already_installed","model":"<name>","path":"<absolute-path>","bytes":N}` on success. On failure, `{"ok":false,"error_code":"download_failed"|"invalid_args"|"internal_error","message":"..."}`. SHA-256 mismatch returns `download_failed` and the partial file is removed.

Use Cases

  • Pre-flight setup: install the model your transcribe workflow needs before any user-facing call.
  • Multi-model workflows: install `small.en` for fast turnaround AND `large-v3` for archival accuracy, then choose per job at Inlay_TRANSCRIBE time.

Notes

  • macOS only. Calls from unsupported platforms return an error response.
  • `.en` models are English-only and noticeably faster/smaller. Multilingual variants (no `.en` suffix) handle 99+ languages with whisper auto-detect.
  • Downloads stream-verify, so a corrupted partial file never lands at the model path.

See Also

Inlay_INSTALL_WHISPER Inlay_TRANSCRIBE

Inlay_TRANSCRIBE

Transcription macOS only Returns JSON

Starts an offline speech-to-text job using whisper.cpp.

Non-blocking: returns immediately with a job id and opens a native progress window. Poll Inlay_TRANSCRIBE_STATUS, cancel via Inlay_TRANSCRIBE_CANCEL, or attach an OnCompleteScript callback to handle terminal status. See the Inlay TechBlog for output format details and boundaryMode behavior.

Declaration

Inlay_TRANSCRIBE ( JSONSetElement ( "{}" ;
    [ "InputPathToFile?" ; "/Media/interview.mov" ; JSONString ] ;
    [ "Model?"           ; "base.en"    ; JSONString ] ;
    [ "Outputs?"         ; "[{\"format\":\"text\",\"path\":\"/tmp/out.txt\"}]" ; JSONString ] ;
    [ "VideoLog?"  ;
        JSONSetElement ( "{}" ;
          [ "frameRate"     ; 29.97 ; JSONNumber ] ;
          [ "timecodeStart" ; "00:00:00:00" ; JSONString ] ;
          [ "boundaryMode"  ; "auto" ; JSONString ]
        )
      ; JSONObject ] ;
    [ "OnCompleteScript?" ; "Handle_Transcribe_Done" ; JSONString ]
  ) )

Parameters

ArgsJson Required
JSON object. Required keys: one of InputPathToFile OR (S3Bucket+S3Key); Model (tiny, tiny.en, base, base.en, small, small.en, medium, medium.en, large-v3, large-v3-turbo); Outputs (non-empty array of {format, path} where format is text, json, srt, vtt, or video_log_json). Optional keys: Language (ISO-639-1), Translate (boolean), S3Region, S3Endpoint, OnCompleteScript, OnCompleteScriptFile, OnCompleteScriptParam, VideoLog.
VideoLog Optional
tuning for video_log_json output. Keys: source, timecodeStart, frameRate, pauseThresholdSeconds, minBlockSeconds, maxBlockSeconds, boundaryMode (one of: auto, video_fade_to_black, scene_change, none, conservative, aggressive, speaker_change, topic_shift). All keys individually optional.

Returns

JSON string Status JSON {"ok":true,"status":"started","job_id":"tr_..."} on accepted submission. Failures return {"ok":false,"error_code":"...","message":"..."} with codes whisper_not_installed, model_not_installed, ffmpeg_not_installed, invalid_args, or internal_error. Terminal status (done, error, cancelled) surfaces via Inlay_TRANSCRIBE_STATUS or OnCompleteScript.

Use Cases

  • Generate searchable SRT/VTT subtitles from interview footage as a background script step.
  • Produce a video_log_json editorial log of a promo reel for ingest into NLE/MAM/DAM tools.
  • Transcribe audio-only files (.mp3/.wav/.m4a) with boundaryMode:"none" to skip the FFmpeg pre-pass.
  • Fire-and-forget with OnCompleteScript so the FM script returns immediately and a callback handles the result.

Notes

  • macOS only. Calls from unsupported platforms return an error response.
  • Prerequisites: Inlay_INSTALL_WHISPER, Inlay_WHISPER_MODEL_INSTALL (for the chosen model), and Inlay_INSTALL_FFMPEG.
  • Job state lives in plugin memory for the FileMaker session; FM quit drops the registry. Use Inlay_TRANSCRIBE_CLEAR_ALL to reset mid-session.
  • The progress window can be cancelled by the user; the job records status:"cancelled" and any OnCompleteScript still fires for that terminal state.
  • InputPathToFile accepts POSIX, filemac:/, file:/, filewin:/, and bare HFS forms.
  • Legacy keys inputPath, s3Bucket, s3Key, s3Region, s3Endpoint, model, language, translate, outputs, onCompleteScript, onCompleteScriptFile, onCompleteScriptParam, videoLog are accepted for one release cycle.

See Also

Inlay_TRANSCRIBE_STATUS Inlay_TRANSCRIBE_CANCEL Inlay_TRANSCRIBE_LIST_JOBS Inlay_INSTALL_WHISPER Inlay_WHISPER_MODEL_INSTALL Inlay_INSTALL_FFMPEG

Inlay_TRANSCRIBE_CANCEL

Transcription macOS only Returns JSON

Requests cancellation of an in-flight Inlay_TRANSCRIBE job.

Writes a sentinel file the helper polls every ~1 s; on detection it terminates the active whisper-cli / FFmpeg child process and records `status:"cancelled"`.

Declaration

Inlay_TRANSCRIBE_CANCEL ( JobId )

Parameters

JobId Required
the opaque id returned by Inlay_TRANSCRIBE (format `tr_<pid>_<unix_ms>_<seq>`).

Returns

Status JSON `{"ok":true,"accepted":true,"job_id":"..."}` if the sentinel was written, `{"ok":true,"accepted":false,"reason":"not_running","status":"<terminal>"}` if the job has already finished, or `{"ok":false,"reason":"missing"}` if the job id is not in the in-memory registry.

Use Cases

  • Cancel a long-running transcription when the user closes the parent record or aborts the workflow.
  • Force-stop a runaway job from an admin layout.

Notes

  • macOS only. Calls from unsupported platforms return an error response.
  • Cancellation is cooperative: the helper kills child processes on the next ~1 s polling tick, so the actual terminal state may lag the cancel call by a second.
  • The onCompleteScript callback (if any) still fires for the `cancelled` terminal state.

See Also

Inlay_TRANSCRIBE Inlay_TRANSCRIBE_STATUS Inlay_TRANSCRIBE_LIST_JOBS

Inlay_TRANSCRIBE_STATUS

Transcription macOS only Returns JSON

Returns the current state of an Inlay_TRANSCRIBE job.

Designed for FM polling: call repeatedly on a timer or in a script loop until status becomes terminal.

Declaration

Inlay_TRANSCRIBE_STATUS ( JobId )

Parameters

JobId Required
the opaque id returned by Inlay_TRANSCRIBE.

Returns

Status JSON `{"ok":true,"kind":"transcribe","job_id":"...","status":"<state>","progress_pct":N,"stage":"<stage>","started_at":N,"updated_at":N,...}`. `status` is one of `missing` (unknown job), `starting`, `downloading` (S3), `extracting_audio` (FFmpeg pre-process), `transcribing` (whisper-cli running), `done`, `error`, or `cancelled`. Once known, the payload also carries `language_detected`, `duration_s`, and on `done` an `outputs[]` array with each generated file's `format`, `path`, and `bytes`. On `error` the payload also carries `error_code` and `error`. Unknown job ids return `status:"missing"` rather than an error.

Use Cases

  • Drive a FileMaker progress UI by repeatedly querying STATUS and updating a layout while the user works elsewhere.
  • Decide branching logic on terminal state: import the transcript on `done`, surface an error dialog on `error`, do nothing on `cancelled`.
  • Confirm a job exists in the registry (vs `missing`) before calling Inlay_TRANSCRIBE_CANCEL or Inlay_TRANSCRIBE_FORGET.

Notes

  • macOS only. Calls from unsupported platforms return an error response.
  • This call is cheap (it reads a small status JSON file the helper updates as it works). Polling at 0.5-1 s is fine.
  • Status is reset when the plugin unloads (FM quit or extension toggle). Surviving status across FM restart is not supported.

See Also

Inlay_TRANSCRIBE Inlay_TRANSCRIBE_CANCEL Inlay_TRANSCRIBE_LIST_JOBS Inlay_TRANSCRIBE_FORGET

Inlay_TRANSCRIBE_LIST_JOBS

Transcription macOS only Returns JSON

Diagnostic listing of every Inlay_TRANSCRIBE job currently tracked in this FileMaker session.

Declaration

Inlay_TRANSCRIBE_LIST_JOBS

This function takes no parameters.

Returns

Status JSON `{"ok":true,"jobs":[ {"job_id":"...","status":"...","input_filename":"...","model":"...","started_at_ms":N,"has_callback":bool}, ... ]}`. Empty `jobs[]` array when no transcribe calls have run this session.

Use Cases

  • Confirm Inlay_TRANSCRIBE actually registered a job (vs. failed pre-spawn).
  • Inspect leftover registry entries before invoking Inlay_TRANSCRIBE_CLEAR_ALL.
  • Surface running/finished jobs in an admin dashboard.

Notes

  • macOS only. Calls from unsupported platforms return an error response.
  • Jobs persist for the FileMaker session and drop only when the plugin unloads (FM quit / extension toggle).
  • `has_callback` is true if the job was started with an onCompleteScript registration that is still pending.

See Also

Inlay_TRANSCRIBE_STATUS Inlay_TRANSCRIBE_FORGET Inlay_TRANSCRIBE_CLEAR_ALL Inlay_TRANSCRIBE

Inlay_TRANSCRIBE_FORGET

Transcription macOS only Returns JSON

Drops a single transcribe job from the plugin's in-memory registry.

The on-disk status file is unlinked and any pending onCompleteScript watcher is cancelled so it won't fire later even if the helper writes a terminal status.

Declaration

Inlay_TRANSCRIBE_FORGET ( JobId )

Parameters

JobId Required
the opaque id returned by Inlay_TRANSCRIBE.

Returns

Status JSON `{"ok":true,"removed":true,"job_id":"..."}` if the entry existed and was removed, or `{"ok":true,"removed":false,"reason":"missing","job_id":"..."}` if the job id was unknown.

Use Cases

  • Clean up completed jobs once their results have been imported into FileMaker.
  • Suppress a stale onCompleteScript invocation when the workflow context has changed.
  • Drop a single bad entry without resetting the whole session via Inlay_TRANSCRIBE_CLEAR_ALL.

Notes

  • macOS only. Calls from unsupported platforms return an error response.
  • This does NOT kill the underlying whisper-cli / FFmpeg subprocess. Use Inlay_TRANSCRIBE_CANCEL first when you need to stop a running job before forgetting it.
  • Idempotent: calling FORGET on an unknown or already-forgotten id is safe.

See Also

Inlay_TRANSCRIBE_CANCEL Inlay_TRANSCRIBE_CLEAR_ALL Inlay_TRANSCRIBE_LIST_JOBS

Inlay_TRANSCRIBE_CLEAR_ALL

Transcription macOS only Returns JSON

Drops every transcribe job from the plugin's in-memory registry, unlinks every on-disk status file, and cancels every pending onCompleteScript watcher.

Declaration

Inlay_TRANSCRIBE_CLEAR_ALL

This function takes no parameters.

Returns

Status JSON `{"ok":true,"removed":N}` where N is the number of registry entries that were removed.

Use Cases

  • Session reset before starting a new workflow to make sure stale jobs from a prior context don't drive callbacks.
  • Diagnostic cleanup when the registry has accumulated entries from cancelled or hung jobs.
  • Forced cleanup before plugin reload.

Notes

  • macOS only. Calls from unsupported platforms return an error response.
  • This does NOT kill running whisper-cli / FFmpeg subprocesses. Cancel running jobs individually via Inlay_TRANSCRIBE_CANCEL first when needed.
  • After CLEAR_ALL, Inlay_TRANSCRIBE_LIST_JOBS returns an empty `jobs[]` and every prior job id will return `status:"missing"` from Inlay_TRANSCRIBE_STATUS.

See Also

Inlay_TRANSCRIBE_FORGET Inlay_TRANSCRIBE_LIST_JOBS Inlay_TRANSCRIBE