Getting Started

Installation

Requirements

  • Omeka S 4.0 or later
  • PHP 8.1 or later, with a generous memory_limit for the PHP CLI (word-level JSON for a multi-hour interview is a few megabytes)
  • The ExtractText module, installed and active. The installer checks for it.
  • ffmpeg and ffprobe on the host. They are needed for video, for recordings above the provider's upload limit, and for duration-based cost estimates. Audio within the upload limit works without them; video queueing is disabled without them.
  • Background jobs using Omeka's default PhpCli dispatch strategy, so long transcriptions are not cut off by web timeouts.

Installing

  1. Copy the OralArchivist folder into your Omeka S modules/ directory.

  2. Add an encryption key to config/local.config.php. It is used to encrypt the OpenAI API key at rest.

    'oralarchivist' => [
    'encryption_key' => 'a-long-random-string',
    // Optional: pin the API key here instead of storing it in the database.
    // It overrides the stored key and is never shown in the UI.
    // 'openai_api_key' => 'sk-...',
],

  3. Log in as a Global Administrator, go to Admin > Modules and click Install next to Oral Archivist.

  4. Open Oral Archivist > Settings, choose providers and paste an OpenAI API key. Click Refresh model list and pick an LLM model. The list is fetched live from the provider.

The module installs with the mock provider selected. It produces a deterministic fake transcript with chapters at no cost, so you can walk through the whole workflow before switching to OpenAI. See Configuration.

An Oral Archivist entry appears in the admin sidebar with a badge showing the number of interviews awaiting review.

Upgrading

Copy the new version over modules/OralArchivist, then visit Admin > Modules and click Upgrade if prompted. Upgrades run any database migrations the new version needs.

Uninstalling

Uninstalling drops the module's tables (transcripts, chapters, topics, speakers, footnotes and job records) and deletes its global settings. Media files and items are untouched. Text already written to the ExtractText property of published media is not removed; unpublish interviews first if you want that cleared.

Log in for Support