MuNode - Distributed Mumble Server

A modern, distributed Mumble server implementation built with Node.js 22 and TypeScript, featuring Hub-Edge architecture for horizontal scalability.

Features

Core Features

✅ Full Protocol Support - Compatible with Mumble 1.3.x and 1.4.x clients
✅ Distributed Architecture - Hub-Edge design for horizontal scaling
✅ External Authentication - Third-party Web API integration
✅ WebSocket + Protobuf RPC - Type-safe server-to-server communication
✅ Persistent Storage - SQLite with async operations
✅ Voice Encryption - OCB2-AES128 encryption for audio streams

Advanced Features

✅ Intelligent Voice Routing - Optimized audio forwarding with VoiceTarget support
✅ UDP Stability Detection - Automatic fallback to TCP when UDP is unstable
✅ Context Actions System - Right-click menu integration
✅ Multi-dimensional Ban System - IP, certificate, and username-based bans
✅ ACL Inheritance - Hierarchical permission system with group support
✅ Listen Channel Support - Monitor channels without joining
✅ Plugin Data Transmission - Support for positional audio and game plugins
✅ Cross-Edge Voice Relay - Seamless voice transmission across Edge servers

Recent Improvements

✅ Pre-connect User State - Preserve client settings during authentication
✅ Dynamic Permission Refresh - ACL changes take effect immediately
✅ Type-safe RPC System - Protobuf-based type-safe communication
✅ Enhanced Testing - Comprehensive integration test suite (27 test suites, 100+ test cases)

Quick Start

Prerequisites

Node.js >= 22.0.0
pnpm >= 8.0.0

Installation

# Clone the repository
git clone https://github.com/garveen/munode.git
cd munode

# Install dependencies
pnpm install

# Generate Protocol Buffers code
pnpm generate:proto

# Build all packages
pnpm build

Configuration

Copy example configuration files:

cp config/hub.example.json config/hub.json
cp config/edge.example.json config/edge.json

Edit the configuration files to match your environment. See DEPLOYMENT.md for detailed configuration options.

Running

Development Mode

# Start Hub Server
pnpm dev:hub

# Start Edge Server (in another terminal)
pnpm dev:edge

Production Mode

# Build first
pnpm build

# Start Hub Server
pnpm start:hub --config config/hub.json

# Start Edge Server
pnpm start:edge --config config/edge.json

Architecture

Hub-Edge Design

                    ┌─────────────┐
                    │  Hub Server │
                    │  (Central)  │
                    └──────┬──────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
       ┌────▼────┐    ┌────▼────┐   ┌────▼────┐
       │ Edge #1 │    │ Edge #2 │   │ Edge #3 │
       └────┬────┘    └────┬────┘   └────┬────┘
            │              │              │
         Clients        Clients        Clients

Components

Hub Server (`packages/hub-server`)

Central management node
User authentication and authorization
Channel and ACL management
Edge server registry
Data persistence (SQLite)
Cross-edge voice routing coordination

Edge Server (`packages/edge-server`)

Client connection handling
Voice packet processing
Local voice routing
UDP stability detection
Authentication caching
Ban management

Common (`packages/common`)

Shared utilities and types
Configuration management
Logging system
Heartbeat mechanism

Protocol (`packages/protocol`)

Protocol Buffers definitions
Type-safe RPC communication
Mumble protocol implementation
OCB2-AES128 encryption

CLI (`packages/cli`)

Certificate generation
Server management tools

Client (`packages/client`)

Mumble client implementation (for testing)

Project Structure

munode/
├── packages/
│   ├── common/          # Shared utilities, types, logging
│   ├── protocol/        # Mumble protocol, encryption, RPC
│   ├── hub-server/      # Central management server
│   ├── edge-server/     # Edge server for client connections
│   ├── client/          # Mumble client implementation (for testing)
│   └── cli/             # Command-line tools
├── config/              # Configuration files
│   ├── hub.example.js
│   ├── edge.example.js
│   └── client.example.js
├── tests/               # Test suites
│   ├── integration/     # Integration tests (27 test suites)
│   ├── unit/            # Unit tests
│   └── utils/           # Test utilities
├── docs/                # Documentation
├── scripts/             # Build and utility scripts
└── .github/             # GitHub configurations
    └── copilot-instructions.md  # AI coding guidelines

