ChannelPointsMiner

ChannelPointsMiner copied to clipboard

= Channel Points Miner :toc: :toclevels: 4 :toc: preamble

image:https://codecov.io/gh/RakSrinaNa/ChannelPointsMiner/branch/main/graph/badge.svg[link="https://codecov.io/gh/RakSrinaNa/ChannelPointsMiner",window="_blank",align="center"] image:https://img.shields.io/docker/pulls/mrcraftcod/channel-points-miner.svg[link="https://hub.docker.com/r/mrcraftcod/channel-points-miner",window="_blank",align="center"] image:https://img.shields.io/discord/1007349372444491856.svg?label=Discord&logo=Discord&colorB=7289da[link="https://discord.gg/uXWsRftdy7",window="_blank",align="center"]

WARN: If you're reading this on GitHub, this may correspond to the documentation of the develop branch. If you want documentation of the latest released version please go to link:https://raksrinana.github.io/ChannelPointsMiner/[pages].

The main objective of this miner is to acquire Twitch channel points automatically. Other forms of point, like those provided by bots through IRC (Streamlabs, etc.), isn't in the scope of the miner.

• Watch streams for you, earning the baseline points as you watch.
• Get the watch streak points by watching streams regularly.
• Claim bonus points when they are available.
• Follow raids.
• Participate and claim link:https://www.twitch.tv/drops/campaigns[campaigns].
• Join IRC chat.
• Participate in predictions and record peoples predictions.
• Claim link:https://help.twitch.tv/s/article/moments[moments].

Limits:

• Twitch makes it so that only 2 streamers can be watched at once. However, actions that are not watching are not limited. This includes raids and predictions.

This project heavily inspired by link:https://github.com/Tkd-Alex/Twitch-Channel-Points-Miner-v2[Tkd-Alex/Twitch-Channel-Points-Miner-v2,window="_blank"], just doing it my own way.

== How to use [[how_to_use]]

=== Clone

Java 17+ is required.

1. Clone this repository git clone [email protected]:RakSrinaNa/ChannelPointsMiner.git.
2. Get into the cloned directory cd ChannelPointsMiner.
3. Build the jar ./gradlew build -x test
4. Run

• Default: java -jar miner/build/libs/miner-shaded.jar --settings config.json
• With your own <<logs,logger>>: java -Dlog4j.configurationFile=log4j2.xml -jar miner/build/libs/miner-shaded.jar --settings config.json

=== Docker

Image link:https://hub.docker.com/r/mrcraftcod/channel-points-miner[mrcraftcod/channel-points-miner,window="_blank"] can be used.

Here's an example dockerfile:

[source,yml]

version: "3.9"

services: miner: image: mrcraftcod/channel-points-miner:latest command: "--settings /usr/src/app/config.json" volumes: - ./authentication:/usr/src/app/authentication - ./streamers:/usr/src/app/streamers - ./config.json:/usr/src/app/config.json:ro

With a custom <<logs,logger>>:

[source,yml]

version: "3.9"

services: miner: image: mrcraftcod/channel-points-miner:latest command: "--settings /usr/src/app/config.json" environment: JDK_JAVA_OPTIONS: "-Dlog4j.configurationFile=/usr/src/app/log4j2.xml" volumes: - ./authentication:/usr/src/app/authentication - ./streamers:/usr/src/app/streamers - ./config.json:/usr/src/app/config.json:ro - ./log4j2.xml:/usr/src/app/log4j2.xml:ro

NOTE: If you have 2FA enabled you'll have to enter your token the first time in order to login. As Docker doesn't give an interactive shell by default you'll have to run the container in interactive mode yourself the first time. More can be read about it in link:https://github.com/RakSrinaNa/ChannelPointsMiner/issues/87[#87].

== How to mine streamers

You have two options to load streamers in the mining list:

• Be specific and define streamer settings for each streamer you want to watch. For this simply add a JSON file withing one of the <<global_settings__streamer_config_directories,streamer config directory>> with the name of the streamer (eg: mystreamer.json). The content of the file will override the <<global_settings__default_streamer_settings,default streamer settings>> for the keys that are redefined. If you want to use the <<global_settings__default_streamer_settings,default streamer settings>> simply use an empty file or put an empty JSON object in the file (ie: {}).
• Load them from the follows list. Every follow will be loaded and default settings will be applied to them.

NOTE: If a stream is both defined in a JSON file and is followed, then the first case will apply.

== Settings

2 kind of settings are present:

• The <<global_settings,global settings>> that defines the global behavior of the miner as well as the default streamer settings.
• The <<streamer_settings,streamer settings>> that'll be applied for each streamer and override the default ones.

