@hotlap.ai/telemetry 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,135 @@
+# Contributing to @hotlap/telemetry
+
+Thank you for your interest in contributing to the HotLap.ai telemetry SDK!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/telemetry.git
+   cd telemetry
+   ```
+3. Install dependencies:
+   ```bash
+   bun install
+   ```
+4. Create a branch for your changes:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0.0
+- Windows (required for live telemetry testing)
+- iRacing (for testing live telemetry features)
+
+### Running the Project
+
+```bash
+# Run the CLI in watch mode
+bun run dev
+
+# Run the telemetry server
+bun run server
+
+# Run tests
+bun run test
+
+# Run benchmarks
+bun run bench
+
+# Type check
+bun run typecheck
+```
+
+### Project Structure
+
+```
+src/
+  binary-reader.ts  # Low-level binary parsing utilities
+  cli.ts            # Command-line interface
+  constants.ts      # iRacing SDK constants and enums
+  ibt.ts            # IBT file parser
+  index.ts          # Main exports
+  live.ts           # Live telemetry via Windows FFI
+  telemetry-server.ts  # WebSocket server for streaming
+  types.ts          # TypeScript type definitions
+```
+
+## Code Style
+
+- Use TypeScript for all new code
+- Follow existing code patterns and naming conventions
+- Use meaningful variable and function names
+- Keep functions focused and small
+- Add types for all function parameters and return values
+
+## Commit Messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat` - New feature
+- `fix` - Bug fix
+- `docs` - Documentation only
+- `style` - Code style (formatting, etc.)
+- `refactor` - Code refactoring
+- `perf` - Performance improvement
+- `test` - Adding/updating tests
+- `chore` - Maintenance tasks
+
+**Examples:**
+```
+feat(ibt): add support for parsing stint data
+fix(live): handle disconnection gracefully
+docs: update API reference for IRSDK class
+perf(binary-reader): optimize variable batch reading
+```
+
+## Pull Requests
+
+1. Ensure your code follows the existing style
+2. Update documentation if needed
+3. Add tests for new functionality
+4. Make sure all tests pass: `bun run test`
+5. Make sure types are correct: `bun run typecheck`
+6. Write a clear PR description explaining your changes
+
+## Reporting Issues
+
+When reporting issues, please include:
+
+- Bun version (`bun --version`)
+- Operating system and version
+- iRacing version (if applicable)
+- Steps to reproduce the issue
+- Expected vs actual behavior
+- Any error messages or logs
+
+## Feature Requests
+
+We welcome feature requests! Please open an issue describing:
+
+- The problem you're trying to solve
+- Your proposed solution
+- Any alternatives you've considered
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 HotLap.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# @hotlap.ai/telemetry
+
+High-performance iRacing telemetry SDK for [Bun](https://bun.sh). Parse IBT telemetry files and stream live data from iRacing via Windows shared memory.
+
+## Features
+
+- **IBT File Parsing** - Read and analyze iRacing telemetry binary files (.ibt)
+- **Live Telemetry** - Stream real-time data from iRacing via Windows shared memory (FFI)
+- **WebSocket Server** - Built-in telemetry server for real-time data streaming
+- **Full TypeScript Support** - Complete type definitions for all APIs
+- **High Performance** - Optimized binary parsing with minimal allocations
+
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.0.0
+- Windows (for live telemetry features)
+- iRacing (for live telemetry)
+
+## Installation
+
+```bash
+bun add @hotlap.ai/telemetry
+```
+
+## Usage
+
+### Parse IBT Files
+
+```typescript
+import { IBT } from '@hotlap.ai/telemetry';
+
+const ibt = new IBT();
+await ibt.open('./telemetry.ibt');
+
+// Get session info
+const weekendInfo = ibt.getSessionInfo('WeekendInfo');
+console.log(`Track: ${weekendInfo.TrackDisplayName}`);
+
+// Read telemetry data
+const speed = ibt.get('Speed', 0); // Get speed at tick 0
+const allSpeeds = ibt.getAll('Speed'); // Get all speed values
+
+// Iterate through records
+for (let i = 0; i < ibt.recordCount; i++) {
+  const lap = ibt.get('Lap', i);
+  const throttle = ibt.get('Throttle', i);
+  const brake = ibt.get('Brake', i);
+}
+```
+
+### Live Telemetry
+
+```typescript
+import { createIRSDK } from '@hotlap.ai/telemetry';
+
+const ir = createIRSDK();
+
+// Connect to iRacing
+const connected = await ir.startup();
+if (!connected) {
+  console.error('Failed to connect to iRacing');
+  process.exit(1);
+}
+
+// Read live telemetry
+setInterval(() => {
+  if (ir.isConnected) {
+    ir.freezeVarBufferLatest();
+
+    const speed = ir.get('Speed');
+    const rpm = ir.get('RPM');
+    const gear = ir.get('Gear');
+
+    console.log(`Speed: ${speed}, RPM: ${rpm}, Gear: ${gear}`);
+
+    ir.unfreezeVarBufferLatest();
+  }
+}, 16); // ~60Hz
+
+// Cleanup on exit
+process.on('SIGINT', () => {
+  ir.shutdown();
+  process.exit(0);
+});
+```
+
+### WebSocket Telemetry Server
+
+```typescript
+import { spawn } from 'bun';
+
+// Start the telemetry server
+const server = spawn(['bun', 'run', 'server'], {
+  cwd: './node_modules/@hotlap.ai/telemetry',
+});
+
+// Connect from client
+const ws = new WebSocket('ws://127.0.0.1:32100/ws');
+
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+
+  switch (msg.type) {
+    case 'session_info':
+      console.log(`Track: ${msg.data.trackDisplayName}`);
+      break;
+    case 'telemetry':
+      console.log(`Speed: ${msg.data.speed}`);
+      break;
+    case 'lap_change':
+      console.log(`Lap ${msg.data.fromLap} completed: ${msg.data.lapTime}`);
+      break;
+  }
+};
+```
+
+## API Reference
+
+### IBT Class
+
+Parse and read iRacing telemetry binary files.
+
+| Method | Description |
+|--------|-------------|
+| `open(path)` | Open an IBT file asynchronously |
+| `get(varName, tick)` | Get a telemetry value at a specific tick |
+| `getAll(varName)` | Get all values for a telemetry variable |
+| `getSessionInfo(key)` | Get parsed session info by key |
+| `getRawSessionInfo()` | Get raw YAML session info string |
+
+| Property | Description |
+|----------|-------------|
+| `recordCount` | Number of telemetry records |
+| `sessionLapCount` | Number of laps in session |
+| `tickRate` | Telemetry sample rate (typically 60Hz) |
+| `varHeaderNames` | List of available telemetry variables |
+
+### IRSDK Class
+
+Connect to iRacing and read live telemetry data.
+
+| Method | Description |
+|--------|-------------|
+| `startup()` | Connect to iRacing shared memory |
+| `shutdown()` | Disconnect and cleanup |
+| `get(varName)` | Get current value of a telemetry variable |
+| `getSessionInfo(key)` | Get parsed session info by key |
+| `freezeVarBufferLatest()` | Freeze telemetry buffer for consistent reads |
+| `unfreezeVarBufferLatest()` | Unfreeze telemetry buffer |
+
+| Property | Description |
+|----------|-------------|
+| `isConnected` | Whether connected to iRacing |
+| `isInitialized` | Whether SDK is initialized |
+| `sessionInfoUpdate` | Session info update counter |
+
+### Broadcast Commands
+
+Control iRacing camera, replay, and more:
+
+```typescript
+ir.camSwitchPos(position, group, camera);
+ir.camSwitchNum(carNumber, group, camera);
+ir.replaySetPlaySpeed(speed, slowMotion);
+ir.replaySearch(searchMode);
+ir.chatCommand(chatCommandMode);
+ir.pitCommand(pitCommandMode, variable);
+```
+
+## Common Telemetry Variables
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `Speed` | float | Vehicle speed (m/s) |
+| `RPM` | float | Engine RPM |
+| `Gear` | int | Current gear (-1=R, 0=N, 1-6=gears) |
+| `Throttle` | float | Throttle position (0-1) |
+| `Brake` | float | Brake position (0-1) |
+| `Clutch` | float | Clutch position (0-1) |
+| `SteeringWheelAngle` | float | Steering angle (radians) |
+| `Lap` | int | Current lap number |
+| `LapDistPct` | float | Lap completion percentage (0-1) |
+| `LapCurrentLapTime` | float | Current lap time (seconds) |
+| `SessionTime` | float | Session time (seconds) |
+| `FuelLevel` | float | Fuel remaining (liters) |
+| `OilTemp` | float | Oil temperature (C) |
+| `WaterTemp` | float | Water temperature (C) |
+
+See iRacing SDK documentation for the complete list of variables.
+
+## Scripts
+
+```bash
+bun run build        # Build the library
+bun run build:server # Build standalone telemetry server executable
+bun run server       # Run telemetry WebSocket server
+bun run dev          # Run CLI in watch mode
+bun run test         # Run tests
+bun run bench        # Run benchmarks
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

package/dist/binary-reader.d.ts

@@ -0,0 +1,18 @@
+import type { VarType } from './constants';
+import type { Header, VarBuffer, VarHeader, DiskSubHeader } from './types';
+export declare function readInt32LE(view: DataView, offset: number): number;
+export declare function readUint32LE(view: DataView, offset: number): number;
+export declare function readFloat32LE(view: DataView, offset: number): number;
+export declare function readFloat64LE(view: DataView, offset: number): number;
+export declare function readBigUint64LE(view: DataView, offset: number): bigint;
+export declare function readBoolLE(view: DataView, offset: number): boolean;
+export declare function readCharLE(view: DataView, offset: number): number;
+export declare function readString(buffer: Uint8Array, offset: number, length: number): string;
+export declare function readVarValue(view: DataView, offset: number, type: VarType, count: number): number | number[] | boolean | boolean[];
+export declare function readVarValueBatch<T extends Float32Array | Float64Array | Int32Array | Uint32Array>(view: DataView, baseOffset: number, varOffset: number, type: VarType, bufLen: number, recordCount: number, output: T): void;
+export declare function parseHeader(view: DataView): Header;
+export declare function parseVarHeader(view: DataView, buffer: Uint8Array, offset: number): VarHeader;
+export declare function parseDiskSubHeader(view: DataView, offset: number): DiskSubHeader;
+export declare function parseVarHeaders(view: DataView, buffer: Uint8Array, header: Header): Map<string, VarHeader>;
+export declare function getLatestVarBuffer(varBufs: VarBuffer[]): VarBuffer;
+//# sourceMappingURL=binary-reader.d.ts.map

package/dist/binary-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-reader.d.ts","sourceRoot":"","sources":["../src/binary-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI3E,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAElE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrF;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,GAAG,OAAO,EAAE,CAkCzC;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,YAAY,GAAG,YAAY,GAAG,UAAU,GAAG,WAAW,EAChG,IAAI,EAAE,QAAQ,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,GACR,IAAI,CA0BN;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAkClD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAU5F;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAQhF;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAO1G;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,SAAS,CAmBlE"}

package/dist/binary-reader.js

@@ -0,0 +1,206 @@
+// @bun
+import {
+  VAR_TYPE_SIZES
+} from "./constants.js";
+
+// src/binary-reader.ts
+var textDecoder = new TextDecoder;
+function readInt32LE(view, offset) {
+  return view.getInt32(offset, true);
+}
+function readUint32LE(view, offset) {
+  return view.getUint32(offset, true);
+}
+function readFloat32LE(view, offset) {
+  return view.getFloat32(offset, true);
+}
+function readFloat64LE(view, offset) {
+  return view.getFloat64(offset, true);
+}
+function readBigUint64LE(view, offset) {
+  return view.getBigUint64(offset, true);
+}
+function readBoolLE(view, offset) {
+  return view.getUint8(offset) !== 0;
+}
+function readCharLE(view, offset) {
+  return view.getInt8(offset);
+}
+function readString(buffer, offset, length) {
+  let end = offset;
+  const maxEnd = offset + length;
+  while (end < maxEnd && buffer[end] !== 0)
+    end++;
+  return textDecoder.decode(buffer.subarray(offset, end));
+}
+function readVarValue(view, offset, type, count) {
+  const size = VAR_TYPE_SIZES[type];
+  if (count === 1) {
+    switch (type) {
+      case 0:
+        return readCharLE(view, offset);
+      case 1:
+        return readBoolLE(view, offset);
+      case 2:
+        return readInt32LE(view, offset);
+      case 3:
+        return readUint32LE(view, offset);
+      case 4:
+        return readFloat32LE(view, offset);
+      case 5:
+        return readFloat64LE(view, offset);
+    }
+  }
+  if (type === 1) {
+    const result2 = new Array(count);
+    for (let i = 0;i < count; i++) {
+      result2[i] = readBoolLE(view, offset + i);
+    }
+    return result2;
+  }
+  const result = new Array(count);
+  for (let i = 0;i < count; i++) {
+    const pos = offset + i * size;
+    switch (type) {
+      case 0:
+        result[i] = readCharLE(view, pos);
+        break;
+      case 2:
+        result[i] = readInt32LE(view, pos);
+        break;
+      case 3:
+        result[i] = readUint32LE(view, pos);
+        break;
+      case 4:
+        result[i] = readFloat32LE(view, pos);
+        break;
+      case 5:
+        result[i] = readFloat64LE(view, pos);
+        break;
+    }
+  }
+  return result;
+}
+function readVarValueBatch(view, baseOffset, varOffset, type, bufLen, recordCount, output) {
+  const size = VAR_TYPE_SIZES[type];
+  let writeIdx = 0;
+  switch (type) {
+    case 4:
+      for (let i = 0;i < recordCount; i++) {
+        output[writeIdx++] = view.getFloat32(baseOffset + i * bufLen + varOffset, true);
+      }
+      break;
+    case 5:
+      for (let i = 0;i < recordCount; i++) {
+        output[writeIdx++] = view.getFloat64(baseOffset + i * bufLen + varOffset, true);
+      }
+      break;
+    case 2:
+      for (let i = 0;i < recordCount; i++) {
+        output[writeIdx++] = view.getInt32(baseOffset + i * bufLen + varOffset, true);
+      }
+      break;
+    case 3:
+      for (let i = 0;i < recordCount; i++) {
+        output[writeIdx++] = view.getUint32(baseOffset + i * bufLen + varOffset, true);
+      }
+      break;
+  }
+}
+function parseHeader(view) {
+  const version = readInt32LE(view, 0);
+  const status = readInt32LE(view, 4);
+  const tickRate = readInt32LE(view, 8);
+  const sessionInfoUpdate = readInt32LE(view, 12);
+  const sessionInfoLen = readInt32LE(view, 16);
+  const sessionInfoOffset = readInt32LE(view, 20);
+  const numVars = readInt32LE(view, 24);
+  const varHeaderOffset = readInt32LE(view, 28);
+  const numBuf = readInt32LE(view, 32);
+  const bufLen = readInt32LE(view, 36);
+  const varBuf = new Array(numBuf);
+  for (let i = 0;i < numBuf; i++) {
+    const offset = 48 + i * 16;
+    varBuf[i] = {
+      tickCount: readInt32LE(view, offset),
+      bufOffset: readInt32LE(view, offset + 4)
+    };
+  }
+  return {
+    version,
+    status,
+    tickRate,
+    sessionInfoUpdate,
+    sessionInfoLen,
+    sessionInfoOffset,
+    numVars,
+    varHeaderOffset,
+    numBuf,
+    bufLen,
+    varBuf
+  };
+}
+function parseVarHeader(view, buffer, offset) {
+  return {
+    type: readInt32LE(view, offset),
+    offset: readInt32LE(view, offset + 4),
+    count: readInt32LE(view, offset + 8),
+    countAsTime: readBoolLE(view, offset + 12),
+    name: readString(buffer, offset + 16, 32),
+    desc: readString(buffer, offset + 48, 64),
+    unit: readString(buffer, offset + 112, 32)
+  };
+}
+function parseDiskSubHeader(view, offset) {
+  return {
+    sessionStartDate: readBigUint64LE(view, offset),
+    sessionStartTime: readFloat64LE(view, offset + 8),
+    sessionEndTime: readFloat64LE(view, offset + 16),
+    sessionLapCount: readInt32LE(view, offset + 24),
+    sessionRecordCount: readInt32LE(view, offset + 28)
+  };
+}
+function parseVarHeaders(view, buffer, header) {
+  const headers = new Map;
+  for (let i = 0;i < header.numVars; i++) {
+    const varHeader = parseVarHeader(view, buffer, header.varHeaderOffset + i * 144);
+    headers.set(varHeader.name, varHeader);
+  }
+  return headers;
+}
+function getLatestVarBuffer(varBufs) {
+  if (varBufs.length === 0) {
+    throw new Error("varBufs array is empty");
+  }
+  let latest = varBufs[0];
+  let secondLatest = varBufs[1] ?? varBufs[0];
+  for (let i = 1;i < varBufs.length; i++) {
+    const current = varBufs[i];
+    if (current.tickCount > latest.tickCount) {
+      secondLatest = latest;
+      latest = current;
+    } else if (current.tickCount > secondLatest.tickCount) {
+      secondLatest = current;
+    }
+  }
+  return secondLatest;
+}
+export {
+  readVarValueBatch,
+  readVarValue,
+  readUint32LE,
+  readString,
+  readInt32LE,
+  readFloat64LE,
+  readFloat32LE,
+  readCharLE,
+  readBoolLE,
+  readBigUint64LE,
+  parseVarHeaders,
+  parseVarHeader,
+  parseHeader,
+  parseDiskSubHeader,
+  getLatestVarBuffer
+};
+
+export { readInt32LE, readUint32LE, readFloat32LE, readFloat64LE, readBigUint64LE, readBoolLE, readCharLE, readString, readVarValue, readVarValueBatch, parseHeader, parseVarHeader, parseDiskSubHeader, parseVarHeaders, getLatestVarBuffer };

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}