View source for King Warz Charts

[[File:King_warz_logo_black.png|thumb|right|150px|King Warz logo as of January 2025, used as his Twitter (X) profile picture.]]

The '''King Warz Charts''' are the official personal charts based on the listening habits of King Warz. Data is collected from King Warz's Spotify account via Stats.fm, and the charts are automatically generated by a program called ''Levboard''.

The charts have been tracking since February 4, 2020. However, Warz did not officially generate the charts until August 2024, meaning that for weeks prior to [[Week 52]] (July 12 – August 22, 2024), he was unaware of the exact positions of songs or albums during those periods; those earlier charts were generated retroactively.

== Background ==
In the summer of 2024, King Warz was searching for a way to create personal charts, believing it would inspire him to stream more music. One of his friends, with whom he co-administers the Ariana Grande Wiki, informed him about CrownNote. However, when he tried to create an account on the platform, he was unable to do so because account creation was paused at the time. His friend gave him an extra CrownNote that he owned, but he didn't end up creating a chart on the platform due to the slowness of the website and the fact that he had to create the chart manually.

Warz knew that a member of the Ariana Grande Wiki administration team, where he serves as a bureaucrat, had their own chart platform called Levboard. He reached out to "Lev," who helped him set up the standard version of Levboard, which generated charts entirely through a terminal.

After using the standard version for a few weeks, Warz realized he enjoyed the charts and wanted to use the expanded version of Levboard, which included a spreadsheet with additional statistics. The process of setting up the spreadsheet, which houses all the data for King Warz Charts, began on November 6, 2024. It took several days to set up, as Warz had to manually import all the songs into the songs spreadsheet and create the albums. Additionally, he encountered numerous issues running the program (which generates the charts through the terminal and sends the data to a spreadsheet). Despite these challenges, the program successfully ran for the first time on November 11, 2024.

== How the charts work ==
This section documents how ''Levboard'' determines chart eligibility, positions, and long-term statistics. The explanations below are based on the Levboard codebase (models, config, storage, and the main weekly generator).

=== Data source (Stats.fm) ===
Levboard pulls listening data from the Stats.fm API (Stats.fm is also known as stats.fm). It uses two types of requests:
* ''Weekly top tracks'' for a specific time window (used to build each week’s chart).
* ''Track stream counts'' for lifetime plays and for specific time windows.

Internally, Levboard identifies each track using its Stats.fm ''track id'' (a numeric string). Songs are stored locally and can optionally be merged into a single listing when multiple IDs represent the “same” track (for example: a remaster).

=== Chart week length and date windows ===
Levboard builds the chart by iterating forward in time from a configured ''start date'':
* Each loop begins with a '''start date''' and an '''end date''' where end date is start date + 7 days.
* The program requests weekly positions using the time window from start → end.
* For display and export, the “week label” is shown as '''start date to (end date − 1 day)'''. (This is why the header often looks like a 7-day range.)

==== Extended weeks (low-activity weeks) ====
If there are not enough eligible songs in a 7-day window, Levboard does '''not''' publish a short chart. Instead it extends the window by another 7 days and tries again. This is why “merged weeks” can happen during low-streaming periods.

=== Eligibility and chart size (Top 60 logic) ===
Levboard requires at least 60 songs to qualify for a chart week.
* First, it fetches the user’s top tracks for the window and filters out songs with '''1 play or fewer'''.
* If fewer than 60 songs remain, the window is considered invalid and will be extended (see above).
* If 60+ songs remain, the program sets the '''cutoff''' to the playcount of the #60 song.
* Only songs with plays '''greater than or equal to the cutoff''' are kept.

Because the cutoff is tied to #60’s plays, weeks can sometimes chart '''more than 60 songs''' if multiple tracks are tied at the cutoff playcount.

