@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 ServerManager class.
• 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.3.1") |

Public example apps:

• Next.js / TypeScript: alpha-sdk-typescript
• Python notebook / data collection: alpha-sdk-python
• Swift SDK + macOS sample app: alpha-sdk-swift

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/api

The 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> <scope> web-api  # install REST API docs MCP server

Programmatic 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/shutdown

Options

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 lines

End-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";

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.properties.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, slotNumber: 1 });
const latest = files[files.length - 1];

// 5. Download the photo to the host. Returns an AsyncOperationResponse —
//    the server pulls bytes from the camera in the background and writes to
//    the configured save path. Watch the `downloadComplete` SSE event for
//    the final file path (see docs/recipes for the SSE pattern).
await client.sdCard.download({
  cameraId,
  slotNumber: 1,
  contentId: latest.contentId,
  fileId: latest.fileId,
  body: {},
});

// 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, the recipes, and the public example apps:

• alpha-sdk-typescript
• alpha-sdk-python
• alpha-sdk-swift

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.