=== Global settings [[global_settings]]

The settings consist of on object with a list of <<account_settings,account settings>> under the accounts field. Something like:

[source,json]

{ "accounts": [{ "accountSetting1": "value", "accountSetting2": "value" }] }

Examples can be found in link:https://github.com/RakSrinaNa/ChannelPointsMiner/blob/main/src/examples/config[src/examples/config,window="_blank"].

=== Account settings [[account_settings]]

Account settings define all the settings for a Twitch account that will be used to mine points.

[cols="1,3a,1"] |=== |Name |Description |Default value

|username |Your Twitch account username. |

|password |Your Twitch account password. |

|use2FA |If you use 2-factor authentication enable this to ask the 2FA code directly when login in. |false

|authenticationFolder |Path to the folder containing the authentication file |./authentication

|loadFollows |If set to true link:https://www.twitch.tv/directory/following/[streamers followed,window="_blank"] on the account will be mined. |false

|enabled |If set to true the account will be mined. Otherwise, it won't be mined but still allows you to have its configuration defined for later. |true

|defaultStreamerSettings [[global_settings__default_streamer_settings]] |Default <<streamer_settings,streamer settings>> to apply to every streamer. |Default streamer settings

|streamerConfigDirectories [[global_settings__streamer_config_directories]] |A list of <<streamer_directories,streamer directories>> containing <<streamer_settings,streamer settings>>. |

|discord |<<discord_settings,Discord settings>>. |

|reloadEvery |Reload <<streamer_settings,streamer settings>> every reloadEvery minutes. New streamer configurations will be added, already existing ones will be updated, and removed one will be removed.

A zero or negative value will disable this feature. We recommend setting this value to something not too low as this is a rather intensive treatment (15 minutes minimum seems fair).

NOTE: Only <<streamer_settings,streamer settings>> are reloaded, not the <<global_settings,global settings>>. |0

|analytics |<<analytics_settings,Analytics settings>>. |

|chatMode |Define what method is used to connect to Twitch chat.

• WS: Using WebSocket method (used on Twitch website).
• IRC: Using IRC protocol. |WS |===

=== Streamer directories [[streamer_directories]]

[cols="1,3,1"] |=== |Name |Description |Default value

|path |Path to a folder containing <<streamer_settings,streamer settings>>. |

|recursive |If set to true, the folder will be scanned recursively. |false |===

=== Discord settings [[discord_settings]]

Discord settings define settings to be used with Discord webhooks. Leave it empty if you don't want the feature.

[cols="1,3,1"] |=== |Name |Description |Default value

|webhookUrl |Discord webhook url to publish events to. |

|embeds |If true embeds will be sent in the chat. |false |===

=== Analytics settings [[analytics_settings]]

Analytics settings define a way to collect data on your twitch account as time passes. This includes:

• Balance evolution
• Your own Predictions made & results
• Predictions from other chat participants and their return-on-investment (only approximate as the bet amount is mostly anonymous).

These are stored in an external database which allows any external software to access it and process it the wanted way.

Several database types are supported and listed below. Each database (logical database for MariaDB, different file for H2/SQLite) will however represent one mined account. You'll therefore have to adjust the settings for each mined account to not point to the same one.

[cols="1,3,1"] |=== |Name |Description |Default value

|enabled |If set to true, data will be collected. |false

|database |<<analytics_database_settings,Analytics database settings>>. |

|recordChatsPredictions |If set to true, other peoples predictions will be recorded. This is done from two sources, from the top-predictors list and from chat messages (via their badge). Reading from chat, requires the joinIrc setting to be set to true. |false |===

==== Analytics database [[analytics_database_settings]]

[cols="1,3a,1"] |=== |Name |Description |Default value

|jdbcUrl |link:https://www.baeldung.com/java-jdbc-url-format[JDBC url] for the database connection

• MariaDB: jdbc:mariadb://host:port/database (great if you have a DB available or running inside docker as you can set a mariadb container)
• SQLite: jdbc:sqlite:/path/to/file (great running locally and want to store it to a file, however less resilient and more prone to corruption).

|

|username |Account username to access database.

NOTE: Can be omitted if no account |

|password |Account password to access database.

NOTE: Can be omitted if no password |

|maxPoolSize |Maximum number of connections to the database.

NOTE: For SQLite connection, value 1 will be forced. |10 |===

=== Streamer settings [[streamer_settings]]

Streamer settings define settings that will override the <<global_settings__default_streamer_settings,default streamer settings>> for a particular streamer.

