npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

voxdown

v1.4.0

Published

VoxDown: a plain-text format for stories read aloud. Parser, readings, writer, formatter and exports, with no dependencies.

Readme

voxdown

The VoxDown parser and writer: read a story into a model, get what a listener hears and what a reader sees, write changes back without disturbing the author’s text, format, export, and import screenplays. No dependencies; ESM with types; browsers, Node 20+, Deno and Bun.

VoxDown is a plain-text format for stories read aloud: Markdown with marks for who speaks, how, sounds, page turns and notes. The format is in SPEC.md; every mark fits on the cheat sheet.

npm install voxdown
import { parse, spokenScript, bookText } from "voxdown";

const story = parse("@Gerald (yawning) “I’ve only just got to sleep,” said the dragon.");
spokenScript(story); // "Gerald (yawning): I’ve only just got to sleep,\nNarrator: said the dragon."
bookText(story); // "“I’ve only just got to sleep,” said the dragon."

Reading

parse(source: string): Story never fails: problems become story.warnings. The model keeps every node’s place in the source (range, UTF-16 offsets), so tools can highlight it or change it in place.

| Field | What | | --- | --- | | meta | title, subtitle, author, language, version (the file’s voxdown: key) and narrator. | | cast | { handle, name, about?, data } in front matter order. handle is the word after @. | | blocks | Paragraphs (lines, each with items), headings and scene breaks, in order, each with its visibility and groups. | | groups | Every ::: group, with its character, direction and visibility. | | warnings | { code, severity, message, range, line, column }. The codes are stable (SPEC.md §12.3). | | frontMatter | The raw YAML and its parsed data, or null. |

A line’s items are, in source order: speech (speaker, direction, ownDirection, text, quoted, continued, and the ranges of its words and quotes), vocal (a sound a character makes), sound, instruction (name, value), note, image, and the marks and directions that produced them. Every type is exported, and documented in src/model.ts.

The two readings

  • spokenScript(story): everything heard, in order, one line each, written as in the spec’s examples (§12.1).
  • bookText(story): the printed story as Markdown, marks removed (§12.2).

The spoken script as data

  • lines(story, { speechOnly? }): one ScriptLine per thing heard: kind (speech, vocal, sound, page, pause, instruction, note, image), speaker, direction, text, name (an instruction’s), heading (a heading’s level), scene (from 1), sceneTitle, page (the page it is on), and its line and column. The shape multi-voice text-to-speech tools take.
  • linesToCsv(rows, columns?): kind,speaker,direction,text,scene,page, RFC 4180; or the columns given, such as line added.
  • textByCharacter(story): a Map from each character to what they say, one line per speech, for a performer’s sides.

Writing back

The text is the source of truth. Writing never reflows or restyles it (§13).

  • write(story) gives back the source, byte for byte, with the changes you made on the model: a speech’s speaker or ownDirection, a sound’s or vocal sound’s description, a note’s text, an instruction’s value, a heading’s level, meta.title/subtitle/author/language, a cast member’s name or handle. Adding or removing items is done with the edits below. A change it can't make as asked, such as a note holding %%, throws a RangeError.
  • changesFrom(story): the same, as text changes.

Each edit returns the smallest list of TextChange ({ from, to, insert }) that makes it. Apply them with applyChanges(source, changes), then parse again. An edit does exactly what it says: every other word is heard as before, by the same character and in the same way, and the printed book doesn't change. Where that can't be done, it returns no changes.

| Edit | What it does (SPEC.md §13) | | --- | --- | | setSpeaker(story, speech, name) | Gives a stretch, or the whole quote it is part of (over lines and paragraphs), to another character; narration that holds quotes gives its first quote. Replaces the name in its mark, or adds one; a later quote that carried the speech on gets a mark too, so it keeps its speaker. | | setDirection(story, speech, direction \| null) | Adds, replaces or removes a stretch’s own direction, where §13 says to write it: to the quote's end, or to a direction of its own inside it. | | setSpeakerWithin(story, from, to, name) | Gives a few words of one line to a character, and nothing else: @Name before them, and after them what gives the rest back as it was (@/ for the narrator, §5.9). Part of a quote can't be given away (a quote has one voice). | | setDirectionWithin(story, from, to, direction \| null) | Says a few words of one line so, and nothing else: @(…) before them, and @() or the direction the rest had after them. Inside a quote too. | | renameCharacter(story, from, to) | Renames a short name in the cast, the narrator: key and every mark. | | setFullName(story, handle, name) | Sets a character’s full name in the cast, adding the cast or the character if needed. | | setMeta(story, key, value \| null) | Sets or removes a front matter detail, such as title; a key whose value is a map or a list, such as cast, is left alone. | | insertSound(story, offset, description) | A sound after the word at offset, never inside or straight after a mark. | | insertLine(story, offset, text) | A page turn, pause or note on a line of its own, never in the front matter or a note. |

isName(word) says whether a word can follow @.

Formatting

format(source, options?) tidies a file and never changes who says what (§13, rule 8): it trims and collapses spaces, makes runs of blank lines one, puts a blank line after the front matter and around headings and scene breaks, ends with one line break, and writes names as the cast spells them. Options: names and spacing (both on unless false), and quotes: "curly" with an optional language (the front matter’s by default) to turn straight quotes into the language’s curly ones: en, de, fr, it, es, pt, ca, ru, uk, da, pl, ja, zh, and Swiss de-CH and fr-CH, English marks for any other. A formatted file comes back unchanged. curlQuotes(source, { language? }) makes just the quotes curly, as format does, and changes nothing else, for an editor that curls what is pasted.

Sizes

Everything reads in time that grows with the story. An edit reads the whole story again to check itself: about 0.2 s on a 100,000-word book, and write() makes one such edit for each speaker or direction changed on the model, so 50 changes there take about 10 s. For many changes at once on a long book, make them on the text with the edits instead, or in parts.

Importing

fromFountain(screenplay, { readSceneHeadings? }) turns a Fountain screenplay into a VoxDown story: cues become marks, parentheticals directions, action narration, scene headings {hidden} headings (read aloud with readSceneHeadings), page breaks {page}, notes %% %%, and the cast is gathered from the cues.

Also

  • tokens(story): syntax ranges for highlighting (mark, name, direction, sound, vocal, instruction, note, group, heading, break, frontmatter, escape, quote).
  • chapterLevel(story): the heading level the story divides into chapters at, the highest used at least twice (SPEC.md §4.4), or undefined: one chapter. # chapters give 1; ## chapters under a single # Title give 2. chapterLevelOf(levels) does the same from a list of heading levels.
  • characterColors(story, overrides?): a color for each character, in cast order, from PALETTE unless the cast gives one (color: "#2563eb").
  • characterReference(text, at): the character a reference such as & or ’ at at stands for, and its length, or null (SPEC.md §11). The parser decodes them already; this is for tools that render the text themselves.
  • SPEC_VERSION: the spec version this package follows, "1.2".

License

MIT. The spec is under CC BY 4.0.