mumble-ruby

mumble-ruby copied to clipboard

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[https://github.com/mumble-voip/mumble-protocol/blob/master/protocol_stack_tcp.rst].