Skip to content

Commit

Permalink
I240 (bbc#242)
Browse files Browse the repository at this point in the history 
* General automated clean up

* Updating feature list

* Updated Readme

* Updated docs for Adapters, Analytics and renaming misspellings.
  • Loading branch information
@emettely
emettely authored Aug 3, 2020
1 parent c132484 commit fa6d651
Show file tree
Hide file tree
Showing 6 changed files with 340 additions and 276 deletions.
192 changes: 97 additions & 95 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# React Transcript Editor

<!-- _One liner_ -->

A React component to make transcribing audio and video easier and faster.

<p>
Expand All @@ -16,9 +14,7 @@ A React component to make transcribing audio and video easier and faster.
</a>
</p>
<br/>

The project uses [this github project boards to organise and the co-ordinate development](https://github.com/bbc/react-transcript-editor/projects).

_--> Work in progress <--_

<!-- _Screenshot of UI - optional_ -->
Expand All @@ -35,42 +31,39 @@ _--> Work in progress <--_

Node version is set in node version manager [`.nvmrc`](https://github.com/creationix/nvm#nvmrc)

<!-- _Coding style convention ref optional, eg which linter to use_ -->

<!-- _Linting, github pre-push hook - optional_ -->

## Setup

<!-- _stack - optional_ -->
<!-- _How to build and run the code/app_ -->

Fork this repository + git clone + cd into folder
1. Fork this repository
2. Clone this repository to a directory of your choice
3. Run `npm i` to install dependencies

## Usage - development

Git clone this repository and cd into the folder.
We use a tool called [`storybook`](https://storybook.js.org)
to run the components locally. To start the Storybook, run:

To start the storybook run

```
```sh
npm start
```

Visit [http://localhost:6006](http://localhost:6006)
Running that command should open the locally hosted Storybook, but if it doesn't,
visit [http://localhost:6006](http://localhost:6006)

## Usage - production

Available on [npm - `@bbc/react-transcript-editor`](https://www.npmjs.com/package/@bbc/react-transcript-editor)
In order to use a published version of `react-transcript-editor`,
install the published module [`@bbc/react-transcript-editor`](https://www.npmjs.com/package/@bbc/react-transcript-editor)
by running:

```
```sh
npm install @bbc/react-transcript-editor
```

```js
import TranscriptEditor from "@bbc/react-transcript-editor";
```

Minimal data needed for initialization
### Basic use case

```js
<TranscriptEditor
Expand All @@ -79,43 +72,52 @@ Minimal data needed for initialization
/>
```

With more attributes
`transcriptData` and `mediaUrl` are non-optional props to use `TranscriptEditor`.
See the full list of options [here](#transcripteditor-props-list).

### Advanced use case

```js
<TranscriptEditor
transcriptData={someJsonFile}
mediaUrl={"https://download.ted.com/talks/KateDarling_2018S-950k.mp4"}
handleAutoSaveChanges={this.handleAutoSaveChanges}
autoSaveContentType={'digitalpaperedit'}
autoSaveContentType={"digitalpaperedit"}
isEditable={true}
spellCheck={false}
sttJsonType={"bbckaldi"}
handleAnalyticsEvents={this.handleAnalyticsEvents}
fileName={"ted-talk.mp4"}
title={"Ted Talk"}
ref={this.transcriptEditorRef}
mediaType={'video'}
mediaType={"video"}
/>
```

| Attributes | Description | required | type |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------- | :------: | :-------: |
| transcriptData | Transcript json | yes | Json |
| mediaUrl | string url to media file - audio or video | yes | String |
|`handleAutoSaveChanges`| returns content of transcription after a change | no | Function |
| autoSaveContentType | specify the file format for data returned by `handleAutoSaveChanges`,falls back on `sttJsonType`. or `draftjs` | no | string |
| isEditable | set to true if you want to be able to edit the text | no | Boolean |
| spellCheck | set to true if you want the browser to spell check this transcript | no | Boolean |
|`handleAnalyticsEvents`| if you want to collect analytics events. | no | Function |
| fileName | used for saving and retrieving local storage blob files | no | String |
| title | defaults to empty string | no | String |
| ref | if you want to have access to internal functions such as retrieving content from the editor. eg to save to a server/db. | no | React ref |
| mediaType | can be `audio` or `video`, if not provided the component uses the url file type to determine and adjust use of the page layout | no | String |
### TranscriptEditor Props List

| Props | Description | required | type | default |
| :---------------------- | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------: | :-------: | :----------------------------------------------------------------------------: |
| `transcriptData` | Transcript JSON | yes | JSON | |
| `mediaUrl` | URL to media (audio or video) file | yes | String | |
| `handleAutoSaveChanges` | Function to handle the content of transcription after a change | no | Function |
| `autoSaveContentType` | Specify the file format for data returned by `handleAutoSaveChanges` | no | String | falls back to `sttJsonType`, if set, or `draftjs` |
| `isEditable` | Set to `true` to have the ability to edit the text | no | Boolean | False |
| `spellCheck` | Set to `true` to spell-check the transcript | no | Boolean | False |
| `sttJsonType` | The data model type of your `transcriptData` | no | String | `draftjs` |
| `handleAnalyticsEvents` | if you want to collect analytics events. | no | Function | false |
| `fileName` | used for saving and retrieving local storage blob files | no, but disables the [local save feature](#local-save) | String |
| `title` | defaults to empty string | no | String |
| `ref` | If you want to have access to internal functions such as retrieving content from the editor. eg to save to a server/db. | no | React ref |
| `mediaType` | Can be `audio` or `video`. Changes the look of the UI based on media type. | no | String | if not provided the component uses the `medialUrl` to determine the media type |

See [`./demo/app.js` demo](./demo/app.js) as a more detailed example usage of the component.

_Note: `fileName` it is optional but it's needed if working with user uploaded local media in the browser, to be able to save and retrieve from local storage. For instance if you are passing a blob url to `mediaUrl` using `createObjectURL` this url is randomly re-generated on every page refresh so you wouldn't be able to restore a session, as `mediaUrl` is used as the local storage key. See demo app for more detail example of this[`./src/index.js`](./src/index.js)_
#### Local save

_Note: `mediaType` if not defined, the component uses the url to determine the type and adjust the layout accordingly, however this could result in a slight delay when loading the component as it needs to fetch the media to determine it's file type_
`fileName` is optional but it's needed if working with user uploaded local media in the browser,
to be able to save and retrieve from local storage.
For instance if you are passing a blob url to `mediaUrl` using `createObjectURL` this url is randomly re-generated on every page refresh so you wouldn't be able to restore a session, as `mediaUrl` is used as the local storage key. See demo app for more detail example of this[`./src/index.js`](./src/index.js)\_

### Typescript projects

Expand All @@ -128,15 +130,17 @@ import { TranscriptEditor } from "@bbc/react-transcript-editor";

#### Internal components

##### Direct imports

You can also import some of the underlying React components directly.
See [the storybook](https://bbc.github.io/react-transcript-editor) for each component details on optional and required attributes.

- `TranscriptEditor`
- `TimedTextEditor`
- `MediaPlayer`
- `VideoPlayer`
- `Settings`
- `KeyboardShortcuts`

- `ProgressBar`
- `PlaybackRate`
- `PlayerControls`
Expand All @@ -153,144 +157,142 @@ import TimedTextEditor from "@bbc/react-transcript-editor/TimedTextEditor";
import { TimedTextEditor } from "@bbc/react-transcript-editor";
```

However if you are not using `TranscriptEditor` it is recommended to follow the second option and import individual components like: `@bbc/react-transcript-editor/TimedTextEditor` rather than the entire library. Doing so pulls in only the specific components that you use, which can significantly reduce the amount of code you end up sending to the client. (Similarly to how [`react-bootstrap`](https://react-bootstrap.github.io/getting-started/introduction) works)
##### Import recommendation

See [the storybook](https://bbc.github.io/react-transcript-editor) for each component details on optional and required attributes.
However if you are not using `TranscriptEditor` it is recommended to follow the second option and import individual components like: `@bbc/react-transcript-editor/TimedTextEditor` rather than the entire library.
Doing so pulls in only the specific components that you use, which can significantly reduce the amount of code you end up sending to the client. (Similarly to how [`react-bootstrap`](https://react-bootstrap.github.io/getting-started/introduction) works)

#### Other Node Modules (non-react)

Some of these node modules can be used as standalone imports.

You can also use this node modules as standalone
##### Export Adapter

Converts from draftJs json format to other formats

```js
import exportAdapter from "@bbc/react-transcript-editor/exportAdapter";
```

Converts from draftJs json format to other formats
##### STT JSON Adapter

Converts various stt json formats to draftJs

```js
import sttJsonAdapter from "@bbc/react-transcript-editor/sttJsonAdapter";
```

Converts various stt json formats to draftJs
##### Conversion modules to/from Timecodes

Some modules to convert to and from timecodes

```js
import {
secondsToTimecode,
timecodeToSeconds,
shortTimecode
shortTimecode,
} from "@bbc/react-transcript-editor/timecodeConverter";
```

some modules to convert to and from timecodes

## System Architecture

<!-- _High level overview of system architecture_ -->

- uses [`storybook`](https://storybook.js.org) with the setup as [explained in their docs](https://storybook.js.org/docs/guides/guide-react/) to develop this React.
- Uses [`storybook`](https://storybook.js.org) with the setup as [explained in their docs](https://storybook.js.org/docs/guides/guide-react/) to develop this React.
- This uses [CSS Modules](https://github.com/css-modules/css-modules) to contain the scope of the css for this component.
- [`.storybook/webpack.config.js](./.storybook/webpack.config.js) enanches the storybook webpack config to add support for css modules.
- [`.storybook/webpack.config.js](./.storybook/webpack.config.js) enables the storybook webpack config to add support for css modules.
- The parts of the component are inside [`./packages`](./packages)
- [babel.config.js](./babel.config.js) provides root level system config for [babel 7](https://babeljs.io/docs/en/next/config-files#project-wide-configuration).

<!-- - for build, packaging, and deployment of the npm module, we use webpack with babel 7 -->

## Documentation

There's a [docs](./docs) folder in this repository.
There's a [docs](./docs) folder in this repository, which contains subdirectories to keep:

[docs/notes](./docs/notes) contains dev notes on various aspects of the project.
- [notes](./docs/notes): dev notes on various aspects of the project.
- [adr](./docs/adr): [Architecture Decision Record](https://github.com/joelparkerhenderson/architecture_decision_record).

[docs/adr](./docs/adr) contains [Architecture Decision Record](https://github.com/joelparkerhenderson/architecture_decision_record).
### ADR

> An architectural decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
We are using [this template for ADR](https://gist.github.com/iaincollins/92923cc2c309c2751aea6f1b34b31d95)

### QA

[There also QA testing docs](./docs/qa/README.md) to manual test the component before a major release, (QA testing does not require any technical knowledge).

## Build

<!-- _How to run build_ -->

> To transpile `./packages` and create a build in the `./dist` folder, run:
```
```sh
npm run build:component
```

## Demo & storybook
To understand the build process, have a read through [this](./docs/guides/storybook-npm-setup.md).

- **Storybook** can bew viewed at [https://bbc.github.io/react-transcript-editor/](https://bbc.github.io/react-transcript-editor/)
## Demo & storybook

- **Storybook** can be viewed at [https://bbc.github.io/react-transcript-editor/](https://bbc.github.io/react-transcript-editor/)
- **Demo** can be viewed at [https://bbc.github.io/react-transcript-editor/iframe.html?id=demo--default](https://bbc.github.io/react-transcript-editor/iframe.html?id=demo--default)

http://localhost:6006

<!-- https://github.com/gitname/react-gh-pages
-->
To run locally, see [setup](#usage---development).

## Build - storybook
### Build - storybook

To build the storybook as a static site
To build the storybook as a static site, run:

```
```sh
npm run build:storybook
```

## Publish storybook & demo to github pages
This will produce a `build` folder containing the static site of the demo.
To serve the `build` folder locally, run:

This github repository uses [github pages](https://pages.github.com/) to host the storybook and the demo of the component

```
npm run deploy:ghpages
```sh
npm run build:storybook:serve
```

add to git, and push to origin master to update
#### Publishing to a web page

<!-- https://help.github.com/articles/user-organization-and-project-pages/#project-pages-sites -->
##### Github Pages

Alternatively If you simply want to build the demo locally in the `build` folder then just
We use [github pages](https://pages.github.com/) to host the storybook and the [demo](https://help.github.com/articles/user-organization-and-project-pages/#project-pages-sites) of the component.
Make sure to add your changes to git, and push to `origin master` to ensure the code in `master` is reflective of what's online on `Github Pages`.
When you are ready, re-publish the Storybook by running:

```
npm run build:storybook
```

you can then run this command to serve the static site locally

```
npm run build:storybook:serve
```sh
npm run deploy:ghpages
```

## Tests

<!-- _How to carry out tests_ -->

Test coverage using [`jest`](https://jestjs.io/), to run tests
We are using [`jest`](https://jestjs.io/) for the testing framework.
To run tests, run:

```sh
npm run test
```

During development you can use
For convenience, during development you can use:

```sh
npm run test:watch
```

## Travis CI
and watch the test be re-run at every save.

On commit this repo uses the [.travis.yml](./.travis.yml) config tu run the automated test on [travis CI](https://travis-ci.org/bbc/react-transcript-editor).
## Travis CI

## Deployment
On commit this repo uses the [.travis.yml](./.travis.yml) config to run the automated test on [travis CI](https://travis-ci.org/bbc/react-transcript-editor).

<!-- _How to deploy the code/app into test/staging/production_ -->
## Publish to NPM

To push to [npm - `@bbc/react-transcript-editor`](https://www.npmjs.com/package/@bbc/react-transcript-editor)
To publish to [npm - `@bbc/react-transcript-editor`](https://www.npmjs.com/package/@bbc/react-transcript-editor) run:

```
```sh
npm publish:public
```

This runs `npm run build:component` and `npm publish --access public` under the hood
This runs `npm run build:component` and `npm publish --access public` under the hood, building the component and publishing to NPM.

> Note that only `README.md` and the `dist` folders are published to npm.
Expand Down
Loading

0 comments on commit fa6d651

Please sign in to comment.