Skip to content
This repository

A headless mumble client API written in Ruby

branch: master
README.rdoc

mumble-ruby

http://www.github.com/perrym5/mumble-ruby

DESCRIPTION:

Mumble-Ruby is a headless client for the Mumble VOIP application. Mumble-Ruby provides the ability to write scripts and bots which interact with mumble servers through a simple DSL. Mumble-Ruby also has the ability to stream raw audio from a fifo pipe (mpd) to the mumble server. There is huge room for improvement in this library and I am willing to accept all sorts of pull requests so please do.

INSTALL:

[sudo] gem install mumble-ruby

REQUIREMENTS:

  • Ruby >= 2.1.0

  • OPUS Audio Codec

  • Murmur server > 1.2.4 – NOTE: mumble-ruby will not connect to servers that don't support OPUS anymore. I haven't looked into backwards-compatability with CELT.

RECENT CHANGES:

  • Added OPUS support

  • Added more configuration options

  • Added image text messages

  • Added ssl cert auth

  • Fixed several bugs

BASIC USAGE:

# Configure all clients globally
Mumble.configure do |conf|
    # sample rate of sound (48 khz recommended)
    conf.sample_rate = 48000

    # bitrate of sound (32 kbit/s recommended)
    conf.bitrate = 32000

    # directory to store user's ssl certs
    conf.ssl_cert_opts[:cert_dir] = File.expand_path("./")
end

# Create client instance for your server
cli = Mumble::Client.new('localhost') do |conf|
    conf.username = 'Mumble Bot'
    conf.password = 'password123'

    # Overwrite global config
    conf.bitrate = 48000
end
# => #<Mumble::Client:0x00000003064fe8 @host="localhost", @port=64738, @username="Mumble Bot", @password="password123", @channels={}, @users={}, @callbacks={}>

# Set up some callbacks for when you recieve text messages
# There are callbacks for every Mumble Protocol Message that a client can recieve
# For a reference on those, see the linked PDF at the bottom of the README.
cli.on_text_message do |msg|
    puts msg.message
end
# => [#<Proc:0x0000000346e5f8@(irb):2>]

# Initiate the connection to the client
cli.connect
# => #<Thread:0x000000033d7388 run>

# Mute and Deafen yourself
cli.mute
cli.deafen

# Join the channel titled "Chillen" (this returns the number of bytes written to the socket)
cli.join_channel('Chillen')
# => 11

# Get a list of channels
cli.channels
# Returns a hash of channel_id: ChannelState Messages

# Join Channel using ID
cli.join_channel(0)

# Join Channel using ChannelState Message
cli.join_channel(cli.channels[0])

# Get a list of users
cli.users
# Returns a hash of session_id: UserState Messages

# Text user
cli.text_user('perrym5', "Hello there, I'm a robot!")
# => 35

# Text an image to a channel
cli.text_channel_img('Chillen', '/path/to/image.jpg')

# Start streaming from a FIFO queue of raw PCM data
cli.stream_raw_audio('/tmp/mpd.fifo')
# => #<Mumble::AudioStream ...>

# Safely disconnect
cli.disconnect
# => nil

MUMBLE PROTOCOL:

The documentation for Mumble's control and voice protocol is a good reference for using this client as all of the callbacks are based on the types of messages the Mumble uses to accomplish its tasks. You can see it here.

Something went wrong with that request. Please try again.