Skip to content
A headless mumble client API written in Ruby
Branch: master
Clone or download
Latest commit 37aaba1 Jul 20, 2015
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Version bump Jul 20, 2015
.gitignore
.ruby-gemset Update .rvmrc format Nov 17, 2013
.ruby-version Update ruby version Jul 20, 2015
Gemfile Fixed gem file and bumped version Jul 13, 2014
LICENSE.txt Add opus support. Add Licence. Fix message too long bug. Feb 23, 2014
README.rdoc Only I would take 2 commits to change a URL... May 5, 2015
Rakefile Initial Commit Mar 25, 2012
mumble-ruby.gemspec

README.rdoc

mumble-ruby

http://www.github.com/mattvperry/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 be able to stream audio to servers that don't support OPUS anymore. I haven't looked into backwards-compatability with CELT.

RECENT CHANGES:

  • Merged changes for proper user/channel objects

  • Merged changes for recording feature

  • Added half-broken support for playing files (Something is wrong, wouldn't recommend using it)

  • Bit of refactoring and renaming

  • 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 after connecting
cli.on_connected do
    cli.me.mute
    cli.me.deafen
end

# Join the channel titled "Chillen" (this will return a channel object for that channel)
cli.join_channel('Chillen')

# Get a list of channels
cli.channels
# Returns a hash of channel_id: Channel objects

# Join Channel using ID
cli.join_channel(0)

# Join Channel using Channel object
cli.join_channel(cli.channels[0])
cli.channels[0].join

# 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!")

# 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.player.stream_named_pipe('/tmp/mpd.fifo')

# EXPERIMENTAL: Recording feature
cli.recorder.start('/home/matt/record.wav')
sleep(2)
cli.recorder.stop

# EXPERIMENTAL: Play wav files
cli.player.play_file('/home/matt/record.wav')

# 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.

You can’t perform that action at this time.