@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

npm install @argmax/local-server

Getting the Argmax Local Server Binary

Get the Argmax Local Server binary from Argmax.
For support, contact [email protected].

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

# 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:

# 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

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

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

# 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.

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

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

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:

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

# 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 [email protected].