journeyover/twitchdropsminer repository overview

⁠Twitch Drops Miner -- Docker

Thanks to @DevilXD and other contributors from the original repo⁠ for the vast majority of the code.

This application allows you to AFK mine timed Twitch drops, without having to worry about switching channels when the one you were watching goes offline, claiming the drops, or even receiving the stream data itself. This helps you save on bandwidth and hassle.

⁠How It Works:

Every several seconds, the application pretends to watch a particular stream by fetching stream metadata - this is enough to advance the drops. Note that this completely bypasses the need to download any actual stream video and sound. To keep the status (ONLINE or OFFLINE) of the channels up-to-date, there's a websocket connection established that receives events about streams going up or down, or updates regarding the current amount of viewers.

⁠Features:

• Stream-less drop mining - save on bandwidth.
• Game priority and exclusion lists, allowing you to focus on mining what you want, in the order you want, and ignore what you don't want.
• Sharded websocket connection, allowing for tracking up to 199 channels at the same time.
• Automatic drop campaigns discovery based on linked accounts (requires you to do account linking⁠ yourself though).
• Stream tags and drop campaign validation, to ensure you won't end up mining a stream that can't earn you the drop.
• Automatic channel stream switching, when the one you were currently watching goes offline, as well as when a channel streaming a higher priority game goes online.
• Login session is saved in a cookies file, so you don't need to login every time.
• Mining is automatically started as new campaigns appear, and stopped when the last available drops have been mined.
• Optional Apprise notifications for claimed drops.

⁠Usage (click for dropdown)

⁠Docker Usage

You can use pre-built Docker images to run Twitch Drops Miner:

1. Pull the Docker Image:

   You can choose from two Docker image repositories:

   • From Docker Hub:

     journeyover/twitchdropsminer:main
     

     Copy

   • From GitHub Container Registry:

     ghcr.io/journeydocker/twitchdropsminer:main
     

     Copy

   ⁠Docker Image Tags

   The TwitchDropsMiner Docker image is available in three primary tag formats, each suited to different use cases:

   • main (Continuous Development)

     • Description: The main tag is automatically updated to reflect the latest commit on the main branch in GitHub. This image corresponds to the latest development state of TwitchDropsMiner.

     • Usage Consideration: This tag is not recommended for production use, as it changes frequently and may include untested or unstable updates. Use main only if you're contributing to development or need access to the latest features and fixes.

     • Frequency: Updated with each new commit to the main branch, making this a rapidly evolving image.

     WARNING: Pulling the main tag may introduce breaking changes or instability, as it represents ongoing development work.

   • latest (Latest Stable Release)

     • Description: This tag points to the most recent stable release of TwitchDropsMiner. Unlike main, the latest tag is only updated with stable, fully-tested versions.

     • Usage Recommendation: Use the latest tag if you want the most current stable build without specifying a particular version. Ideal for production environments where stability is critical.

     IMPORTANT: Currently, there is no latest tag available. Please check back for updates on the availability of this tag.

   • A.B.C.D (Versioned Release)

     • Description: Versioned tags, such as A.B.C.D, are frozen at a specific release version and will not receive updates after publication. Each versioned tag corresponds directly to a released version of TwitchDropsMiner on GitHub.

     • Usage Recommendation: Use versioned tags when you need consistency and want to avoid updates that might alter functionality. These tags are ideal for production environments requiring fixed versions.

     IMPORTANT: Currently, there are no versioned tags (e.g., A.B.C.D) available. When they are published, each will remain fixed, ensuring a stable and unchanging image for users needing version control.

