This is a Rust implementation of Ableton Link, a technology that synchronizes musical beat, tempo, and phase across multiple applications running on one or more devices. Applications on devices connected to a local network discover each other automatically and form a musical session in which each participant can perform independently: anyone can start or stop while still staying in time. Anyone can change the tempo, the others will follow. Anyone can join or leave without disrupting the session.

This Rust crate provides an asynchronous, safe implementation of the Link protocol, leveraging Rust's memory safety guarantees and Tokio's async runtime for efficient network operations.

• Full Link Protocol Support: Implements the complete Ableton Link specification for tempo and timeline synchronization
• Platform-Specific Optimizations: High-performance timing and networking optimized for each platform
• Async/Await: Built on Tokio for efficient asynchronous network operations
• Memory Safe: Leverages Rust's ownership system to prevent common networking and concurrency bugs
• Cross-Platform: Works on macOS, Linux, and Windows with platform-specific optimizations
• Session Management: Automatic peer discovery and session state synchronization
• Start/Stop Sync: Optional synchronization of play/stop states across devices
• Real-time Safe: Provides separate audio and application session state APIs

This Rust implementation is licensed under the GNU General Public License v3.0, consistent with the original Ableton Link project.

Add this to your Cargo.toml :

[dependencies]
ableton-link-rs = "0.1.0"

use ableton_link_rs::link::BasicLink;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new Link instance with 120 BPM
    let mut link = BasicLink::new(120.0).await;
    
    // Enable Link (starts network discovery)
    link.enable().await;
    
    // Capture current session state
    let mut session_state = link.capture_app_session_state();
    
    // Get current tempo
    println!("Current tempo: {} BPM", session_state.tempo());
    
    // Change tempo
    let current_time = link.clock().micros();
    session_state.set_tempo(140.0, current_time);
    
    // Commit changes back to Link
    link.commit_app_session_state(session_state).await;
    
    Ok(())
}

The project includes a Rust version of LinkHut, demonstrating basic Link functionality:

# Clone the repository
git clone https://github.com/anweiss/ableton-link-rs.git
cd ableton-link-rs

# Build the project
cargo build

# Run the RustHut example natively
cargo run --example rusthut

For containerized deployment, you can run the rusthut example in Docker:

# Build the Docker image
docker build -t rusthut-app .

# Run the container with interactive mode and host networking
docker run -it --network host rusthut-app

Host networking is recommended for optimal Ableton Link peer discovery across the network.

The rusthut example provides an interactive command-line interface similar to the original LinkHut:

• a: Enable/disable Link
• space: Start/stop playback
• w/e: Decrease/increase tempo
• r/t: Decrease/increase quantum
• s: Enable/disable start/stop sync
• q: Quit

The platform_demo example showcases the platform-specific optimizations:

# Run the platform optimizations demo
cargo run --example platform_demo

This demo demonstrates:

• High-resolution platform-specific timing performance
• Optimized network interface discovery
• Platform-specific thread naming
• Performance comparisons with generic implementations

The main entry point for using Ableton Link:

// Create a new Link instance
let mut link = BasicLink::new(120.0).await;

// Enable/disable Link
link.enable().await;
link.disable().await;

// Check status
let is_enabled = link.is_enabled();
let peer_count = link.num_peers();

// Session state management
let session_state = link.capture_app_session_state();
link.commit_app_session_state(session_state).await;

Represents the current state of the Link session:

let mut state = link.capture_app_session_state();

// Tempo operations
let tempo = state.tempo();
state.set_tempo(140.0, current_time);

// Beat/time operations
let beat = state.beat_at_time(current_time, 4.0);
let time = state.time_at_beat(1.0, 4.0);
let phase = state.phase_at_time(current_time, 4.0);

// Start/stop operations
state.set_is_playing(true, current_time);
let is_playing = state.is_playing();

For real-time audio applications, use the audio-specific session state methods:

// In your audio callback
let session_state = link.capture_audio_session_state();

// Use session_state to sync your audio...

// If you need to modify state from audio thread
link.commit_audio_session_state(modified_state);

Note: The current implementation's audio session state methods are placeholders. For production audio applications, these would need to be implemented with lock-free, real-time safe mechanisms.

The Link implementation uses platform-specific high-resolution clocks for precise time handling:

use chrono::Duration;

let clock = link.clock();
let current_time = clock.micros(); // Returns Duration since epoch in microseconds

The Clock abstraction provides platform-specific implementations for obtaining high-resolution system time, essential for accurate synchronization:

• macOS: Uses mach_absolute_time() for maximum precision
• Linux: Uses clock_gettime() with CLOCK_MONOTONIC_RAW for best performance
• Windows: Uses QueryPerformanceCounter() for high-resolution timing
• Other platforms: Falls back to standard library timing

This implementation includes comprehensive platform-specific optimizations that match the performance characteristics of the official C++ Link library:

• macOS/iOS: mach_absolute_time() with cached mach_timebase_info() conversion factors
• Linux: clock_gettime() with CLOCK_MONOTONIC_RAW, falling back to CLOCK_MONOTONIC
• Windows: QueryPerformanceCounter() with cached frequency conversion factors

• POSIX platforms: Direct getifaddrs() system calls with optimized two-pass IPv4/IPv6 scanning
• Windows: Native GetAdaptersAddresses() API with proper adapter filtering
• Performance: Significantly faster than generic cross-platform alternatives

• macOS: pthread_setname_np(name) for improved debugging
• Linux: pthread_setname_np(thread, name) for thread identification
• Windows: SetThreadDescription() when available (Windows 10+)

These optimizations provide:

• ~37ns per clock read performance (measured on macOS)
• Faster network interface discovery with reduced allocations
• Better debugging experience with properly named threads
• Full compatibility with the C++ implementation's performance characteristics

The Rust implementation is structured with the following key modules:

• link: Main Link API and session management
• discovery: Peer discovery and network messaging
• clock: Platform-specific time sources
• timeline: Beat/tempo/phase calculations
• controller: Session state management and coordination

Key dependencies include:

• tokio: Async runtime for network operations
• chrono: Precise time handling
• bincode: Efficient serialization for network messages
• socket2: Low-level socket operations
• tracing: Structured logging

Contributions are welcome! Please ensure that:

1. All tests pass: cargo test
2. Code is formatted: cargo fmt
3. No clippy warnings: cargo clippy
4. Documentation is updated for new features

For more information about Ableton Link concepts and theory:

• Official Ableton Link Documentation
• Rust API Documentation (when published)

This implementation aims for full compatibility with the official Ableton Link specification and should interoperate seamlessly with applications using the official C++ Link library.

This is an early-stage implementation. While the core Link protocol is implemented and functional, some areas may need additional work for production use:

• Audio thread real-time safety optimizations
• Platform-specific optimizations
• Additional testing and validation

For questions about this Rust implementation, please open an issue on GitHub. For general Ableton Link questions or licensing inquiries, contact link-devs@ableton.com.