Features

• Connect to any Mumble server over TLS
• Manage channels: create, remove, link/unlink, fetch ACLs
• Manage users: move, mute/deafen, register/deregister, rename
• Query channel permissions
• Event-driven architecture with full TypeScript support
• Automatic keep-alive pinging

Installation

npm i @tf2pickup-org/mumble-client

Quick start

import { Client } from '@tf2pickup-org/mumble-client';

const client = new Client({
  host: 'mumble.example.com',
  port: 64738,
  username: 'my-bot',
  rejectUnauthorized: false,
});

await client.connect();
console.log(`Connected! Welcome message: ${client.welcomeText}`);
console.log(`Logged in as ${client.self?.name}`);

// ... do work ...

client.disconnect();

Examples

Connect with a password and access tokens

const client = new Client({
  host: 'mumble.example.com',
  port: 64738,
  username: 'my-bot',
  password: 'server-password',
  tokens: ['token-for-acl-group'],
  clientName: 'my-awesome-bot',
  rejectUnauthorized: false,
});

await client.connect();

List all channels

import { type Channel } from '@tf2pickup-org/mumble-client';

function printChannel(channel: Channel, level = 0) {
  if (channel.name) {
    console.log(' '.repeat(level * 2) + channel.name);
  }

  for (const subChannel of channel.subChannels) {
    printChannel(subChannel, level + 1);
  }
}

printChannel(client.channels.root);

Find a channel

// by name
const lobby = client.channels.byName('Lobby');

// by path (from root)
const redTeam = client.channels.byPath('Match 1', 'RED');

// by custom predicate
const tempChannels = client.channels.findAll(ch => ch.temporary);

Create and manage channels

const root = client.channels.root;

// create a sub-channel under root
const matchChannel = await root.createSubChannel('Match 1');

// create team channels
const red = await matchChannel.createSubChannel('RED');
const blu = await matchChannel.createSubChannel('BLU');

// link two channels together
await red.link(blu);

// unlink them
await red.unlink(blu);

// remove a channel (and all its sub-channels)
await matchChannel.remove();

Move users between channels

const user = client.users.byName('PlayerOne');
const targetChannel = client.channels.byName('RED');

if (user && targetChannel) {
  await user.moveToChannel(targetChannel.id);
}

Mute/deafen yourself

// self-mute
await client.self.setSelfMute(true);

// self-deafen
await client.self.setSelfDeaf(true);

// unmute
await client.self.setSelfMute(false);

Register and manage users

// register the currently logged-in user
await client.self.register();

// fetch all registered users from the server
const registeredUsers = await client.fetchRegisteredUsers();
for (const user of registeredUsers) {
  console.log(`${user.userId}: ${user.name}`);
}

// rename a registered user (does not need to be online)
await client.renameRegisteredUser(userId, 'NewName');

// deregister a user (does not need to be online)
await client.deregisterUser(userId);

Check channel permissions

const channel = client.channels.byName('Lobby');
if (channel) {
  const permissions = await channel.getPermissions();
  console.log('Can join:', permissions.canJoinChannel);
  console.log('Can create sub-channels:', permissions.canCreateChannel);
  console.log('Can remove:', permissions.canRemoveChannel);
  console.log('Can link:', permissions.canLinkChannel);
}

Listen to events

// user connected
client.on('userCreate', user => {
  console.log(`${user.name} connected`);
});

// user disconnected
client.on('userRemove', user => {
  console.log(`${user.name} disconnected`);
});

// user state changed (e.g. moved channel, muted, etc.)
client.on('userUpdate', (user, changes) => {
  if (changes.channelId) {
    const from = client.channels.byId(changes.channelId.previousValue);
    const to = client.channels.byId(changes.channelId.currentValue);
    console.log(`${user.name} moved from ${from?.name} to ${to?.name}`);
  }
});

// channel created
client.on('channelCreate', channel => {
  console.log(`Channel created: ${channel.name}`);
});

// channel removed
client.on('channelRemove', channel => {
  console.log(`Channel removed: ${channel.name}`);
});

// speaking state changes
client.on('speakingStateChange', ({ user, speaking }) => {
  console.log(`${user.name} ${speaking ? 'started' : 'stopped'} speaking`);
});

