Nothing measured this '
f'week helps this pitch — the track reads level across {across}, '
f'so there is no chart evidence to quote. What sells this record '
f'is what only you know: the story, the plan, who it is for. '
f'Editors hear the tempo and the mood themselves.
')
# How many charting records the Tags tab leads with. Six is what fits on a
# phone screen without scrolling past the suggestions the tab is for, and it
# is enough for a pattern to be visible: one record carrying a label is an
# anecdote, six carrying the same one is the neighbourhood.
TAG_NEIGHBOURS = 6
# `genre_source` in reader English.
GENRE_SOURCE = {"itunes": "iTunes", "deezer": "Deezer"}
def neighbours(res: dict, limit: int = TAG_NEIGHBOURS) -> list[dict]:
"""The charting records this track sits closest to, across the markets
the report shows, deduped and strongest first.
One record can lead several markets — Kusslove leads both Kenya and
Tanzania on the real YO YO reading — and listing it twice makes one
record look like two pieces of evidence. It is kept where it first
appears, which is the strongest of those markets, because the shown
markets arrive in rank order.
A record at or above the same-recording mark is the track meeting its own
chart entry, not a neighbour, so it is left out: "your own record carries
these tags" is not evidence about anything.
"""
regions = res.get("regions") or {}
rows: list[dict] = []
seen: set[tuple] = set()
for iso in res.get("shown_markets") or []:
r = regions.get(iso)
if not r:
continue
for m in r.get("top") or []:
key = (m.get("artist"), m.get("title"))
if key in seen:
continue
sim = float(m.get("similarity") or 0)
if sim >= SAME_RECORDING:
continue
seen.add(key)
rows.append({**m, "iso": iso,
"market": r.get("name") or iso})
rows.sort(key=lambda m: -float(m.get("similarity") or 0))
return rows[:limit]
def _neighbour_tags(res: dict, flat_field: bool) -> str:
""""The records this track sits closest to, and the tags they carry."
Kalam's standing ask, unblocked now the corpus is labelled: the tag
section used to suggest words and then, separately, list which genres
happened to appear near the track. This is the linkage — each nearby
record with the tags it actually carries, so a suggestion can be checked
against the records it came from.
An analysis saved before the labels were carried through
`livematch.rank_regions` has rows with no `genres` key at all, and "no
label" would be a claim this page cannot make about them. Those rows get
no block; a re-run brings it back.
"""
rows = neighbours(res)
if not rows or not any("genres" in m for m in rows):
return ""
out = ['']
c = res["corpus"]
out.append(f'
marathonmvp · chart week '
f'{ESC(str(res["week"]))}
')
out.append(f'
{ESC(track_label)}
')
# The scale is dropped rather than printed as zeroes when the stored
# result does not carry it — an older build's result, or a corpus
# exported before a key existed. A number a page cannot stand behind is
# worse than a shorter sentence.
scale = ''
if c.get("sounds") and c.get("regions"):
scale = (f' · compared against {int(c["sounds"]):,} sounds charting '
f'in {int(c["regions"])} markets this week')
out.append(f'
{res["duration_s"]:.0f} seconds long'
f'{scale}.
')
# The track itself, playable at the top — every market card below quotes
# a trending sound with its own player, and comparing means hearing both.
if track_audio_url:
out.append(f'
')
elif not cutting:
# A report with no track player used to draw nothing at all, so the
# reader was left comparing against a record they could not hear and
# no reason for it (23 Aug audit). While the clips are still being
# cut this stays quiet — the player is on its way with them.
try:
import store as storemod
cap = f"{storemod.SOURCE_AUDIO_CAP // (1024 * 1024)} MB"
except Exception:
cap = "25 MB"
out.append(
f'
NO TRACK PLAYER
'
f'
The whole track is not kept with this '
f'analysis , so there is nothing to play here. The clip '
f'shortlist below is unaffected. A file over {cap} is never '
f'kept, which is why a WAV master reads this way — analyse an '
f'mp3 or m4a export of it to have the record playable here.'
f'
')
# -- markets ----------------------------------------------------------
shown = res["shown_markets"]
# A flat field is a refusal to rank, and it has to reach the cards: the
# opening says no market stands out, so a card underneath it must not
# wear a confident verdict, a verdict colour or a filled scale.
flat_field = worldmap.field(res)["flat"]
# -- the opening: what this says, what to do, and where in the world ---
# Kalam, twice: "open the page with high level analysis and summary plus a
# world map of relevant regions highlighted ... then when you scroll down
# it all slots in for the reader." Everything below this point is the
# detail that block is the summary of, so it goes above "Where it fits"
# and nowhere else. There is one renderer and three callers — a fresh
# upload, a reopened saved analysis and a re-run all reach this line.
#
# PAGE_RUBRIC §1 and §2, measured on the four stored reports: the opening
# read well and handed the reader nothing to do. The first actionable
# line — "Pitch it into Kenya first" — was 1,300 characters, a world map,
# 19 chips and a tab row further down, inside the first market card. The
# number-one action is hoisted into the block that opens the report; the
# card keeps its own copy, because a filtered view shows that card alone.
#
# `_market_action` builds it, so there is one author of the sentence and
# no second wording to drift. It hands back nothing at all for a
# self-match, and a flat field is excluded here: the flat summary already
# ends "treat the market order as a list of places that have been
# checked, not a ranking to act on", and a hoisted action would contradict
# the paragraph above it. The honesty guards — a short chart, a market
# standing alone — ride along, because the guard is part of the sentence.
lead_action = ''
if shown and not flat_field:
lead = regions[shown[0]]
if lead["best"] < SAME_RECORDING:
lead_action = _market_action(res, shown[0], 0,
livematch.band(lead["best"]))
out.append(worldmap.opening(res, lead_action=lead_action))
# -- the tab row -------------------------------------------------------
# The summary and the map stay above this line on every view: they are
# the thing the three sections are three views of, and tabbing away from
# the map would break the chips that jump into the first tab. "Where it
# fits" is checked, which is where every `#market-XX` anchor lands.
picks = [] if snippet_note else res["snippets"]
if not snippet_note and not picks and res.get("snippet_sets"):
old = res["snippet_sets"]
seen, picks = set(), []
for p in list(old.get("trend") or []) + list(old.get("hook") or []):
if p["start_s"] not in seen:
seen.add(p["start_s"])
picks.append(p)
tf = res["tags"]["fields"]
tabs = [('rt-fits', 'Where it fits', len(shown), 'market'),
('rt-clips', '30 seconds', len(picks), 'clip'),
('rt-tags', 'Tags', len(_tag_rows(tf, res)), 'field')]
row = []
for tid, label, n, unit in tabs:
row.append(f'
')
row.append(f'
{label}'
f'{_plural(n, unit)} ')
out.append('
' + "".join(row) + '
')
out.append('
')
out.append(f'Where it fits '
f'{_plural(len(shown), "closest market")}'
f' ')
out.append(
f'
{ESC(r["name"])} '
f'{ESC(iso)} '
f'{chip(b)}
')
# A cosine this high is the record meeting itself. It happened the
# first time the archive was seeded: Joshua Baraka's "What Do I Know"
# read 100.0% in Uganda because it is charting in Uganda, and without
# this line that reads as a spectacular fit rather than as the track
# recognising its own reflection. It is a good sign that the
# measurement works, and it is not a market opportunity — so the
# percentage and the scale are not drawn at all here. A number the
# page then spends a paragraph disowning should not be printed.
if is_self:
near_s = ''
if top:
near = f'{top[0]["artist"] or "—"} — {top[0]["title"] or "—"}'
near_s = f' The chart entry it meets is
{ESC(near)} .'
out.append(
'
'
'This is the same recording. The track is already '
f'charting in {ESC(worldmap.in_market(iso, r["name"]))}, so '
f'it is being compared '
f'against itself — anything over '
f'{SAME_RECORDING:.1%} is the same record, so there is no '
f'percentage to read here.{near_s} Read the markets below it '
'for where else it sits.
')
else:
out.append('
'
f'
'
f'{livematch.whole_pct(r["best"])}'
f'%
')
if top:
near = f'{top[0]["artist"] or "—"} — {top[0]["title"] or "—"}'
out.append(f'
{ESC(near)}
')
out.append(f'
{CAPTION[b]}
'
'
')
out.append(_scale(pct, b) + '
')
out.append(f'
{_pool_line(r)}. Closest three:
')
for m in top:
url = previews.get(m.get("deezer_id"))
player = (f'
'
if url else '')
rank = f'#{m["rank"]}' if m.get("rank") else ''
mb = livematch.band(m["similarity"])
out.append(
f'
'
f'{livematch.pct(m["similarity"])} '
f'{ESC(m["artist"] or "—")} — '
f'{ESC(m["title"] or "—")} '
f'{ESC(rank)} {player}
')
# What this market is for, in one sentence, with the chart position of
# the record the number was measured against and whichever honesty
# guard the numbers earn — a short chart, or a market standing alone.
out.append(_market_action(res, iso, i, b))
out.append('
')
# -- snippets: ONE list ------------------------------------------------
# It used to be two, side by side — closest-to-the-trend and
# strongest-hook — with a window appearing on both marked ON BOTH LISTS.
# Kalam, reading it: "the organisation of two approaches with duplicates
# and place, on both lists, highlighted in green looks confusing...
# duplication doesn't mean anything to someone scrolling through." The
# duplicate was a fact about how the list was built, and the reader had to
# understand the construction before the green chip meant anything.
#
# Now: one list of distinct windows, strongest hook first, every card
# carrying both readings side by side. That is what the two lists were
# for. The best trend fit is appended with a caption when the hook order
# missed it, so nothing is lost.
# `picks` is built above the tab row, because the tab carries its count.
# A report saved before this change still carries `snippet_sets`, and that
# is flattened into the new list there rather than being drawn the old way.
out.append('
')
out.append('Which 30 seconds to deliver '
+ (f'{_plural(len(picks), "section")} '
if picks else '')
+ 'Nobody has listened for you. '
'Play the clip before it goes anywhere.
')
if snippet_note:
out.append(snippet_note)
elif not picks:
out.append(
f'This file is {res["duration_s"]:.0f} '
f'seconds long — shorter than the 30-second clip a distributor '
f'asks for, so there is no window to choose. The market ranking '
f'above used the whole file.
')
def snippet_card(p: dict, i: int) -> None:
b = p["band"]
# ONE time, and it is the corrected one. The card used to print the
# window at the top and a second clock time inside the sentence
# telling you to move it — two times, one of them wrong to use.
start_s, end_s = p["start_s"], p["end_s"]
db, corr = p.get("nearest_downbeat"), ""
if db is not None:
delta = db - start_s
if abs(delta) < 0.06:
corr = "Already starts on the first beat of a bar."
else:
start_s, end_s = db, db + (end_s - p["start_s"])
corr = (f'Moved {abs(delta):.2f}s '
f'{"later" if delta > 0 else "earlier"} to start on '
f'the first beat of a bar.')
t0, t1 = _fmt_time_frac(start_s), _fmt_time_frac(end_s)
# The chip says what this clip is FOR. It used to say PLACE, which is
# a verdict about a market and means nothing about a 30-second window.
role = "deliver" if i == 1 else "alt"
word = "DELIVER" if i == 1 else "SECOND CHOICE"
out.append(f''
f'{i} '
f'{t0} – {t1} '
f'{word} '
f''
f'{livematch.pct(p["affinity"])}
')
out.append(f'
'
f'{CAPTION[b]} against what is charting'
+ (f' in {ESC(worldmap.in_market(p.get("market"), p["market_name"]))}'
if p.get("market_name")
else '')
+ (f'. {corr}' if corr else '.') + '
')
# Four rows, three words. The floats that were here — 0.62, 0.41 —
# were the model's own scale printed raw, and nobody can act on the
# difference between 0.62 and 0.58. The bar carries the order.
rows = []
if p.get("hook_label") and p.get("hook") is not None:
rows.append(("Hook signal", p["hook_label"],
float(p["hook"])))
parts = p.get("hook_parts") or {}
for key, label_ in (("repeats", "Comes back"),
("voice", "Voice up front"),
("lift", "Energy")):
if key in parts:
v = float(parts[key])
rows.append((label_, _word_band(v), v))
if rows:
cells = []
for label_, word_, v in rows:
cells.append(
f'
{ESC(label_)} '
f'
{ESC(word_)} '
f'
')
out.append('
' + "".join(cells) + '
')
out.append('
The mark on '
'each bar is this track\'s own average. Every word '
'here is read against the record itself, never '
'against anyone else\'s.
')
# One sentence: what to do with this clip.
near = p.get("nearest")
near_s = (f' The closest charting record to this part is '
f'
{ESC(near["artist"] or "—")} — '
f'{ESC(near["title"] or "—")} .' if near else '')
if i == 1:
act = (f'
Send this one. It is the strongest 30 seconds of '
f'the record by the hook reading, and it sits at '
f'{livematch.pct(p["affinity"])} to what is charting'
+ (f' in {ESC(worldmap.in_market(p.get("market"), p["market_name"]))}'
if p.get("market_name")
else '') + f'.{near_s}')
elif p.get("pick_reason") == "trend":
act = (f'
Keep this as the alternate. It is here because it '
f'is the closest section to the trend, not the strongest '
f'hook.{near_s}')
else:
act = (f'
Keep this as the alternate. Same record, a '
f'different section — use it if the first one starts '
f'mid-word.{near_s}')
out.append(f'
{act}
')
ci = p.get("clip_i")
clip = clips[ci] if ci is not None and ci < len(clips) else None
if clip:
# The played clip may stop at the last bar line inside the window
# so that what the team hears finishes its phrase. The DELIVERED
# window is still the full 30 seconds printed at the top of the
# card, and the label under the player says which is which.
nat = p.get("natural_end_s")
if nat and nat < p["end_s"] - 0.2:
lab = "PLAYS TO THE BAR"
foot = ('This clip stops on the last bar line inside the '
'window so the phrase finishes. The 30 seconds you '
'deliver are the times above.')
else:
lab, foot = "THIS 30s", ""
out.append(f'
{lab} '
# metadata, not none: the duration should be on screen
# before anyone presses play
f'
'
' ')
if foot:
out.append(f'
'
f'{foot}
')
elif cutting:
# The report goes on screen before the clips are cut — that gap
# is 8 seconds on the Space and is why the numbers arrive first.
# Every card spent it saying the clips had expired, on a report
# computed two seconds earlier (23 Aug audit). The players arrive
# on their own when the cutting finishes.
out.append('
CUTTING '
'The audio for '
'this window is still being cut. It arrives here on '
'its own in a few seconds — the times above are '
'already final.
')
else:
# The message belongs here, where the player is missing, rather
# than in a footer under four cards: this is the card the reader
# is looking at when they wonder where the audio went. It says
# "analyse the file again" and not "re-run", because a re-run
# reads the saved track against this week's charts and cuts no
# audio at all — only the file can do that.
out.append('
NO CLIP '
'No clip for this '
'window. Analyse the file again to cut one. '
'
')
out.append('
How these were picked
'
f'{res["window_count"]} sections of the track were compared, '
f'moving in 5-second steps. They are ordered by the hook '
f'reading: how often the section comes back elsewhere in the '
f'record, how much sits in the centre of the stereo image where '
f'a lead vocal usually is, and how loud and busy it is against '
f'the track\'s own average. Each card also shows how close that '
f'section sits to the charting music above, so both readings are '
f'in front of you when you choose.'
f'
Sections are placed so a musical phrase ends where the '
f'clip ends, rather than stopping flat at 30 seconds. Where that '
f'lands before the mark, the player here stops on the bar and '
f'the card says so; the 30 seconds you hand a distributor are '
f'the times printed on the card.'
f'
The centre-of-image measurement cannot tell a voice '
f'from a lead instrument, and nothing here separates the vocal '
f'out — a section can score well and still start mid-word. '
f'Listen to each one before you send it.
How these were picked
'
f'{res["window_count"]} sections of the track were compared, '
f'moving in 5-second steps, ranked by how close each sounds to '
f'the charting music above. The hook reading could not be taken '
f'on this file. Listen to each one before you send it.
')
# -- tags: platform suggestions lead, evidence follows ---------------
out.append('
')
out.append('Tags for the platforms '
'suggested ')
rows = _tag_rows(f, res)
for label_, value, note in rows:
out.append(f'
{ESC(label_)}
'
f'
'
f'
{ESC(note)}
')
if rows:
# No Copy button. One would need JavaScript, which does not run in a
# Gradio HTML component, and a button that does nothing is worse than
# no button. The fields are selectable; the affordance is deferred.
# The line says what to do, not why the button is missing — a label
# manager has no use for the reason.
out.append('
Tap a field to '
'select it, then copy.
')
if flat_field and not any(label_ == "PITCH FORM · PROSE"
for label_, _v, _n in rows):
# After the copy line, because that line belongs to the fields above
# it and this note is about the field that is not there.
out.append(_no_pitch_note(res))
if f.get("main_genre") and f.get("show_african_list"):
afro = "".join(f'
{ESC(n)} '
for n in tagmod.APPLE_AFRICAN)
out.append(f'
Apple lists '
f'{len(tagmod.APPLE_AFRICAN)} African genres — the pick '
f'is a human call '
f'The reading narrows to a family. '
f'Naming which of these it is takes a person who knows '
f'the record.
'
f'{afro}
')
out.append('
TikTok
'
'
Genre goes in on the distribution form '
'(SoundOn or your distributor\'s TikTok delivery). Whether '
'that field is a fixed list or free text is not yet verified '
'— use the main genre above until it is.
')
out.append('
YouTube
'
'
No tag field worth filling: YouTube Music '
'takes genre through the distributor delivery and shows none '
'of it, and video keywords carry almost no weight in '
'discovery.
')
out.append('
How the family reads
')
out.append('')
for n, r in enumerate(genres):
place = ("1st", "2nd", "3rd", "4th")[n]
out.append(
f'{place} '
f'{ESC(r["tag"])} '
f'
')
out.append('
'
'Naming the family is reliable; naming the '
'sub-genre is not. The bars carry the order these '
'words came in and nothing else — on our own test '
'records this reading put "latin pop" next to '
'afrobeats, and missed gospel on a gospel track. '
'How it works has the detail.
')
other = [(g, (t["model"]["by_group"].get(g) or []))
for g in ("mood", "production")]
other = [(g, rs) for g, rs in other if rs]
if other:
out.append('
What else the sound reads as'
' ')
for group, rs in other:
out.append(f'{ESC(group)}
'
''
+ "".join(f'{ESC(r["tag"])}'
f' ' for r in rs)
+ '
')
out.append('')
out.append('
Tag suggestions '
'are switched off on this run: on the reference check the '
'reading did not tell the genre words apart well enough '
'to be worth pasting into a delivery form.
Taken from this week\'s '
'chart data.
')
# Country names, not ISO codes — "BO" tells a label reader nothing, and
# this was the one row in the app still speaking in codes (Kalam, 23 Aug).
regions_by_iso = res.get("regions") or {}
# A market the track already charts in prints no percentage here either.
# This row read "Australia 100% · Chile 100% · Spain 100%" while the card
# above it wore a SELF chip with no number and spent a paragraph on why
# there is no percentage to read (23 Aug audit) — the same rule, three
# inches apart, stated two different ways.
chips = "".join(
f'
'
f'{ESC((regions_by_iso.get(m["iso"]) or {}).get("name") or m["iso"])}'
f' '
f'{CHIP["self"] if float(m["best"]) >= SAME_RECORDING else livematch.pct(m["best"])}'
f' '
for m in tr["markets"][:8])
out.append(f'
markets it sits nearest
'
f'
{chips}
')
if tr["surfaces"]:
out.append('
charts the nearest records appear on
'
'
'
+ "".join(f'{ESC(s)} '
for s in tr["surfaces"]) + '
')
if tr["genres"]:
out.append('
genre, per Apple and Deezer
'
'
'
+ "".join(f'{ESC(g)} '
for g in tr["genres"]) + '
')
elif not c.get("genre_labelled"):
# The charts publish no genre of their own. Labels are looked up
# afterwards against Apple's taxonomy, with Deezer as the fallback,
# so a corpus exported before that pass has run carries none.
# The denominator is dropped rather than guessed at when the stored
# result does not carry it.
of = (f'the {int(c["sounds"]):,} charting sounds' if c.get("sounds")
else 'the charting sounds')
out.append(f'
No genre label this week: none of '
f'{of} carry one yet. Labels '
f'are looked up on Apple\'s genre list, and on Deezer '
f'where Apple carries none — the charts publish no genre '
f'of their own.
')
else:
of = (f'the {int(c["sounds"]):,} charting sounds this week'
if c.get("sounds") else 'the charting sounds this week')
out.append(f'
The records nearest yours carry no '
f'genre label. {int(c["genre_labelled"]):,} of {of} do; '
f'these are among the rest.
')
out.append('
')
# -- caveats -----------------------------------------------------------
# Outside the tabs on purpose. Everything here is a limit that changes
# what a number means, and a limit behind a tab is a limit somebody does
# not read.
tempo = res["beat"].get("tempo")
items = [
'
A high percentage means two recordings sound alike. Use it to '
'decide where a track fits. It carries no information about how a '
'record will perform.',
f'
The cut-offs are a first pass. Above '
f'{livematch.PLACE_THRESHOLD:.0%} reads as a direct fit, '
f'{livematch.DERIVE_THRESHOLD:.0%}–{livematch.PLACE_THRESHOLD:.0%} as '
f'remix or edit territory, and below that as no real connection. They '
f'were set on US and global chart data and have not been re-checked '
f'for African markets.',
'
This is one week of charts. A single week cannot tell a rising '
'sound from a fading one, so nothing here says which way anything is '
'moving.',
'
Charting records are compared using their official 30-second '
'preview. Your upload is the whole track. A whole track covers '
'more music, which lifts its score against everything. Compare '
'tracks by where they sit in this list, and read the percentages as '
'approximate.',
'
Only the sound is heard. Nothing here knows the lyrics, the '
'language, who is on the record, or whether a market would take it.',
]
items.append(
f'
Tempo read as {tempo:.0f} BPM. The beat reading was told to '
f'expect something near 110 BPM, which suits Afrobeats. If the tempo '
f'is wrong, only the start-time suggestions above are affected. The '
f'market ranking does not use tempo.' if tempo else
'
The beat could not be read on this file , so the clips were '
'ranked on how they sound alone, with nothing lined up to the bar.')
out.append('
Read this with the '
'numbers
'
+ "".join(f'{i} ')
# The chart sources by the names they publish under, and the pull as a
# date. It used to print "from soundcloud, youtube · pulled
# 2026-08-22T00:31:47+00:00" — two machine strings on a line whose whole
# job is telling a label reader how old the numbers are.
# Every field is read with `.get`: a stored result from an older build,
# or a corpus exported before a key existed, must print a shorter line
# rather than the word None or an error (23 Aug audit).
src = ", ".join(SOURCE_NAMES.get(s, s) for s in (c.get("sources") or []))
pulled = str(c.get("generated_at") or "").split("T")[0]
bits = [f'Charts used: {ESC(str(c.get("week") or "—"))}']
if c.get("sounds"):
bits.append(f'{int(c["sounds"]):,} sounds')
if c.get("regions"):
bits.append(f'{int(c["regions"])} markets')
if src:
bits.append(f'from {ESC(src)}')
if pulled:
bits.append(f'read on {ESC(pulled)}')
out.append(f'')
out.append('