Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A headless mumble client API written in Ruby
branch: master

Merge pull request #40 from qwertos/move_user

Move User Function in Mumble::Client
latest commit d84ec397ce
perrym5 authored

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

Something went wrong with that request. Please try again.