1 | # React Transcript Editor
|
2 |
|
3 | A React component to make transcribing audio and video easier and faster.
|
4 |
|
5 | <p>
|
6 | <a href="https://unpkg.com/react-transcript-editor@1.3.1-alpha.4/TranscriptEditor.js">
|
7 | <img src="http://img.badgesize.io/https://unpkg.com/react-transcript-editor@1.3.1-alpha.4/index.js?compression=gzip&label=size">
|
8 | </a>
|
9 | <a href="https://packagephobia.now.sh/result?p=@bbc/react-transcript-editor">
|
10 | <img src="https://badgen.net/packagephobia/install/@bbc/react-transcript-editor">
|
11 | </a>
|
12 | <a href="./package.json">
|
13 | <img src="https://img.shields.io/npm/v/@bbc/react-transcript-editor.svg?maxAge=3600&label=version&colorB=007ec6">
|
14 | </a>
|
15 | </p>
|
16 | <br/>
|
17 | The project uses [this github project boards to organise and the co-ordinate development](https://github.com/bbc/react-transcript-editor/projects).
|
18 | _--> Work in progress <--_
|
19 |
|
20 |
|
21 |
|
22 | - [You can see a demo by clicking here](https://bbc.github.io/react-transcript-editor/iframe.html?id=demo--default) (and then click the `load demo` button)
|
23 | - [And you can see a list of features here](./docs/features-list.md).
|
24 |
|
25 | ## Development env
|
26 |
|
27 |
|
28 |
|
29 | - npm > `6.1.0`
|
30 | - [Node 10 - dubnium](https://scotch.io/tutorials/whats-new-in-node-10-dubnium)
|
31 |
|
32 | Node version is set in node version manager [`.nvmrc`](https://github.com/creationix/nvm#nvmrc)
|
33 |
|
34 | ## Setup
|
35 |
|
36 | 1. Fork this repository
|
37 | 2. Clone this repository to a directory of your choice
|
38 | 3. Run `npm i` to install dependencies
|
39 |
|
40 | ## Usage - development
|
41 |
|
42 | We use a tool called [`storybook`](https://storybook.js.org)
|
43 | to run the components locally. To start the Storybook, run:
|
44 |
|
45 | ```sh
|
46 | npm start
|
47 | ```
|
48 |
|
49 | Running that command should open the locally hosted Storybook, but if it doesn't,
|
50 | visit [http://localhost:6006](http://localhost:6006)
|
51 |
|
52 | ## Usage - production
|
53 |
|
54 | In order to use a published version of `react-transcript-editor`,
|
55 | install the published module [`@bbc/react-transcript-editor`](https://www.npmjs.com/package/@bbc/react-transcript-editor)
|
56 | by running:
|
57 |
|
58 | ```sh
|
59 | npm install @bbc/react-transcript-editor
|
60 | ```
|
61 |
|
62 | ```js
|
63 | import TranscriptEditor from "@bbc/react-transcript-editor";
|
64 | ```
|
65 |
|
66 | ### Basic use case
|
67 |
|
68 | ```js
|
69 | <TranscriptEditor
|
70 | transcriptData={someJsonFile}
|
71 | mediaUrl={"https://download.ted.com/talks/KateDarling_2018S-950k.mp4"}
|
72 | />
|
73 | ```
|
74 |
|
75 | `transcriptData` and `mediaUrl` are non-optional props to use `TranscriptEditor`.
|
76 | See the full list of options [here](#transcripteditor-props-list).
|
77 |
|
78 | ### Advanced use case
|
79 |
|
80 | ```js
|
81 | <TranscriptEditor
|
82 | transcriptData={someJsonFile}
|
83 | mediaUrl={"https://download.ted.com/talks/KateDarling_2018S-950k.mp4"}
|
84 | handleAutoSaveChanges={this.handleAutoSaveChanges}
|
85 | autoSaveContentType={"digitalpaperedit"}
|
86 | isEditable={true}
|
87 | spellCheck={false}
|
88 | sttJsonType={"bbckaldi"}
|
89 | handleAnalyticsEvents={this.handleAnalyticsEvents}
|
90 | fileName={"ted-talk.mp4"}
|
91 | title={"Ted Talk"}
|
92 | ref={this.transcriptEditorRef}
|
93 | mediaType={"video"}
|
94 | />
|
95 | ```
|
96 |
|
97 | ### TranscriptEditor Props List
|
98 |
|
99 | | Props | Description | required | type | default |
|
100 | | :---------------------- | :---------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------: | :-------: | :----------------------------------------------------------------------------: |
|
101 | | `transcriptData` | Transcript JSON | yes | JSON | |
|
102 | | `mediaUrl` | URL to media (audio or video) file | yes | String | |
|
103 | | `handleAutoSaveChanges` | Function to handle the content of transcription after a change | no | Function |
|
104 | | `autoSaveContentType` | Specify the file format for data returned by `handleAutoSaveChanges` | no | String | falls back to `sttJsonType`, if set, or `draftjs` |
|
105 | | `isEditable` | Set to `true` to have the ability to edit the text | no | Boolean | False |
|
106 | | `spellCheck` | Set to `true` to spell-check the transcript | no | Boolean | False |
|
107 | | `sttJsonType` | The data model type of your `transcriptData` | no | String | `draftjs` |
|
108 | | `handleAnalyticsEvents` | if you want to collect analytics events. | no | Function | false |
|
109 | | `fileName` | used for saving and retrieving local storage blob files | no, but disables the [local save feature](#local-save) | String |
|
110 | | `title` | defaults to empty string | no | String |
|
111 | | `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 |
|
112 | | `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 |
|
113 |
|
114 | See [`./demo/app.js` demo](./demo/app.js) as a more detailed example usage of the component.
|
115 |
|
116 | #### Local save
|
117 |
|
118 | `fileName` is optional but it's needed if working with user uploaded local media in the browser,
|
119 | to be able to save and retrieve from local storage.
|
120 | 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)\_
|
121 |
|
122 | ### Typescript projects
|
123 |
|
124 | If using in a parent project where [typescript](https://www.typescriptlang.org/) is being used you might need to add `//@ts-ignore` before the import statment like this
|
125 |
|
126 | ```js
|
127 | //@ts-ignore
|
128 | import { TranscriptEditor } from "@bbc/react-transcript-editor";
|
129 | ```
|
130 |
|
131 | #### Internal components
|
132 |
|
133 | ##### Direct imports
|
134 |
|
135 | You can also import some of the underlying React components directly.
|
136 | See [the storybook](https://bbc.github.io/react-transcript-editor) for each component details on optional and required attributes.
|
137 |
|
138 | - `TranscriptEditor`
|
139 | - `TimedTextEditor`
|
140 | - `MediaPlayer`
|
141 | - `VideoPlayer`
|
142 | - `Settings`
|
143 | - `KeyboardShortcuts`
|
144 | - `ProgressBar`
|
145 | - `PlaybackRate`
|
146 | - `PlayerControls`
|
147 | - `RollBack`
|
148 | - `Select`
|
149 |
|
150 | To import the components you can do as follows
|
151 |
|
152 | ```js
|
153 | import TimedTextEditor from "@bbc/react-transcript-editor/TimedTextEditor";
|
154 | ```
|
155 |
|
156 | ```js
|
157 | import { TimedTextEditor } from "@bbc/react-transcript-editor";
|
158 | ```
|
159 |
|
160 | ##### Import recommendation
|
161 |
|
162 | 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.
|
163 | 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)
|
164 |
|
165 | #### Other Node Modules (non-react)
|
166 |
|
167 | Some of these node modules can be used as standalone imports.
|
168 |
|
169 | ##### Export Adapter
|
170 |
|
171 | Converts from draftJs json format to other formats
|
172 |
|
173 | ```js
|
174 | import exportAdapter from "@bbc/react-transcript-editor/exportAdapter";
|
175 | ```
|
176 |
|
177 | ##### STT JSON Adapter
|
178 |
|
179 | Converts various stt json formats to draftJs
|
180 |
|
181 | ```js
|
182 | import sttJsonAdapter from "@bbc/react-transcript-editor/sttJsonAdapter";
|
183 | ```
|
184 |
|
185 | ##### Conversion modules to/from Timecodes
|
186 |
|
187 | Some modules to convert to and from timecodes
|
188 |
|
189 | ```js
|
190 | import {
|
191 | secondsToTimecode,
|
192 | timecodeToSeconds,
|
193 | shortTimecode,
|
194 | } from "@bbc/react-transcript-editor/timecodeConverter";
|
195 | ```
|
196 |
|
197 | ## System Architecture
|
198 |
|
199 | - 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.
|
200 | - This uses [CSS Modules](https://github.com/css-modules/css-modules) to contain the scope of the css for this component.
|
201 | - [`.storybook/webpack.config.js](./.storybook/webpack.config.js) enables the storybook webpack config to add support for css modules.
|
202 | - The parts of the component are inside [`./packages`](./packages)
|
203 | - [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).
|
204 |
|
205 | ## Documentation
|
206 |
|
207 | There's a [docs](./docs) folder in this repository, which contains subdirectories to keep:
|
208 |
|
209 | - [notes](./docs/notes): dev notes on various aspects of the project.
|
210 | - [adr](./docs/adr): [Architecture Decision Record](https://github.com/joelparkerhenderson/architecture_decision_record).
|
211 |
|
212 | ### ADR
|
213 |
|
214 | > An architectural decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
|
215 |
|
216 | We are using [this template for ADR](https://gist.github.com/iaincollins/92923cc2c309c2751aea6f1b34b31d95)
|
217 |
|
218 | ### QA
|
219 |
|
220 | [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).
|
221 |
|
222 | ## Build
|
223 |
|
224 | > To transpile `./packages` and create a build in the `./dist` folder, run:
|
225 |
|
226 | ```sh
|
227 | npm run build:component
|
228 | ```
|
229 |
|
230 | To understand the build process, have a read through [this](./docs/guides/storybook-npm-setup.md).
|
231 |
|
232 | ## Demo & storybook
|
233 |
|
234 | - **Storybook** can be viewed at [https://bbc.github.io/react-transcript-editor/](https://bbc.github.io/react-transcript-editor/)
|
235 | - **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)
|
236 |
|
237 | To run locally, see [setup](#usage---development).
|
238 |
|
239 | ### Build - storybook
|
240 |
|
241 | To build the storybook as a static site, run:
|
242 |
|
243 | ```sh
|
244 | npm run build:storybook
|
245 | ```
|
246 |
|
247 | This will produce a `build` folder containing the static site of the demo.
|
248 | To serve the `build` folder locally, run:
|
249 |
|
250 | ```sh
|
251 | npm run build:storybook:serve
|
252 | ```
|
253 |
|
254 | #### Publishing to a web page
|
255 |
|
256 | ##### Github Pages
|
257 |
|
258 | 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.
|
259 | 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`.
|
260 | When you are ready, re-publish the Storybook by running:
|
261 |
|
262 | ```sh
|
263 | npm run deploy:ghpages
|
264 | ```
|
265 |
|
266 | ## Tests
|
267 |
|
268 | We are using [`jest`](https://jestjs.io/) for the testing framework.
|
269 | To run tests, run:
|
270 |
|
271 | ```sh
|
272 | npm run test
|
273 | ```
|
274 |
|
275 | For convenience, during development you can use:
|
276 |
|
277 | ```sh
|
278 | npm run test:watch
|
279 | ```
|
280 |
|
281 | and watch the test be re-run at every save.
|
282 |
|
283 | ## Travis CI
|
284 |
|
285 | 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).
|
286 |
|
287 | ## Publish to NPM
|
288 |
|
289 | To publish to [npm - `@bbc/react-transcript-editor`](https://www.npmjs.com/package/@bbc/react-transcript-editor) run:
|
290 |
|
291 | ```sh
|
292 | npm publish:public
|
293 | ```
|
294 |
|
295 | This runs `npm run build:component` and `npm publish --access public` under the hood, building the component and publishing to NPM.
|
296 |
|
297 | > Note that only `README.md` and the `dist` folders are published to npm.
|
298 |
|
299 | ## Contributing
|
300 |
|
301 | See [CONTRIBUTING.md](./CONTRIBUTING.md) guidelines and [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) guidelines.
|
302 |
|
303 | ## Licence
|
304 |
|
305 |
|
306 |
|
307 | See [LICENCE](./LICENCE.md)
|
308 |
|
309 | ## Legal Disclaimer
|
310 |
|
311 | _Despite using React and DraftJs, the BBC is not promoting any Facebook products or other commercial interest._
|