{"id":16259694,"url":"https://github.com/volverjs/ai","last_synced_at":"2025-03-19T22:30:57.007Z","repository":{"id":257805566,"uuid":"858342478","full_name":"volverjs/ai","owner":"volverjs","description":"Hugging Face Transformers.js wrapper for on-device AI with web-workers","archived":false,"fork":false,"pushed_at":"2025-03-11T00:23:10.000Z","size":1048,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-11T01:24:15.979Z","etag":null,"topics":["ai","huggingface","huggingface-transformers","on-device-ai","remove-background","transformers","translation","vue","vuejs","web-worker"],"latest_commit_sha":null,"homepage":"https://volverjs.github.io/ai/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/volverjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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-09-16T18:20:25.000Z","updated_at":"2025-03-11T00:23:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"e57a506b-1ff2-445b-b5c8-023543ec930d","html_url":"https://github.com/volverjs/ai","commit_stats":{"total_commits":18,"total_committers":3,"mean_commits":6.0,"dds":"0.16666666666666663","last_synced_commit":"5f921d7b85cf9536c3c2497a5528a603d7187cf1"},"previous_names":["volverjs/ai"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volverjs%2Fai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/volverjs","download_url":"https://codeload.github.com/volverjs/ai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244029385,"owners_count":20386397,"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":["ai","huggingface","huggingface-transformers","on-device-ai","remove-background","transformers","translation","vue","vuejs","web-worker"],"created_at":"2024-10-10T16:04:22.064Z","updated_at":"2025-03-19T22:30:56.709Z","avatar_url":"https://github.com/volverjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n[![volverjs](public/volverjs-ai-reduced.svg)](https://volverjs.github.io/ai)\n\n## @volverjs/ai\n\n`ai` `transformers.js` `translation` `offline` `web worker`\\\n`remove background` `offscreen canvas`\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=volverjs_ai\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=volverjs_ai) [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=volverjs_ai\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=volverjs_ai) [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=volverjs_ai\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=volverjs_ai)\n\n\u003cbr\u003e\n\nmaintained with ❤️ by\n\n\u003cbr\u003e\n\n[![8 Wave](public/8wave.svg)](https://8wave.it)\n\n\u003cbr\u003e\n\n\u003c/div\u003e\n\n## Get Started\nVolver AI is an Hugging Face [Transformers.js](https://github.com/xenova/transformers.js) wrapper for add AI capabilities to your web applications in a simple way with multithreading support.\n\n- [Install](#install)\n- [Model initialization](#model-initialization)\n- [Download progress](#download-progress)\n- [Translator](#translator)\n  - [Choose a model](#choose-a-model)\n  - [Translate text](#translate-text)\n  - [Listen updates](#listen-updates)\n  - [Vue.js](#vuejs)\n- [Remove Background](#remove-background)\n  - [Create an instance](#create-an-instance)\n  - [Process an image](#process-an-image)\n  - [Canvas](#canvas)\n  - [Vue.js](#vuejs-1)\n\n### Install\n\nAdd the library to your project using your favorite package manager.\n\n```bash\n# pnpm\npnpm add @volverjs/ai\n\n# yarn\nyarn add @volverjs/ai\n\n# npm\nnpm i -s @volverjs/ai\n```\n\nThen you can import and instantiate the AI functionality you need.\n\n```typescript\nimport { Translator, RemoveBackground } from '@volverjs/ai'\n\nconst translator = new Translator()\nconst removeBackground = new RemoveBackground()\n```\n\nThe library automatically downloads and run the model inside a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker).\nUsing a Web Worker allows the library to run the model in a separate thread, preventing the main thread from blocking.\n\n\u003e [!WARNING]\n\u003e Any instance of the AI classes initializes a new Web Worker with the model and manages the communication between the main thread and the worker. If you need to use the same worker in multiple places, you can create a single instance and share it across your application.\n\n### Model initialization\n\nThe first time you instantiate the model, it will download the model files from [Hugging Face Hub](https://huggingface.co/docs/hub/index). This process can take a few seconds or minutes depending on the model size and your internet connection.\n\n```typescript\nawait translator.init()\n```\n\nOtherwise the model is initialized automatically when you call any method that requires the model to be loaded.\n\n### Download progress\n\nYou can listen to the download progress of the model using the `progress` event.\n\n```typescript\ntranslator.on('progress', ({ file, progrees }) =\u003e {\n    console.log(`Download progress of ${file} is ${progress}%`)\n})\n```\n\nOr with `onProgress` initialization option.\n\n```typescript\ntranslator.init({\n    onProgress: ({ file, progress }) =\u003e {\n        console.log(`Download progress of ${file} is ${progress}%`)\n    }\n})\n```\n\n## Translator\nTranslator allows to convert text from one language to another with the AI model of your choice\n\n### Choose a model\n\nBy default, the library uses the [Xenova/nllb-200-distilled-600M](https://huggingface.co/Xenova/nllb-200-distilled-600M) model to translate text.\n\n```typescript\nimport { Translator } from '@volverjs/ai'\n\nconst translator = new Translator()\n```\nYou can change the model by passing the `model` option to the constructor. You can find a list of available models [here](https://huggingface.co/models?pipeline_tag=translation\u0026library=transformers.js\u0026sort=downloads).\n\n```typescript\nconst translator = new Translator({\n    model: 'Xenova/opus-mt-it-en'\n})\n```\n\n### Translate text\n\nTo translate text, use the `translate` method passing the text to translate and the `from` and `to` options with the language codes of the source and target languages.\n\n```typescript\nconst text = 'Ciao, come stai?'\nconst translated = await translator.translate(text, {\n    from: 'ita_Latn',\n    to: 'eng_Latn'\n})\n```\n\nFor `Xenova/nllb-200-distilled-600M` model you can find the full list of supported languages [here](https://github.com/facebookresearch/flores/blob/main/flores200/README.md#languages-in-flores-200).\n\n### Listen updates\n\nDuring the translation process, you can get the partial translation using the `onUpdate` option.\n\n```typescript\nconst text = 'How are you?'\nconst translated = await translator.translate(text, {\n    from: 'eng_Latn',\n    to: 'ita_Latn',\n    onUpdate: ({ output }) =\u003e {\n        console.log(`Partial translation: ${output}`)\n    }\n})\n```\n\n### Vue.js\n\nIf you are using Vue.js, you can use the Composition API to create a reactive translation.\n\n```vue\n\u003cscript lang=\"ts\" setup\u003e\nimport { useTranslator } from '@volverjs/ai/vue'\nimport { ref } from 'vue'\n\nconst text = ref('')\nconst { translate } = useTranslator()\nconst { result } = translate(text, {\n    from: 'eng_Latn',\n    to: 'ita_Latn'\n})\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n    \u003cinput v-model=\"text\" type=\"text\" name=\"from\"\u003e\n    \u003cp\u003e{{ result }}\u003c/p\u003e\n\u003c/template\u003e\n```\n\n\u003e [!TIP]\n\u003e The `result` reactive property contains the partial translation during process and the final result when the translation is completed.\n\nYou can use a custom model by passing the `model` option to the `useTranslator` function.\n\n```typescript\nconst { translate } = useTranslator({\n    model: 'Xenova/opus-mt-it-en'\n})\n```\n\nBy default, a new worker is created for each `useTranslator` call. You can share the worker across multiple components by passing `global` option.\n\n```typescript\nconst { translate } = useTranslator({\n    global: true\n})\n```\n\nThe model is initialized automatically when you use the `translate` function.\nTo monitor the download progress, you can use the `progress` reactive property.\n\n```typescript\nconst { result, progress } = translate(text, {\n    from: 'eng_Latn',\n    to: 'ita_Latn'\n})\nwatch(progress, ({ file, progress: value }) =\u003e {\n    console.log(`Download of file ${file} with progress: ${value}%`)\n})\n```\n\nTo initialize the model manually, you can use the `init` method.\n\n```typescript\nconst { init } = useTranslator()\nconst { isReady, progress } = init()\n```\n\nBelow is a complete example of a Vue.js component that uses the `useTranslator` function.\n\n```vue\n\u003cscript lang=\"ts\" setup\u003e\nimport { useTranslator } from '@volverjs/ai/vue'\nimport { ref, watch } from 'vue'\n\nconst text = ref('')\nconst { translate } = useTranslator()\nconst {\n    // Ref\u003cstring\u003e\n    // the partial translation and the final result\n    result,\n    // Ref\u003c{file: string, progress: number}[]\u003e\n    // the download progress of the model\n    progress,\n    // Ref\u003cError | undefined\u003e\n    // the error object if an error occurs\n    error,\n    // Ref\u003cboolean\u003e\n    // is true when an error occurs\n    isError,\n    // Ref\u003cboolean\u003e\n    // is true when the model is downloading\n    isLoading,\n    // Ref\u003cboolean\u003e\n    // is true when the model is ready\n    isReady,\n    // Promise\u003cstring\u003e\n    // the promise that resolves when the translation is completed\n    promise,\n    // (text?: string) =\u003e Promise\u003cstring | undefined\u003e\n    // manually execute the translation\n    execute\n} = translate(\n    // Ref\u003cstring\u003e | string | undefined\n    // the text to translate\n    text,\n    {\n        // the source language\n        from: 'eng_Latn',\n        // the target language\n        to: 'ita_Latn',\n        // boolean (default: true)\n        // set to false to disable the first translation execution\n        immediate: true,\n        // number (default: 500)\n        // the debounce time in milliseconds to wait before executing the translation\n        debounce: 800\n    }\n)\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n    \u003cinput v-model=\"text\" type=\"text\" name=\"from\"\u003e\n    \u003cp\u003e{{ result }}\u003c/p\u003e\n\u003c/template\u003e\n```\n\n## Remove Background\nRemove the background from an image uses [briaai/RMBG-1.4](https://huggingface.co/briaai/RMBG-1.4) as background removal AI model, designed to effectively separate foreground from background in a range of categories and image types.\n\n### Process an image\nTo remove the background from an image, use the `predict` method passing the image URL.\n\n```typescript\nimport { RemoveBackground } from '@volverjs/ai'\n\nconst sourceImageURL = 'https://example.com/image.jpg'\n\nconst removeBackground = new RemoveBackground()\nconst result = await removeBackground.predict(sourceImageURL)\n```\n\nThe URL could be a local file or a remote file. The library automatically downloads the image and processes it.\n\nYou can customize the quality and the type of the output image using the `quality` and `type` options.\nThe `quality` option accepts a number from 0 to 1, and the `type` option accepts the image MIME type.\n\n```typescript\nconst resultImageBlob = await removeBackground.predict(sourceImageURL, {\n    quality: 0.5,\n    type: 'image/webp'\n})\nconst resultImageURL = URL.createObjectURL(resultImageBlob)\n```\n\n### Canvas\n\nYou can pass a canvas element in the DOM to the `predict` method to draw the result directly on the canvas.\n\n```typescript\nconst canvas = document.getElementById('canvas') as HTMLCanvasElement\nremoveBackground.predict(sourceImageURL, { canvas })\n```\n\n\u003e [!TIP]\n\u003e `@volverjs/ai` use the [OffscreenCanvas API](https://web.dev/articles/offscreen-canvas) to delegate the image processing in the canvas to the worker thread.\n\n### Vue.js\n\nIf you are using Vue.js, you can use the Composition API to create a reactive background removal.\n\n```vue\n\u003cscript lang=\"ts\" setup\u003e\nimport { useRemoveBackground } from '@volverjs/ai/vue'\nimport { ref } from 'vue'\n\nconst sourceImageURL = ref('https://example.com/image.jpg')\nconst { predict } = useRemoveBackground()\nconst { resultUrl } = predict(sourceImageURL)\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n    \u003cimg :src=\"sourceImageURL\" alt=\"Source Image\"\u003e\n    \u003cimg v-if=\"resultUrl\" :src=\"resultUrl\" alt=\"Result Image\"\u003e\n\u003c/template\u003e\n```\nThe `resultUrl` reactive property contains the URL of the processed image. Change the `sourceImageURL` to trigger the background removal process.\n\nTo use a canvas element, pass the canvas element to the `predict` method.\n\n```vue\n\u003cscript lang=\"ts\" setup\u003e\nimport { useRemoveBackground } from '@volverjs/ai/vue'\nimport { ref } from 'vue'\n\nconst sourceImageURL = ref('https://example.com/image.jpg')\nconst canvasEl = ref\u003cHTMLCanvasElement\u003e()\nconst { predict } = useRemoveBackground()\npredict(sourceImageURL, {\n    canvas: canvasEl\n})\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n    \u003cimg :src=\"sourceImageURL\" alt=\"Source Image\"\u003e\n    \u003ccanvas ref=\"canvasEl\" /\u003e\n\u003c/template\u003e\n```\n\nBy default, a new worker is created for each `useRemoveBackground` call. You can share the worker across multiple components by passing `global` option.\n\n```typescript\nconst { predict } = useRemoveBackground({\n    global: true\n})\n```\n\nThe model is initialized automatically when you use the `translate` function.\nTo monitor the download progress, you can use the `progress` reactive property.\n\n```typescript\nconst { resultUrl, progress } = predict(sourceImageURL)\nwatch(progress, ({ file, progress: value }) =\u003e {\n    console.log(`Download of file ${file} with progress: ${value}%`)\n})\n```\n\nTo initialize the model manually, you can use the `init` method.\n\n```typescript\nconst { init } = useRemoveBackground()\nconst canvasEl = ref\u003cHTMLCanvasElement\u003e()\nonMounted(() =\u003e {\n    init({\n        canvas: canvasEl\n    })\n})\n```\n\nBelow is a complete example of a Vue.js component that uses the `useRemoveBackground` function.\n\n```vue\n\u003cscript lang=\"ts\" setup\u003e\nimport { useRemoveBackground } from '@volverjs/ai/vue'\nimport { ref, watch } from 'vue'\n\nconst sourceImageURL = ref('https://example.com/image.jpg')\nconst canvasEl = ref\u003cHTMLCanvasElement\u003e()\nconst { predict } = useRemoveBackground()\nconst {\n    // Ref\u003cBlob | undefined\u003e\n    // the processed image blob\n    result,\n    // Ref\u003cstring | undefined\u003e\n    // the processed image URL\n    resultUrl,\n    // Ref\u003c{file: string, progress: number}[]\u003e\n    // the download progress of the model\n    progress,\n    // Ref\u003cError | undefined\u003e\n    // the error object if an error occurs\n    error,\n    // Ref\u003cboolean\u003e\n    // is true when an error occurs\n    isError,\n    // Ref\u003cboolean\u003e\n    // is true when the model is downloading\n    isLoading,\n    // Ref\u003cboolean\u003e\n    // is true when the model is ready\n    isReady,\n    // Promise\u003cstring\u003e\n    // the promise that resolves when the removal is completed\n    promise,\n    // (sourceUrl?: string) =\u003e \u003cPromise\u003cBlob | undefined\u003e\u003e\n    // manually execute the removal\n    execute\n} = predict(\n    // Ref\u003cstring\u003e | string | undefined\n    // the source image URL\n    sourceImageURL,\n    {\n        // the source language\n        canvas: canvasEl,\n        // the target language\n        type: 'image/webp',\n        // number (default: 0.5)\n        // the quality of the output image\n        quality: 0.5,\n        // boolean (default: true)\n        // set to false to disable the first removal execution\n        immediate: true,\n    }\n)\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n    \u003cimg :src=\"sourceImageURL\" alt=\"Source Image\"\u003e\n    \u003ccanvas ref=\"canvasEl\" /\u003e\n\u003c/template\u003e\n```\n\n## Documentation\nTo learn more about `@volverjs/ai`, check [its documentation](https://volverjs.github.io/ai).\n\n## License\n[MIT](http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolverjs%2Fai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolverjs%2Fai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolverjs%2Fai/lists"}