npm package: @argmaxinc/local-server
Description: Library for managing Argmax Local Server on macOS
Author: Argmax, Inc.
Latest version: 0.0.5

# @argmax/local-server

Node.js wrapper for managing Argmax Local Server on macOS

## Overview

A Node.js wrapper for the Argmax Local Server binary that provides:
- **Process management** - Start, stop, and monitor the server 
- **REST API client** - Interface with server endpoints
- **WebSocket transcription** - Real-time speech-to-text
- **CLI tool** - Command-line interface for server management

## Installation

```bash
npm install @argmax/local-server
```

## Getting the Argmax Local Server Binary

Get the Argmax Local Server binary from [Argmax](https://www.argmaxinc.com/blog/argmax-local-server).  
For support, contact [support@argmaxinc.com](mailto:support@argmaxinc.com).

## Development CLI Wrapper

For development purposes, this package includes a `create-dev-cli.sh` script that creates a signed CLI wrapper. This is useful when you need to run the Argmax Local Server binary through a wrapper for development or testing.

### Creating the Development CLI

```bash
# Create a signed dev_cli binary (requires macOS with Xcode command line tools)
./node_modules/@argmaxinc/local-server/dist/create-dev-cli.sh <TEAM_ID>
```

This will create a `dev_cli` binary that can be used as a launch wrapper:

```bash
# Use the dev_cli as a launch wrapper
npx @argmax/local-server start --launch-wrapper ./dev_cli --binary /path/to/argmax-local-server
```

**Note:** This script is intended for development use only and requires:
- macOS with Xcode command line tools installed
- Valid Apple Developer code signing certificate
- Team ID for code signing

## Quick Start

### Basic Usage

```typescript
import { ArgmaxLocalServer } from '@argmax/local-server';

const server = new ArgmaxLocalServer({
  binaryPath: '/path/to/argmax-local-server',
  apiKey: 'your-api-key'
});

// Start the server
await server.startProcess();

// Initialize with a model
await server.init({ 
  apiKey: 'your-api-key',
  model: 'tiny.en' 
});

// Wait for ready
await server.waitForReady();

// Get status
const status = await server.status();
console.log('Server status:', status);

// Clean shutdown
await server.shutdown();
await server.stopProcess();
```

### Real-time Transcription

```typescript
// Create transcriber
const transcriber = server.createTranscriber({ source: 'microphone' });

// Set up event listeners
transcriber.on('transcription', (result) => {
  if (result.isFinal) {
    console.log(`[FINAL] ${result.transcript}`);
  } else {
    console.log(`[INTERIM] ${result.transcript}`);
  }
});

// Connect and start transcribing
await transcriber.connect({
  keywords: ['Argmax', 'AI', 'transcription'],
});
```

## CLI Usage

```bash
# Start server
npx @argmax/local-server start --binary /path/to/argmax-local-server

# Start with launch wrapper for development
npx @argmax/local-server start --launch-wrapper /path/to/wrapper --binary /path/to/argmax-local-server

# Check status
npx @argmax/local-server status

# Initialize with model
npx @argmax/local-server init --api-key your-key --model tiny.en

# Real-time transcription
npx @argmax/local-server transcribe --api-key your-key
```

## API Reference

### ArgmaxLocalServer

Main class for server management.

```typescript
constructor(config: ArgmaxLocalServerConfig)
```

**Methods:**
- `startProcess()` - Start the server process
- `stopProcess()` - Stop the server process  
- `status()` - Get server status
- `init(config)` - Initialize server with model
- `waitForReady(timeout?)` - Wait for server to be ready
- `reset()` - Reset server state
- `shutdown()` - Shutdown server
- `createTranscriber(options?)` - Create WebSocket transcriber

### Configuration

```typescript
interface ArgmaxLocalServerConfig {
  binaryPath: string;           // Path to argmax-local-server binary
  launchWrapper?: string | string[]; // Optional wrapper command/script to launch the binary
  host?: string;                // Server host (default: localhost)
  port?: number;                // Server port (default: 50060)  
  apiKey?: string;              // Argmax API key (ax_your_key from https://app.argmaxinc.com/)
  autoRestart?: boolean;        // Auto-restart on failure (default: true)
  verbose?: boolean;            // Enable verbose logging
  args?: string[];              // Additional CLI arguments
}
```

## Environment Variables

```bash
ARGMAX_SERVER_PATH=/path/to/argmax-local-server
ARGMAX_API_KEY=your-api-key
```

## Deepgram SDK Integration

You can use the Deepgram SDK to connect to your local Argmax server instead of Deepgram's cloud service:

```javascript
const { createClient, LiveTranscriptionEvents } = require("@deepgram/sdk");

// Instead of connecting to Deepgram cloud:
// const deepgram = createClient(process.env.DEEPGRAM_API_KEY);

// Connect to local Argmax server:
// Note: Use your Argmax API key (ax_...) instead of Deepgram API key
const deepgram = createClient(process.env.ARGMAX_API_KEY, {
  global: {
    websocket: {
      options: {
        url: "ws://localhost:50060"
      }
    }
  }
});

// Use the same Deepgram SDK API as usual
const connection = deepgram.listen.live({
  model: "any model here", // ignored
  language: "en",
  smart_format: true, // not supported
  interim_results: true,
  encoding: 'linear16',
  channels: 1,
  sampleRate: 48000
});

connection.on(LiveTranscriptionEvents.Open, () => {
  console.log("Connection opened.");
});

connection.on(LiveTranscriptionEvents.Transcript, (data) => {
  console.log(data.channel.alternatives[0].transcript);
});
```

This allows you to keep your existing Deepgram SDK code while routing requests to your local Argmax server.

**Note:** For testing purposes, you can start the server with `--any-token` to allow any token value.

## Testing

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run with real server binary
ARGMAX_SERVER_PATH=/path/to/binary npm test
```

## License

MIT

## Support

For questions and support, contact [support@argmaxinc.com](mailto:support@argmaxinc.com).