FLAT annotation viewer and media player

This repository contains deployable Drupal custom modules and their Vue source projects:

• flat_annotation_viewer/ — an annotation-viewer Drupal module for visualising media annotated with the ELAN annotation tool. This includes the Vue Javascript bundle used by Drupal. Expands on the older FLAT annotation viewer and its included EAF parser.
• flat_media_player/ — essentially the media player part of the above annotation viewer, for playing video and audio files in Drupal.
• flat_media_visualization/ — the server-side media-visualization module for generating waveform and spectrogram cache files.
• annotation_viewer_vue/ and media_player_vue/ — Vue/Vite source projects used to build the browser components.
• shared/ — JavaScript shared by the visualization tooling.

Drupal deployment

These modules target an existing FLAT/Islandora site, not a bare Drupal install. Before enabling them, install and configure:

• Drupal 11 with Node, Media and File enabled, and PHP SimpleXML.
• Islandora and its configured Fedora/Flysystem connection for the annotation viewer and for any media stored under fedora://.
• Islandora media relationships (field_media_of), media-use taxonomy (field_media_use, using Original File/Service File labels), and file-based media source fields. The annotation viewer additionally expects an annotation media bundle containing EAF files and uses field_member_of when resolving media belonging to a collection or compound object.
• Drush on the queue worker's PATH, FFmpeg/FFprobe, Python 3 and NumPy for server-generated waveforms and spectrograms, plus writable private storage outside the web root and a regularly scheduled queue worker.

Optional FLAT Permissions integration

FLAT Permissions is optional. When its flat_permissions.fedora_reader service is available, the annotation viewer and visualization worker use its FedoraReader::runAs() method to read source files. Configure a dedicated Fedora read account in flat_permissions.settings:fedora_read_user, with permission to read the repository sources. Install FLAT Permissions' dependencies too; this repository does not bundle them or their site configuration.

Without that service, source files are read through the site's normal Drupal stream wrappers, using their configured storage credentials. Ensure the web process and Drush queue worker can read the sources. Removing this dependency does not remove the Islandora and field-configuration prerequisites above.

Drupal node, media and file download access checks apply in both cases. Sites serving public collections must grant the appropriate anonymous access through Drupal; installing without FLAT Permissions does not automatically make content public. Verify access as both anonymous and restricted users before exposing protected collections.

For sites using FLAT Permissions, check that its reader API is available:

drush php:eval 'if (!Drupal::hasService("flat_permissions.fedora_reader")) { throw new RuntimeException("Install and enable FLAT Permissions with FedoraReader."); }'

Enable the viewer modules

Follow visualization setup for private storage, executable paths, resource limits and the queue command. Copy the three flat_* directories into Drupal's custom-modules directory, then:

drush en flat_media_visualization flat_media_player flat_annotation_viewer -y
drush cr

The checked-in JavaScript files referenced by each module's *.libraries.yml file are the deployment assets.

Front-end development

Use Node.js 22.12+ within the 22.x line, or Node.js 24+, as declared in each package's engines field. Keep shared/ alongside both Vue directories when building. Each Vue project has its own dependency lockfile:

cd annotation_viewer_vue   # or media_player_vue
npm ci
npm run dev

These are web-component libraries, without standalone HTML demo pages. Vite's development server needs a custom harness; the supported integration check is to build and load the components in Drupal.

Run npm run build to produce a local dist/ directory. Deploy a newly built bundle to the corresponding Drupal module only after updating the module's library definition to reference it.

Libraries

Both Vue applications use WaveSurfer.js to display audio waveforms and spectrograms.

AI assistance

This project was developed with assistance from Claude Code, Google Gemini, and ChatGPT. Human contributors reviewed, directed, and remain responsible for all project decisions and released code.