2. Run the Docker Container:

   Configure the container with environment variables to customize its behavior:

   • Allow Unlinked Campaigns: Set the UNLINKED_CAMPAIGNS environment variable to 1 to ENABLE mining drops from campaigns that are not linked to your account. By default, this is set to 0 (disabled). Note that even when unlinked campaigns are enabled, the application will still consider your priority list, so ensure the desired game is included in your priority list.

   • Apprise URLs: Set the APPRISE_URL environment variable to a comma list of Apprise URLs (e.g., Discord webhooks, email, etc.).

   • Priority Mode: Set the PRIORITY_MODE environment variable to one of the following values to determine how the miner prioritizes campaigns:

     • 0: Use the priority list directly. Campaigns are mined in the exact order they appear in the priority list, without additional prioritization.
     • 1 (default): Prioritize based on time-to-end. Campaigns in the priority list are mined based on how soon they are ending, with those nearing their end being prioritized higher.
     • 2: Optimize by time ratio. Campaigns are prioritized according to the ratio of elapsed time to remaining time, aiming to mine campaigns that are ending soonest more accurately.

   Example of running the container with these environment variables:

   docker run -itd \
     --init \
     --pull=always \
     --restart=always \
     -e UNLINKED_CAMPAIGNS=1 \
     -e PRIORITY_MODE=1 \
     -v ./cookies.jar:/TwitchDropsMiner/cookies.jar \
     -v ./settings.json:/TwitchDropsMiner/settings.json \
     -v ./logs:/TwitchDropsMiner/logs \
     -v /etc/localtime:/etc/localtime:ro \
     --name twitch_drops_miner \
     ghcr.io/journeydocker/twitchdropsminer:main
   

   Copy

   ⁠Docker Compose Example

   To simplify running TwitchDropsMiner, you can use Docker Compose with the following configuration. Create a docker-compose.yml file in your working directory:

   version: '3.8'
   
   services:
     twitchdropsminer:
       image: ghcr.io/journeydocker/twitchdropsminer:main
       container_name: twitch_drops_miner
       restart: always
       environment:
         UNLINKED_CAMPAIGNS: "0"   # Set to "1" to enable unlinked campaigns mining
         PRIORITY_MODE: "1"        # Set priority mode (0, 1, or 2)
       volumes:
         - ./cookies.jar:/TwitchDropsMiner/cookies.jar
         - ./settings.json:/TwitchDropsMiner/settings.json
         - ./logs:/TwitchDropsMiner/logs
         - /etc/localtime:/etc/localtime:ro
   

   Copy

   After creating the docker-compose.yml file, start the container with:

   docker-compose up -d
   

   Copy

• Docker Considerations: If you are running the application in Docker, remember to shut down the container before making changes directly to the settings.json file.

• IMPORTANT: Users are expected to provide their own settings.json and cookies.jar files for configuration. A webUI for easier setup is planned to come in a future release.

⁠Manual Usage:

• Download and unzip the latest release⁠.
• Run it and login/connect the miner to your Twitch account by using the in-app login form.
• After a successful login, the app should fetch a list of all available campaigns and games you can mine drops for - you can then select and add games of choice to the Priority List available on the Settings tab, and then press on the Reload button to start processing. It will fetch a list of all applicable streams it can watch, and start mining right away. You can also manually switch to a different channel as needed.
• Make sure to link your Twitch account to game accounts on the campaigns page⁠, to enable more games to be mined.

⁠Pictures:

⁠Notes:

⁠Notes about the Windows build:

• To achieve a portable-executable format, the application is packaged with PyInstaller into an EXE. Some antivirus engines (including Windows Defender) might report the packaged executable as a trojan, because PyInstaller has been used by others to package malicious Python code in the past. These reports can be safely ignored. If you absolutely do not trust the executable, you'll have to install Python yourself and run everything from source.
• The executable uses the %TEMP% directory for temporary runtime storage of files, that don't need to be exposed to the user (like compiled code and translation files). For persistent storage, the directory the executable resides in is used instead.
• The autostart feature is implemented as a registry entry to the current user's (HKCU) autostart key. It is only altered when toggling the respective option. If you relocate the app to a different directory, the autostart feature will stop working, until you toggle the option off and back on again

⁠Notes about the Linux build:

