Example INI File

This is an example configuration file for Mastoscore. It shows all available options with example values and explanations.

[mastoscore]
# Credentials file for the bot account that will post the analysis
# This should be a path to a file containing your Mastodon API token
cred_file    = .env/mastoscore.env

# The hashtag to analyze (without the # symbol)
hashtag      = myhashtag

# The Mastodon server where your bot account is hosted
api_base_url = https://example.social

# Event metadata - used for titles
event_title   = My Event         # Overall event name (e.g., "Monsterdon")
episode_title = Episode Title    # Specific episode or instance (e.g., "Cat Girl (1957)")

# Date of the event - used for data file names, and picking the right dates for posts
event_year   = 2025              # Year of the event (YYYY)
event_month  = 04                # Month of the event (MM)
event_day    = 15                # Day of the event (DD)

# Time components for the event - include timezone offset
event_time_start = 21:00:00-04:00  # Start time with timezone offset
event_time_end   = 22:30:00-04:00  # End time with timezone offset

# Analysis settings
top_n        = 3                 # Number of top toots to report in each category
lookback     = 3                 # Days to look back when fetching toots
debug        = INFO              # Logging level (DEBUG, INFO, WARN, ERROR)
timezone     = America/New_York  # Timezone for analysis and display
botusername  = mastoscore        # Username of the bot account (without @)

# Directory settings for data storage
journaldir   = data              # Base directory for storing journal files

# These values are composed from the settings above - don't change them directly
journalfile  = ${mastoscore:hashtag}
start_time   = ${mastoscore:event_year}-${mastoscore:event_month}-${mastoscore:event_day}T${mastoscore:event_time_start}
end_time     = ${mastoscore:event_year}-${mastoscore:event_month}-${mastoscore:event_day}T${mastoscore:event_time_end}

# Whether to include @ symbols when mentioning users in the analysis posts
tag_users    = False             # If True, we prepend the '@' to aliases. Like '@person@example.social`. This will cause `person@example.social` to receive a notification that they were mentioned. Some people don't like that, so you can omit them if you want.

[fetch]
# Settings for the fetch phase

# Maximum number of toots to fetch from each server
max          = 2400              # Higher values get more toots but take longer

# Can override these values from the mastoscore section if needed
hashtag      = myhashtag         # Usually the same as mastoscore:hashtag
api_base_url = https://example.social
cred_file    = .env/mastoscore.env

# Set to True to test without contacting remote servers
dry_run      = False             # True for testing, False for actual fetching

[analyse]
# Settings for the analysis phase

# Hours to add before/after the event times when filtering toots
hours_margin = 1                 # Include toots 1 hour before/after event times

# Can override top_n and debug from mastoscore section if needed

[graph]
# Settings for the graph generation phase

# Labels for the start and end markers on the graph
start_label  = ${mastoscore:episode_title} Start
end_label    = ${mastoscore:episode_title} End

# Title for the graph - can be multi-line by indenting subsequent lines
graph_title  = ${mastoscore:event_title}
  ${mastoscore:event_year}-${mastoscore:event_month}-${mastoscore:event_day}
  ${mastoscore:episode_title}

[wordcloud]
# Settings for the wordcloud generation phase

# Path to a font file for the wordcloud text
font         = /usr/share/fonts/opentype/LateralIncisedNF.otf

# Dimensions of the wordcloud image in pixels
size_x       = 1280
size_y       = 960

# How to handle the hashtag in the wordcloud:
# - "remove": completely exclude the hashtag
# - "reduce": include fewer instances of the hashtag
# - "as-is": include all instances of the hashtag
hashtag_fix  = remove

# Optional: comma-separated list of words to exclude from the wordcloud
stop_words   = movie, film, watch, watching


[postgraphs]
# Set to True to see what would be posted without actually posting
dry_run            = False       # True for testing, False for actual posting
visibility         = public      # Visibility of this post
message            = Here are the visualizations for our hashtag analysis!
# Optional to overried the cred_file and api_base_url if you want to post
# to another server for testing
cred_file          = .env/susbot-always.env
api_base_url       = https://always.grumpy.world

[post]
# Settings for posting the analysis to Mastodon

# Visibility settings for the posts
root_visibility    = public      # Visibility of the first post in the thread
thread_visibility  = unlisted    # Visibility of subsequent posts in the thread

# Whether to include @ symbols when mentioning users
tag_users          = False       # Usually matches mastoscore:tag_users

# Set to True to see what would be posted without actually posting
dry_run            = False       # True for testing, False for actual posting

# Can override api_base_url, cred_file, debug, botusername from mastoscore section

Directory Structure

With this configuration, Mastoscore will organize files as follows:

Journal Files

data/
├── 2025/
│   ├── 04/
│   │   ├── 15/
│   │   │   ├── myhashtag-example.social.json
│   │   │   ├── myhashtag-other.social.json
│   │   │   └── ...

Graph Outputs

When you run the graph and wordcloud modules, they will write their PNG files to graphs and wordcloud directories respectively.

graphs/
├── myhashtag-20250415.png              # Time-based graph
wordcloud/
├── wordcloud-myhashtag-20250415-remove.png
└── ...

For more details on configuration options, see the config module documentation.