{"id":23823218,"url":"https://github.com/jdomizz/hydra-element","last_synced_at":"2025-09-07T05:32:25.806Z","repository":{"id":57269830,"uuid":"395438663","full_name":"jdomizz/hydra-element","owner":"jdomizz","description":"🍬 A custom element for wrapping the hydra-synth engine","archived":false,"fork":false,"pushed_at":"2024-04-07T10:00:59.000Z","size":294,"stargazers_count":15,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-01T22:51:50.832Z","etag":null,"topics":["creative-coding","custom-elements","glsl","hydra-synth","livecoding","web-components"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jdomizz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2021-08-12T20:39:57.000Z","updated_at":"2024-08-20T15:00:45.000Z","dependencies_parsed_at":"2023-12-12T22:39:06.189Z","dependency_job_id":"f1c86396-5314-44d0-8396-ff9bc15ef64b","html_url":"https://github.com/jdomizz/hydra-element","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdomizz%2Fhydra-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdomizz%2Fhydra-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdomizz%2Fhydra-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jdomizz%2Fhydra-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jdomizz","download_url":"https://codeload.github.com/jdomizz/hydra-element/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232140808,"owners_count":18478295,"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":["creative-coding","custom-elements","glsl","hydra-synth","livecoding","web-components"],"created_at":"2025-01-02T10:15:34.394Z","updated_at":"2025-01-02T10:15:35.209Z","avatar_url":"https://github.com/jdomizz.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🍬 \\\u003chydra-element\u003e\n\nA custom element for wrapping the [hydra-synth](https://github.com/hydra-synth/hydra-synth) engine.\n\n## Rationale\n\n[Hydra](https://hydra.ojack.xyz/) is a video synth and coding environment that runs in the browser. It stands out for its elegant DSL, modeled on a fluent interface.\n\nThis project aims to simplify the render of Hydra scripts in HTML documents embedding [hydra-synth](https://github.com/hydra-synth/hydra-synth) (Hydra's video synthesizer and shader compiler) in a [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components). \n\nBy default each `hydra-element` contains its own `hydra-synth` (with its own sources, functions and outputs). In this way, several elements can be used in the same HTML document without collisions.\n\n## Installation\n\nThis package is published in the [npm](https://www.npmjs.com/) registry as `hydra-element`. You can load it via CDN (the easiest way) or install it with a package manager.\n\n### CDN\n\nLoad the custom element via CDN adding the following script to your HTML file.\n\n```html\n\u003cscript type=\"module\" src=\"https://cdn.jsdelivr.net/npm/hydra-element\"\u003e\u003c/script\u003e\n```\n\n### Package\n\nInstall the package from [npm](https://docs.npmjs.com/cli/commands/npm) with the following command.\n\n```sh\nnpm install hydra-element\n```\n\nOnce you’ve done that, import the custom element in your JavaScript module.\n\n```js\nimport \"hydra-element\"\n```\n\n## Usage\n\nInclude your code between the element tags.\n\n```html\n\u003chydra-element\u003e\n  s0.initImage(\"https://upload.wikimedia.org/wikipedia/commons/2/25/Hydra-Foto.jpg\")\n\n  osc(30,0.01,1)\n    .mult(osc(() =\u003e (100 * Math.sin(time * 0.1)),-0.1,1).modulate(noise(3,1)).rotate(0.7))\n    .blend(src(s0))\n    .posterize([3,10,2].fast(0.5).smooth(1))\n    .modulateRotate(o0, () =\u003e mouse.x * 0.003)\n    .out()\n\u003c/hydra-element\u003e\n```\n\nIf you need to update the code, use the `code` property with JavaScript.\n\n```js\ndocument.querySelector('hydra-element').code = 'osc().out()'\n```\n\nFinally, use CSS to style the element.\n\n```css\nhydra-element {\n  width: 15rem;\n  height: 15rem;\n  color: white;\n}\n```\nYou can see and remix a live example [here](https://glitch.com/edit/#!/hydra-element).\n\n## Configuration\n\nBy default the embedded `hydra-synth` engine is created with these settings:\n\n```js\ncanvas: null,\nwidth: window.innerWidth,\nheight: window.innerHeight,\nautoLoop: true,\nmakeGlobal: false,\ndetectAudio: false,\nnumSources: 4,\nnumOutputs: 4,\nextendTransforms: [],\nprecision: null,\npb: null\n```\n\nYou can use the following attributes and properties to configure these options. Read the `hydra-synth` [API](https://github.com/hydra-synth/hydra-synth#api) documentation for more information.\n\n### Attributes `width` and `height`\n\nIn addition to the engine, the custom element also takes care of the canvas. By default it creates one the size of the window, which is useful for many cases. If this is not yours, you can use the `width` and `height` attributes to modify the canvas size. \n\n```html\n\u003chydra-element width=\"250\" height=\"250\"\u003e\u003c/hydra-element\u003e\n```\n\n### Property `canvas`\n\nIf you prefer to take care of the canvas yourself, use the `canvas` property to specify a canvas element to render on. In this case the component does not create any canvas but uses the assigned one.\n\n```js\ndocument.querySelector('hydra-element').canvas = yourCanvasElement\n```\n\n### Attribute `loop`\n\nIf you want to use your own render loop for triggering Hydra updates, set the `loop` attribute to `false`.\n\n```html\n\u003chydra-element loop=\"false\"\u003e\u003c/hydra-element\u003e\n```\n\nNote you will need to call the `tick` method, where `dt` is the time elapsed in milliseconds since the last update.\n\n```js\ndocument.querySelector('hydra-element').tick(dt)\n```\n\n### Attribute `global`\n\nIf you set the `global` attribute to `true` all sources, functions and outputs of the synthesizer will be stored in the `window` object, so they will be directly available. You should use this option if you need to extend the functionality of the synthesizer by loading extensions or external libraries with `loadScript`.\n\n```html\n\u003chydra-element global=\"true\"\u003e\n  await loadScript(\"https://cdn.statically.io/gl/metagrowing/extra-shaders-for-hydra/main/lib/lib-noise.js\")\n  \n  warp().out()\n\u003c/hydra-element\u003e\n```\n\n\u003e **Warning**\n\u003e You must not use more than one `hydra-element` with `global` set to `true` in the same HTML document.\n\n### Attribute `audio`\n\nHydra's audio capabilities are disabled by default because they require requesting microphone permissions and not all scripts use them, so don't forget to set the `audio` attribute to `true` if you use the `a` object in your script.\n\n```html\n\u003chydra-element audio=\"true\"\u003e\n  a.show()\n\n  osc(10, 0, () =\u003e a.fft[0]*4).out()\n\u003c/hydra-element\u003e\n```\n\n### Attribute `sources`\n\nYou can use the `sources` attribute to set the number of source buffers available for multimedia resources. The default value is `4`. Extra buffers are available via the `synth` object.\n\n```html\n\u003chydra-element sources=\"8\"\u003e\n  const { s6, s7 } = synth\n\n  s0.initCam()\n  s1.initScreen()\n  s6.initImage('https://upload.wikimedia.org/wikipedia/commons/2/25/Hydra-Foto.jpg')\n  s7.initVideo('https://media.giphy.com/media/AS9LIFttYzkc0/giphy.mp4')\n\n  src(s0)\n    .blend(src(s1))\n    .blend(src(s6))\n    .blend(src(s7))\n    .out()\n\u003c/hydra-element\u003e\n```\n\n### Attribute `outputs`\n\nYou can use the `outputs` attribute to set the number of output buffers to use. The default value is `4`. Extra buffers are available via the `synth` object.\n\n```html\n\u003chydra-element outputs=\"8\"\u003e\n  const { o7 } = synth\n\n  osc().out(o7)\n\n  render(o7)\n\u003c/hydra-element\u003e\n```\n\n\u003e **Warning**\n\u003e Note that `hydra-synth` itself has only been tested with `4` outputs, so use this attribute with caution.\n\n### Attribute `precision`\n\nYou can use the `precision` attribute to force precision of shaders. By default no precision is specified, so the engine will use `highp` for iOS and `mediump` for everything else. Avaiblable options are `highp`, `mediump` and `lowp`.\n\n```html\n\u003chydra-element precision=\"highp\"\u003e\u003c/hydra-element\u003e\n```\n\n### Property `transforms`\n\nYou can add custom GLSL functions setting the `transforms` property with JavaScript.\n\n```js\ndocument.querySelector('hydra-element').transforms = [{\n  name: 'yourNoise',\n  type: 'src',\n  inputs: [\n    { type: 'float', name: 'scale', default: 5 },\n    { type: 'float', name: 'offset', default: 0.5 }\n  ],\n  glsl: `return vec4(vec3(_noise(vec3(_st*scale, offset*time))), 0.5);`\n}]\n```\n\nOnce done, you can use the new functions in your script. Generator functions (those of type `src`) will be available via the `synth` object.\n\n```html\n\u003chydra-element\u003e\n  const { yourNoise } = synth\n\n  yourNoise().out()\n\u003c/hydra-element\u003e\n```\n\n### Property `pb`\n\nIf you have access to an instance of `rtc-patch-bay` for streaming, you can assign it to the `pb` property with JavaScript.\n\n```js\ndocument.querySelector('hydra-element').pb = yourRtcPatchBayInstance\n```\n\n## Limitations\n\n- The `loadScript` function is only available when `global` is `true`.\n- It is not possible to work with [p5.js](https://p5js.org) as in the Hydra web editor.\n\n## Development\n\nThis project uses [Vite](https://vitejs.dev/) for development and [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) for testing. The following `npm` scripts are available:\n\n- `dev`: serves `index.html` for _development_ (reloading on file changes)\n- `test`: runs the test suites in a headless chrome\n- `build`: bundles the custom element for _distribution_ (in the `dist` directory)\n\n## Credits\n\n- [Naoto Hieda](https://naotohieda.com/) for improving the usability of the custom element 🪄\n- [Olivia Jack](https://ojack.xyz/) for creating such a fun tool as Hydra 🌈\n- The Hydra community for turning the tool into something even more fun 🧩\n\n## License\n\nDistributed under the GNU Affero General Public License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdomizz%2Fhydra-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjdomizz%2Fhydra-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjdomizz%2Fhydra-element/lists"}