• The Linux app is built and distributed using two distinct portable-executable formats: AppImage⁠ and PyInstaller⁠.
• There are no major differences between the two formats, but if you're looking for a recommendation, use the AppImage.
• The Linux app should work out of the box on any modern distribution, as long as it has glibc>=2.35, plus a working display server.
• Every feature of the app is expected to work on Linux just as well as it does on Windows. If you find something that's broken, please open a new issue⁠.
• The size of the Linux app is significantly larger than the Windows app due to the inclusion of the gtk3 library (and its dependencies), which is required for proper system tray/notifications support.
• As an alternative to the native Linux app, you can run the Windows app via Wine⁠ instead. It works really well!

⁠Notes about the macOS build:

• The macOS version is packaged using PyInstaller into a standalone .app bundle, distributed as a ZIP archive.
• Since this application is not signed with a paid Apple Developer Certificate, macOS Gatekeeper will block it on the first run (saying it "The application is damaged and can't be opened").
  • To fix this: Either open the Terminal in the folder the app is in (or navigating with cd path/to/folder) and enter xattr -cr Twitch Drops Miner (by DevilXD).app or just type xattr -cr (make sure to put a space at the end), drag and drop the Twitch Drops Miner (by DevilXD).app file into the terminal window (this will auto-fill the path) and enter
• Persistent files (like cookies.jar, settings.json, lock.file and the cache folder) are stored inside the application bundle in Twitch Drops Miner (by DevilXD).app/Contents/MacOS (to access them Right-click the application and select Show Package Contents)

⁠Advanced Usage:

If you'd be interested in running the latest master from source or building your own executable, see the wiki page explaining how to do so: https://github.com/DevilXD/TwitchDropsMiner/wiki/Setting-up-the-environment,-building-and-running⁠

⁠Support

If you encounter any issues with the miner:

• Please see the troubleshooting page⁠ for some common issues and their explanation.
• Please search the issues page⁠ or issues page⁠ to see if your issue hasn't been reported yet.
• Before reporting a new issue, please test the original version to see if the problem happens there as well:
  • If the issue occurs on the original upstream version, please report it on the DevilXD repo.
  • If the issue is only present on this version, please report the issue on my repo.

⁠Project goals:

Twitch Drops Miner (TDM for short) has been designed with a couple of simple goals in mind. These are, specifically:

• Twitch Drops oriented - it's in the name. That's what I made it for.
• Easy to use for an average person. Includes a nice looking GUI and is packaged as a ready-to-go executable, without requiring an existing Python installation to work.
• Intended as a helper tool that starts together with your PC, runs in the background through out the day, and then closes together with your PC shutting down at the end of the day. If it can run continuously for 24 hours at minimum, and not run into any errors, I'd call that good enough already.
• Requiring a minimum amount of attention during operation - check it once or twice through out the day to see if everything's fine with it.
• Underlying service friendly - the amount of interactions done with the Twitch site is kept to the minimum required for reliable operation, at a level achievable by a diligent site user.

TDM is not intended for/as:

• Mining channel points - again, it's about the drops: only.
• Mining anything else besides Twitch drops - no, I won't be adding support for a random 3rd party site that also happens to rely on watching Twitch streams.
• Unattended operation: worst case scenario, it'll stop working and you'll hopefully notice that at some point. Hopefully.
• 100% uptime application, due to the underlying nature of it, expect fatal errors to happen every so often.
• Being used with more than one managed account.

This means that features such as:

• Anything that increases the site processing load caused by the application.
• Any form of additional notifications system (email, webhook, etc.), beyond what's already implemented.

..., are most likely not going to be a feature, ever. You're welcome to search through the existing issues to comment on your point of view on the relevant matters, where applicable. Otherwise, most of the new issues that go against these goals will be closed and the user will be pointed to this paragraph.

For more context about these goals, please check out these issues: #161⁠, #105⁠, #84⁠

⁠Credits⁠