Speed Run Portal Format

What Speed Run Portal Format Actually Is

The Speed Run Portal Format is a file structure used to organize speedrun categories, personal bests, and routing data for games that track performance through community platforms like TASVideos or custom leaderboards. It isn't standardized across every game, but the core idea is consistent: a directory tree paired with a configuration file that maps routes, segment times, and verification criteria. Most people encounter it when trying to submit a run to a portal that requires structured proof—segment times, tool-assisted verification notes, or even frame-perfect routing data. The format itself is usually just a JSON or YAML file wrapped around a folder of recordings and a text-based route map.

Speed Run Portal Format

Inside the format, you'll typically find three components. A metadata block that identifies the game, category, runner, and date. A segment table that breaks the run into meaningful chunks—usually at least one per level, boss, or major mechanic. And a verification section that holds links to raw footage, tool logs, or hash values for any emulated input files. Here's what I've learned after spending years dealing with this stuff. The trick isn't the file layout itself. It's how you structure the verification data so it survives platform migration. I once spent six hours rebuilding a submission for Celeste because someone moved their YouTube links from direct URLs to embed codes, and the portal's parser treated them as broken references. The workaround was straightforward: always store both the original URL and a local backup in the same directory. That way, when a link dies, you can swap it without re-exporting the entire run. Another thing people get wrong is the segment naming convention. There's no universal standard, but the most portable approach uses snake_case with a consistent delimiter between area and objective. "01_start_to_first_boss," not "Level 1 - First Fight!" The former parses cleanly across different leaderboard scripts. The latter breaks half of them.

How to Build One From Scratch

Start by picking a base format. JSON is more common, easier to debug with any text editor, and widely supported. YAML reads cleaner for humans but occasionally trips up older submission tools that expect strict indentation. For a new project, JSON is the safer bet. Create a folder with this structure: RunName_Date/ run.json footage/ route.txt notes.md

The run.json file needs at minimum these fields: game name, category, runner handle, date ISO string, total time in seconds, and a segments array. Each segment object requires a name, a start time, and an end time. Everything else—tool assist flags, skip counts, glitch notes—is optional but useful for verification. I've found that the total time field is where most mistakes happen. Platforms calculate it differently depending on whether you include loading screens, menu transitions, or death resets. Always define your total time source in the metadata and stick to it. Mixing manual timestamps with auto-captured segment logs creates drift that ruins verification.

Common Pitfalls and Edge Cases

Platform incompatibility is the biggest headache. Speedrun.com uses one schema. AnyList uses another. Community-run portals often build their own parsers on top of incomplete documentation. Before submitting anywhere, check what the platform expects for segment naming, time precision, and footage format. Raw MP4 works everywhere. WebM sometimes causes issues with older tools that expect H.264 specifically. Here's a counter-intuitive one: more segments isn't always better. I've seen runners break levels into thirty tiny chunks just to look thorough, and it actually hurts verification. Fewer, well-defined segments that map to clear in-game events are easier to audit. Three segments per level is usually the sweet spot. Anything more creates noise without adding clarity. Another thing nobody talks about is date formatting. ISO 8601 looks like this: 2024-03-15T14:32:00Z. Some platforms accept YYYY-MM-DD without the time portion. A few insist on UTC timestamps with the Z suffix. I learned this the hard way after getting three rejections from different portals for the same run, each citing a different date format error. The fix was keeping both a raw date string and a UTC timestamp in the metadata, then letting the submission script pick whichever the target platform required.

When the Format Breaks Completely

There are scenarios where the Speed Run Portal Format just doesn't work. Tool-assisted speedruns that span multiple save states across different emulators often need custom extensions to the standard schema. If your run involves hardware modifications, cheat devices, or real-world physical input that can't be logged digitally, the verification section becomes unreliable. No amount of formatting fixes that. You're better off documenting everything manually in a notes file and submitting alongside the standard format rather than forcing it into a schema that wasn't built for edge cases like that. Emulator-specific timing quirks also break the format. Different emulator versions handle frame advancement differently. A run verified on one build might show a two-frame discrepancy on another. The solution is to lock your emulator version in the metadata and include the exact binary hash. Without that, verification becomes impossible when the platform runs a different build.

Where to Download Templates and Tools

There's no single official download for the Speed Run Portal Format because it's a community-maintained standard, not a licensed product. However, several projects maintain compatible templates. The speedrun.com portal tools repository on GitHub has reference schemas. Community discord servers often share format converters that translate between different platform expectations. If you're building from scratch, I'd recommend starting with the JSON schema from the Speedrun.com documentation and adjusting it for your specific game and category. For automated verification, tools like TASClient or open-source segment parsers can read your run.json and cross-reference it against raw footage timestamps. They're not perfect, but they catch common errors like overlapping segments or negative duration gaps before you submit.

Final Thoughts on Practical Usage

The Speed Run Portal Format is useful but limited. It works well for standard categories with clean routing and consistent tools. It struggles with experimental categories, hardware-assisted runs, or games with non-linear progression that defies simple segment mapping. When it works, it cuts verification time from hours down to minutes. When it fails, you're left manually explaining why your run doesn't fit a schema that was never designed for your use case. The most practical approach is to learn the format thoroughly, then know when to push against its limits. Document everything. Keep backups of raw footage and unmodified submission files. And don't assume a format designed for one platform will work cleanly on another without adjustment.