gleiswechsel/README.md

Gleiswechsel

Gleiswechsel [ˈɡlaɪsvɛksəl] (german for "platform change") is a selfhostable discord bot which regularly changes the name of a voice chat to a real public transport connection. The channel will keep the name until the connection arrived at its last stop, after that it will automatically select a new one.

Features

• International support for both countries and cities
• Support for various types of transportations, including but not limited to Subways, Busses, Funiculars, Trams and Trains
• Multi language support (+ option to easily add more languages)
• Announcements, including the option to join the voice chat and play an audio file while arriving at a specific station
• Highly customizable
• pretty /info embed with some details about your current ride

Setup

Follow this guide to create your discord bot up until you have a token.

Make sure that you have Python installed!

Download the repo (either with git or by clicking the big "Code" button at the start on this page, downloading the zip and extracting it) and run:

# Create a virtual environment so that the bot won't cluster your system with dependencies
python -m venv venv

# Activate your venv, you should have gotten instructions after running the first command, e.g.:
source venv/bin/activate

# Install the required dependencies
pip install -r requirements.txt

Next, you should configure the bot to your liking

Config

Even if it seems a bit tedious, I highly recommend going through the entire config and checking if there's something that you would like to customize.

I added an example config:

{
  "discord": {
    "token": "",
    "server": ,
    "vc": ,
    "lang": "de",
    "formatting": "┇",
    "emojis": true
  },
  "connections": {
    "stations": [
      "Berlin Hauptbahnhof",
      "Amsterdam",
      "Helsinki"
    ],
    "IDs": [],
    "blacklist": [
      "OTHER",
      "RIDE_SHARING"
    ],
    "min_duration": 10,
    "max_duration": null,
    "max_wait_time": null,
    "timezone": "Europe/Berlin"
  },
  "announcements": {
    "enabled": true,
    "voice": [
      {
        "enabled": false,
        "end_stations": {
          "general": "general.aac",
        },
        "stops": {
        }
      }
    ]
  },
  "http": {
    "user_agent": "Gleiswechsel-Discord-Bot"
  }
}

You have to rename config.json.example to config.json and fill out the essential fields so that the bot is usable.

Explanations

discord

• "token" is for the discord bot token. You should have copied it earlier

• "server" and "vc" are the ID's for the server and the voice chat that the bot should use. Follow this guide to get them.

• "lang" is for the language that the bot should use within discord. The relevant language files are located in src/data/locales/. Current available languages are english ("en") and german ("de"). Feel free to add your language if you miss it!

• "formatting" and "emojis" are for the channel name. Set emojis to False and "formatting" to null if you just want the connection as the channel's name without any decor.

connections

stations

You can add your desired stations that the bot should search connections from there. The bot will choose one of the stations at random.

The bot will also search for similar named stations if it couldn't find an exact match to your input. This is really handy if you'd just like to ride around in a city with various stations. For example, if you just input "Amsterdam" as a station, the bot would randomly choose one of these stations:

"Amsterdam": [
    "Amsterdam Zuid",
    "Amsterdam RAI",
    "Amsterdam Amstel",
    "Amsterdam, Gein",
    "Amsterdam Centraal",
    "Amsterdam, Noord",
    "Amsterdam, Rokin",
    "Amsterdam Lelylaan",
    "Amsterdam Sloterdijk"
]

The bot will also warn you if it couldn't find a station with the exact name as your input:

22:44:46: INFO: No station associated as 'Amsterdam', choosing random from similar named stations

but you can safely ignore this warning if you're fine with it.

If not, I've created a tool which would help you to get the exact station name. You can use the tool by running

$ python run main.py stations

Example output:

22:47:56: INFO: Exact match found! London is an assigned station! Bot would use that station directly
22:48:33: INFO: {
    "stations": {
        "Amsterdam": [
            "Amsterdam Zuid",
            "Amsterdam RAI",
            "Amsterdam Amstel",
            "Amsterdam, Gein",
            "Amsterdam Centraal",
            "Amsterdam, Noord",
            "Amsterdam, Rokin",
            "Amsterdam Lelylaan",
            "Amsterdam Sloterdijk"
        ],
        "Berlin": [
            "Berlin Hbf",
            "Berlin ZOB",
            "Berlin Ostbf",
            "Berlin-Spandau",
            "Berlin Südkreuz",
            "U Rudow (Berlin)",
            "S Buch (Berlin)",
            "U Hönow (Berlin)"
        ]
    }
}