=== How positions are calculated (including ties) ===
After the eligible song list is finalized, Levboard assigns a rank to each song using playcount comparison:
* A song’s place is calculated as: '''(number of songs with more plays) + 1'''.
* Songs with the same playcount receive the same chart position (ties).
* The final week list is displayed and exported sorted by plays (highest to lowest).

=== Song entries and what gets stored ===
Each weekly appearance is stored as an '''Entry''', which includes:
* start date
* end date
* plays (must be greater than 1)
* place (chart position)

If a song already has an entry for the same end date, Levboard only replaces it if the new entry has a higher playcount. Entries are kept sorted from earliest to latest.

=== Movement codes (MV column) ===
Levboard calculates movement by comparing the current week to the previous week:
* '''NEW''' = first-ever appearance (song has only 1 total charting week)
* '''RE''' = re-entry (song charted before, but was absent last week)
* '''=''': no change in position
* '''▲N''' = moved up by N positions
* '''▼N''' = moved down by N positions

=== Common chart columns (TW, LW, OC, PLS, PK) ===
When outputting the weekly table, Levboard uses the following logic:
* '''TW''' ([[This Week]]): the song’s current calculated place.
* '''LW''' ([[Last Week]]): the song’s place on the prior week if it charted; otherwise “-”.
* '''OC''' (On Chart): the total number of weeks the song has charted (the length of its entries list).
* '''PLS''' ([[Plays]]): the song’s playcount during the current chart window (not lifetime plays).
* '''PK''' (Peak): the best-ever place (lowest numeric rank) the song has achieved.
** If a song spent multiple weeks at its peak, Levboard displays peak weeks as a superscript when peak ≤ 10 (example: 1², 3³, etc.).
** If the peak is greater than 10, the superscript formatting is not applied (the program displays the number normally).

=== Points and units (all-time stats) ===
Levboard calculates two major all-time values for each song:

==== Points ====
Points are based on chart placements across all weeks:
* For every entry, Levboard adds '''(61 − place)''' points.
* Example: #1 earns 60 points, #10 earns 51 points, #60 earns 1 point.

This means charting higher (lower number) earns more points, and points accumulate over time.

==== Units ====
Units represent an all-time “total performance” score:
* '''Units = (2 × lifetime plays) + points'''

Lifetime plays are retrieved from Stats.fm and can include additional alternate IDs if a track has been merged (see “Track merging” below).

=== Certifications ===
Levboard assigns certifications based on a song’s total units (not based on chart peaks). Certifications are stored and formatted using a certification model.

==== Certification thresholds (songs) ====
Song certifications are determined by total units:
* '''Un-Certified''' ( - ): under 100 units
* '''[[Gold]]''' ( ● ): 100–199 units
* '''[[Platinum]]''' ( ▲ ): 200–1999 units
* '''Diamond''' ( ⬥ ): 2000+ units

==== Multipliers (multi-Platinum / Diamond+) ====
Levboard supports multipliers for high-unit songs:
* Multi-Platinum is calculated in 200-unit steps (example: 400 units becomes 2× Platinum).
* Diamond uses the same 200-unit stepping once the total exceeds 2000 units, and is displayed with a multiplier (example: 11× ⬥).

Certifications can be shown as symbols (● ▲ ⬥) or in expanded “full words” form depending on output formatting.

=== Track naming and “lazy name” mode ===
Levboard stores a song with:
* an internal id (Stats.fm track id)
* a stored name (can be custom)
* the official name and artist list from Stats.fm

If '''lazy name''' is enabled (the default in settings), new songs are automatically stored using the official title from Stats.fm. If it is disabled, Levboard will prompt for a custom database name when it encounters a new track.

=== Track merging (alternate IDs) ===
Levboard supports merging multiple Stats.fm track IDs into one chart listing.
* If a stored song dictionary includes a merge target, that ID will be treated as an alternate version.
* Alternate IDs are counted when calculating plays for a time period and for lifetime plays.
* This prevents “splitting” the performance of the same song across multiple IDs.

