hs.camera
ModuleModule 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))hs.camera.findByName(name) -> HSCamera
Find the first camera whose name matches the given string.
Declaration
hs.camera.findByName(name) -> HSCameraParameters
| 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")hs.camera.findByUID(uid) -> HSCamera
Find the camera with the given unique identifier.
Declaration
hs.camera.findByUID(uid) -> HSCameraParameters
| 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")hs.camera.on(event, listener) -> None
Register a listener for camera device connect/disconnect events.
Declaration
hs.camera.on(event, listener) -> NoneParameters
| Name | Type | Description |
|---|---|---|
| event | any | The event to listen for |
| listener | any | Called with the affected camera when a matching event occurs |
Returns
None
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.camera.on('connected', camera => console.log("connected: " + camera.name))
hs.camera.on('disconnected', camera => console.log("disconnected: " + camera.name))
} catch (err) {
console.error(err.message)
}hs.camera.off(event, listener) -> None
Remove a previously registered camera device event listener.
Declaration
hs.camera.off(event, listener) -> NoneParameters
| 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)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) -> NoneParameters
| 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
Throws
Throws an Error on failure; wrap calls in try/catch to handle it.
Example
try {
hs.camera.once('connected', camera => console.log("First camera connected: " + camera.name))
} catch (err) {
console.error(err.message)
}