diff --git a/README.md b/README.md index a2bdfab..6efc459 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,161 @@ -# hushup +# 🤫 HushUp - Tame Your Mastodon Timeline -HushUp helps you temporarily mute the most active follows, bringing a little calm back to your timeline. \ No newline at end of file +Ever spend some time touching grass only to come back to a busy afternoon on the timeline? Wish you could just hit a temporary mute button on accounts having a *really* chatty day without unfollowing them and missing their future gems? + +HushUp is a simple Python script designed to help you manage timeline noise by identifying and temporarily muting overly active accounts, based on your preferences. + +## Features + +* **Intelligent Activity Detection:** Automatically identifies accounts posting a little too much. +* **Temporary Muting:** Silences noisy accounts for a configurable duration, bringing them back automatically. +* **Easy Setup:** Quick first-time registration with your Mastodon instance. +* **Customizable:** Fine-tune mute duration, activity thresholds, and API behavior via environment variables. +* **API Friendly:** Designed with Mastodon API rate limits in mind, with sensitive defaults and automatic backoff. + +## Get Started + +As long as Python doesn't freak you out, getting HushUp running is a breeze. + +### Installation (conda recommended) + +Using `conda` helps keep your project dependencies tidy. + +```bash +# Create a dedicated conda environment +conda create -n hushup python=3.10 + +# Activate your new environment +conda activate hushup + +# Install HushUp's dependencies +pip install -r requirements.txt +``` + +### First-Time Setup & Authorization + +You'll need to authorize HushUp to access your Mastodon account. This step only needs to be done once. + +```bash +# Run the initial setup process +python hushup.py --register +``` + +Follow the prompts: +1. Enter your Mastodon instance URL (e.g., `https://mastodon.social`). +2. HushUp will provide you with a URL. Open this in your browser, authorize the application, and you'll get an authorization code. +3. Paste the authorization code back into your terminal when prompted. + +HushUp will save your credentials securely for future use. + +### Configuration (`.env` file) + +After successfully registering, HushUp will create a `.env` file in the project directory. This is where you can customize its behavior. Open this file with your favorite text editor and tweak the settings to your liking: + +```ini +# API Performance Settings - Adjust these if you encounter rate limits often or need faster processing +HUSHUP_MAX_REQUESTS=40          # Maximum number of API requests to fetch timeline data per run (default: 20) +HUSHUP_ITEMS_PER_REQUEST=100    # How many items (toots) to request in each API call (default: 80) +HUSHUP_RATE_LIMIT_DELAY=1.0     # Short delay between API calls to stay under limits (default: 0.5) + +# Behavior Settings - Control how HushUp decides who to mute and for how long +HUSHUP_MUTE_DURATION=3600       # How long to mute identified accounts, in seconds (default: 21600 = 6 hours) +HUSHUP_MIN_ACTIVITIES=20        # The activity threshold: mute accounts that have posted *at least* this many times in the analyzed period (default: 10) +``` + +*Remember to save the `.env` file after making changes.* + +## Running HushUp + +Once set up and configured, running HushUp is straightforward: + +```bash +# Analyze your timeline and apply mutes based on your .env settings +python hushup.py +``` + +You can also override the activity threshold directly from the command line for a specific run: + +```bash +# Analyze and mute accounts with at least 20 activities +python hushup.py --min_activities 20 +``` + +The mute duration is controlled by the `HUSHUP_MUTE_DURATION` setting in your `.env` file. It's best to stick with one of Mastodon's default mute values: + + * 5 minutes (300) + * 30 minutes (1800) + * 1 hour (3600) + * 6 hours (21600) + * 1 day (86400) + * 3 days (259200) + * 7 days (604800) + +## Advanced Usage + +### Re-registering / Clearing Credentials + +If you need to connect to a different instance or encounter authorization issues, you can force a fresh registration: + +```bash +# Clear existing credentials and start the registration process over +python hushup.py --clear --register +``` + +### Resetting Configuration + +To revert your settings back to the original defaults and go through registration again: + +```bash +# Remove the generated config and credential files +rm .env clientcred.secret + +# Run the registration process, which will also create a new .env with defaults +python hushup.py --register +``` + +## Safety & API Rate Limits + +HushUp is designed to be a good Fediverse citizen. The default settings are conservative in order to minimize the risk of hitting API rate limits on your Mastodon instance: + +* Defaults limit analysis to around 1,600 toots per run (20 requests × 80 items). +* A small delay is added between API calls (default 0.5 seconds). +* HushUp includes automatic rate limit detection and will pause if the API tells it to slow down. + +**Important:** Most Mastodon instances have a rate limit of around 300 requests every 5 minutes. While HushUp tries its best, adjusting `HUSHUP_MAX_REQUESTS`, `HUSHUP_ITEMS_PER_REQUEST`, and `HUSHUP_RATE_LIMIT_DELAY` should be done carefully based on your instance's specific limits and your usage frequency. + +## Troubleshooting + +* **Authorization Errors:** If you see errors related to credentials or authorization, try clearing them and re-registering: + ```bash + python hushup.py --clear --register + ``` +* **Rate Limit Warnings:** + ```text + WARNING: Rate limited. Waiting 30 seconds... + ``` + This means HushUp hit the API limit. The script will automatically wait and retry. If you see this frequently, consider reducing the `HUSHUP_ITEMS_PER_REQUEST` or `HUSHUP_MAX_REQUESTS` in your `.env` file. +* **Missing Dependencies:** If you get import errors, ensure you've installed the requirements: + ```bash + pip install -r requirements.txt + ``` + +## Uninstalling + +To remove HushUp and its environment: + +```bash +# Deactivate the conda environment +conda deactivate + +# Remove the conda environment +conda env remove -n hushup + +# Remove configuration and credential files +rm -rf .env clientcred.secret +``` + +## License + +This project is licensed under the MIT License. + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) \ No newline at end of file