CC Audio Expand

English | 中文

A mod that extends CC: Tweaked's speaker peripheral with PCM audio playback capabilities.

Introduction

CC Audio Expand adds high-quality PCM audio playback support to ComputerCraft: Tweaked's speaker peripheral, solving audio synchronization and playback smoothness issues in the vanilla implementation.

Core Features

Multiple Format Support

• PCM_S16LE (16-bit signed little-endian)
• PCM_U8 (8-bit unsigned)
• PCM_S8 (8-bit signed)

Intelligent Audio Synchronization

• Timestamp-based synchronization: Each audio packet carries a server-side send timestamp
• Automatic stale data skipping: Client detects and skips audio packets that have been queued for more than 200ms
• Fast recovery: Automatically catches up to server playback progress after lag

Anti-Lag Optimization

• Improved pump strategy: More proactive audio engine wake-up
• Persistent keep-alive mechanism: Reduces "~1 second audio reception pauses"
• Smart buffer management: Dynamically adjusts pump count based on queue status

Technical Highlights

Timestamp-based Synchronization

// Server records timestamp when sending
packet.sendTimestampNanos = System.nanoTime();

// Client detects stale data
long age = System.nanoTime() - arrivalTime;
if (age > 200_000_000L) {  // 200ms
    // Skip stale audio packet
    buffers.remove();
}

Improved Wake-up Strategy

// More aggressive pump mechanism
pumpBuffers(currentChannel, wasEmpty ? 1 : 2);
// Pump 1 buffer when empty, 2 when not

Problems Solved

This mod references and solves upstream CC: Tweaked issues:

• Issue #2120 - Client-server audio desync When the client experiences lag or volume is set to 0, playback resumes with old queued audio, causing severe desynchronization with the server.

• PR #2412 - Failed fix attempt This PR attempted to solve the problem using sample counting but was rejected by maintainers, who required "must use time, not sample count". This mod adopts the correct timestamp-based approach.

Installation

Requirements

• Minecraft 1.20.1 (Forge) or 1.21.1 (NeoForge)
• CC: Tweaked 1.118.0 or higher

Download

Choose the appropriate JAR file for your Minecraft version:

• Forge 1.20.1: cc-audio-expand-forge-1.20.1-0.2.0-SNAPSHOT.jar
• NeoForge 1.21.1: cc-audio-expand-neoforge-1.21.1-0.2.0-SNAPSHOT.jar

Installation Steps

1. Ensure CC: Tweaked 1.118.0+ is installed
2. Place the downloaded JAR file in your mods folder
3. Launch the game; speakers will automatically support PCM audio playback

Version History

0.2.0-SNAPSHOT (Current)

• ✨ Added timestamp-based audio synchronization
• ⚡ Improved audio engine wake-up strategy
• 🔧 Set stale data threshold to 200ms
• 📄 Adopted MIT License

0.1.0-SNAPSHOT (Initial Release)

• 🎵 Basic PCM audio playback support
• 🔄 Multiple audio format support

Technical Specifications

Item	Description
Current Version	0.2.0-SNAPSHOT
Supported Platforms	Forge 1.20.1 / NeoForge 1.21.1
Dependencies	CC: Tweaked 1.118.0+
License	MIT License
Author	HKXluo

How It Works

1. Data Flow

Server Audio Source
    ↓ (Add timestamp)
SpeakerAudioPacket
    ↓ (Network transmission)
Client Reception
    ↓ (Record arrival time)
SpeakerPcmStream Queue
    ↓ (Check data age)
Audio Engine Playback

2. Synchronization Strategy

• Normal Operation: Packets arrive and are consumed quickly, residence time < 200ms
• Lag Occurs: Audio engine stops reading, queue builds up
• Recovery: Stale data detected (age > 200ms), automatically skipped
• Fast Catch-up: Continuously skip old data until finding the latest packet

3. Design Principles

• ✅ Use time instead of sample count
• ✅ Maintain server-side flow control
• ✅ Independent per-packet judgment
• ✅ No playback speed changes

API Documentation

For detailed API usage, please refer to:

• 中文文档
• English Documentation

Development

Building

./gradlew build

Build artifacts are located in the build/dist/ directory.

Project Structure

cc-audio-expand/
├── common/                     # Shared code
│   └── src/main/java/cc/speaker/
│       ├── SpeakerAudioPacket.java
│       ├── SpeakerPcmStream.java
│       └── SpeakerPcmQueue.java
├── platforms/
│   ├── forge-1.20.1/          # Forge platform implementation
│   └── neoforge-1.21.1/       # NeoForge platform implementation
└── stubs/                     # API stubs

License

This project is licensed under the MIT License.

Contributing

Issues and Pull Requests are welcome.