# 🤫 HushUp - Tame Your Mastodon Timeline

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)