{"id":19122965,"url":"https://github.com/digitalbazaar/qram","last_synced_at":"2025-07-18T05:38:03.339Z","repository":{"id":66015290,"uuid":"202401119","full_name":"digitalbazaar/qram","owner":"digitalbazaar","description":"Cram arbitrarily large data into multiple streaming QR-codes","archived":false,"fork":false,"pushed_at":"2019-10-03T14:29:36.000Z","size":328,"stargazers_count":18,"open_issues_count":2,"forks_count":5,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-06-12T13:56:20.096Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://digitalbazaar.github.io/qram","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalbazaar.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,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-14T18:03:08.000Z","updated_at":"2024-05-16T14:12:52.000Z","dependencies_parsed_at":"2023-05-29T04:00:32.315Z","dependency_job_id":null,"html_url":"https://github.com/digitalbazaar/qram","commit_stats":{"total_commits":102,"total_committers":2,"mean_commits":51.0,"dds":0.009803921568627416,"last_synced_commit":"c6e3598555e474cfeef9fcff9f5b6e3678a037a9"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/digitalbazaar/qram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fqram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fqram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fqram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fqram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalbazaar","download_url":"https://codeload.github.com/digitalbazaar/qram/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalbazaar%2Fqram/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265529822,"owners_count":23782949,"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-11-09T05:23:45.800Z","updated_at":"2025-07-18T05:38:03.316Z","avatar_url":"https://github.com/digitalbazaar.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# qram\nCram arbitrarily large data into, e.g., multiple streaming QR-codes\n\n## Table of Contents\n\n- [Background](#background)\n- [Install](#install)\n- [Usage](#usage)\n- [Contribute](#contribute)\n- [Commercial Support](#commercial-support)\n- [License](#license)\n\n## Background\n\nThe primary purpose of this library is to allow arbitrarily large data to\nbe transmitted using QR codes. It uses [LT Codes][] to pack blocks of data\ninto packets for efficient delivery via a lossy medium (such as QR codes). The\nmeans of delivery is decoupled from this library so that the data can be\ntransmitted using any means the programmer is capable to employ. However,\nfrom here forward the examples and documentation focus on delivering the\ndata via QR codes.\n\nQR-codes can be used to represent relatively small data (e.g., ~7k chars\nor ~3k binary data). This library enables arbitrarily large data to be\ntransferred from one device to another using QR-codes. The term \"arbitrarily\"\nis used loosely here as there will always be various other physical limitations\n(e.g., RAM, time, etc.). Extremely large data can be broken into chunks before\nbeing passed to this library, but, not only will transfer time will always be\na limiting factor, constructing a viable transfer system where there is little\nto no feedback from the decoder would be challenging.\n\nThis README demonstrates how to setup an encoder and decoder for a stream of\nQR-codes that can be displayed as a video to a QR-code scanner. The QR-codes\nwill be efficiently repeated until all of the data has been successfully read\nby the scanner.\n\nThis project reuses some of the ideas from a similar project written\nin Go, [TXQR][].\n\n## Install\n\n- Node.js 8.6+ required.\n\nTo install locally (for usage):\n\n```\nnpm install qram\n```\n\nTo install locally (for development):\n\n```\ngit clone https://github.com/digitalbazaar/qram.git\ncd qram\nnpm install\n```\n\n## Usage\n\n### Transmitting data\n\n```js\nimport {Encoder} from 'qram';\n// user selected qr-code generator\nimport QRCode from 'qrcode';\n// for converting binary data to text\nimport * as base64url from 'base64url-universal';\n\n// some data to encode (arbitrarily large)\nconst data = new Uint8Array([1, 2, 3]);\n\n// create encoder that will produce packets of data for decoder(s)\nconst encoder = new Encoder({data});\n\n// get a timer for managing frame rate\n// TODO: add option to progressively reduce fps after internally calculated\n// expected transfer interval\nconst timer = encoder.createTimer({fps: 30});\n\n// get the stream of packets to efficiently deliver the data to decoder(s)\n// stream will indefinitely generate packets to be decoded; stop reading\n// from the stream once the decoder has received all of the data\nconst stream = await encoder.createReadableStream();\n\n// create a function to display the packet as a qr-code\nconst canvas = document.querySelector('canvas');\nconst display = ({packet}) =\u003e\n  QRCode.toCanvas(canvas, base64url.encode(packet.data));\n\n// keep reading and displaying the packets as qr-code images until the decoder\n// has received the data\nconst reader = stream.getReader();\ntimer.start();\nwhile(true) {\n  // read the next packet\n  const {value: packet, done} = await reader.read();\n  if(done) {\n    break;\n  }\n\n  // display the packet as a qr-code for scanning\n  await display({packet});\n\n  // manage your frame rate\n  // Note: `timer` internally uses `requestAnimationFrame`, if available, to\n  // prevent the promise returned from `nextFrame` from resolving until\n  // `requestAnimationFrame` runs, preventing changes while the user is\n  // not viewing the appropriate window/tab and preventing changes that\n  // are faster than the browser itself can render\n  await timer.nextFrame();\n}\n\n// ... somewhere out-of-band cancel the stream once the decoder has the data\nstream.cancel();\n```\n\n### Receiving Data\n\nPick a qr-code reader engine (e.g., [jsQR][]) or use the\n[Shape Detection API][]). Wrap your engine of choice in a simple driver API\nthat takes an image and returns the encoded data as a JavaScript string or\nas a Uint8Array.\n\n```js\nimport {Decoder} from 'qram';\n// user selected reader\nimport jsQR from 'jsqr';\n// for converting text to binary data\nimport * as base64url from 'base64url-universal';\n\nconst decoder = new Decoder();\n\n// get a video element to read images of qr-codes from\nconst video = document.querySelector('video');\n\n// use `requestAnimationFrame` so that scanning will not happen unless the\n// user has focused the window/tab displaying the qr-code stream\nrequestAnimationFrame(function enqueue() {\n  // use qram helper to get image data\n  const imageData = qram.getImageData(video);\n  // use qr-code reader of choice to get Uint8Array or Uint8ClampedArray\n  // representing the packet\n  const {data: text} = jsQr(imageData.data, imageData.width, imageData.height);\n  // enqueue the packet data for decoding, ignoring any errors\n  // and rescheduling until done or aborted\n  decoder.enqueue(base64url.decode(text)\n    .then(progress =\u003e {\n      // show progress, e.g. `progress.receivedBlocks / progress.totalBlocks`,\n      // to user somehow ...\n\n      if(!progress.done) {\n        // not done yet, schedule to get another packet\n        requestAnimationFrame(enqueue);\n      }\n    })\n    .catch(e =\u003e e.name === 'AbortError' ?\n      null : requestAnimationFrame(enqueue));\n});\n\ntry {\n  // result found\n  const {data} = await decoder.decode();\n} catch(e) {\n  // failure to decode\n  console.error(e);\n}\n\n// ... somewhere out-of-band you can cancel if desired\ndecoder.cancel();\n```\n\n## Commercial Support\n\nCommercial support for this library is available upon request from\nDigital Bazaar: support@digitalbazaar.com\n\n## License\n\n[New BSD License (3-clause)](LICENSE) © Digital Bazaar\n\n[jsQR]: https://github.com/cozmo/jsQR\n[Shape Detection API]: https://wicg.github.io/shape-detection-api/\n[TXQR]: https://github.com/divan/txqr\n[LT Codes]: https://en.wikipedia.org/wiki/Luby_transform_code\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalbazaar%2Fqram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalbazaar%2Fqram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalbazaar%2Fqram/lists"}