=== The Top 20 Album Charts ===
Alongside the Top 60 Song Charts, Levboard generates a weekly '''Top 20 Album Charts'''. Albums are ranked each week by the '''units''' they earned during that window:
* An album's weekly units come from the performance of its tracks: 2 × the plays of its songs that week, plus the chart points those songs earned.
* An album's all-time units are the sum of its member tracks' units, so deep albums with many charting songs accumulate units even in weeks when the album itself is off the chart.
* The weekly album tables show [[MV]], [[TW]], [[LW]], [[OC|On Chart]], [[PK]], [[UTS]] (units), [[PLS]] and [[PTS]], mirroring the song table.

==== Album certifications ====
Albums certify on a larger unit scale than songs:
* '''Un-Certified''': under 500 units
* '''[[Gold]]''' ( ● ): 500–999 units
* '''[[Platinum]]''' ( ▲ ): 1,000 units, with a new multiplier at every additional 1,000 (2× through 9×)
* '''[[Diamond]]''' ( ⬥ ): from 10× Platinum (10,000 units), displayed with its multiplier (example: 29× ⬥)

== Classifications ==
Every song and album page carries an automatic classification in its infobox, derived from its peak position and weeks at #1. Each classification page hosts a bot-maintained list of its current members:

* '''Songs''': [[Major Hit Song]] (5+ weeks at #1), [[No.1 Hit Song]], [[Top 5 Hit Song]], [[Top 10 Hit Song]], [[Top 20 Hit Song]] and [[Charted Song]].
* '''Albums''': [[Major Hit Album]] (5+ weeks at #1), [[Number One Hit Album]], [[Hit Album]] (peak #2–#5) and [[Charted Album]] (peak #6–#20).
* '''Artists''': [[Elite Chart Artist]] (10+ total #1s), [[Major Chart Artist]] (3–9), [[General Chart Artist]] (1–2), [[Established Chart Artist]] (no #1s yet, with 3+ top-10 hits or 25+ chart weeks) and [[Minor Chart Artist]].

== Chart ecosystem ==
The charts feed an interconnected set of wiki pages, all refreshed weekly by automation:
* '''Week pages''' ([[Week 1]] onward): the full Top 60 song and Top 20 album tables for every chart week, along with a written summary (number ones, debuts, movers, milestones), the week's new certifications, an interactive Top 10 Race graph, dropout lists and a cover collage of the week's top 4 songs.
* '''Song and album pages''': chart summaries with all-time records context, notable achievements, certification history tables with crossing dates, listening milestones, interactive position and units graphs, and complete chart histories.
* '''Year-end and month-end charts''': every song and album page lists its year-end and month-end finishes, and the biggest years and months in chart history are tracked as records.
* '''[[Albums of the Week]]''': a weekly editorial feature selected from nominations, displayed on the Main Page and each week page.
* '''The Main Page''': the current #1 song and album with records-aware write-ups, and an On This Day box drawing on chart history, certifications, first listens, debuts and listening records.

== Chart Adjustments ==
There have been two major chart adjustments since the November 2024. Usually when chart adjustments happen, they have a major impact on the layout of weeks and the charting of songs and albums on the charts.

==== October 17, 2025 - Levboard Update ====
On October 17, 2025, King Warz implemented the latest Levboard update, which merged a lot of low play weeks. Before the update there were 199 weeks of the chart, but after the update was implemented it was adjusted to about 123 weeks.

==== November 5, 2025 - Chart Start Date Adjustment ====
On November 5, 2025, during [[Week 112]], Warz updated the chart code to shift the tracking date from Friday to Thursday. This adjustment was made to prevent songs released on Fridays from gaining an unfair advantage at the end of the tracking week, ensuring they debut on the following week’s chart instead.

== Notes ==
* Levboard settings (like username, minimum plays filtering, and the start date used to begin scanning weeks) are stored in a local settings file and can be updated without rewriting the code.
* Some weeks may cover longer than 7 days if the program cannot find enough eligible songs to create a valid chart week.