The tool will also ask if it should save a .json file with more informations for every similar station. If you're unsure about what which station is, then it can be really helpful! It would give you data like which types of transports arrive at every similar station, in which country they are and also their coordinates.

If you choose to generate the json, then you'll find the file as stations.json in the same directory as main.py

IDs

For every station inside of the stations.json you'll find an ID. You can add that ID to "IDs" to really specify that you would like to use THAT station, and not a different one.

This is especially useful if you want to add a station whose name isn't unique and also used by other stations. The bot would falsely use the first station with the same name and consider it an exact match, even if you wanted a different one. This won't happen with the ID, as every ID is uniquely assigned to only one station.

blacklist

You can blacklist specific types of transport, the bot would then skip them while selecting a connection. You can get the type either in your console (mode)

22:44:47: INFO: Agency: GVB, mode: TRAM

or in the /info embed.

I highly recommend keeping "OTHER" blacklisted, if the API doesn't know what that is then we probably shouldn't use it. Also, it would probably a good idea to keep "RIDE_SHARING" blacklisted as they have weird timetables

min_duration, max_duration, max_wait_time, timezone

• min_duration is the minimal duration of the connection in minutes. It is HIGHLY recommended to set it to atleast 10, as discord only allows to change the name of a voice chat twice every 10 minutes.

• max_duration is the maximun duration of the connection in minutes. Set to null to disable

• max_wait_time is the maximun wait time for a connection in hours. Don't set that one too low, as the bot may have some issues finding a suitable connection at night, or at stations that aren't frequently used. Set to null to disable

• timezone is timezone in the IANA timezone format. You can look it up here

announcements

The bot can send a text announcement in the voice chat at the start/end of a trip. At the end of a trip, it would send this embed:

It will also send the /info embed at the start of a new connection with informations about your new trip.

To reduce spam, the bot will only send announcements if someone is in the voice chat

voice

⚠️ Requires announcements to be set to enabled

The bot can join the voice chat, play an audio file, and leave at various points of your trip. You have to have FFmpeg installed for this to work.

Place the audio file of your desired station in src/data/announcements. Then, define the stations name with the name of the audio file in either end_stations or stops. The path will be autocompleted to src/data/announcements. The station name has to be EXACT, if you're unsure then get the name through the helper script

end_stations is for audio files that should play at the end of your trip, and stops is for audio files that should play while the train is passing through your desired station. If you set the name of a station to general, then the bot will always play that file before the trip ends/a new stop has been reached.

I'm hoping that I didn't explain this too complicated. Here's an example to visualize this:

  "announcements": {
    "enabled": true,
    "voice": [
      {
        "enabled": true,
        "end_stations": {
          "general": "general.aac",
          "Hannover Hbf": "hannover.aac"
        },
        "stops": {
          "Amsterdam, Noorderpark": "noorderpark.aac"
        }
      }
    ]
  },

http

• "user_agent": The user agent of the bot for the API. If you don't know what that is, then you shouldn't have to change that. Even if you do, you still probably don't have to

Running

After you've set everything up, you're ready to start the bot!

$ python run main.py

src/data

src/data contains a few files/directories which may be interesting to customize.

emojis.py

if emojis is enabled in the config, the bot will use that file to determine the right emoji for the voice chats name according to the current mode. You can add missing modes there or customize the emojis

operators.py

Metadata for the /info embed. You can assign an agency a logo, color and (optionally) some slogans. The agency name is visible in the console log and the /info embed.

If multiple agencys should use the same metadata, take a look at OPERATOR_ALIASES.

You don't have to restart the bot after editing this file.

locales/

Covered in locales

announcements/

Covered in voice announcements

announcements

Assets (such as images) which the bot uses. You shouldn't have to change anything there