Differences
This shows you the differences between two versions of the page.
|
ii:labs:04:tasks:03 [2021/12/06 17:02] radu.mantu |
ii:labs:04:tasks:03 [2024/11/20 16:03] (current) florin.stancu created |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ==== 03. [??p] Adding features ==== | + | ==== 03. [40p] Adding features ==== |
| + | |||
| + | Up until now, everything was pretty tutorial-ish. From here on out, it's time for you to get your hands dirty and add some new features to the bot! This means looking stuff on the Internet. For yourselves. Scary stuff... I know! \\ | ||
| + | **Hint:** a good starting point would be the [[https://docs.pycord.dev/en/stable/api/index.html|API Reference page]]. | ||
| + | |||
| + | === [20p] Task A - Playing music === | ||
| + | |||
| + | Let's begin by adding the most important feature of a music bot: a ''play'' command that takes a song name (e.g.: [[https://www.youtube.com/watch?v=yK0P1Bk8Cx4|danger_zone.mp3]]) as argument. Invoking this command while present in a voice channel should cause the bot to connect to that channel and play the song. The song should be loaded from a local file (hint: use any music file that you have on hand, or a [[https://x2convert.com/en129/download-youtube-to-mp3-music|YouTube downloader]]). | ||
| + | |||
| + | In order to do that, please note how the commands are defined: | ||
| + | |||
| + | <code python> | ||
| + | @bot.command(brief='Generate random number between 1 and <arg>') | ||
| + | async def roll(ctx, max_val: int): | ||
| + | # implementation goes here ... | ||
| + | </code> | ||
| + | |||
| + | To create new discord bot commands, simply define your function with the name of the command and decorate them with [[https://docs.pycord.dev/en/stable/api/application_commands.html#discord.commands.application_command|@bot.command]] as above. Oh, and whats with that '': int'' declaration? I thought Python doesn't require us to give types to our variables... that's right! But [[https://docs.python.org/3/library/typing.html|we're now able to]], if we want ;) | ||
| + | |||
| + | But, as expected, the hardest part will be implementing it. There are several questions: how can you load an ''.mp3'' file from disk? how can you send it streaming over the Discord server? etc. | ||
| + | |||
| + | You will need to read some more API references to find the appropiate calls: | ||
| + | |||
| + | * Start from [[https://docs.pycord.dev/en/stable/api/voice.html#discord.VoiceClient|VoiceClient]]. You can read that it provides a ''play()'' function, though note that you cannot instantiate this directly... so we'll move on through the links! | ||
| + | * Next is the ''VoiceChannel.connect()'' routine that gives us a voice channel, but how to we get a voice channel object? | ||
| + | * Here's the idea: find the voice channel the user issuing the play command is connected to! | ||
| + | * So we start from our ''ctx'' variable, which we can find that is of type [[https://docs.pycord.dev/en/stable/api/application_commands.html#discord.ApplicationContext|ApplicationContext]] (ofc!); we follow up with the ''author'', which has a ''voice'' property (of type ''VoiceState''), which finally brings us to our desired channel! | ||
| + | * Once we got ahold of our ''VoiceChannel'', we connect to it and we finally get a ''VoiceClient'', phew! Now we can simply use ''play()''... | ||
| + | * What's that? ''play()'' requires an [[https://docs.pycord.dev/en/stable/api/voice.html#discord.AudioSource|AudioSource]]-type argument? We just need something that reads ''mp3'' files... oh, we see a [[https://www.ffmpeg.org/|ffmpeg]] naming in there, which is a very popular open source library which can read almost every audio/video format in existence (check the right side menu!), so problem solved! | ||
| + | * Now get to writing the code! :P | ||
| + | |||
| + | <note> | ||
| + | **Hint:** check this out for an example: https://brucecodes.gitbook.io/pycord/guide/voice-commands | ||
| + | </note> | ||
| + | |||
| + | === [10p] Task B - Enumerating the songs === | ||
| + | |||
| + | This one is easier: build a **list** command that lists all available songs in the discord chat. | ||
| + | |||
| + | Use the basic Python [[https://docs.python.org/3/library/os.html|OS functions]] for easily reading directory contents and filtering by ''mp3'' extension. | ||
| + | |||
| + | |||
| + | === [10p] Task C - Misc commands === | ||
| + | |||
| + | Let's assume someone enters your channel and [[https://www.youtube.com/watch?v=nZ-hHx9yh0s|plays this]]. We'll need a quick solution... | ||
| + | |||
| + | So: create a **scram** command that tells the bot to disconnect from the current voice channel immediately (which will stop the play!). | ||
| + | |||
| + | Finally, make an event handler for ''on_voice_state_update'' that checks if the bot was left alone in the channel after a user left. If the bot is indeed alone, it should also disconnect. | ||
| + | |||
| + | That's it! | ||
| - | When you want to add a new feature to your project, you should first develop it in a [[https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches|branch]]. A branch is a named copy of the deltas that comprise your codebase up to a certain point. By adding commits to this copy, you won't interfere with other people trying to do their own thing. | ||
| - | {{ :ii:labs:04:tasks:branches.png?700 |}} | ||
