Signum / teamster

Driving images to MS Teams.

Teamster

driving background images to M$ Teams

what is this about?

As Linux users, we were only able to envy Windows users for applying custom virtual background images in video conferences. But behold, this time is now over.

The inofficial Teams client Teams for Linux (highly recommendable) exposes the same API that Teams uses to fetch the default images from the Microsoft CDN. This is documented in the readme.

By changing from the default CDN to Teamster, you can use your own backgrounds!!!

how to install?

We have not yet built a wheel package. Thus, clone this repo, and install requirements into a new virtual environment:

git clone https://github.com/kaHaleMaKai/teamster.git
cd teamster
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python teamster.py

dbus

If you want to receive desktop notifications from Teamster, please run pip install dbus-python after activating your virtual environment (source .venv/bin/activate).

beware

You will always have to start Teamster before starting Teams-for-Linux. Else you might not be able to see any backgrounds in it. In case Teamster crashes during your use of Teams-for-Linux, you might need to stop Teams-for-Linux and start Teamster first.

how to configure?

Teams for Linux

You will have to start the Teams client with a cli flag:

teams-for-linux --isCustomBackgroundEnabled=true

Teamster

Teamster consumes a JSON config file, ${XDG_CONFIG_DIR}/teamster/config.json, and falls back to ${HOME}/.config/teamster/config.json.

The config file accepts the following options:

{
  "port": 6789,
  "debug": false,
  "teams_version": 2,
  "update_teams_config": true,
  "ignore_teams_images": true,
  "image_dir": "/home/lars/Pictures/video-backgrounds",
  "thumbnail_dir": "/home/lars/.cache/teamster",
  "fetch_interval": 60
}

The individual options are

• port: the port to run the service on (host is restricted to localhost)
• debug: whether to run in Flask debug mode or not (only useful for Python development)
• teams_version: the Teams API version. should be set to 2, usually
• update_teams_config: whether to sync some config options into the config file of Teams for Linux
• ignore_teams_images: whether to ignore the default Teams images – mirrored option from Teams for Linux
• image_dir: where to store images. defaults to images/ subdir of checked out repository
• thumbnail_dir: where to store thumbnails. default to teamster/ below $XDG_CACHE_DIR (or ${HOME}/.cache)
• fetch_interval: how often Teams for Linux should look for new background images – again, a mirrored config option

When setting update_teams_config=true, then some options such the URL of the Teamster service will be automatically written into the Teams for Linux config. If you do not wish that, please add it manually (e.g. {"customBGServiceBaseUrl": "http://localhost:6789"}).

Systemd

If you wish to run this web service via systemd, you can execute ./install-service.sh from this repository. It will create a user-scoped service called teamster.service, that you can start/stop via

systemctl --user start teamster
systemctl --user stop teamster

You can check the logs via

journalctl --user -u teamster

# or, for a quick overview
systemctl --user status teamster

endpoints

When opening the Teamster base url (per default: http://localhost:6789), you will see a simple HTML page that looks likes this

• config.json – exposes the complete list of images to Teams-for-Linux * images/ – simple directory serving of your image folder for debugging * thumbnails/ – simple directory serving of your thumbnail folder for debugging

The config.json endpoint is required by Teams itself. It delivers both the information what images are served, and their URLs. Additionally, Teams wants to show a thumbnail of the background images. Those are get on-the-fly when calling config.json ifn ot existent. Thus, on subsequent calls the thumbnails will get served from disk.

debugging

If you do not see any custom backgrounds in Teams-for-Linux, please check if

• Teamster running,
• Teamster serves the images,
• Teamster hasn't crashed

When in doubt, please stop Teams-for-Linux, start Teamster and only then again Teams-for-Linux.