Development

Available Commands

# Development
pnpm dev              # Start all servers in dev mode
pnpm dev:hub          # Start only Hub server
pnpm dev:edge         # Start only Edge server

# Building
pnpm build            # Build all packages
pnpm clean            # Clean build artifacts

# Testing
pnpm test                      # Run unit tests
pnpm test:watch                # Run unit tests in watch mode
pnpm test:integration          # Run integration tests
pnpm test:integration:watch    # Run integration tests in watch mode
pnpm test:integration:ui       # Run integration tests with UI

# Code Quality
pnpm lint             # Lint all packages
pnpm lint:fix         # Fix linting issues
pnpm type-check       # TypeScript type checking
pnpm format           # Format code with Prettier

# Protocol Buffers
pnpm generate:proto   # Generate TS code from .proto files

Integration Tests

The project includes comprehensive integration tests covering:

Authentication (10+ tests) - Password, certificate, token auth
ACL System (15+ tests) - Permissions, inheritance, groups, suppress
Channel Management (11+ tests) - Create, move, link, delete
Voice Transmission (15+ tests) - Normal, whisper, VoiceTarget, loopback
Voice Routing (10+ tests) - Cross-edge routing, quality detection
Hub-Edge Communication (8+ tests) - Registration, sync, routing
Ban System (6+ tests) - IP, certificate, username bans
Plugin System (9+ tests) - Plugin data transmission
UDP Quality (5+ tests) - Connection quality simulation
TCP Voice (8+ tests) - TCP voice fallback
User Visibility (4+ tests) - Cross-edge user state sync
Pre-connect State (3+ tests) - Client state preservation

Total: 27 test suites, 100+ integration test cases

Run tests with:

# Run all integration tests
pnpm test:integration

# Run specific test suite
pnpm test:integration tests/integration/suites/voice.test.ts

# Run tests in watch mode
pnpm test:integration:watch

# Run tests with UI
pnpm test:integration:ui

Configuration

Hub Server Configuration

Key configuration options in config/hub.js:

Network - Host, port, TLS settings
Database - SQLite path, backup settings
Control Channel - WebSocket port for Edge connections
Blob Store - User avatars and channel descriptions
Web API - Optional REST API (for management)
Voice UDP - Shared secret for UDP handshake

Edge Server Configuration

Key configuration options in config/edge.js:

Network - Host, port, region, capacity
Hub Connection - Hub server address, control port, TLS
Authentication - External API configuration
Server Settings - Welcome text, limits, permissions
UDP - Stability detection settings
Ban System - Ban database configuration
Voice Encryption - OCB2-AES128 settings

See configuration examples in the config/ directory.

Deployment

For production deployment:

Build the project:

pnpm install
pnpm generate:proto
pnpm build

Configure servers:

cp config/hub.example.js config/hub.js
cp config/edge.example.js config/edge.js
# Edit configuration files as needed

Generate certificates:
```
pnpm generate:cert
```

Start services:

# Using PM2 (recommended)
pm2 start pnpm --name munode-hub -- start:hub
pm2 start pnpm --name munode-edge -- start:edge

# Or using systemd
# Create systemd service files for hub and edge

System Requirements

CPU: 2+ cores recommended
Memory: 2GB+ RAM (Hub), 4GB+ RAM per Edge (1000 users)
Network: Low latency connection between Hub and Edge servers
Storage: SSD recommended for database

Performance Tuning

Enable UDP for better voice quality
Use dedicated servers for Hub and Edge in production
Configure appropriate maxClients per Edge based on your hardware
Monitor memory usage and adjust Node.js heap size if needed

Documentation

Core Documentation

Copilot Instructions - Coding guidelines and architecture overview
Implementation Comparison - Node vs Go implementation

Technical Documentation (Chinese)

Located in docs/ directory:

API Documentation

Each package contains detailed README files:

