A React component which displays structural metadata about an ingested audio/video file, and displays a visualized waveform to help navigating sections of the audio waveform. A user can add, edit and delete headers and timespans within the structural metadata, and save the record into a consuming application.
See how this React component works on the demo page hosted using Netlify.
Note: We are not currently publishing this package to NPM, but rather consuming it directly via a Github repository URL address. See Usage notes below for more info and example code.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
You'll need to have node installed on your local machine. Also, preferably yarn (as a wrapper for npm commands) installed as well. You can check either with:
node --version
yarn --version
- Clone this repository to your local machine
git clone https://github.com/avalonmediasystem/react-structural-metadata-editor.git
- Install dependencies
yarn install
- Start the development server
yarn dev
Open up a browser and navigate to: http://localhost:3001/. Hot reloading via webpack is enabled, so you'll see live updates in the browser during development.
All development should be done in the /src directory.
The /demo directory contains the demo application entry point index.html file, and mocks a host application consuming the SME component.
If you'd like to try out a new development feature before merging your code into main, create a new branch, ie: my-new-feature, and push your branch to https://github.com/avalonmediasystem/react-structural-metadata-editor. See the Usage section below on how to import from either main or your own feature branch.
The following commands are available to the application via npm scripts located in the package.json file.
yarn clean
Cleans the output directory dist, ensuring a fresh copy of files when preparing your files for packaging.
yarn dev
Starts the webpack development server at http://localhost:3001 in which you can view your work.
yarn test:watch
If you prefer to keep an open watch on your tests during development, run this command in a separate tab in your terminal/shell.
yarn transpile
This command prepares the SME React component for packaging and distribution. It moves packaged, transpiled files into the /dist director, which is ready to be imported by another application.
** Run this command when you're happy with your development changes, before committing a branch which you wish to push to GitHub or import locally.
To run the tests once, with a full coverage report:
yarn test
To run tests in watch mode:
yarn test:watch
Jest is our testing framework, and we're in the process of incorporating react-testing-library https://github.com/testing-library/react-testing-library.
There is a prettierrc file with project coding style settings.
To create a new build package which can be imported by a consuming application, run:
yarn transpile
This will create a component package in the /dist folder which is ready to be imported by another application.
This commands needs to be run and its output pushed to the remote branch, before making a pull request to merge the changes in your working branch to main.
When new code changes are merged to the main branch, it automatically triggers a new deploy in Netlify. And the changes will be visible shortly on the demo website.
To add this component to a host application, currently we're installing the component through a GitHub repo instead of the NPM repository, so to import the default package into your application, run:
yarn add https://github.com/avalonmediasystem/react-structural-metadata-editor
If you'd like to import a feature branch you're working on, maybe called my-new-feature, do the following:
yarn remove react-structural-metadata-editor
(to make sure old files aren't hanging around)
Then,
yarn add https://github.com/avalonmediasystem/react-structural-metadata-editor#my-new-feature
See the yarn docs (https://yarnpkg.com/lang/en/docs/cli/add/) for more info on alternative ways of importing packages.
A consuming application is expected to provide the following configuration props passed to the SME component.
| Prop Name | Type | Description | |
|---|---|---|---|
structureURL |
string | URL of the structure.json file on the server. This endpoint should accept POST requests with the updates made to the structure in the editor |
Required |
manifestURL |
string | URL of the IIIF manifest containing the media and waveform for editing. The component assumes the waveform file is listed under seeAlso property for each Canvas in the Manifest |
Required |
canvasIndex |
number | Index of the canvas relevant to the media resource in the Manifest. This has a default value of 0 in the component. | Optional |
withCredentials |
boolean | Value to pass through to xhr.withCredentials on the HLS stream request | Optional |
structureIsSaved |
function | Function to keep track of the status of the structure changes in the editor | Optional |
disableSave |
boolean | Boolean flag to remove Save Structure functionality in the UI. Value of this flag defaults to false. When saving is disabled in the editor, 'Save Structure' button will not be displayed. |
Optional |
const props = {
structureURL: 'http://example.com/structure.json',
manifestURL: 'http://example.com/manifest.json',
canvasIndex: 0,
structureIsSaved: (value) => {},
};
<StructuralMetadataEditor {...props} />
- React - JavaScript component library
- Peak.js - Waveform display library from BBC
- Jest - Testing framework
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository.
- Adam J. Arling - Front End Developer - Northwestern University
- Dananji Withana - Front End Developer - Indiana University
See also the list of contributors who participated in this project.
This project is licensed under the MIT License - see the LICENSE.md file for details