Merge pull request #7 from icheered/main

.gitattributes

@@ -0,0 +1,2 @@
+build/* binary
+build/* linguist-generated=true

.gitignore

@@ -1,6 +1,4 @@
 /.vscode/c_cpp_properties.json
-/ui/libapi.*
-!/ui/libapi.mjs.d.ts
 /node_modules
 /deps/*
 !/deps/libgphoto2

Makefile

@@ -5,7 +5,7 @@ export LDFLAGS += -L$(SYSROOT)/lib
 export ACLOCAL_PATH := $(SYSROOT)/share/aclocal:$(ACLOCAL_PATH)
 
 # Common linking flags for all targets.
-export LDFLAGS += -s DYNAMIC_EXECUTION=0 -s AUTO_JS_LIBRARIES=0 -s AUTO_NATIVE_LIBRARIES=0
+export LDFLAGS += -s DYNAMIC_EXECUTION=0 -s AUTO_JS_LIBRARIES=0 -s AUTO_NATIVE_LIBRARIES=0 -s ENVIRONMENT=web,worker
 
 # Common compilation & linking flags for all langs and targets.
 COMMON_FLAGS = -Os -flto
@@ -15,7 +15,7 @@ export LDFLAGS += $(COMMON_FLAGS)
 
 ## Main API module
 
-ui/libapi.mjs: api.o $(SYSROOT)/lib/libltdl.la $(SYSROOT)/lib/libgphoto2.la
+build/libapi.mjs: api.o $(SYSROOT)/lib/libltdl.la $(SYSROOT)/lib/libgphoto2.la
 	libtool --verbose --mode=link $(LD) $(LDFLAGS) -o $@ $+ \
 		-fexceptions --bind -s ASYNCIFY -s ALLOW_MEMORY_GROWTH \
 		-dlpreopen $(SYSROOT)/lib/libgphoto2/2.5.28.1/ptp2.la \

README.md

@@ -1,9 +1,65 @@
-This is a [demo app](https://web.dev/porting-libusb-to-webusb/) running gPhoto2 on the Web:
+# Web-gPhoto2
 
-![A picture of DSLR camera connected via a USB cable to a laptop. The laptop is running the Web demo mentioned in the article, which mirrors a live video feed from the camera as well as allows to tweak its settings via form controls.](https://web-dev.imgix.net/image/9oK23mr86lhFOwKaoYZ4EySNFp02/MR4YGRvl0Z9AWT6vv3sQ.jpg?auto=format&w=1600)
+A gPhoto2 implementation using WebAssembly to control DSLR cameras from the browser.
 
 Powered by a [custom fork](https://github.com/RReverser/libgphoto2) of [libgphoto2](https://github.com/gphoto/libgphoto2), the [WebUSB](https://github.com/WICG/webusb) backend of [libusb](https://github.com/libusb/libusb), and WebAssembly via [Emscripten](https://emscripten.org/).
 
+# NPM
+
+## Installation
+```bash
+npm install web-gphoto2
+// or
+yarn add web-gphoto2
+```
+
+## Usage
+A short example on how to use this package:
+
+```ts
+import { Camera } from "web-gphoto2";
+
+let camera = new Camera();
+
+async function connectCamera() {
+  await Camera.showPicker();
+  await camera.connect();
+}
+
+async function getSupportedOps() {
+  const ops = await camera.getSupportedOps();
+  console.log("Supported Ops:", ops);
+}
+
+async function getCameraConfig() {
+  const config = await camera.getConfig();
+  console.log("Config:", config);
+}
+
+async function updateConfig() {
+  await camera.setConfigValue("iso", "800");
+}
+
+async function capturePreviewAsBlob() {
+  // Capture a frame while in live view mode
+  const blob = await camera.capturePreviewAsBlob();
+  imageUrl = URL.createObjectURL(blob);
+  // Set the imageUrl as the src of an image element in your HTML
+}
+
+async function captureImageAsFile() {
+  // Capture an image
+  const file = await camera.captureImageAsFile();
+  imageUrl = URL.createObjectURL(file);
+  // Set the imageUrl as the src of an image element in your HTML
+}
+```
+
+# Demo
+
+This repository also contains a [demo app](https://web.dev/porting-libusb-to-webusb/) running gPhoto2 on the Web:
+![A picture of DSLR camera connected via a USB cable to a laptop. The laptop is running the Web demo mentioned in the article, which mirrors a live video feed from the camera as well as allows to tweak its settings via form controls.](https://web-dev.imgix.net/image/9oK23mr86lhFOwKaoYZ4EySNFp02/MR4YGRvl0Z9AWT6vv3sQ.jpg?auto=format&w=1600)
+
 For the detailed technical write-up, see [the official blog post](https://web.dev/porting-libusb-to-webusb/). To see the demo in action, visit the hosted version [here](https://web-gphoto2.rreverser.com/) (but make sure to read the [cross-platform compatibility notes](https://web.dev/porting-libusb-to-webusb/#important-cross-platform-compatibility-notes) first).
 
 If you don't have a DSLR, you can check out a recording of the demo below:
@@ -16,10 +72,58 @@ To build, you'll need Docker. Then:
 
 ```bash
 ./build.sh # runs build in Docker
-npx serve ui # starts a local server with COOP/COEP
+npx serve examples/preact # starts a local server with COOP/COEP
 ```
 
-Then, navigate to http://localhost:5000/ in Chrome.
+Then, navigate to http://localhost:3000/ in Chrome.
+
+## Common Issues
+<details>
+<summary>
+SharedArrayBuffer can not be found
+</summary>
+SharedArrayBuffer has been disabled across all browsers due to the Spectre vulnerability. This package uses SharedArrayBuffer to communicate with the WebAssembly module. To work around this issue, you need to set two response headers for your document:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Information from [Stackoverflow](https://stackoverflow.com/questions/64650119/react-error-sharedarraybuffer-is-not-defined-in-firefox)
+</details>
+
+<details>
+<summary>
+ Error: Not found: /node_modules/.vite/deps/libapi.wasm
+ </summary>
+Vite tries to optimize the dependencies by default. This causes the WebAssembly module to be moved to a different location. To prevent this, you need to exclude the web-gphoto2 package from the optimization.
+
+In vite, both of the above mentioned issues are solved by adding the following to your vite.config.js:
+
+```ts
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+
+/** @type {import('vite').Plugin} */
+const viteServerConfig = {
+  name: "add headers",
+  configureServer: (server) => {
+    server.middlewares.use((req, res, next) => {
+      res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+      res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+      next();
+    });
+  },
+};
+
+export default defineConfig({
+  plugins: [sveltekit(), viteServerConfig],
+  optimizeDeps: {
+    exclude: ["web-gphoto2"],
+  },
+});
+```
+</details>
 
 ## See also
 

build/libapi.worker.js

@@ -0,0 +1 @@
+"use strict";var Module={};var initializedJS=false;function threadPrintErr(){var text=Array.prototype.slice.call(arguments).join(" ");console.error(text)}function threadAlert(){var text=Array.prototype.slice.call(arguments).join(" ");postMessage({cmd:"alert",text:text,threadId:Module["_pthread_self"]()})}var err=threadPrintErr;self.alert=threadAlert;Module["instantiateWasm"]=((info,receiveInstance)=>{var instance=new WebAssembly.Instance(Module["wasmModule"],info);receiveInstance(instance);Module["wasmModule"]=null;return instance.exports});self.onmessage=(e=>{try{if(e.data.cmd==="load"){Module["wasmModule"]=e.data.wasmModule;Module["wasmMemory"]=e.data.wasmMemory;Module["buffer"]=Module["wasmMemory"].buffer;Module["ENVIRONMENT_IS_PTHREAD"]=true;(e.data.urlOrBlob?import(e.data.urlOrBlob):import("./libapi.mjs")).then(function(exports){return exports.default(Module)}).then(function(instance){Module=instance})}else if(e.data.cmd==="run"){Module["__performance_now_clock_drift"]=performance.now()-e.data.time;Module["__emscripten_thread_init"](e.data.threadInfoStruct,0,0,1);Module["establishStackSpace"]();Module["PThread"].receiveObjectTransfer(e.data);Module["PThread"].threadInit();if(!initializedJS){Module["___embind_register_native_and_builtin_types"]();initializedJS=true}try{var result=Module["invokeEntryPoint"](e.data.start_routine,e.data.arg);if(Module["keepRuntimeAlive"]()){Module["PThread"].setExitStatus(result)}else{Module["__emscripten_thread_exit"](result)}}catch(ex){if(ex!="unwind"){if(ex instanceof Module["ExitStatus"]){if(Module["keepRuntimeAlive"]()){}else{Module["__emscripten_thread_exit"](ex.status)}}else{throw ex}}}}else if(e.data.cmd==="cancel"){if(Module["_pthread_self"]()){Module["__emscripten_thread_exit"](-1)}}else if(e.data.target==="setimmediate"){}else if(e.data.cmd==="processThreadQueue"){if(Module["_pthread_self"]()){Module["_emscripten_current_thread_process_queued_calls"]()}}else{err("worker.js received unknown command "+e.data.cmd);err(e.data)}}catch(ex){err("worker.js onmessage() captured an uncaught exception: "+ex);if(ex&&ex.stack)err(ex.stack);throw ex}});

examples/preact/build

@@ -0,0 +1 @@
+../../build

examples/preact/index.js

@@ -22,9 +22,9 @@ import { connect, rethrowIfCritical } from './ops.js';
 import { Preview } from './preview.js';
 import { Widget } from './widget.js';
 
-/** @typedef {import('../libapi.mjs').Context} Context */
-/** @typedef {import('../libapi.mjs').Config} Config */
-/** @typedef {import('./ops').Connection} Connection */
+/** @typedef {import('./build/libapi.mjs').Context} Context */
+/** @typedef {import('./build/libapi.mjs').Config} Config */
+/** @typedef {import('./ops.js').Connection} Connection */
 
 export const isDebug = new URLSearchParams(location.search).has('debug');
 

examples/preact/ops.js

@@ -16,7 +16,7 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  */
 
-import initModule from '../libapi.mjs';
+import initModule from './build/libapi.mjs';
 
 /** @typedef {import('../libapi.mjs').Context} Context */
 

examples/preact/widget.js

@@ -18,7 +18,7 @@
 
 import { h, Component, createRef } from 'preact';
 
-/** @typedef {import('../libapi.mjs').Config} Config */
+/** @typedef {import('./build/libapi.mjs').Config} Config */
 
 /**
  * @param {Config} config

package.json

@@ -1,4 +1,43 @@
 {
+  "name": "web-gphoto2",
+  "version": "1.0.0",
+  "description": "WebAssembly implementation of gphoto2 and libusb to control DSLR cameras over USB on the Web",
+  "type": "module",
+  "main": "src/camera.js",
+  "types": "src/types.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GoogleChromeLabs/web-gphoto2"
+  },
+  "keywords": [
+    "gphoto2",
+    "libusb",
+    "webassembly"
+  ],
+  "author": {
+    "name": "Ingvar Stepanyan",
+    "email": "me@rreverser.com",
+    "url": "https://rreverser.com"
+  },
+  "contributors": [
+    {
+      "name": "Tjeerd Bakker",
+      "email": "tjeerd992@gmail.com",
+      "url": "https://icheered.com"
+    }
+  ],
+  "license": "LGPL-2.1-or-later",
+  "bugs": {
+    "url": "https://github.com/GoogleChromeLabs/web-gphoto2/issues"
+  },
+  "homepage": "https://github.com/GoogleChromeLabs/web-gphoto2#readme",
+  "files": [
+    "src/*",
+    "build/*"
+  ],
   "devDependencies": {
     "@types/emscripten": "^1.39.5",
     "@types/requestidlecallback": "^0.3.4",

src/camera.js

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2023 Google LLC
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+import initModule from "../build/libapi.mjs";
+
+export function rethrowIfCritical(err) {
+  // If it's precisely Error, it's a custom error; anything else - SyntaxError,
+  // WebAssembly.RuntimeError, TypeError, etc. - is treated as critical here.
+  if (err.constructor !== Error) {
+    throw err;
+  }
+}
+
+const INTERFACE_CLASS = 6; // PTP
+const INTERFACE_SUBCLASS = 1; // MTP
+
+let ModulePromise = null;
+
+export class Camera {
+  constructor() {
+    this.queue = Promise.resolve();
+    this.Module = null;
+    this.context = null;
+  }
+
+  static async showPicker() {
+    // @ts-ignore
+    await navigator.usb.requestDevice({
+      filters: [
+        {
+          classCode: INTERFACE_CLASS,
+          subclassCode: INTERFACE_SUBCLASS,
+        },
+      ],
+    });
+  }
+
+  async connect() {
+    if (!ModulePromise) {
+      ModulePromise = initModule()
+    }
+    this.Module = await ModulePromise;
+    this.context = await new this.Module.Context();
+  }
+
+  async schedule(op) {
+    let res = this.queue.then(() => op(this.context));
+    this.queue = res.catch(rethrowIfCritical);
+    return res;
+  }
+
+  async disconnect() {
+    if (!this.context.isDeleted()) {
+      this.context.delete();
+    }
+  }
+
+  async getConfig() {
+    return this.schedule((context) => context.configToJS());
+  }
+
+  async getSupportedOps() {
+    if (this.context) {
+      return await this.context.supportedOps();
+    }
+    throw new Error("You need to connect to the camera first");
+  }
+
+  async setConfigValue(name, value) {
+    const uiTimeout = new Promise((resolve) => setTimeout(resolve, 800));
+    const setResult = this.schedule((context) =>
+      context.setConfigValue(name, value)
+    );
+    return Promise.all([setResult, uiTimeout]);
+  }
+
+  async capturePreviewAsBlob() {
+    return this.schedule((context) => context.capturePreviewAsBlob());
+  }
+
+  async captureImageAsFile() {
+    return this.schedule((context) => context.captureImageAsFile());
+  }
+
+  async consumeEvents() {
+    return this.schedule((context) => context.consumeEvents());
+  }
+}

src/libapi.mjs.d.ts

@@ -16,7 +16,7 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
  */
 
-export type Config = {
+type Config = {
   name: string;
   info: string;
   label: string;
@@ -59,7 +59,7 @@ export interface Module extends EmscriptenModule {
   Context: typeof Context;
 }
 
-export type { Context };
+export type { Config, Context, SupportedOps };
 
 declare const initModule: EmscriptenModuleFactory<Module>;
 export default initModule;

src/types.d.ts

@@ -0,0 +1,25 @@
+// Import types Context and SupportedOps ./libapi.mjs.d.ts
+import type { Config, Context, SupportedOps } from './libapi.mjs.d.ts';
+
+export declare class Camera {
+    constructor();
+
+    static showPicker(): Promise<void>;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+
+    getConfig(): Promise<Config>;
+
+    getSupportedOps(): SupportedOps;
+
+    setConfigValue(name: string, value: number | string | boolean): Promise<void>;
+
+    capturePreviewAsBlob(): Promise<Blob>;
+    captureImageAsFile(): Promise<File>;
+    consumeEvents(): Promise<boolean>;
+
+    private rethrowIfCritical(err: any): void;  // any error type can be replaced by more specific if available
+    private schedule<T>(op: (ctx: any) => Promise<T>): Promise<T>;  // ctx and T types can be replaced by more specific if available
+}
+
+export type { Config, Context, SupportedOps };