@samvera/ramp
v5.1.0
Published
Ramp (React Avalon Media Player), React component library for rendering a media player for a IIIF 3.0 spec Manifest
Readme
@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 showcasing all the components at https://ramp.avalonmediasystem.org/
Installation Guide:
With React (NPM package)
For React applications using a build tool (Webpack, Vite, etc.).
Prerequisites
Please ensure you have the following installed:
- Node.js (>= 20.x)
reactandreact-dom(version compatibility with each Ramp version listed below)- NPM or Yarn
React Version Compatibility
@samvera/rampv5.0.0 and later require React 19@samvera/rampv3.3.0 to v4.0.2 support React 18. Note:@samvera/rampv3.3.0 works with both React 17 and React 18. If upgrading to React 18, update bothreactandreact-domto the same version.- For older versions of
@samvera/ramp, use React 17.
For ReactJS upgrade instructions, see the official upgrade guides for React 18 and for React 19 as needed.
Steps
- Add
@samvera/rampcomponents library from NPM into your application:
yarn add @samvera/ramp
npm install @samvera/rampFrom @samvera/ramp v5.x, VideoJS is included as a dependency and does not need to be installed separately.
For @samvera/ramp versions < 5.x, install the recommended VideoJS version for your Ramp version:
@samvera/rampversions <v3.1.3: Install[email protected]@samvera/rampversions between (inclusive)v3.1.3andv4.0.2: Install[email protected]
yarn add video.js@<version>
npm install video.js@<version>- Import the library into your application:
import { IIIFPlayer, MediaPlayer, StructuredNavigation, Transcript } from "@samvera/ramp";
// For @samvera/ramp versions < v5.0.0 import VideoJS styles from installed library
// import "video.js/dist/video-js.css";
// Import starter styles (includes VideoJS CSS for @samvera/ramp >= 5.0.0)
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;Without React (Standalone bundle)
For plain HTML/JS applications (Rails, PHP, etc.) with no React or build tools.
The standalone bundle uses Preact internally to keep the file size small, but exposes the full React API so the app can render components using React.createElement.
Steps
- In your HTML page, load the bundle and styles directly from unpkg (no download or build step required):
<link rel="stylesheet" href="https://unpkg.com/@samvera/ramp/dist/ramp.css" />
<script src="https://unpkg.com/@samvera/ramp/dist/ramp.standalone.umd.js"></script>To pin to a specific version, include it in the URL:
<link rel="stylesheet" href="https://unpkg.com/@samvera/[email protected]/dist/ramp.css" />
<script src="https://unpkg.com/@samvera/[email protected]/dist/ramp.standalone.umd.js"></script>Alternatively, download both files from the latest release and serve them locally.
<link rel="stylesheet" href="ramp.css" />
<script src="ramp.standalone.umd.js"></script>- In the HTML page, render the player:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<link rel="stylesheet" href="https://unpkg.com/@samvera/ramp/dist/ramp.css" />
</head>
<body>
<script src="https://unpkg.com/@samvera/ramp/dist/ramp.standalone.umd.js"></script>
<div id="root"></div>
<script>
// Import components and React
const { IIIFPlayer, MediaPlayer, StructuredNavigation, React, ReactDOM } = RampIIIF;
// Parse Manifest URL
const manifestUrl = new URLSearchParams(window.location.search).get('iiif-content');
if (!manifestUrl) {
alert('No manifest URL provided. Add ?iiif-content=<url> to the page URL.');
} else {
let parsed;
try {
parsed = new URL(manifestUrl);
} catch {
alert('Invalid URL in iiif-content parameter.');
parsed = null;
}
if (parsed) {
const root = document.getElementById('root');
const playerTree = React.createElement(
IIIFPlayer,
{ manifestUrl },
React.createElement(
'div', { className: 'iiif-player-demo' },
React.createElement(MediaPlayer),
React.createElement(StructuredNavigation)
)
);
ReactDOM.createRoot(root).render(playerTree);
}
}
</script>
</body>
</html>Questions
If you have any questions, reach out on the Samvera Community Slack:
Or, submit a new issue in the GitHub issues to report any issues or new feature requests.
Contributing
We welcome contributions! See CONTRIBUTING.md for setup instructions, development workflow, testing, and branch conventions.
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.