@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

React Version Compatibility

• @samvera/ramp versions later than v4.0.2 will only work with React 19
• @samvera/ramp v3.3.0 and later support React 18. Note: @samvera/ramp v3.3.0 works with both React 17 and React 18. If upgrading to React 18, update both react and react-dom to the same version.
• For older versions of @samvera/ramp, use React 17.

For ReactJS upgrade instructions, see the ReactJS official upgrade guide.

Steps

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

yarn add @samvera/ramp

OR

npm install @samvera/ramp

Important:

• Post @samvera/ramp v4.0.2, VideoJS is included as a dependency and does not need to be installed separately.
• For older versions:
  • @samvera/ramp <= v3.1.2: Install [email protected]
  • @samvera/ramp v3.1.3 to v4.0.2: Install [email protected]
• For best results, use the recommended VideoJS version for your Ramp version.

2. Import the library into your application:

import { IIIFPlayer, MediaPlayer, StructuredNavigation, Transcript } from "@samvera/ramp";

// Import starter styles (includes VideoJS CSS)
import "@samvera/ramp/dist/ramp.css";

3. 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