README.md

June 23, 2026 ยท View on GitHub

Mirador with support for displaying annotations on videos

Forked from official https://github.com/ProjectMirador/mirador#

Node.js CI codecov

We welcome contributions and collaborations, especially on the tests and documentation side. It's mainly the lack of tests that has prevented us from submitting a PR to the main Mirador repository so far.

Demo

We will soon submit a PR to the official Mirador repository to add video support for annotations and other enhancement. We already support React 18/19, MUI7 and are up-to-date to Mirador 4 (4.0.0 version).

We provide also a new plugin to display and edit annotations on videos : https://github.com/TETRAS-IIIF/mirador-annotation-editor-video

We have also old version compatible with M3 and older version of React. Contact us to have more information.

For Mirador Users

We recommend installing Mirador using a JavaScript package manager like npm or yarn.

Our fork of Mirador is available as a package on npm. To use it change your existing Mirador dependency to mirador-video in your package.json file.

Before

"mirador": "^4.0.0"

After

"mirador": "npm:mirador-video@^1.2.8"

Then run npm install to refresh your package.

Running Mirador locally for development

Mirador local development requires nodejs to be installed. Use nvm use to set minimal supported version of NPM.

npm install

Starting the project

$ npm start

Then navigate to http://127.0.0.1:4444/

Instantiating Mirador

var miradorInstance = Mirador.viewer({
  id: 'mirador' // id selector where Mirador should be instantiated
});

> miradorInstance
{ actions, store }

Example Action

Add a window:

store.dispatch(actions.addWindow());

To focus a window run:

store.dispatch(actions.focusWindow('window-1'))

Check current state

store.getState()

Running the tests

We use Vitest to run our test suite.

$ npm test

You can see the helpful Vitest UI in your browser by running Vitest with the --ui flag. To pass the flag through to npm run the following:

$ npm test -- --ui

You can run Vitest without the additional linting and size checks in our npm test command. You can also test a single file:

$ npx vitest __tests__/integration/tests/sequence-switching.test.js --ui

Linting the project

$ npm run lint

Image Fallback

Mirador automatically displays a simple fallback placeholder when images fail to load. Customize the fallback image via configuration:

const config = {
  fallbackImage: 'https://example.com/custom-fallback.jpg',
};

The error message is translatable via the imageFailedToLoad translation key. Detailed error information is logged to the console for debugging.

Debugging

Local instance

The following browser extensions are useful for debugging a local development instance of Mirador:

Test suite

To debug the test suite, run:

$ npm run test:debug

then spin up a nodejs inspector client and set some breakpoints. See here for a guide to debugging with Chrome DevTools.