@samvera/ramp

@samvera/ramp

A ReactJS component library of interactive components created to display audio/video resources in IIIF Presentation 3.0 manifests. These components are designed and built with reusability, customizability, and accessibility in mind.

This is the renamed NPM component library previously known as @samvera/iiif-react-media-player

Documentation

For full documentation of the component library, visit GitHub Wiki

Demo site built show-casing all the components at https://ramp.avalonmediasystem.org/

Installation Guide:

Prerequisites

Please ensure you have the following installed:

• Node.js (>= 16.x)
• react and react-dom (>= 17.x)
• NPM or Yarn

Only v3.3.0 or later versions, has support for React 18. For prior @samvera/ramp versions, please use React 17.

Important: v3.3.0 can still be used with React 17. However, if you choose to upgrade to React 18; react and react-dom both need to be updated simultaneously to the same version.

To upgrade ReactJS in your application, please follow the instruction on the ReactJS' official upgrade guide.

Steps

• Add @samvera/ramp components library from NPM into your application"

// Using yarn
yarn add @samvera/ramp

// Using NPM
npm install @samvera/ramp

• Add peer dependency for Video.js library:

// Using yarn
yarn add video.js@8.10.0

// Using NPM
npm install video.js@8.10.0

Important: @samvera/ramp <= v3.1.2 needs video.js@7.21.3, because the included version of @silvermine/videojs-quality-selector is incompatible with video.js >= v8.0.0.

• Import the library and Video.js into your application:

import { IIIFPlayer, MediaPlayer, StructuredNavigation, Transcript } from "@samvera/ramp";
import 'video.js/dist/video-js.css';

// Import starter styles 
import "@samvera/ramp/dist/ramp.css";

• Example use of the components from the component library:

const App = () => {
  // Get your manifest from somewhere
  const manifestUrl = "https://some-manifest-url-here.json";

  // Transcript props
  const props = {
    playerID: 'player-id',
    transcripts: [
      {
        canvasId: 0,
        items: [ { title: "Title", url: "https://some-transcript-url-here.json" } ]
      }
    ]
  }

  return (
    <IIIFPlayer manifestUrl={manifestUrl}>
      <MediaPlayer enableFileDownload={false} />
      <StructuredNavigation />
      <Transcript {...props} />
    </IIIFPlayer>
  );
}

export default App;

Development

Ramp provides two development environments,

• using React Styleguidist: a documentation site for all the components and their usage accompanied with code snippets, running on http://localhost:6060.
• using Webpack: show-case of how these components can be arranged on a web page and styled according to user preference, running on http://localhost:3003.

Both of these can run on your localhost at the same time, and can live-reload based on your code changes.

Styleguidist environment

React Styleguidist, in addition to providing documentation, also offers an isolated development environment. To start the dev environment, run:

yarn dev

To build a static html version of the docs (which Github pages uses), run:

yarn styleguide:build

This will create a set of static documentation HTML files in the project's /docs directory. In this documentation, each component is explained with a code sample and a description of its props and functionality.

Webpack environment

An example usage of all the components in the library is served from the /demo directory. This showcases the real-time usage of the components in an application. To start this example, run:

yarn demo

Testing

Ramp uses Jest and react-testing-library to build an automated unit test suite. To run these tests, with a full coverage report, run:

yarn test

To run tests in watch mode:

yarn test:watch

Deployment

When new code is added into the main branch of the GitHub repo, it is deployed into two locations.

Deploying to Netlify demo site

The demo site is hosted with Netlify, which displays all the components in the library in a similar manner to real-life usage of them.

This demo instance can read a publicly available IIIF Presentation 3.0 Manifest given the URL of the manifest and display content in the manifest.

A new build is triggered and published in Netlify when code changes are merged to main branch in this repository.

Deploying to GitHub Pages

The GitHub pages site, https://samvera-labs.github.io/ramp/ is built using ReactJS Styleguidist docs.

Similar to the demo site, a new build of this site it triggered and published when new code changes are merged to main branch.

Contributing

If you're working on PR for this project, create a feature branch off of main.

We welcome your contributions. This repository follows the Samvera Community Code of Conduct and language recommendations.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Contributors

• Dananji Withana - Software Engineer - Indiana University
• Mason Ballengee - Software Engineer - Indiana University
• Chris Colvard - DevOps Engineer - Indiana University
• Adam J. Arling - Front End Developer - Northwestern University
• Patrick Lienau - Developer - Thirdwave, LLC
• Phuong Dinh - DevOps Engineer - Indiana University
• Divya Katpally - Front End Developer - Northwestern University

See also the list of contributors to see others who participated in this project.

License

The library is available as open source under the terms of the Apache 2.0 License.

Acknowledgments

• Avalon Media System

Changelog

v4.0.2 tag (08/05/2025)

• Fix voiceover and a11y for cues in transcripts & annotations by @Dananji in https://github.com/samvera-labs/ramp/pull/859