Package Exports
- @alpha-sdk/api
Readme
@alpha-sdk/api
The Alpha Camera REST API for Sony cameras (powered by the Sony Camera Remote SDK). This package ships the server itself — a native HTTP + SSE + WebSocket binary — bundled with three ways to drive it:
- As an embedded server in any Node.js app via the
ServerManagerclass. - As a standalone CLI (
camera-server start) for one-off scripting or as a sidecar in Electron / Tauri / Pi deployments. - As an interactive playground (
camera-server playground start) — a browser UI for exploring the API live, no client SDK required.
Pair it with one of the language-specific REST clients to call the API from your code:
| Language | Package | Install |
|---|---|---|
| TypeScript | @alpha-sdk/client |
npm install @alpha-sdk/client |
| Python | alpha-sdk-client |
pip install alpha-sdk-client |
| Swift | AlphaSDK |
.package(url: "https://github.com/jordlee/alpha-sdk-swift.git", from: "0.2.0") |
Install
# CLI globally — the most common path
npm install -g @alpha-sdk/api
# Or per-project (for ServerManager + bundling in your app)
npm install @alpha-sdk/apiThe matching platform binary (@alpha-sdk/darwin-arm64, @alpha-sdk/linux-arm64, @alpha-sdk/linux-x64, @alpha-sdk/win32-x64) is pulled in automatically as an optionalDependency. No separate download step.
CLI usage
camera-server start # spawn the server on :8080
camera-server stop
camera-server status
camera-server info # version, platform, paths
camera-server doctor # verify prerequisites
camera-server platforms # list installed/available platforms
camera-server install-sdk ts # add @alpha-sdk/client to current project
camera-server install-sdk python # add alpha-sdk-client
camera-server install-sdk swift # print SwiftPM snippet for Package.swift
camera-server install-sdk all # auto-detect each project type and install
camera-server playground start # interactive web playground
camera-server mcp install <agent> # install Camera Help Guides MCP serverProgrammatic usage (ServerManager)
import { ServerManager } from "@alpha-sdk/api";
const server = new ServerManager();
await server.start(); // resolves once HTTP is responsive
console.log(`server on :${server.getPort()}`);
// ... do stuff against http://localhost:${port}/api ...
await server.stop(); // graceful shutdown via /api/server/shutdownOptions
new ServerManager({
port: 8080, // default 8080
binaryPath: "...", // override auto-detect (rare)
autoPort: true, // find a free port if 8080 is taken
detached: false, // server outlives parent process
});Useful methods
server.start(); // async — resolves when /api/server/status responds
server.stop(); // async — graceful → SIGTERM → SIGKILL escalation
server.kill(); // sync — for use in signal handlers
server.isRunning(); // async — pings /api/server/status
server.getPort(); // current port
server.getPid(); // child process PID (or detached PID)
server.getStdout(); // captured stdout lines
server.getStderr(); // captured stderr linesEnd-to-end example
Pair ServerManager with @alpha-sdk/client — start the server, connect to a camera, change a setting, fire the shutter, list and download the resulting photo, then disconnect:
import { ServerManager } from "@alpha-sdk/api";
import { AlphaSDKClient } from "@alpha-sdk/client";
import { writeFile } from "node:fs/promises";
const server = new ServerManager();
await server.start();
const client = new AlphaSDKClient({
environment: `http://localhost:${server.getPort()}`,
});
// 1. List + connect to the first detected camera
const { cameras } = await client.cameras.list();
const camera = cameras.find(c => c.connected !== true) ?? cameras[0];
const cameraId = camera.id;
await client.cameras.connect({
cameraId,
mode: "remote-transfer", // full control + explicit file fetch
reconnecting: "on",
});
// Required for the host to drive most settings
await client.cameras.setPriorityKey({ cameraId, setting: "pc-remote" });
// 2. Change shutter speed
await client.properties.set({
cameraId,
propertyName: "shutter-speed",
value: "1/250",
});
// 3. Take a photo
await client.actions.shutter({ cameraId });
// 4. Wait briefly for the camera to write the file, then list slot 1
await new Promise(r => setTimeout(r, 1500));
const { files } = await client.sdCard.list({ cameraId, slot: 1 });
const latest = files[files.length - 1];
// 5. Download the photo (binary endpoint — fetch the bytes directly)
const url = `http://localhost:${server.getPort()}/api/cameras/${cameraId}/sd-card/slot/1/files/${latest.contentId}/${latest.fileId}/download`;
const bytes = new Uint8Array(await (await fetch(url)).arrayBuffer());
await writeFile(`./${latest.name}`, bytes);
// 6. Clean up
await client.cameras.disconnect({ cameraId });
await server.stop();That covers the most common flow. For SSE event streams, live-view JPEG polling/streaming, discovery + reconnect, multi-camera coordination, and other non-REST patterns, see the docs and the recipes in docs/recipes/.
Integration modes
| App type | Pattern | What's bundled |
|---|---|---|
| Node CLI / script | ServerManager.start() |
binary auto-installed via npm |
| Electron | ServerManager + extraResources |
binary copied into .app |
| Tauri | sidecar | binary in src-tauri/binaries/ |
| Web SPA | client only | nothing — server runs separately |
| iOS / Android | client only | nothing — server runs on a Mac/Pi/etc. |
The binary cannot run on iOS/Android — those platforms must talk to a server running elsewhere on the network.
License
MIT — see LICENSE.
The bundled native binary is licensed by Sony under their separate Camera Remote SDK License Agreement; see the LICENSE file shipped inside each @alpha-sdk/<platform> package.