Skip to content

docs: refresh the README for GitHub, npm and NuGet - #2962

Merged
Danielku15 merged 4 commits into
developfrom
docs/readme-refresh
Oct 17, 2026
Merged

Danielku15 merged 4 commits into
developfrom
docs/readme-refresh

Conversation

@Danielku15

@Danielku15 Danielku15 commented Oct 17, 2026 •

Copy link
Copy Markdown
Member

Note

AI-authored disclosure (alphatab-ai-authored-v1)

Portions of this content were authored by an AI agent. The agent has read
AGENTS.md and the human submitter accepts responsibility for
compliance with the rules in that document.

Issues

Fixes #

Proposed changes

The README is the landing page on GitHub, and the same file ships verbatim in the npm package and both NuGet packages. The current one is outdated: it lists Guitar Pro 3–7, leaves out Capella, has no code sample and still shows netcoreapp3.1 platform rows.

This PR restructures it as a modern landing page:

  • First screen: tagline, a two-sentence pitch, version and download badges for npm, NuGet and Maven, and a link row (website, docs, Playground, features, release notes, discussions).
  • Hero image: bars 77–80 of the Iron Waltz demo song, rendered by alphaTab in a player window with a loop range, playback cursor and the backing track's waveform. It links to the Playground. The image is a single self-contained SVG (66 KiB, 19 KiB gzipped) that follows the viewer's light or dark theme through prefers-color-scheme. All text and music symbols are outlined, so it needs no fonts wherever it is embedded.
  • Hero generator: npm run readme-hero -- --song <file> regenerates img/hero.svg. It renders the passage with alphaTab in Node through a custom render engine. That engine outlines text and Bravura symbols with the fonts bundled in packages/alphatab/font and measures text with the same fonts, so layout and outlines match. Timing, section labels and the waveform come from the song and its backing track (decoded with ffmpeg). opentype.js (MIT) is added as a root devDependency for the outlines. The song itself is not part of the repository.
  • Content: highlights, supported read and write formats, a quick start with npm install and a runnable CDN snippet, a platforms table, the packages in this repository, documentation links (including llms.txt), community links including Show and tell, licensing of the bundled fonts and SoundFont, and thanks.
  • Rendering everywhere: plain Markdown with absolute URLs only. nuget.org strips HTML and only loads images from allowlisted hosts such as raw.githubusercontent.com, and npm ignores <picture>, so the file renders the same on all three.
  • npm listing: new description and keywords for @coderline/alphatab.

The hero URL points at develop, so the image only appears in the rendered README once this is merged.

Checklist

  • I consent that this change becomes part of alphaTab under its current or any future open source license
  • This PR is linked to an accepted issue (see above)
  • Changes are implemented
  • New tests were added
  • I have read AGENTS.md if an AI helped draft any part of this PR

AI authorship disclosure

  • No AI agent authored any part of this PR (description, code, tests, or commit messages)
  • An AI agent contributed to this PR. The AI-authored disclosure block
    (alphatab-ai-authored-v1) is present at the top of this body, and I have
    personally reviewed every change and can explain each one

Further details

  • This is a breaking change
  • This change will require update of the documentation/website

Restructure the README as a landing page: tagline and pitch, version and
download badges, a link row, a hero image rendered by alphaTab from the
Iron Waltz demo song, highlights, supported formats, a runnable CDN
quick start, a platforms table, the packages in this repository,
documentation links, community, licensing and thanks.

All links and images are absolute and the markup is plain Markdown, so
the same file renders on GitHub, npmjs.com and nuget.org, which ship it
verbatim.

Also update the npm description and keywords of @coderline/alphatab.
Add `npm run readme-hero`, which renders a passage of a song with
alphaTab in Node and composes it into a player window, written as a
single self-contained SVG with light and dark colors selected via
prefers-color-scheme.

A custom render engine outlines all text and music symbols with the
fonts bundled in packages/alphatab/font and measures text with the same
fonts, so layout and outlines match and the image needs no fonts where
it is embedded. Glyph outlines are shared through <defs>. Timing,
section labels and the waveform come from the song and its backing
track (decoded with ffmpeg).

img/hero.svg is generated from the Iron Waltz demo song.
The SVG follows the viewer's light or dark theme and is smaller than the
PNG it replaces.
@Danielku15
Danielku15 merged commit 925f21d into develop Oct 17, 2026
5 checks passed
@Danielku15
Danielku15 deleted the docs/readme-refresh branch October 17, 2026 13:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant