API Docs

hs.camera

Module

Module for discovering and interacting with camera devices.

This module lets you enumerate cameras, capture still images, and react to device connect/disconnect events in real time.

Camera access requires user permission. Call hs.permissions.requestCamera() before using captureImage() or reading isInUse.

Enumerating cameras

const cameras = hs.camera.all()
cameras.forEach(cam => {
    console.log(cam.name + " — " + (cam.isInUse ? "in use" : "idle"))
})

Finding a specific camera

const cam = hs.camera.findByName("FaceTime HD Camera")
if (cam) {
    cam.captureImage()
        .then(img => img.saveToFile("/tmp/snapshot.png"))
        .catch(err => console.error("Capture error: " + err))
}

Watching for connect / disconnect events

hs.camera.on("connected", camera => console.log("Camera connected: " + camera.name))
hs.camera.on("disconnected", camera => console.log("Camera disconnected: " + camera.name))

Watching a camera's in-use state

const cam = hs.camera.all()[0]
cam.on(() => {
    console.log(cam.name + " is now " + (cam.isInUse ? "in use" : "idle"))
})

Types

This module provides the following types:

Properties

This module has no properties.

Methods

hs.camera.all() -> HSCamera[]

All video camera devices currently connected to the system.
Declaration
hs.camera.all() -> HSCamera[]
Returns
HSCamera[]
An array of `HSCamera` objects
Example
hs.camera.all().forEach(c => console.log(c.name))
Hammerspoon 2/Modules/hs.camera/HSCameraModule.swift:64

hs.camera.findByName(name) -> HSCamera

Find the first camera whose name matches the given string.
Declaration
hs.camera.findByName(name) -> HSCamera
Parameters
Name Type Description
name string The device name to search for (exact match)
Returns
HSCamera
An `HSCamera` if found, `null` otherwise
Example
const cam = hs.camera.findByName("FaceTime HD Camera")
Hammerspoon 2/Modules/hs.camera/HSCameraModule.swift:73

hs.camera.findByUID(uid) -> HSCamera

Find the camera with the given unique identifier.
Declaration
hs.camera.findByUID(uid) -> HSCamera
Parameters
Name Type Description
uid string The device UID to search for
Returns
HSCamera
An `HSCamera` if found, `null` otherwise
Example
const cam = hs.camera.findByUID("CC26C0000082005")
Hammerspoon 2/Modules/hs.camera/HSCameraModule.swift:82

hs.camera.on(event, listener) -> None

Register a listener for camera device connect/disconnect events.
Declaration
hs.camera.on(event, listener) -> None
Parameters
Name Type Description
event any The event to listen for
listener any Called with the affected camera when a matching event occurs
Returns
None
Example
hs.camera.on('connected', camera => console.log("connected: " + camera.name))
hs.camera.on('disconnected', camera => console.log("disconnected: " + camera.name))
Hammerspoon 2/Modules/hs.camera/hs.camera.js:23

hs.camera.off(event, listener) -> None

Remove a previously registered camera device event listener.
Declaration
hs.camera.off(event, listener) -> None
Parameters
Name Type Description
event any The event the listener was registered for
listener any The function originally passed to `on`
Returns
None
Example
const onConnected = camera => console.log(camera.name)
hs.camera.on('connected', onConnected)
// later…
hs.camera.off('connected', onConnected)
Hammerspoon 2/Modules/hs.camera/hs.camera.js:38

hs.camera.once(event, listener) -> None

Register a listener that fires at most once for a camera device event.
Declaration
hs.camera.once(event, listener) -> None
Parameters
Name Type Description
event any The event to listen for
listener any Called the next time a matching event occurs, then automatically removed
Returns
None
Example
hs.camera.once('connected', camera => console.log("First camera connected: " + camera.name))
Hammerspoon 2/Modules/hs.camera/hs.camera.js:50