README.md (4379B)
1 # songy 2 3 This is a telegram bot written in [rust](https://www.rust-lang.org/) using the [frankenstein](https://github.com/ayrat555/frankenstein) telegram bot library. 4 5 ## what does it do? 6 7 This bot provides an interface to files. It is meant to be used as a digital songbook. 8 9 <img src="https://github.com/devnibo/songy/raw/master/example.gif" alt="example" height="600" /> 10 11 ### bot commands 12 13 To let telegram know what commands the bot provides you have to set these in the [BotFather](https://telegram.me/BotFather). 14 The `/list` command lists all available files in the provided --songs-path recursively. There is one thing you can do for additional structuring. Suppose you have provided the path `/var/songs` as the --songs-path. If you create the subfolder `/var/songs/en` then the command `/en` will be available in the bot to list only files/songs recursively in that subfolder. That way you could organize your songs in different languages. 15 16 ## installation 17 18 1. Download the [latest release](https://github.com/devnibo/songy/releases) executable 19 2. Don't forget to make the downloaded file executable: `chmod +x <file>` 20 3. Decide about the configuration 21 1. [Create a telegram bot](https://telegram.me/BotFather) to obtain the bot api token (--token) 22 2. Which language do you want the bot to speak? english, german or romanian/moldovan (--lang) 23 3. Where do you store the files that the bot uses? (--songs-path) 24 4. Start the bot: `./songy --token <api_token> --songs-path <full/path/to/songs/folder>` 25 26 ### config 27 28 Instead of providing all settings via command line arguments you can provide a yml config file with the settings with the `--config` argument. 29 30 e.g. `./songy --config songy.yml`. 31 32 These are the available configuration options: 33 34 songy.yml 35 ``` 36 search_file: <path_to_file> 37 reports_path: <path_to_folder> 38 token: <telegram_bot_token> 39 songs_path: <path_to_folder> 40 lang: <en|de|md> 41 ``` 42 43 Command line arguments have precedence over configuration file options. 44 45 ### setup systemd service under linux 46 47 As the bot has to run endlessly you probably want to create some sort of background service. Here's a simple solution I use. 48 49 1. `touch /etc/systemd/system/songy.service` 50 2. Copy this into `songy.service` 51 ``` 52 [Unit] 53 Description=Digital song book 54 55 [Service] 56 ExecStart=/full/path/to/songy/executable --token <api_token> --songs-path <full/path/to/songs/folder> --lang <en|de|md> 57 Restart=on-failure 58 59 [Install] 60 WantedBy=default.target 61 ``` 62 3. `systemctl start songy` 63 64 ### Searching Files 65 66 #### Basic 67 68 If you have some images or pdf files and you want to sing now then you can just throw 69 them into a folder, assign that folder in the `--songs-path` argument, start the bot and you're done. 70 This way every text you send to the bot that doesn't start with a slash (`/`) will be 71 used to search in the file names you provided. This way you have a basic search. 72 73 #### Advanced 74 75 Alternatively you can provide a text file via the `--search-file` argument. 76 When sending the bot a text message that doesn't start with a slash (`/`) now 77 it won't search in the provided file names rather in the provided `--search-file` 78 text file. For that to work the `--search-file` text file has to have the following 79 structure: 80 81 One song per line. 82 83 ``` 84 line 1: <filename_without_extension>:<song_title>:<song_lyrics> 85 line 2: <filename_without_extension>:<song_title>:<song_lyrics> 86 ... 87 ``` 88 89 `<filename_without_extension>` will be taken as a bot command. Telegram has the following rules about bot commands: `Commands must always start with the / symbol and contain up to 32 characters. They can use Latin letters, numbers and underscores`. 90 91 `<song_title>` can contain umlauts. 92 93 `<song_lyrics>` can contain umlauts. 94 95 ##### Example 96 97 So suppose you have the song `Love Me Tender` in your `--songs-path` folder and the actual file name is `Love_Me_Tender.pdf` . The line for the `--search_file` text file could look like this: 98 99 ``` 100 Love_Me_Tender:lovemetender:lovemetenderlovemesweetneverletmegoyouhavemademylifecompleteandiloveyousolovemetenderlovemetrueallmydreamsfulfillformydarlingiloveyouandialwayswilllovemetenderlovemelongtakemetoyourheartforitstherethatibelongandwillneverpartlovemetenderlovemedeartellmeyouaremineillbeyoursthroughalltheyearstilltheendoftime 101 ``` 102 103 ## Help 104 105 If you want to use this repo but you face problems configuring it you can [contact me](mailto:kroekerrobin@gmail.com).