hushup/README.md

🤫 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.

# 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.

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

  python hushup.py --clear --register
  

• Rate Limit Warnings:

  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:

  pip install -r requirements.txt
  

Uninstalling

To remove HushUp and its environment:

# 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.