Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rwxrob/cmd-live


https://github.com/rwxrob/cmd-live

Last synced: 4 months ago
JSON representation

Awesome Lists containing this project

README 

          
# Live Streamer Command Line Utility



This bash script helps live streamers communicate the current state of

their stream quickly from the Linux command line by creating and

changing a number of streaming *modes* which are stored in a simple

configuration file. Streamers can also optionally post a corresponding

Twitch chat message, GitHub status, and/or Twitter update. This script

can also be used to post markers in the current live stream to help with

video editing later, lookup user information, ban and timeout users,

list the top channels in a given category, and more.



Each mode has the following properties which can be easily set and get

using the `config` commands:



* Name

* Emoji

* Default Status

* Current Status

* Category

* Tags



Each is added using either the `config.set` or `config.edit` commands.

The `set` command sets it directly from the command line. The `edit`

command opens the configuration `values` file using your configured

default `$EDITOR`.



**Name** is a memorable name uniquely identifying the mode.  Names may

contain dots (.) to separate modes into submodes easily (`playing.dota2`,

`playing.witcher3`, `out.cycling`, `out.watching.birds`,

`out.watching.movie`). This makes for quick and organized tab completion

later.



## Installation



Just put the script someplace in your PATH and add completion to your

`~/.bashrc` or other file:



```bash

complete -C live live

```



This script manages completion with `-C` instead of depending on

a separate script or requiring wasteful sourcing of completion code in

your `bashrc` file.



> ⚠️

> This script was once called `iam` instead of `live` (`alias iam=live` if needed).



## Dependencies



Required:



* Bash 4+

* `jq` - JSON Parsing

* `twitch` - Official Twitch Command Line Utility



Optional:



* `gh` - GitHub Status Updates

* `twurl` - Twitter Posts

* `pandoc` - Rich Help Docs



## Security



This script is expected to be installed for a specific user and only

ever run by that user. No additional security vetting for running as an

untrusted user has been done.



## Legal



Copyright 2021 Rob Muhlestein   

Released under Apache-2.0 License  

Please mention rwxrob.tv for attribution



## The `about` Command



```

live about

```



Prints Markdown output suitable for pasting into an About text pane.

Also sends to `xclip` if it is detected on the system.



## The `category` Command



```

live category [NEW]

```



Print or change the current mode category (which is still `game_id`

internally in the Twitch API). Prints both the category ID number and

the long written form separated by a space. Note that

changing the category requires the number only and does not immediately

update the current category on Twitch, only the local entry in the

configuration data. Consider adding popularly used categories to the

local configuration. See `list.categories` and `category.select`.



## The `category.select` Command



```

live category.select

```



Change the current mode category (which is still `game_id` internally in

the Twitch API) by selecting from a menu containing all categories

loaded into the local configuration cache values file (see `config path`

for more).  Note that this does not update the current category on

  Twitch, only the local entry in the configuration data.  See

  `list.categories` and `category`.



## The `config` Command



```

live config

live config KEY

live config.set KEY VALUE

live config.set KEY ""

live config.keys

live config.values

live config.directory

live config.path [file]

live config.edit [file]

live config.delete

live config.read

live config.write

live config.dump

```



The `config` command is for reading, writing, and displaying standard

open desktop configuration properties. 



### Arguments



With no arguments calls `dump` and outputs all the currently cached

configuration settings.



With a single KEY argument fetches the value for that key and outputs

it unless it is one of the following special (reserved) key names:



* `directory` full path to config directory

* `path`   full path to specific config file (default: `values`) 

