Repository files navigation

Tethr is a JavaScript/TypeScript library designed to control USB-connected digital cameras directly from browsers.

It is built on top of theWebUSB API and aims to provide support for cameras by various vendors. The library utilizes the Picture Transfer Protocol (PTP), which offers a means to access camera functionalities such as shutter control, aperture adjustment, ISO settings, and more via USB or TCP/IP connections. However, due to the varying vendor-specific extensions employed by different camera models, acheving compatibility among them has been challenging.

Tethr addreses this issue by acting as a bridge and offering a standarized and contemporary interface for developers. With Tethr, developers can interact with cameras seamlessly, abstracting away the underlying differences and complexities. The project takes inspiration fromlibgphoto2 in its pursuit of providing a comprehensive camera control solution.

• 📸 Control camera functionalities such as shutter, aperture, ISO, and more.
• ⚡️ Access cameras via USB using the PTP (Picture Transfer Protocol) standard.
• 🌎 Vendor-specific support to fully access all features of each camera model.
• 🤳 Automatic fallback to web cameras when WebUSB is disabled or no USB camera is connected.

npm install tethryarn add tethr

As mentioned, due to the vendor-specific extensions added to the PTP, comprehensive support for each camera model's features requires vendor-specific implementation. Without such support, the library can only access a limited set of configs exposed through standard device properties defined in the PTP specification.

In addition, the library offers fallback functionality to web cameras in situations where WebUSB is disabled or when no USB-connected camera is detected. This enables developers to seamlessly switch to using web cameras, such as those integrated into smartphones, as an alternative capture source.

Here's a list of camera models currently supported by the library:

** LV: Liveview, AF: Auto Focus, MF: Manual Focus

If you want to implement a support code for a new camera model, or ask someone for support instead, please refer to the contribution guide shown below.

• Guide for supporting a new camera
• 新しいカメラをサポートする (Japanese)

The project is in the early stages of development and lacks complete documentation. Here is a code sample to provide you with an understanding of how to utilize the library. it's important to note that all camera operations are asynchronous, and Tethr's instance methods returnPromises.

import{TethrManager}from'tethr'// Since the TethrManager.requestCamera must be called in a user interaction, you need to call it in a button click event or something like that.document.getElementById('#connect').addEventListener('click',test)asyncfunctiontest(){// Create a new TethrManager instanceconstmanager=newTethrManager()// It will display a prompt to select a USB cameraconstcamera=awaitmanager.requestCamera('ptpusb')awaitcamera.open()camera.name// -> 'Lumix S5'awaitcamera.set('shutterSpeed','1/1000')constexposureModeDesc=awaitcamera.getDesc('exposureMode')console.log(exposureModeDesc)/* -> {value: 'M',writable: false // Because this can be set by the physical dial on a cameraoption: {type: 'enum',values: ['M', 'S', 'A', 'P']}} */constautoFocusResult=awaitcamera.runAutoFocus()// -> {status: 'ok'}if(!autoFocusResult.status!=='ok'){console.warn('AF failed')}consttakePhotoResult=awaitcamera.takePhoto({download:true})if(takePhotoResult.status==='ok'){consturl=URL.createURLObject(takePhotoResult.value[0])$img.src=url}// Get storage informationsconststorages=awaitcamera.getStorages()for(conststorageofstorages){console.log('Storage ID= '+storage.id)console.log('name='+storage.name)console.log('free space in images='+storage.freeSpaceInImages)}awaitcamera.close()}

This is a list of ConfigName and their value types:

TheconfigName mentioned in the subsequent sample code can be replaced with the names shown above.

You can retrieve and modify configs like code shown below:

// Gettersawaitcamera.get('configName'):Promise<ConfigType|null>awaitcamera.getConfigName():Promise<ConfigType|null>// Settersawaitcamera.set('configName',value):Promise<OperationResult>awaitcamera.setConfigName(value):Promise<OperationResult>// Setters return the following object:interfaceOperationResult{status:'ok'|'unsupported'|'invalid parameter'|'busy'|'general error'}

If you want to obtain information about a config, such as its writability and a list of valid values.

awaitcamera.getDesc('configName'):Promise<ConfigDesc<ConfigType>>awaitcamera.getConfigNameDesc():Promise<ConfigDesc<ConfigType>>interfaceConfigDesc<ConfigType>{writable:booleanvalue:ConfigType|nulloption?:|{type:'enum';values:ConfigType[]}|{type:'range';min:ConfigType;max:ConfigType;step:ConfigType}}

Whenever a config is changed, a correspoindingconfigNameChange event will be fired. Since Tethr class inherits fromEventEmitter, you can monitor the value change using the following pattern:

camera.on('apertureChange',(newValue:Aperture)=>{// Handle the value change here})// Or watch oncecamera.once('shutterSpeedChange',callback)// Delete event listenercamera.off('apertureChange',callback)// Or you can watch all config changescamera.on('change',(configName:ConfigName,newValue:ConfigType[ConfigName])=>{// Handle the value change here})

An eventconfigNameChange is triggered in the the following:

• When you manually set the value of theconfigName.
• When you modify other configs that have a side effect on the value ofconfigName. For example, setting thewhiteBalance to'auto' will make thecolorTemperature read-only.
• When users change settings by camera buttons or dials.

git clone https://github.com/baku89/tethr tethrcd tethryarn installyarn dev

npm i -g lernalerna version --no-privatelerna publish from-git

This repository is published under an MIT License. See the includedLICENSE file.