{"id":14156672,"url":"https://github.com/kbumsik/opus-media-recorder","last_synced_at":"2025-04-06T06:13:21.225Z","repository":{"id":33899933,"uuid":"151457668","full_name":"kbumsik/opus-media-recorder","owner":"kbumsik","description":"MediaRecorder polyfill for Opus recording using WebAssembly","archived":false,"fork":false,"pushed_at":"2024-04-20T20:32:52.000Z","size":2329,"stargazers_count":319,"open_issues_count":44,"forks_count":39,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-10-13T01:11:48.525Z","etag":null,"topics":["emscripten","mediarecorder","mediarecorder-api","ogg","opus","opus-recording","recording","webassembly","webm"],"latest_commit_sha":null,"homepage":"http://kbumsik.io/opus-media-recorder/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kbumsik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-03T18:05:56.000Z","updated_at":"2024-10-06T18:34:24.000Z","dependencies_parsed_at":"2024-10-26T00:28:37.614Z","dependency_job_id":null,"html_url":"https://github.com/kbumsik/opus-media-recorder","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbumsik%2Fopus-media-recorder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbumsik%2Fopus-media-recorder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbumsik%2Fopus-media-recorder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kbumsik%2Fopus-media-recorder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kbumsik","download_url":"https://codeload.github.com/kbumsik/opus-media-recorder/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441059,"owners_count":20939239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emscripten","mediarecorder","mediarecorder-api","ogg","opus","opus-recording","recording","webassembly","webm"],"created_at":"2024-08-17T08:07:53.113Z","updated_at":"2025-04-06T06:13:21.206Z","avatar_url":"https://github.com/kbumsik.png","language":"JavaScript","funding_links":[],"categories":["webassembly"],"sub_categories":[],"readme":"# opus-media-recorder\n\n* [Try it!](https://kbumsik.io/opus-media-recorder/)\n* [JS Fiddle example](https://jsfiddle.net/kbumsik/v3wpnxao/)\n\n`opus-media-recorder` is a [MediaRecorder API](https://w3c.github.io/mediacapture-record/#mediarecorder-api) polyfill written in ES6 and WebAssembly. It aims for cross-browser Opus codec support with various audio formats such as Ogg and WebM. `opus-media-recorder` can be used as a polyfill, or it can replace the built-in MediaRecorder since `opus-media-recorder` supports more MIME types.\n\n`opus-media-recorder` uses WebAssembly compiled from popular libraries (e.g libopus, libogg, libwebm, and speexdsp) to ensure good performance and standards-compliance.\n\n- [Why opus-media-recorder?](#why-opus-media-recorder)\n- [How to use](#how-to-use)\n  - [Thing to know](#thing-to-know)\n  - [JavaScript](#javascript)\n    - [Examples](#examples)\n    - [Installation](#installation)\n    - [Working with a bundler](#working-with-a-bundler)\n    - [Simple JavaScript example (webpack)](#simple-javascript-example-webpack)\n  - [HTML `\u003cscript\u003e` tag](#html-script-tag)\n  - [Use opus-media-recorder only when a browser doesn't support it](#use-opus-media-recorder-only-when-a-browser-doesnt-support-it)\n- [Browser support](#browser-support)\n- [MIME Type support](#mime-type-support)\n- [Limitations](#limitations)\n- [How to build](#how-to-build)\n- [Changelog](#changelog)\n\n## Why opus-media-recorder?\n\n|              | opus-media-recorder | Chrome | Firefox | iOS | Edge |\n|--------------|:-------------------:|:------:|:-------:|:---:|:----:|\n| `audio/ogg`  |          O          |    X   |    O    |  X  |   X  |\n| `audio/webm` |          O          |    O   |    X    |  X  |   X  |\n| `audio/wav`  |          O          |    X   |    X    |  X  |   X  |\n\n\\* Both `audio/ogg` and `audio/webm` refer containers for Opus audio codec.\n\nCurrently the MediaRecorder API suffers from the two problems:\n\n1. Not all browsers support MediaRecorder.\n2. Even the browsers that provides MediaRecorder don't support the same format.\n\n`opus-media-recorder` tackles these problems by supporting all major modern browsers (Chrome, Firefox, iOS, and Edge) and by providing various formats.\n\nBy taking advantages of WebAssembly and Web Workers, `opus-media-recorder` tries to have minimum performace penalties of running encoders in a browser.\n\n## How to use\n\nopus-media-recorder is compatible with the [Mediastream Recording API](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder) standard.\n\n### Thing to know\n\n* The page must be served over HTTPS in order to record.\n* Being able to record does *not always* mean you can play it in a browser:\n  * macOS/iOS Safari cannot play Opus natively yet.\n  * Old Edge requires [an extension](https://wpdev.uservoice.com/forums/257854-microsoft-edge-developer/suggestions/6513488-ogg-vorbis-and-opus-audio-formats-support-firefox) to play Opus natively.\n  * You can get an Opus decorder to play it. There are Opus decoders available, such as [Chris Rudmin's Opus decoder](https://github.com/chris-rudmin/opus-recorder).\n  * Otherwise, users can download as a recording file and play it using apps like [VLC](https://www.videolan.org/vlc/index.html).\n* When `mimeType` is not specified a default encoder is loaded depending on OS:\n  * Chrome: `audio/webm`\n  * Firefox: `audio/ogg`\n  * Edge: `audio/webm`\n  * iOS/macOS Safari: `audio/wave` - because they cannot play Opus at all.\n\n### JavaScript\n\nFor standard usages of `MediaRecorder`, see the [MDN reference](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder) and other online resources. Our [testing website](docs) and [example section](example) may be useful as well.\n\n#### Examples\n\n* [Webpack](example/webpack)\n* [create-react-app](example/create-react-app)\n* [Rollup](example/rollup)\n* [Browserify](example/browserify)\n\n#### Installation\n\n```bash\nnpm install --save-dev opus-media-recorder\n```\n\n#### Working with a bundler\n\nBecause `opus-media-recorder` needs to load a dedicated web worker and `.wasm` binaries, special configurations are necessary. In general:\n\n```javascript\nimport OpusMediaRecorder from 'opus-media-recorder';\n// Choose desired format like audio/webm. Default is audio/ogg\nconst options = { mimeType: 'audio/ogg' }\n// Web worker and .wasm configuration. Note: This is NOT a part of W3C standard.\nconst workerOptions = {\n  encoderWorkerFactory: function () {\n    // UMD should be used if you don't use a web worker bundler for this.\n    return new Worker('.../path/to/opus-media-recorder/encoderWorker.umd.js')\n  },\n  OggOpusEncoderWasmPath: '.../path/to/opus-media-recorder/OggOpusEncoder.wasm',\n  WebMOpusEncoderWasmPath: '.../path/to/opus-media-recorder/WebMOpusEncoder.wasm'\n};\n\nwindow.MediaRecorder = OpusMediaRecorder;\nrecorder = new MediaRecorder(stream, options, workerOptions);\n```\n\n#### Simple JavaScript example (webpack)\n\n```javascript\nimport MediaRecorder from 'opus-media-recorder';\n// Use worker-loader\nimport EncoderWorker from 'worker-loader!opus-media-recorder/encoderWorker.js';\n// You should use file-loader in webpack.config.js.\n// See webpack example link in the above section for more detail.\nimport OggOpusWasm from 'opus-media-recorder/OggOpusEncoder.wasm';\nimport WebMOpusWasm from 'opus-media-recorder/WebMOpusEncoder.wasm';\n\n// Non-standard options\nconst workerOptions = {\n  encoderWorkerFactory: _ =\u003e new EncoderWorker(),\n  OggOpusEncoderWasmPath: OggOpusWasm,\n  WebMOpusEncoderWasmPath: WebMOpusWasm\n};\n\nlet recorder;\n\nfunction startRecording () {\n  navigator.mediaDevices.getUserMedia({ audio: true }).then(stream =\u003e {\n    let options = { mimeType: 'audio/ogg' };\n    // Start recording\n    recorder = new MediaRecorder(stream, options, workerOptions);\n    recorder.start();\n    // Set record to \u003caudio\u003e when recording will be finished\n    recorder.addEventListener('dataavailable', (e) =\u003e {\n      audioElement.src = URL.createObjectURL(e.data);\n    });\n  });\n}\n\n// Recording should be started in user-initiated event like buttons\nrecordButton.addEventListener('click', startRecording);\n\n// Stop recording\nstopButton.addEventListener('click', () =\u003e {\n  recorder.stop();\n  // Remove “recording” icon from browser tab\n  recorder.stream.getTracks().forEach(i =\u003e i.stop());\n})\n```\n\n### HTML `\u003cscript\u003e` tag\n\nThe `OpusMediaRecorder` object is available in the global namespace using [UMD](https://github.com/umdjs/umd).\n\n```html\n\u003c!-- load OpusMediaRecorder.umd.js. OpusMediaRecorder will be loaded. --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/opus-media-recorder@latest/OpusMediaRecorder.umd.js\"\u003e\u003c/script\u003e\n\u003c!-- load encoderWorker.umd.js. This should be after OpusMediaRecorder. --\u003e\n\u003c!-- This script tag will create OpusMediaRecorder.encoderWorker. --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/opus-media-recorder@latest/encoderWorker.umd.js\"\u003e\u003c/script\u003e\n\n\u003cscript\u003e\n...\n// If you already load encoderWorker.js using \u003cscript\u003e tag,\n// you don't need to define encoderWorkerFactory.\nconst workerOptions = {\n  OggOpusEncoderWasmPath: 'https://cdn.jsdelivr.net/npm/opus-media-recorder@latest/OggOpusEncoder.wasm',\n  WebMOpusEncoderWasmPath: 'https://cdn.jsdelivr.net/npm/opus-media-recorder@latest/WebMOpusEncoder.wasm'\n};\n\n// Replace MediaRecorder\nwindow.MediaRecorder = OpusMediaRecorder;\nlet recorder = new MediaRecorder(stream, {}, workerOptions);\n...\n\u003c/script\u003e\n```\n\n### Use opus-media-recorder only when a browser doesn't support it\n\n```javascript\n// Check if MediaRecorder available.\nif (!window.MediaRecorder) {\n  window.MediaRecorder = OpusMediaRecorder;\n}\n// Check if a target format (e.g. audio/ogg) is supported.\nelse if (!window.MediaRecorder.isTypeSupported('audio/ogg;codecs=opus')) {\n  window.MediaRecorder = OpusMediaRecorder;\n}\n```\n\n## Browser support\n\nSupported:\n\n* Chrome \u003e= 58\n* Firefox \u003e= 53\n* Microsoft Edge \u003e= 41\n* Safari (macOS and iOS) \u003e= 11\n\nBrowsers with issues:\n\n* iOS 11.2 only: Not working due to a regression in WebAssembly: https://bugs.webkit.org/show_bug.cgi?id=181781\n\n## MIME Type support\n\n* `audio/webm`\n* `audio/webm; codecs=opus`\n* `audio/ogg`\n* `audio/ogg; codecs=opus`\n* `audio/wav` or `audio/wave`\n\n## Limitations\n\n* Does not support Video recording.\n* `opus-media-recorder` throws generic Error objects instead of native DOMException.\n* Because `audio/wav` is not designed for streaming, when `mimeType` is `audio/wav`, each `dataavailabe` events produces a complete and separated `.wav` file that cannot be concatenated together unlike Ogg and WebM. Therefore, it is recommended not to use `timeslice` option when calling `start()`, unless you know what the implication is.\n* There is no [`SecurityError`](https://w3c.github.io/mediacapture-record/#exception-summary) case implemented. (WIP)\n\n## How to build\n\n1. To build from the source, you need [Emscripten](https://github.com/kripken/emscripten), [yarn](https://yarnpkg.com), Python 2.7 or higher, and basic C program build systems such as [GNU Make](https://www.gnu.org/software/make/).\n\n2. `yarn install` to install JavaScript dependencies.\n\n3. `yarn run build` to build. `yarn run build:production` to build files for distribution.\n\n4. `yarn run serve` to run a test web server locally. Default URL is `https://localhost:9000` (It has to be HTTPS). You might have to change `DEV_SERVER_URL` and `DEV_SERVER_PORT` to change the address of the local test server.\n\n5. `yarn run clean` to clean up build files.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkbumsik%2Fopus-media-recorder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkbumsik%2Fopus-media-recorder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkbumsik%2Fopus-media-recorder/lists"}