spice-client

中文 | English

A TypeScript port of spice-html5 - a JavaScript client for the SPICE protocol.

Attribution

This project is a TypeScript port of the original spice-html5 project.

• Original Project: https://gitlab.freedesktop.org/spice/spice-html5.git
• Original Authors: SPICE Project [email protected] (https://www.spice-space.org)
• Original License: LGPL-3.0-or-later

All credit goes to the original authors. This project simply:

• Converted the JavaScript code to TypeScript
• Added unit tests
• Implemented a modern build process with Vite
• Added LZ4 image compression support
• Optimized message processing to handle multiple ArrayBuffers directly, avoiding buffer concatenation overhead
• Uses native DataView for single ArrayBuffer operations, falling back to custom SpiceDataView only for multi-buffer scenarios
• Improved mouse motion handling with queue + collapse strategy and requestIdleCallback for smoother input

The TypeScript conversion and build setup code was generated with the assistance of the GLM-5 model in Trae Solo Coder mode.

License

This project is licensed under the GNU Lesser General Public License v3.0 or later - see the LICENSE file for details.

This project includes copies of:

• COPYING - GNU General Public License v3.0
• COPYING.LESSER - GNU Lesser General Public License v3.0

Installation

npm install spice-client

Usage

ES Modules

import { SpiceMainConn, Constants } from 'spice-client';

const spice = new SpiceMainConn({
  uri: 'ws://localhost:5959',
  password: 'your-password',
  onsuccess: () => console.log('Connected!'),
  onerror: (e) => console.error('Error:', e)
});

CommonJS

const { SpiceMainConn, Constants } = require('spice-client');

Browser Global (IIFE)

Include the minified bundle:

<script src="node_modules/spice-client/dist/global/spice-client.min.js"></script>
<script>
  const spice = new SpiceClient.SpiceMainConn({
    uri: 'ws://localhost:5959',
    password: 'your-password'
  });
</script>

Requirements

1. A modern browser (Firefox, Chrome, or Edge)
2. A WebSocket proxy (e.g., websockify)
3. A SPICE server

Quick Start

1. Start your SPICE server
2. Start websockify:

   websockify 5959 localhost:5900

3. Connect using the client

API

Exports

| Export | Description | |--------|-------------| | SpiceMainConn | Main SPICE connection class | | SpiceConn | Base SPICE connection | | SpiceDisplayConn | Display channel connection | | SpiceInputsConn | Inputs (keyboard/mouse) channel | | SpiceCursorConn | Cursor channel connection | | SpicePlaybackConn | Audio playback channel | | SpicePortConn | Port channel connection | | Constants | SPICE protocol constants | | SpiceEventType | Event type definitions | | SpiceEventHandlers | Event handler type definitions | | handle_file_dragover | File drag handler | | handle_file_drop | File drop handler | | resize_helper | Resize helper function | | handle_resize | Resize handler | | sendCtrlAltDel | Send Ctrl+Alt+Del sequence |

Events

The SpiceMainConn class supports event registration using on() and off() methods.

connection_status

Emitted when the connection status changes.

spice.on('connection_status', (status) => {
  console.log('Connection status:', status);
  // Possible values: 'connecting', 'connected', 'error', 'disconnected'
});

keyboard_modifiers

Emitted when keyboard modifier keys (NumLock, CapsLock, ScrollLock) state changes.

spice.on('keyboard_modifiers', (modifiers) => {
  console.log('NumLock:', modifiers.num_lock);
  console.log('CapsLock:', modifiers.caps_lock);
  console.log('ScrollLock:', modifiers.scroll_lock);
});

Build

# Build all formats (ESM, CJS, global minified)
npm run build

Build output:

dist/
├── esm/           # ES Module build
├── cjs/           # CommonJS build
└── global/        # Minified IIFE for browsers

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run e2e tests
npm run test:e2e

Related Projects

• spice-html5 - Original JavaScript implementation
• websockify - WebSocket to TCP proxy
• SPICE Project - Official SPICE project
• Electerm - Terminal/SSH/SFTP/Spice/Telnet/Ftp/RDP/VNC/Serial client using this library