mumble-client

A simple mumble client for managing mumble servers

Features

• Connect to any Mumble server over TLS
• Manage channels: create, remove, link/unlink, fetch ACLs
• Manage users: move, mute/deafen, register/deregister, rename
• Send and receive private text messages; read certificate hashes and client IP addresses
• 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);

Text messages, certificate hashes and addresses

client.on('textMessage', async ({ sender, message, isPrivate }) => {
  if (sender && isPrivate) {
    await sender.sendMessage(`you said: ${message}`);
  }
});

// message everyone in a channel
await client.channels.byName('Lobby')?.sendMessage('hello');

// SHA1 hash of the user's certificate, sent for every user
console.log(user.hash);

// IP address; needs the Ban permission on the root channel
console.log(await user.fetchAddress());

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,
  ClientDisconnectedError,
  ConnectionRejectedError,
  PermissionDeniedError,
} from '@tf2pickup-org/mumble-client';

try {
  await client.connect();
} catch (error) {
  if (error instanceof ConnectionRejectedError) {
    console.error('Connection rejected by server');
  } else if (error instanceof ClientDisconnectedError) {
    // the server dropped the connection during the handshake,
    // or another connect() call superseded this one
    console.error('Connection lost');
  }
}

// background errors, e.g. a failed keep-alive ping; without a listener
// Node.js throws on an 'error' event
client.on('error', error => {
  console.error('Client error:', error);
});

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.

ChannelManager

Channel

UserManager

User

Permissions

Events

ClientOptions

Extends Node.js tls.ConnectionOptions.

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

License

MIT