{"id":22227496,"url":"https://github.com/Furison-Tech/editorjs-audio","last_synced_at":"2025-07-27T19:31:04.820Z","repository":{"id":260320801,"uuid":"879983252","full_name":"Furison-Tech/editorjs-audio","owner":"Furison-Tech","description":"An EditorJS tool to upload audio files and use them as a HTML audio element in your EditorJS posts. This is mostly a copy of EditorJS's own image tool, rewritten to work with audio files.","archived":false,"fork":false,"pushed_at":"2024-10-30T19:39:59.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2024-12-01T06:37:22.902Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Furison-Tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2024-10-28T22:42:48.000Z","updated_at":"2024-10-30T19:40:02.000Z","dependencies_parsed_at":"2024-10-30T18:19:51.699Z","dependency_job_id":"9f1e7bd7-8e3f-4c2b-b68a-2b76cbedfaf5","html_url":"https://github.com/Furison-Tech/editorjs-audio","commit_stats":null,"previous_names":["furison-tech/editorjs-audio"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Furison-Tech%2Feditorjs-audio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Furison-Tech%2Feditorjs-audio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Furison-Tech%2Feditorjs-audio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Furison-Tech%2Feditorjs-audio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Furison-Tech","download_url":"https://codeload.github.com/Furison-Tech/editorjs-audio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227830384,"owners_count":17826031,"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":[],"created_at":"2024-12-03T01:01:44.044Z","updated_at":"2024-12-03T01:05:30.603Z","avatar_url":"https://github.com/Furison-Tech.png","language":"TypeScript","funding_links":[],"categories":["Tools"],"sub_categories":["Block Tools"],"readme":"![](https://badgen.net/badge/Editor.js/v2.0/blue)\n\n# Audio Tool\n\nAudio Block for the [Editor.js](https://editorjs.io).\n\n\u003e [!NOTE]  \n\u003e This tool is basically a copy of the [editor-js/image](https://github.com/editor-js/image) tool, rewritten to work with audio files, producing a HTML audio element.\n\n## Features\n\n- Uploading file from the device\n- Pasting copied content from the web\n- Pasting audios by drag-n-drop\n- Pasting files from Clipboard\n- Allows configuring if an audio file can be downloaded\n\n**Notes**\n\nThis Tool requires server-side implementation for the file uploading. See [backend response format](#server-format) for more details.\n\n\n## Installation\n\nGet the package\n\n```shell\nyarn add @furison-tech/editorjs-audio\n```\n\nInclude module at your application\n\n```javascript\nimport AudioTool from '@furison-tech/editorjs-audio';\n```\n\n## Usage\n\nAdd a new Tool to the `tools` property of the Editor.js initial config.\n\n```javascript\nimport AudioTool from '@furison-tech/editorjs-audio';\n\n// or if you inject AudioTool via standalone script\nconst AudioTool = window.AudioTool;\n\nvar editor = EditorJS({\n  ...\n\n  tools: {\n    ...\n    audio: {\n      class: AudioTool,\n      config: {\n        endpoints: {\n          byFile: 'http://localhost:8008/uploadFile', // Your backend file uploader endpoint\n          byUrl: 'http://localhost:8008/fetchUrl', // Your endpoint that provides uploading by Url\n        }\n      }\n    }\n  }\n\n  ...\n});\n```\n\n## Config Params\n\nAudio Tool supports these configuration parameters:\n\n| Field | Type     | Description        |\n| ----- | -------- | ------------------ |\n| endpoints | `{byFile: string, byUrl: string}` | Endpoints for file uploading. \u003cbr\u003e Contains 2 fields: \u003cbr\u003e __byFile__ - for file uploading \u003cbr\u003e __byUrl__ - for uploading by URL |\n| field | `string` | (default: `audio`) Name of uploaded audio field in POST request |\n| types | `string` | (default: `audio/*`) Mime-types of files that can be [accepted with file selection](https://github.com/codex-team/ajax#accept-string).|\n| additionalRequestData | `object` | Object with any data you want to send with uploading requests |\n| additionalRequestHeaders | `object` | Object with any custom headers which will be added to request. [See example](https://github.com/codex-team/ajax/blob/e5bc2a2391a18574c88b7ecd6508c29974c3e27f/README.md#headers-object) |\n| buttonContent | `string` | Allows to override HTML content of «Select file» button |\n| uploader | `{{uploadByFile: function, uploadByUrl: function}}` | Optional custom uploading methods. See details below. |\n| actions | `array` | Array with custom actions to show in the tool's settings menu. See details below. |\n\nNote that if you don't implement your custom uploader methods, the `endpoints` param is required.\n\n## Tool's settings\n\nThere is 1 block tune for configuring if an audio file can be downloaded or not.\n\n\u003e [!IMPORTANT]  \n\u003e A html audio element is downloadable by default. \n\u003e The audio element the editor produces is NOT downloadable by default. \n\u003e But, the restriction of downloading is done via the [controlList](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/controlsList) attribute, which is not universally supported yet.\n\u003e Also note that this setting just determines if a download button should be shown or not on the audio element. \n\u003e A malicious visitor can always steal audio that is referenced in HTML.\n\nAdd extra setting-buttons by adding them to the `actions`-array in the configuration:\n```js\nactions: [\n    {\n        name: 'new_button',\n        icon: '\u003csvg\u003e...\u003c/svg\u003e',\n        title: 'New Button',\n        toggle: true,\n        action: (name) =\u003e {\n            alert(`${name} button clicked`);\n        }\n    }\n]\n```\n\n**_NOTE:_**  return value of `action` callback for settings whether action button should be toggled or not is *deprecated*. Consider using `toggle` option instead.\n\n## Output data\n\nThis Tool returns `data` with following format\n\n| Field       | Type      | Description                                                                               |\n|-------------| --------- |-------------------------------------------------------------------------------------------|\n| file        | `object`  | Uploaded file data. Any data got from backend uploader. Always contain the `url` property |\n| canDownload | `boolean` | Indicates if the audio is downloadable or not                                             |\n\n\n```json\n{\n    \"type\" : \"audio\",\n    \"data\" : {\n        \"file\": {\n            \"url\" : \"https://bangerly.com/community-content/samples/1-kick.mp3\"\n        },\n        \"canDownload\" : true\n    }\n}\n```\n\n## Backend response format \u003ca name=\"server-format\"\u003e\u003c/a\u003e\n\nThis Tool works by one of the following schemes:\n\n1. Uploading files from the device\n2. Uploading by URL (handle audio-like URL's pasting)\n3. Uploading by drag-n-drop file\n4. Uploading by pasting from Clipboard\n\n### Uploading files from device \u003ca name=\"from-device\"\u003e\u003c/a\u003e\n\nScenario:\n\n1. User select file from the device\n2. Tool sends it to **your** backend (on `config.endpoints.byFile` route)\n3. Your backend should save file and return file data with JSON at specified format.\n4. Audio tool shows saved audio and stores server answer\n\nSo, you can implement backend for file saving by your own way. It is a specific and trivial task depending on your\nenvironment and stack.\n\nThe tool executes the request as [`multipart/form-data`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST), with the key as the value of `field`  in configuration.\n\nThe response of your uploader **should**  cover the following format:\n\n```json5\n{\n    \"success\" : 1,\n    \"file\": {\n        \"url\" : \"https://www.tesla.com/tesla_theme/assets/img/_vehicle_redesign/roadster_and_semi/roadster/hero.jpg\",\n        // ... and any additional fields you want to store, such as width, height, color, extension, etc\n    }\n}\n```\n\n**success** - uploading status. 1 for successful, 0 for failed\n\n**file** - uploaded file data. **Must** contain an `url` field with full public path to the uploaded audio.\nAlso, can contain any additional fields you want to store. For example, width, height, id etc.\nAll additional fields will be saved at the `file` object of output data.\n\n### Uploading by pasted URL\n\nScenario:\n\n1. User pastes an URL of the audio file to the Editor\n2. Editor pass pasted string to the Audio Tool\n3. Tool sends it to **your** backend (on `config.endpoints.byUrl` route) via 'url' in request body\n4. Your backend should accept URL, **download and save the original file by passed URL** and return file data with JSON at specified format.\n5. Audio tool shows saved audio and stores server answer\n\nThe tool executes the request as `application/json` with the following request body:\n\n```json5\n{\n  \"url\": \"\u003cpasted URL from the user\u003e\",\n  \"additionalRequestData\": \"\u003cadditional request data from configuration\u003e\"\n}\n```\n\nResponse of your uploader should be at the same format as described at «[Uploading files from device](#from-device)» section\n\n\n### Uploading by drag-n-drop or from Clipboard\n\nYour backend will accept file as FormData object in field name, specified by `config.field` (by default, «`audio`»).\nYou should save it and return the same response format as described above.\n\n## Providing custom uploading methods\n\nAs mentioned at the Config Params section, you have an ability to provide own custom uploading methods.\nIt is a quite simple: implement `uploadByFile` and `uploadByUrl` methods and pass them via `uploader` config param.\nBoth methods must return a Promise that resolves with response in a format that described at the [backend response format](#server-format) section.\n\n\n| Method         | Arguments | Return value | Description |\n| -------------- | --------- | -------------| ------------|\n| uploadByFile   | `File`    | `{Promise.\u003c{success, file: {url}}\u003e}` | Upload file to the server and return an uploaded audio data |\n| uploadByUrl    | `string`  | `{Promise.\u003c{success, file: {url}}\u003e}` | Send URL-string to the server, that should load audio by this URL and return an uploaded audio data |\n\nExample:\n\n```js\nimport AudioTool from '@editorjs/audio';\n\nvar editor = EditorJS({\n  ...\n\n  tools: {\n    ...\n    audio: {\n      class: AudioTool,\n      config: {\n        /**\n         * Custom uploader\n         */\n        uploader: {\n          /**\n           * Upload file to the server and return an uploaded audio data\n           * @param {File} file - file selected from the device or pasted by drag-n-drop\n           * @return {Promise.\u003c{success, file: {url}}\u003e}\n           */\n          uploadByFile(file){\n            // your own uploading logic here\n            return MyAjax.upload(file).then(() =\u003e {\n              return {\n                success: 1,\n                file: {\n                  url: 'https://bangery.com/community-content/samples/1-kick.mp3',\n                  // any other audio data you want to store, such as width, height, color, extension, etc\n                }\n              };\n            });\n          },\n\n          /**\n           * Send URL-string to the server. Backend should load audio by this URL and return an uploaded audio data\n           * @param {string} url - pasted audio URL\n           * @return {Promise.\u003c{success, file: {url}}\u003e}\n           */\n          uploadByUrl(url){\n            // your ajax request for uploading\n            return MyAjax.upload(file).then(() =\u003e {\n              return {\n                success: 1,\n                file: {\n                  url: 'https://bangery.com/community-content/samples/1-kick.mp3',\n                  // any other audio data you want to store, such as width, height, color, extension, etc\n                }\n              }\n            })\n          }\n        }\n      }\n    }\n  }\n\n  ...\n});\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFurison-Tech%2Feditorjs-audio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFurison-Tech%2Feditorjs-audio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFurison-Tech%2Feditorjs-audio/lists"}