Each streamer setting will be defined in a json file named with the username of the streamer (eg: myusername.json) and placed in the <<global_settings__streamer_config_directories,streamerConfigDirectory>> directory.

An example can be found link:https://github.com/RakSrinaNa/ChannelPointsMiner/blob/main/miner/src/test/resources/factory/fullyOverridden.json[here,window="_blank"].

[cols="1,3,1"] |=== |Name |Description |Default value

|enabled |If set to false, this streamer won't be mined nor will join chat. |true

|makePredictions |If set to true, predictions will be made for this streamer. |false

|followRaid |If set to true, the miner raid will attend raids for extra points. |false

|participateCampaigns |If set to true, progression towards campaigns will be made, and completed rewards will be claimed. |false

|claimMoments |If set to true, link:https://help.twitch.tv/s/article/moments[moments] will be claimed when available. |false

|joinIrc |If set to true IRC channel of the streamer will be joined. |false

|predictions |Settings related to predictions (see <<prediction_settings,prediction settings>>. |Default <<prediction_settings,predictions settings>>.

|priorities |A list of conditions that if met will prioritize this streamer (see <<priorities,priorities>>). |empty

|index |The streamer index. This value is used when streamers have the same score from the <<priorities,priorities>>, the one with the lowest index will be picked first. |max value (last to be picked) |===

==== Prediction settings [[prediction_settings]]

[cols="1,3,1"] |=== |Name |Description |Default value |minimumPointsRequired |Minimum amount of points to have to place a bet. If this threshold is not reached, no bet is placed. |0

|delayCalculator |How to calculate when to place the bet (see <<prediction_delay,prediction delay>>). |fromEnd(10)

|outcomePicker |How to choose what outcome (side / color) to place the bet on (see <<outcome_picker,outcome pickers>>). |smart(0.2)

|amountCalculator |How to calculate the amount to the bet (see <<amount_calculator,amount calculators>>). |percentage(percentage: 20, max: 50000)

|actions |A list of <<prediction_actions,prediction actions>> to perform before a bet is placed | |===

==== Priorities [[priorities]]

Priorities is a way to prioritize streamers among each others to mine one over another based on some conditions.

You can then modify the position of a streamer by adding priorities to the streamers you want and if the condition is met then a score will be added to its overall score (sum of all the priority's scores). The 2 streamers that have the highest overall score will be those mined. If there's an exe-quo they'll be picked by their index, and if equal too it'll be random.

Each priority is different and can have a set of different parameters. The table below will list their type to be used in the JSON configuration as well as the conditions of activation and parameters.

[cols="1,3,1,2a"] |=== |Type |Description |Condition |Parameters

|constant |Adds a constant value to the score of the streamer. For example if you want a streamer to always be first, you can set this priority with a score of 99999, and it'll always have at least this amount. |Always |* score: Score to give.

|subscribed |Return a score if the logged-in user is subscribed to the streamer. Values can be defined per sub tier. |User is subscribed. |* score: Score for a T1 sub.

• score2: Score for a T2 sub.

• score3: Score for a T3 sub.

|pointsAbove |Return a score if owned points are above a defined value. |Channel points are above threshold. |* score: Score to give.

• threshold: Current points must strictly be above this value to give the score.

|pointsBelow |Return a score if owned points are below a defined value. |Channel points are below threshold. |* score: Score to give.

• threshold: Current points must strictly be below this value to give the score.

|watchStreak |Return a score if the streamer has a potential watch streak to claim. |A watch streak may be claimed. |* score: Score to give.

|drops |Return a score if a drop campaign may be progressed by watching this stream. |Drops can be progressed. |* score : Score to give. |===

NOTE: If you're banned from the chat of a channel, it'll be skipped as you can't gather points there.

==== Prediction delays [[prediction_delay]]

Prediction delays allow you to define when a bet should be placed.

NOTE: All delays will be within an imposed time window: [created date + 5s ; created date + prediction window - 5s].

WARNING: Delay are calculated from when the prediction is created, if a moderator closes the bet early (which happens on some channels where a long timer is set) and the bet hasn't already been placed, then it'll be too late.

The table below will list their type to be used in the JSON configuration as well as how the delay is computed and parameters.

[cols="1,3,1,2a"] |=== |Type |Description |Computation |Parameters

|fromEnd |Place the bet a certain amount of time before the end of the original prediction. |Prediction end date - seconds seconds. |* seconds: Number of seconds before the end to place the bet.

|fromStart |Place the bet a certain amount of time after the beginning of the original prediction. |Prediction start date + seconds seconds. |* seconds: Number of seconds after the start to place the bet.

|percentage |Place the bet after percent% of the original timer elapsed. |Prediction stat date + precent * time window. |* percent: The percentage of the timer, as a decimal value, between 0 and 1. |===

==== Outcome pickers [[outcome_picker]]

Outcome pickers allow you to define what outcome (side / color) will be chosen to place the bet on.

The table below will list their type to be used in the JSON configuration as well as how the side is computed and parameters.

[cols="1,3,1,2a"] |=== |Type |Description |Computation |Parameters

|mostUsers |Choose the outcome with the most users. |Outcome with the higher user count is picked. |

|leastUsers |Choose the outcome with the least users. |Outcome with the lower user count is picked. |

|mostPoints |Choose the outcome with the most points. |Outcome with the higher total points is picked.

This is the same as "the outcome with lower odds". |

|leastPoints |Choose the outcome with the least points. |Outcome with the lower total points is picked.

This is the same as "the outcome with higher odds". |

|biggestPredictor |Choose the outcome with the biggest predictor. |Outcome with the person that placed the biggest prediction overall. |

|mostTrusted |Choose the outcome that's backed by other users with the highest average return-on-investment. Requires at least some data gathered beforehand via the 'recordChatsPredictions' setting! E.g. only users with at least 5 made predictions are taken into account by default. |Take the return-on-investment from people who already placed a prediction, calculate the average per outcome, then pick the highest. |* minTotalBetsPlacedByUser: only user with at least this number of bets are considered in the calculation. Default is 5.

• minTotalBetsPlacedOnPrediction: if not enough bets were placed, skip this prediction. Default is 10.

• minTotalBetsPlacedOnOutcome: if not enough bets were placed on the chosen outcome, skip this prediction. Default is 5.

|smart |Choose the outcome with the most users. However, if the two most picked outcomes have a user count similar, choose the outcome with the least points (higher odds). |If the difference of the user percentages between the 2 most picked outcomes is less than percentageGap% then choose the outcome with lower points, otherwise the one with most users. | * percentageGap: The percent gap of the user count, as decimal, between 0 and 1.

(i.e. Setting this to 0.1, will mean that the condition switches states when the difference between sides is 10%, so 45% of the users on one side and 55% on the other) |===

==== Amount calculators [[amount_calculator]]

Amount calculators allow you to define how the amount to place is calculated.

WARNING: The minimum amount that can be placed is 10.

The table below will list their type to be used in the JSON configuration as well as how the amount is computed and parameters.

[cols="1,3,1,2a"] |=== |Type |Description |Computation |Parameters

|constant |Always bet the same amount. |Place amount points. |* amount: Amount to place.

|percentage |Place a percentage of your points (with a limit). |Place percentage% of your current points. If this values goes over max then max points will be placed instead. |* percentage: Percentage of your owned points to place, as a decimal value, between 0 and 1.

• max: Maximum number of points. |===

==== Prediction actions [[prediction_actions]]

Prediction actions are a way to perform actions / verifications before a bet is placed.

The table below will list their type to be used in the JSON configuration as well as what is performed.

[cols="1,3,1,2a"] |=== |Type |Description |Computation |Parameters

|stealth |Ensure that the amount placed is lower than the top predictor. |If no top predictor is found, cancel the bet. Otherwise, if the amount placed by the top predictor is lower or equal to our prediction then set ours to his amount - 1. | |===

== Logs [[logs]]

You can define yourself how the logs looks like by supplying your own link:https://logging.apache.org/log4j/2.x/manual/configuration.html[Log4j2 configuration file] (see <<how_to_use,how to use>> to see how to load this config file).

Some examples are provided in the src/examples/loggers folder.

When you configure your link:https://logging.apache.org/log4j/2.x/manual/layouts.html[patterns] you'll of course have access to all the default fields possible like the date, message, etc. In addition to that the context will be populated with some keys depending on the available data (in the caase of the Pattern layout, see %X). These keys are listed below:

[cols="1,3"] |=== |Key |Description

|account_name |The account used to do the mining.

|streamer_name |The name of the streamer for which the message is linked to.

|websocket_id |The id of the websocket that is at the origin of the message sent/received on the websocket.

|websocket_topic |Topic name of the message received on the websocket.

|event_id |Event id of a prediction. |===

== Viewer

Another module is available to display analytics data, see link:viewer/README.adoc[viewer module].

== Disclaimer

This project comes with no guarantee or warranty. You are responsible for whatever happens from using this project. It is possible to get soft or hard banned by using this project if you are not careful. This is a personal project and is in no way affiliated with Twitch.