packages/common/README.md - Shared utilities
packages/protocol/README.md - Protocol implementation
packages/hub-server/README.md - Hub server API
packages/edge-server/README.md - Edge server API
packages/client/README.md - Client API

Performance

Typical Performance Metrics

Latency (same Edge): ~5-10ms
Latency (cross-Edge): ~20-50ms
Memory per client: ~5-10 MB
CPU usage: Low to moderate (depends on codec)

Scalability

Hub Server: Supports up to 100 Edge servers
Edge Server: 1000 concurrent users per server (recommended)
Total Capacity: 100,000+ users (with 100 Edge servers)

Contributing

We welcome contributions! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow TypeScript strict mode - no any, unknown, or loose types
Prefer interface over type for object types
Use ESModule syntax (not CommonJS)
Write integration tests for new features
Follow existing code style and naming conventions
Update documentation for significant changes

See .github/copilot-instructions.md for detailed coding guidelines.

Running Tests

# Run all tests
pnpm test

# Run unit tests
pnpm test:unit

# Run integration tests
pnpm test:integration

# Run tests in watch mode
pnpm test:integration:watch

License

MIT License - see LICENSE for details

Acknowledgments

This project is inspired by and based on:

Mumble Protocol - The original Mumble VoIP protocol
Grumble - Go implementation of Mumble server
Hall (ShitSpeak) - Go-based Mumble server with enhancements

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Status

Current Version: 0.1.0 (Beta)

Production Ready: ⚠️ Beta stage - suitable for testing and small-to-medium deployments. Thoroughly test in your environment before large-scale production use.

Core Features Status:

✅ Full Mumble protocol support (1.3.x and 1.4.x)
✅ Hub-Edge distributed architecture
✅ Voice transmission (UDP + TCP fallback)
✅ Channel and user management
✅ ACL and permission system
✅ Plugin data transmission
✅ Cross-edge voice routing
✅ External authentication integration

Known Limitations:

⚠️ Blob storage system (avatars, comments) partially implemented
⚠️ Some statistics counters return placeholder values
⚠️ Limited production deployment experience

Test Coverage:

✅ 27 integration test suites
✅ 100+ test cases covering core functionality
✅ All critical features tested and verified

Name		Name	Last commit message	Last commit date
Latest commit History 333 Commits
.github		.github
config		config
docker		docker
docs		docs
features		features
packages		packages
rust		rust
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.nvmrc		.nvmrc
.prettierrc		.prettierrc
CHANNEL_NINJA_IMPLEMENTATION.md		CHANNEL_NINJA_IMPLEMENTATION.md
IMPLEMENTATION_COMPARISON.md		IMPLEMENTATION_COMPARISON.md
README.md		README.md
SETUP_STATUS.md		SETUP_STATUS.md
crypto_benchmark.cjs		crypto_benchmark.cjs
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
tsconfig.json		tsconfig.json
vitest.config.integration.ts		vitest.config.integration.ts
vitest.config.unit.ts		vitest.config.unit.ts

Folders and files

Latest commit

History

Repository files navigation

MuNode - Distributed Mumble Server

Features

Core Features

Advanced Features

Recent Improvements

Quick Start

Prerequisites

Installation

Configuration

Running

Development Mode

Production Mode

Architecture

Hub-Edge Design

Components

Hub Server (packages/hub-server)

Edge Server (packages/edge-server)

Common (packages/common)

Protocol (packages/protocol)

CLI (packages/cli)

Client (packages/client)

Project Structure

Development

Available Commands

Integration Tests

Configuration

Hub Server Configuration

Edge Server Configuration

Deployment

System Requirements

Performance Tuning

Documentation

Core Documentation

Technical Documentation (Chinese)

API Documentation

Performance

Typical Performance Metrics

Scalability

Contributing

Development Guidelines

Running Tests

License

Acknowledgments

Support

Status

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Hub Server (`packages/hub-server`)

Edge Server (`packages/edge-server`)

Common (`packages/common`)

Protocol (`packages/protocol`)

CLI (`packages/cli`)

Client (`packages/client`)