{"id":13410076,"url":"https://github.com/cronokirby/alchemy","last_synced_at":"2025-09-27T15:30:44.563Z","repository":{"id":17583459,"uuid":"80942788","full_name":"cronokirby/alchemy","owner":"cronokirby","description":"A discord library for Elixir","archived":true,"fork":false,"pushed_at":"2023-05-01T17:54:31.000Z","size":581,"stargazers_count":152,"open_issues_count":26,"forks_count":34,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-05-16T11:17:19.379Z","etag":null,"topics":["discord","discordapp","elixir","library"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cronokirby.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-04T19:29:03.000Z","updated_at":"2024-07-30T22:51:35.705Z","dependencies_parsed_at":"2024-07-30T23:09:01.227Z","dependency_job_id":null,"html_url":"https://github.com/cronokirby/alchemy","commit_stats":{"total_commits":475,"total_committers":20,"mean_commits":23.75,"dds":"0.12210526315789472","last_synced_commit":"7952a0edfd39958cb9e949aff4602263c38ab494"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronokirby%2Falchemy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronokirby%2Falchemy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronokirby%2Falchemy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cronokirby%2Falchemy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cronokirby","download_url":"https://codeload.github.com/cronokirby/alchemy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219872008,"owners_count":16554482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord","discordapp","elixir","library"],"created_at":"2024-07-30T20:01:04.841Z","updated_at":"2025-09-27T15:30:39.248Z","avatar_url":"https://github.com/cronokirby.png","language":"Elixir","funding_links":[],"categories":["Libraries"],"sub_categories":["Elixir"],"readme":"# Alchemy\n\nA Discord library / framework for Elixir.\n\nThis library aims to provide a solid foundation, upon which to build\na simple, yet powerful interface. Unlike other libraries, this one comes\nalong with a framework for defining commands, and event hooks. No need\nto mess around with consumers, or handlers, defining a command is as simple\nas defining a function!\n\n\n### Installation\nSimply add *Alchemy* to your dependencies in your `mix.exs` file:\n```elixir\ndef deps do\n  [{:alchemy, \"~\u003e 0.7.0\", hex: :discord_alchemy}]\nend\n```\n\n### [Docs](https://hexdocs.pm/discord_alchemy/0.6.9)\n\nThis is the stable documentation for the library, I highly recommend going\nthrough it, as most of the relevant information resides there.\n\n### QuickStart\nRun `mix alchemy.init` to generate a template bot file for your project.\n\n### Getting Started\nThe first thing we need to do is define some kind of application for our bot.\nThankfully, the `Application` module encapsulates this need.\n```elixir\ndefmodule MyBot do\n  use Application\n  alias Alchemy.Client\n\n\n  defmodule Commands do\n    use Alchemy.Cogs\n\n    Cogs.def ping do\n      Cogs.say \"pong!\"\n    end\n  end\n\n\n  def start(_type, _args) do\n    run = Client.start(\"your token here\")\n    use Commands\n    run\n  end\nend\n```\nSo we defined what we call a `Cog` in the `Commands` module, a cog\nis simply a module that contains commands. To wire up this command into the bot,\nwe need to `use` the module, which we do after starting the client. We need\nto provide a valid return type in `start/2`, which is why we capture the result\nof `Client.start` in a variable.\n\nNow all we need to do to wire up this application, is to add it to our `mix.exs`:\n```elixir\ndef application do\n  [mod: {MyBot, []}]\nend\n```\nThis makes our bot automatically start when we run our project.\nNow, to run this project, we have 2 options:\n - use `mix run --no-halt` (the flags being necessary to\n   prevent the app from ending once our `start/2` function finishes)\n - or use `iex -S mix` to start our application in the repl.\n\nStarting the application in the repl is very advantageous, as it allows\n you to interact with the bot live.\n\n### Using Voice\nAlchemy also supports using Discord's Voice API to play audio.\nWe rely on [ffmpeg](https://ffmpeg.org/) for audio encoding,\nas well as [youtube-dl](https://rg3.github.io/youtube-dl/) for streaming\naudio from sites. Before the Voice API can be used, you'll need to acquire\nthe latest versions of those from their sites (make sure you get ffmpeg\nwith opus support), and then configure the path to those executables in\nalchemy like so:\n```\n# in config.exs\nconfig :alchemy,\n  ffmpeg_path: \"path/to/ffmpeg\",\n  youtube_dl_path: \"path/to/youtube_dl\"\n```\n\nNow you're all set to start playing some audio!\n\nThe first step is to connect to a voice channel with `Alchemy.Voice.join/2`,\nthen, you can start playing audio with `Alchemy.Voice.play_file/2`,\nor `Alchemy.Voice.play_url/2`. Here's an example command to show off these\nfeatures:\n```elixir\nCogs.def play(url) do\n  {:ok, guild} = Cogs.guild()\n  default_voice_channel = Enum.find(guild.channels, \u0026match?(%{type: 2}, \u00261))\n  # joins the default channel for this guild\n  # this will check if a connection already exists for you\n  Alchemy.Voice.join(guild.id, default_voice_channel.id)\n  Alchemy.Voice.play_url(guild.id, url)\n  Cogs.say \"Now playing #{url}\"\nend\n```\n\n### Porcelain\nAlchemy uses [`Porcelain`](https://github.com/alco/porcelain), to\nhelp with managing external processes, to help save on memory usage,\nyou may want to use the `goon` driver, as suggested by `Porcelain`.\nFor more information, check out their GitHub.\n\n# Other Examples\nIf you'd like to see a larger example of a bot using `Alchemy`,\ncheckout out [Viviani](https://github.com/cronokirby/viviani).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcronokirby%2Falchemy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcronokirby%2Falchemy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcronokirby%2Falchemy/lists"}