Set Up a Score¶

This assumes you've already done the installation steps.

Once you get going, the easiest way to keep going is to use the Backstage web interface to copy a prior INI file and just change a few variables. This document will talk about setting up your first INI file and what you should choose.

Manual Configuration¶

Create a mastoscore.ini file and edit it in a text editor. I recommend starting with the example.ini file and then customising it. All the possible options are listed in the config module.

Mandatory Options¶

In the [mastoscore] section, you have to define these options.

• cred_file: The credential file you set in Create a credential file.
• hashtag: What hashtag are you looking at? Omit the # character. If you're searching for #stuff, just write hashtag = stuff.
• api_base_url What server did is your credential file account on? Include the https:// in the URL. If your userid is mastoscore@example.social then your api_base_url is https://example.social.
• top_n: How many top toots do you want to report?
• timezone: This is important. All your times in all your toots and graphs will be localized to this time.
• journaldir: directory where we write a bunch of JSON files
• journalfile: name for each json file. See the documentation in the config module
• event_title: The overall event title. Might be the same as the hashtag, but doesn't have to be
• episode_title: The title of a specific episode. In the case of Monsterdon, each week is a different film. So the event_title is "Monsterdon" and the episode_title is "The Thing from Outer Space"
• event_year, event_month, and event_day: The numeric values
• event_start: The starting time, including the date (for now), and timezone: E.g., 2026-02-22T21:00:00-05:00
• event_duration: The duration of the event. We will look for posts starting at the event_start time until this duration. E.g., 1:23:32
• timezone: The time zone for reporting times. Typically something like America/New_York

[fetch] Options¶

In the [fetch] section you may want to add:

• max = n: This is the maximum number of toots that we will download from any given server. It defaults to 2000.
• overwrite = True: If you want to fetch posts for an event you already fetched, this will overwrite any files that match a server name. In the interest of picking up where we left off, the fetch module will skip a server if there already exists a journal file of the right name, regardless of whether there is anything usable in that file.
• parallel_workers = n: Fetch will connect to many servers in parallel. It's because the servers are slow and they also rate limit. Fetching 180,000 posts for a typical #monsterdon often takes me 60-80 minutes if I do them one server at a time. This doesn't change the experience of any one server. Each server is only contacted by one thread, which obeys whatever rate limits the server imposes.

[post] Options¶

In the [post] section you may want to add:

• tag_users = False: This will stop us from generating toots that notify the mentioned users. Good for testing.

[wordcloud] Options¶

In the [wordcloud] section you may want to add fonts. This should be full path specifications to one or more font files that will be used in the word cloud. If you want them all to have the same font every time, just put one font name in there. If you want some randomness, put more fonts in.

Run the analysis¶

When you think you've got your INI file right, go to run an analysis or fire up the backstage to actually do it!