 |
Summary | Calculates performer ratings from category-based tags. |
 |
Repository | https://github.com/ordureconnoisseur/plugins/tree/main/plugins/advancedPerformerRating |
 |
Source URL | https://ordureconnoisseur.github.io/plugins/main/index.yml |
 |
Install | How to install a plugin? |
Advanced Performer Rating
A Stash plugin that adds a multi-category rating system for performers. Rate each performer across several criteria (Face, Technique, etc.), grouped into weighted buckets, and Stashâs overall performer rating is calculated and updated automatically.
Everything is configured through a dedicated settings panel â no plugin tasks, no manual tag creation. Rename criteria, add custom ones, tweak weights, and add/remove groups all in one place.
Credits
Inspired by the Advanced Rating System plugin on the Stash community forums, which introduced the concept of using tags for multi-category ratings.
Requirements
- Stash v0.27+
- Python 3.x
- stashapp-tools (bundled in
vendor/; auto-installed via pip when available)
Installation
- In Stash go to Settings â Plugins â Add Source and enter:
https://ordureconnoisseur.github.io/plugins/main/index.yml - Find Advanced Performer Rating in the plugin browser and click Install.
- Open Settings â Plugins â Advanced Performer Rating and click Save in the panel â this seeds the default config and creates the rating tags for you.
Usage
Click the â + button on any performerâs page to open the rating modal. The button shows a count badge when the performer has criteria still unrated â yellow if the performer is partially rated (e.g. youâve added a new criterion since they were last rated), grey when fully unrated. No badge means every criterion is rated.
The modal renders each criterion grouped by its configured group, with a bold header per group. Rate each category using the 1â5 star selectors. Hover over the â icon next to a category name to see its description. Unrated criteria are highlighted with a small âunratedâ pill so you can see at a glance which ones still need a score.
As you click stars, the corresponding category tag (Face â
: 4, etc.) is applied to the performer and Stashâs overall rating is recalculated automatically via the Performer.Update.Post hook.
Click Score breakdown at the bottom of the modal to expand a panel that shows exactly how the rating is being calculated: per-group weighted average, then the final weighted mean across groups, and the rating100 result after precision snapping. The collapsed/expanded state is remembered across sessions.
The rating is visible directly on the performer page alongside the category tags that were assigned.
Configuration
Open Settings â Plugins â Advanced Performer Rating to access the settings panel. The panel replaces Stashâs native plugin-settings UI (which canât reliably render dropdowns or persist non-boolean values) with a fully interactive React component.
General
- Rating Star Precision â auto-matched from Stashâs own rating-system setting (Settings â Interface â Editing â Rating System).
FULL = 20,HALF = 10,QUARTER = 5,TENTH = 1,DECIMAL = 1. The panel polls every few seconds so the displayed value tracks Stashâs setting without reopening the panel. - Allow Destructive Actions â gates the orange âRemove orphaned tagsâ and red âDelete all rating tagsâ buttons. Off by default.
Groups
Criteria are bucketed into groups, and the final rating is a weighted mean of each groupâs average.
- Name â display label. Renaming a group doesnât touch any tags (tags are per-criterion, not per-group).
- Weight â how much this group counts in the final score relative to others.
- Reorder / Delete â at least one group must exist. Deleting a group reassigns its criteria to another group.
Defaults seed Physical and Performance with equal weight.
Criteria
Each criterion is a rateable category that produces a tag prefix <Name> â
with children <Name> â
: 0 ⊠<Name> â
: 5.
| Field | Meaning |
|---|---|
| Toggle | Enabled / disabled. Disabled criteria are ignored by the rating math and hidden from the modal. |
| Name | Display name. Used as the tag prefix (a â
is automatically appended in the tag name). |
| Group | Which group this criterion contributes to. Populated from the configured group list. |
| Weight | How much this criterion counts within its group. |
| â | Edit the description shown as a tooltip in the rating modal. Clear it to hide the tooltip; Reset to default restores the bundled wording (only available for the eight default criteria). |
| â â | Reorder. |
| Ă | Remove the criterion from this configuration. Tags stay on disk â use Remove orphaned tags to clean up. |
+ Add criterion appends a new custom criterion with a generated slug id.
Actions
- Save â persists configuration AND automatically creates any missing tags for new criteria AND renames tags for any criterion you renamed. One click handles every workflow.
- Recalculate all performers â walks every performer in Stash and updates their
rating100based on the current configuration. Useful after changing weights or group settings. - Reset to defaults â restores the bundled 2 groups + 8 criteria.
- Remove orphaned tags â scans Stash for criterion tags whose criterion was renamed or removed and deletes them with their
0â5children. Requires Allow Destructive Actions. - Delete all rating tags â destroys the parent tag plus every configured criterionâs tags. Requires Allow Destructive Actions.
How It Works
Each criterion produces a tag prefix like Face â
, with six child tags Face â
: 0 through Face â
: 5 organised under a single Advanced Performer Rating parent tag.
When a performer is updated, the Performer.Update.Post hook fires the Python script. It:
- Reads the pluginâs configuration from Stashâs plugin-config store.
- Builds the criteria/groups model.
- Scans the performerâs tags for any matching
<prefix>: <0â5>. - Computes a weighted average per group, then a weighted mean across groups.
- Snaps the result to Stashâs configured rating precision and updates
rating100.
Rating Calculation
For each group g with at least one matching tag:
group_avg(g) = ÎŁ(score Ă criterion_weight) / ÎŁ(criterion_weight)
Final rating:
final_avg = ÎŁ(group_avg(g) Ă group_weight(g)) / ÎŁ(group_weight(g)) over groups with hits
rating100 = round(final_avg Ă 20, snapped to precision)
- One group â flat weighted average across all enabled criteria.
- Two groups with equal weight â original plugin behaviour: Physical and Performance carry equal weight regardless of how many criteria are in each.
- Three or more groups â weighted mean of their averages.
- Groups with no tag matches are skipped; if no groups have any hits, the rating is not updated.
Where settings are saved
Plugin configuration (groups, criteria, weights, descriptions, the destructive-actions toggle) is persisted via Stashâs configurePlugin GraphQL mutation, which writes to Stashâs main config.yml under plugins.advancedPerformerRating.* (~/.stash/config.yml on Linux/Mac, %USERPROFILE%\.stash\config.yml on Windows).
| Scenario | Plugin config | Rating tags | Performer ratings |
|---|---|---|---|
| Uninstall + reinstall plugin |  (itâs in config.yml, not the plugin folder) |
(DB) |
(DB) |
| Database backup / restore | (not in DB) |
Restored |
Restored |
| Wipe DB only | |
 â re-run Save in the panel |
|
Restore older config.yml |
 reverts to that backup |
untouched |
untouched |
| Stash factory reset | |
|
|
For a backup of just the criteria/group setup, the file to keep is config.yml. Tags live in the DB, so a DB backup plus a config.yml copy together cover both halves.
License
AGPL v3.
