# Barnard

## Documentation

Please feel free to give suggestions and corrections for this file (as wellas Barnard propper).
Find a sample notification script in examples/.

## Audio boost

If a user is too soft to hear, you can boost their audio.
The audio should drastically increase once you have hit the VolumeUp key over 10 times (from the silent/0 position).
The boost setting is saved per user, just like per user volume.

## FIFO Control

If you pass the --fifo option to Barnard, a FIFO pipe will be created.
You can control Barnard by sending commands to this FIFO.
Each command must end with a  \n (0x0a) character.
Commands may be added at any time.
Per the robustness principle, be liberal in what you receive.
Current Commands:
* error: An error has occured to prevent transmitting audio, or taking another action.
* micup: Start transmitting, just as when you hold down the talk key. Does nothing if you are already transmiting.
* micdown: Stop transmitting, just like when you release your talk key. Does nothing if you are not already transmitting.
* toggle: Toggle your transmission state.
* talk: Synonym for toggle.
* exit: Exit Barnard, just like when you press your quit key.

## Event Notification

You can use the notifycommand parameter in your config file to run a program on certain events.
Each event has the following parameters:
* event: the name of the event
    - join: user has joined the channel you are in
    - leave: user has left the channel you are in
    - micup: you have begun transmitting
    - micdown: you have stopped transmitting
    - connect: you have connected to a server
    - disconnect: you have disconnected from a server
    - msg: the channel you are currently connected to has received a message
    - pm: you have received a private message
* who: the person causing initiation of the event ("me" for self-generated events)
* what: the body of the event as applicable (message, channel name, etc)

Warning:
Keep in mind that Barnard opens an Alsa sound device when starting.
For this reason, any notification command used here will need to be able to work while other sound is playing.
It is recommended that you test  your notification command by hand, while Barnard is running, before including it here.

You can create a command that will take any of these parameters as desired, by prepending the name of the parameter in your command with a % (percent) sign.
As an example, to attempt to play wave files for each event, you could set notifycommand to:
aplay /home/username/sounds/mumble/%event.wav
When you begin transmitting, aplay will attempt to play /home/username/sounds/mumble/micup.wav.
The same will be attempted for the other events, such as leave, join, micdown, etc.

In order to process messages and the like, Barnard will parse your command as a properly quoted shell command.
For this reason, you should put quotes around arguments that have spaces.
If you want to do more complex things, write a shell script (or c application, python script, etc) to process the arguments passed into it.

## Connecting Via Text Interface

You can now manage your server lists in a text GUI.
An Ncurses interface has been created by members of the [F123 Group](https://gitlab.com/f123).
Make sure the folder in which you store the barnard binary is in your path. This should be the default for any f123 user.
Then just run ./barnard-ui from this folder, and follow the instructions.
You can add barnard-ui to your path as well, and access it from anywhere.

## Modifications

This copy of Barnard and it's associated Gumble library have been modified to support usage by blind users.
Our thanks go out to Tim Cooper for the massive amount of work put into this client, originally found at [github.com/layeh/barnard](https://github.com/layeh/barnard).

## Config

By default, the file $HOME/.barnard.yaml will hold the configuration for Barnard.
You can have barnard read another file by using the -c option, like `./barnard -c ~/.anotherbarnard.yaml`.
It will be created automatically if it doesn't exist.
If you modify the config file while Barnard is running, your changes may be overwritten.

## Defaults

You can set username and defaultserver in your config file, and they will be used if none is specified when launching barnard.
(Note that the default username (an empty string) and the default server name (localhost:64738) have been the defaults for barnard up to this  point, and have been left that way for compatibility.)

## Audio Devices

You can set the default input and output devices in the config file as well.
Pass the -list_devices parameter to barnard to be given a list of audio input and output devices.
Copy lines from the above list into inputdevice and outputdevice as desired.
To clear your inputdevice or outputdevice options and set them to defaults, set them to "" or delete them entirely.

## Keystrokes

You can see the below keystrokes in your config file.

Pressing tab inside the main window switches between the user/channel tree view and the message input box.
When in the message input box:
* left and right arrow keys move by character
* home/end moves to the beginning/end of the text respectively
* enter submits the entered message

When in the treeview, pressing:
* f5 or f6 on a channel changes the volume for all users in that channel
* f5 or f6 on a user changes the volume for that user.
* enter on de-selected user selects that user for PM mode.
* enter on selected user de-selects the user
* enter on a channel de-selects any selected users (if any) and moves you to the specified channel.

## Volume

If you set the volume for a user (using the F5/F6 keys by default), Barnard will remember that volume, and will keep that user at that volume.
The volume is set for a single user on a single server.
This means you may have to set a person to a custom volume multiple times, if you are both on multiple servers together.

If you set the volume of a channel, you are basically relatively adjusting each user's volume.
If Jim's volume is set to 0.1, and larry's volume is set to 0.9, lowering the channel by one increment will mute Jim,and set Larry to 0.8.

You can change the volume for a user once that user has spoken at least once during a session.
Attempts to change the volume of a user who has not spoken will be ignored.
If you are unable to hear a user speaking, you can edit the .barnard.yaml file in your home directory, after closing Barnard, and set the volume parameter to 1.0 for a particular user.

### Technical

The volume for each user is set via the audio session created for that user; no talking means no session means no settable volume.

## PM Mode

This mode sets the text to the left of your message entry box to [@username], where username is the name of the person you are PMing.
While a user is selected, both private messages and channel messages are displayed.
However, any messages you send will be delivered only to the selected user.
Private messages between you and another party are shown as `pm/source/dest`, where source and dest are the sender and receiver of the message respectively.
When you are finished sending private messages to a user, press tab to reactivate the tree view, and de-select the user as above.

## Info

barnard is a terminal-based client for the [Mumble](https://mumble.info) voice
chat software.

![Screenshot](https://i.imgur.com/B8ldT5k.png)

## Installation

Requirements:

1. [Go](https://golang.org/)
2. [Git](https://git-scm.com/)
3. [Opus](https://opus-codec.org/) development headers
4. [OpenAL](http://kcat.strangesoft.net/openal.html) development headers

To fetch and build:

    go get -u git.2mb.codes/~cmb/barnard

After running the command above, `barnard` will be compiled as `$(go env GOPATH)/bin/barnard`.

## Manual

### Key bindings

- <kbd>F1</kbd>: toggle voice transmission
- <kbd>Ctrl+L</kbd>: clear chat log
- <kbd>Tab</kbd>: toggle focus between chat and user tree
- <kbd>Page Up</kbd>: scroll chat up
- <kbd>Page Down</kbd>: scroll chat down
- <kbd>Home</kbd>: scroll chat to the top
- <kbd>End</kbd>: scroll chat to the bottom
- <kbd>F10</kbd>: quit

## License

GPLv2

## Contributors

Tim Cooper (<tim.cooper@layeh.com>)
Brandon McGinty-Carroll (<bmmcginty.barnard@bmcginty.us>)