* `edit`   opens config file in editor (default: `editor` or `$EDITOR)

* `keys`   output the configuration keys, one per line

* `values` output the configuration values, one per line

* `delete` if key argument then delete a specific key, otherwise prompt

* `read` reads the configuration file into CONF associative array

* `write` write the CONF associative array to the configuration file

* `dump` write the flattened CONF associative array to standard output



With more than one argument the remaining arguments after the KEY will

be combined into the VALUE and written to a `values` file in the

configuration directory. 



### Configuration Directory



The configuration directory path relies on the following environment

variables:



* `EXE` - defaults to name of currently running command (live)

* `HOME` - checked for `$HOME/.config/$EXE/values`

* `XDG_CONFIG_HOME` - overrides `$HOME/.config`

* `CONFIG_DIR` - full path to directory containing `values` file



The `CONFIG_DIR` always takes priority over anything else if set, but is

never implied. If the directory does not exist it will be created the

first time a value is set.



### Configuration `values` File Format



The file (which is almost always located at

`~/.config/live/values`) uses the simplest possible format to

facilitate standard UNIX parsing and filtering with any number of

existing tools (and no `jq` dependency).



* One KEY=VALUE per line

* KEYs may be anything but the equal sign (`=`)

* VALUEs may be anything but line returns must be escaped



Note that, although similar, this is *not* the same as Java properties

and other similar format. It is designed for ultimate simplicity,

efficiency, and portability.



## The `create` Command



```

live create MODE

```



Create a new mode with interactive prompt. Note that modes can also be

created directly by simply adding the lines to the `live config

path` values file.



## The `delete` Command



```

live delete MODE

```



Delete all data for a specific. WARNING: Does not ask for confirmation.



## The `description` Command



```

live description [NEW]

```



Print or change the current mode description.



## The `emoji` Command



```

live emoji [NEW]

```



Print or change the current mode emoji.



## The `emojis` Command



```

live list.emojis

live emojis

```



List emojis from all modes. See `emoji`.



## The `help` Command



```

live help [COMMAND]

```



Displays specific help information. If no argument is passed displays

general help information (main). Otherwise, the documentation for the

specific argument keyword is displayed, which usually corresponds to

a COMMAND name (but not necessarily). All documentation is written in

GitHub Flavored Markdown and will displayed as a web page if `pandoc`

and `$HELP_BROWSER` are detected, otherwise, just the Markdown is sent

to `$PAGER` (default: more).



Also see `readme` and `usage` commands.



## The `list.categories` Command



```

live list.categories

```



List available categories.



## The `list.emojis` Command



```

live list.emojis

live emojis

```



List emojis from all modes. See `emoji`.



## The `list.modes` Command



```

live list.modes

live modes

```



List available modes.



## The `list.tags` Command



```

live list.tags

```



List available tags. Note that tags (without list) is an entirely

different command. To add tags to the local configuration cache edit the

configuration file directly with `config edit` each tag should be in the

format of the following example:



```

tag.cozy=adc4a830-07f5-457b-95e5-5ab6cc1f9af3

```



Note that there cannot be any whitespace anywhere in the line.



## The `list.titles` Command



```

live list.titles

live titles

```



List all titles in alphabetical order by mode name.



## The `list.titles.modes` Command



```

live list.titles.modes

```



Same as list.titles but also show the mode name.



## The `mode` Command



```

live mode [NEW]

```



Print the current mode name (from local cache) or set to a new one and

update it on Twitch as well. Note that this does not fetch the current

remote Twitch status so it is possible that if Twitch stream info and

tags have been set some other way that the local cache will be out of

sync. A quick check of the current title should help identify when this

happens, but it is inconsequential since usually a new mode is wanted

anyway.



## The `modes` Command



```

live list.modes

live modes

```



List available modes.



## Generate `README.md` File



```

live readme > README.md

```



The `readme` command will output the embedded help documentation in raw

GitHub Flavored Markdown suitable for use as a `README.md` file on

GitHub or similar hosting service.



## The `status` Command



```

live status [NEW]

```



Print or change the current status. Note this does not change the

status.default. To remove and return to status.default use

status.clear.



## The `status.clear` Command



```

live status.clear

```



Clears the current status (effectively switching back to status.default)

.



## The `status.default` Command



```

live status.default [NEW]

```



Print or change the current mode status default. (See status also.)



## The `tag` Command



```

live tag (UUID|NAME)

```



Lookup a tag in the local configuration cache by UUID or short name

(NAME). See list.tags for how tags are added to the cache.



## The `tags` Command



```

live tags [NEW]

```



Print or change the current Twitch tags list. Twitch limits tags to five

total. Tags with their Twitch unique identifiers must first be added

before they will work. See `list.tags`.



## The `title` Command



```

live title [MODE]

```



Print the current emoji and status suitable for setting twitch.title.

The current status is used if MODE is not passed. This is default

command when no arguments are passed.



## The `titles` Command



```

live list.titles

live titles

```



List all titles in alphabetical order by mode name.



## The `twitch.category` Command



```

live twitch.category [NEW]

```



Set or get the remote Twitch category (game_id) for the current

`twitch.id`. The special SAME category will skip any attempt to update

the current Twitch category. This is useful for break modes and such.



## The `twitch.channel` Command



```

live twitch.channel

live channel

```



Print the Twitch API channel JSON data for the current `twitch.id`.



## The `twitch.title` Command



```

live twitch.title [NEW]

```



Set or get the remote Twitch title for the current `twitch.id`.



## The `twitch.user` Command



```

live twitch.user [NAME]

```



Fetch and print summary for a give Twitch user by name. If no name is

provided, will display summary for the current `twitch.name`.



## The `usage` Command



```

live usage

```



Display all possible commands. Note that this is usually easier by

simply using tab completion instead.



----



*Autogenerated Mon Jan  3 09:31:38 AM EST 2022*