// disconnected from server
client.on('disconnect', payload => {
  console.log(`Disconnected: ${payload?.reason ?? 'unknown reason'}`);
});

Error handling

import {
  Client,
  ConnectionRejectedError,
  PermissionDeniedError,
  NoSuchChannelError,
} from '@tf2pickup-org/mumble-client';

try {
  await client.connect();
} catch (error) {
  if (error instanceof ConnectionRejectedError) {
    console.error('Connection rejected by server');
  }
}

try {
  await client.channels.root.createSubChannel('test');
} catch (error) {
  if (error instanceof PermissionDeniedError) {
    console.error('Insufficient permissions to create channel');
  }
}

API overview

Client

The main entry point. Connects to the server and provides access to channels, users, and events.

| Property / Method | Description | |---|---| | channels | ChannelManager instance for finding channels | | users | UserManager instance for finding users | | self | The currently logged-in User | | welcomeText | Server welcome message | | serverVersion | Server version info | | connect() | Connect to the Mumble server | | disconnect() | Disconnect from the server | | isConnected() | Returns true if connected | | fetchRegisteredUsers() | Fetch all registered users | | deregisterUser(userId) | Deregister a user by ID | | renameRegisteredUser(userId, name) | Rename a registered user |

ChannelManager

| Method | Description | |---|---| | root | The root channel | | byId(channelId) | Find channel by ID | | byName(name) | Find channel by name | | byPath(...path) | Find channel by path segments | | find(predicate) | Find first matching channel | | findAll(predicate) | Find all matching channels |

Channel

| Property / Method | Description | |---|---| | id | Channel ID | | name | Channel name | | temporary | Whether the channel is temporary | | users | Users currently in this channel | | subChannels | Direct sub-channels | | linkedChannels | Linked channels | | createSubChannel(name) | Create a sub-channel | | remove() | Remove this channel | | link(channel) | Link with another channel | | unlink(channel) | Unlink from another channel | | getPermissions() | Fetch permissions for this channel | | fetchAcl() | Fetch the channel ACL | | saveAcl(acl) | Save the channel ACL |

UserManager

| Method | Description | |---|---| | bySession(session) | Find user by session ID | | byName(name) | Find user by name | | findAll(predicate) | Find all matching users |

User

| Property / Method | Description | |---|---| | session | Session ID | | name | Username | | channel | Current channel | | channelId | Current channel ID | | isRegistered | Whether the user is registered | | mute / deaf / suppress | Server mute/deaf/suppress state | | selfMute / selfDeaf | Self-mute/deaf state | | moveToChannel(channelId) | Move user to a channel | | setSelfMute(mute) | Set self-mute state | | setSelfDeaf(deaf) | Set self-deaf state | | register() | Register the user | | deregister() | Deregister the user | | rename(name) | Rename a registered user |

Permissions

| Property / Method | Description | |---|---| | canJoinChannel | Can join/enter the channel | | canCreateChannel | Can create sub-channels | | canRemoveChannel | Can remove channels | | canLinkChannel | Can link channels | | canSelfRegister | Can self-register | | canRegister | Can register other users |

Events

| Event | Payload | Description | |---|---|---| | connect | — | Client connected successfully | | disconnect | { reason?: string } | Client disconnected | | channelCreate | Channel | A channel was created | | channelUpdate | Channel, ChannelChanges | A channel was updated | | channelRemove | Channel | A channel was removed | | userCreate | User | A user connected | | userUpdate | User, UserChanges | A user's state changed | | userRemove | User | A user disconnected | | speakingStateChange | { user: User, speaking: boolean } | A user started/stopped speaking |

ClientOptions

Extends Node.js tls.ConnectionOptions.

| Option | Type | Default | Description | |---|---|---|---| | host | string | — | Server hostname | | port | number | 64738 | Server port | | username | string | — | Username for authentication | | password | string? | — | Server or user password | | tokens | string[]? | [] | Access tokens for server ACL groups | | clientName | string? | 'simple mumble bot' | Client name sent to the server | | pingInterval | number? | 10000 | Keep-alive ping interval in ms |

Since ClientOptions extends tls.ConnectionOptions, you can pass any TLS option such as rejectUnauthorized, cert, key, ca, etc.

License

MIT