{"id":13523459,"url":"https://github.com/brendan-duncan/webgpu_recorder","last_synced_at":"2025-04-11T20:41:32.177Z","repository":{"id":66114975,"uuid":"417599509","full_name":"brendan-duncan/webgpu_recorder","owner":"brendan-duncan","description":"WebGPU debugging tool for recording and playing back of WebGPU commands.","archived":false,"fork":false,"pushed_at":"2024-05-13T04:37:44.000Z","size":804,"stargazers_count":57,"open_issues_count":0,"forks_count":3,"subscribers_count":7,"default_branch":"main","last_synced_at":"2024-05-13T05:27:22.349Z","etag":null,"topics":["javascript","webgpu"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/brendan-duncan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"brendan-duncan"}},"created_at":"2021-10-15T18:32:37.000Z","updated_at":"2024-05-13T05:27:24.926Z","dependencies_parsed_at":"2024-05-13T05:27:24.236Z","dependency_job_id":"cc5c2bda-d81a-425f-be91-cffd8780f280","html_url":"https://github.com/brendan-duncan/webgpu_recorder","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendan-duncan%2Fwebgpu_recorder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendan-duncan%2Fwebgpu_recorder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendan-duncan%2Fwebgpu_recorder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brendan-duncan%2Fwebgpu_recorder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brendan-duncan","download_url":"https://codeload.github.com/brendan-duncan/webgpu_recorder/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248478745,"owners_count":21110754,"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":["javascript","webgpu"],"created_at":"2024-08-01T06:01:00.256Z","updated_at":"2025-04-11T20:41:32.148Z","avatar_url":"https://github.com/brendan-duncan.png","language":"JavaScript","funding_links":["https://github.com/sponsors/brendan-duncan"],"categories":["JavaScript","Debuggers and Profilers"],"sub_categories":["Safari"],"readme":"# WebGPU Recorder\r\n\r\n**Note** The WebGPU Recorder tool is incorperated into my general WebGPU debugging tool, [WebGPU Inspector](https://github.com/brendan-duncan/webgpu_inspector).\r\n\r\n---\r\n\r\nWebGPU Recorder is a debugging tool for WebGPU.\r\n\r\nIt is a playback recorder, designed to capture all WebGPU commands and data, with the ability to play back the commands to recreate the render.\r\n\r\nIt captures all WebGPU commands, buffers, and textures, over a given number of frames. It will then generate an HTML file containing javascript with all of the WebGPU commands recorded. This generated HTML file can be opened in the browser to play back the recording.\r\n\r\nThis can be used to diagnose issues with WebGPU rendering by eliminating everything but the raw WebGPU commands. This is also very helpful for submitting self-contained reproduction examples for bug reports.\r\n\r\n## Usage\r\n\r\n### Loading and Starting the WebGPU Recorder\r\n\r\nThe WebGPU Recorder script is an ES6 module and can be loaded via\r\n\r\n```html\r\n\u003cscript id=\"webgpu_recorder\" type=\"module\"\u003e\r\n    import {WebGPURecorder} from \"webgpu_recorder.js\";\r\n    new WebGPURecorder(); // Create and start the WebGPU Recorder\r\n\u003c/script\u003e\r\n````\r\n\r\n### From NPM\r\n\r\nwebgpu_recorder can be loaded via NPM\r\n\r\n```\r\nnpm install webgpu_recorder\r\n```\r\n\r\nThen you can import the module from\r\n```javascript\r\nimport {WebGPURecorder} from \"webgpu_recorder/webgpu_recorder.js\";\r\nnew WebGPURecorder(); // Create and start the WebGPU Recorder\r\n```\r\n\r\n### From CDN\r\n\r\nThe webgpu_recorder.js script can be loaded from a CDN so you don't have to store it locally and make sure you're always using the latest version of the recorder.\r\n\r\n```html\r\n\u003cscript id=\"webgpu_recorder\" type=\"module\"\u003e\r\n    import {WebGPURecorder} from \"https://cdn.jsdelivr.net/gh/brendan-duncan/webgpu_recorder/webgpu_recorder.js\";\r\n    new WebGPURecorder(); // Create and start the WebGPU Recorder\r\n\u003c/script\u003e\r\n````\r\n\r\n### Starting The Recorder\r\n\r\nThe **WebGPURecorder** class will start the recorder with the options provided to the constructor.\r\n\r\nBecause the recorder needs to record all commands and data, it starts recording as soon as it is constructed, and will continue recording for the maximum number of frames. **The recorder should be created before any rendering code starts so it has a chance to wrap WebGPU.**\r\n\r\nThe recording will download automatically as an HTML file with embedded Javascript after the maximum number of frames have been recorded or when `generateOutput` is called (see [example](test/test3.html)).\r\n\r\nYou can optionally configure the recorder\r\n\r\n```javascript\r\nnew WebGPURecorder({\r\n    \"frames\": 100,\r\n    \"export\": \"WebGPURecord\",\r\n    \"removeUnusedResources\": false,\r\n    \"download\": true\r\n});\r\n```\r\n\r\nWhere\r\n\r\n* **frames**: the maximum number of frames to record.\r\n* **export**: the name of the generated HTML file, as ${export}.html\r\n* **removeUnusedResources**: if true, resource commands not needed for rendering are removed, otherwise all commands are recorded.\r\n* **download**: if true, the html will be downloaded.\r\n\r\n## Recording From a Web Worker\r\n\r\nRecording from a web worker rendering to an offscreen canvas requires a little more work, due to restrictions of web workers.\r\n\r\nWhen WebGPURecorder is run from a worker thread, instead of downloading the generated html, it will post a message back to the main thread with the data. The main thread can listen to the worker messages, and when it recieves the \"webgpu_record_data\" message, it can call the \"webgpu_recorder_download_data\" function to trigger the browser to download the generated html file.\r\n\r\n#### Worker.html\r\n\r\n```html\r\n\u003cscript type=\"module\"\u003e\r\n    import { webgpu_recorder_download_data } from \"webgpu_recorder.js\";\r\n    const worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });\r\n    worker.addEventListener('message', (ev) =\u003e {\r\n        switch (ev.data.type) {\r\n            case \"webgpu_record_data\":\r\n                webgpu_recorder_download_data(ev.data.data, ev.data.filename);\r\n                break;\r\n        }\r\n    });\r\n    // ...\r\n\u003c/script\u003e\r\n```\r\n\r\n#### Worker.js\r\n\r\n```html\r\nimport {WebGPURecorder} from \"webgpu_recorder.js\";\r\nasync function run(canvas) {\r\n    new WebGPURecorder({\r\n        \"frames\": 10,\r\n        \"export\": \"WebGPURecord\"});\r\n    // ...\r\n}\r\n```\r\n\r\n## Play The Recording\r\n\r\nThe recording is a self-contained HTML file so you don't need a local server to view it.\r\n\r\nOpen the downloaded HTML file in a WebGPU capable browser to play back the recording.\r\n\r\n***\r\n*A recording from a WebGPU game:*\r\n\r\n![Recording Screenshot](test/test2.png)\r\n![Recording Code](test/test2_code.png)\r\n\r\n***\r\n\r\n### Notes\r\n\r\nIt is necessary to start the recorder prior to rendering so that all WebGPU objects are correctly recorded.\r\n\r\nIt is best suited for small tests, as the recorded data can get quite large.\r\n\r\nAll buffer and texture data is stored in the recording. The recording stores the data in base64 format to reduce file size, but it can still make the recording files large.\r\n\r\nExternal textures in WebGPU can't be captured. _copyExternalImageToTexture_ will get converted to _writeTexture_ in the recording, with the external image data getting converted to raw data.\r\n\r\nExternal video textures can't currently be recorded.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrendan-duncan%2Fwebgpu_recorder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrendan-duncan%2Fwebgpu_recorder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrendan-duncan%2Fwebgpu_recorder/lists"}