https://github.com/tf2pickup-org/mumble-client

A simple mumble client for managing mumble servers
https://github.com/tf2pickup-org/mumble-client
bot mumble mumble-client mumble-server murmur nodejs
Last synced: 4 months ago
JSON representation
A simple mumble client for managing mumble servers
Host: GitHub
URL: https://github.com/tf2pickup-org/mumble-client
Owner: tf2pickup-org
License: mit
Created: 2022-05-09T22:43:52.000Z (about 4 years ago)
Default Branch: master
Last Pushed: 2026-02-10T18:37:01.000Z (4 months ago)
Last Synced: 2026-02-10T21:57:38.608Z (4 months ago)
Topics: bot, mumble, mumble-client, mumble-server, murmur, nodejs
Language: TypeScript
Homepage:
Size: 12.5 MB
Stars: 9
Watchers: 1
Forks: 5
Open Issues: 6
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project

README

          
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

- Query channel permissions

- Event-driven architecture with full TypeScript support

- Automatic keep-alive pinging

## Installation

```bash

npm i @tf2pickup-org/mumble-client

```

## Quick start

```typescript

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

```typescript

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

```typescript

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

```typescript

// 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

```typescript

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

```typescript

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

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

if (user && targetChannel) {

  await user.moveToChannel(targetChannel.id);

}

```

### Mute/deafen yourself

```typescript

// self-mute

await client.self.setSelfMute(true);

// self-deafen

await client.self.setSelfDeaf(true);

// unmute

await client.self.setSelfMute(false);

```

### Register and manage users

```typescript

// 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

```typescript

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

```typescript

// 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

```typescript

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](https://opensource.org/licenses/MIT)
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/tf2pickup-org/mumble-client

Awesome Lists containing this project

README

mumble-client
