# WaveDrom: rendering digital timing diagrams from WaveJSON > WaveDrom turns a compact JSON description of a digital waveform into SVG, in the browser or from the command line. It suits hardware and IC engineers who want timing diagrams kept as text next to their RTL, and it assumes you are willing to learn its shorthand. **wavedrom/wavedrom** — :ocean: Digital timing diagram rendering engine - Repository: https://github.com/wavedrom/wavedrom - Website: https://wavedrom.com - Stars: 3,502 · Forks: 422 - Language: JavaScript - License: MIT - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/wavedrom-wavedrom ## What WaveDrom solves for hardware and IC engineers Timing diagrams are usually drawn in a general-purpose vector editor, which means the source of truth is a binary or proprietary file that no reviewer can diff. WaveDrom takes the opposite position. The README describes it as a "Free and Open Source online digital timing diagram (waveform) rendering engine that uses javascript, HTML5 and SVG to convert a WaveJSON input text description into SVG vector graphics." The input is text, the output is SVG, and the intermediate step is a rendering engine rather than a person moving rectangles. The intended audience is stated in the README: WaveJSON exists "to provide a compact exchange format for digital timing diagrams utilized by digital HW / IC engineers." That is a narrow audience on purpose. A clock, a bus with named values, and a wire that toggles are the primitives, and the shorthand is built around them rather than around general illustration. If your diagram is a block diagram, a state machine, or a floorplan, this is not the tool. The practical gain is that a waveform can sit in the same repository as the RTL it describes. A pull request that changes a bus encoding can also change the diagram, and the diff is readable. The cost is that you now maintain a second representation of the same behaviour, and nothing in the repository checks that the two agree. ## WaveJSON in, SVG out: the rendering path The engine is small and its data flow is short. A WaveJSON document is JSON, and the README calls WaveJSON "an application of the JSON format." The engine reads that object and emits SVG. Rendering is delegated to what the README calls the "WaveDromSkin skin mechanism to render a complete picture," and the repository keeps a skins/ directory at the top level, which matches that description. The package.json exports map exposes "./skins/*" alongside the main entry point, so skins are reachable as a public surface rather than an internal detail. The library entry is ./lib, and the browser builds are produced by esbuild from lib/wave-drom.js into wavedrom.js, wavedrom.min.js, and the unpkg variants. That means the same engine serves the npm import, the script tag, and the CLI. The CLI is declared in package.json as bin/cli.js under the name wavedrom, so an installed package puts a wavedrom executable on the path. One detail worth noting for anyone embedding it: the browser build is an IIFE bundle, and the documented entry point is a global called WaveDrom with a ProcessAll method. There is no documented ES module build for the browser; the exports map covers the Node side. If you want to render inside a bundler-based front end, the README does not describe that path. ## Installing the WaveDrom CLI and rendering a first diagram The README gives two ways to run the command line tool. The quickest needs no install: npx fetches the package and runs it, with the required input flag and a redirect to a file. ```bash npx wavedrom --input source.json5 > output.svg ``` After that command, output.svg contains the rendered diagram. The README uses a .json5 extension for the input, and the test directory in the repository holds files such as test/signal-step4.json5, so JSON5 is the format the project itself uses for examples even though the engine is described as reading JSON. For repeated use, install it globally. The README shows the global install and then the same command with an indent option: ```bash npm install -g wavedrom wavedrom --input source.json5 --indent 2 > output.svg ``` The CLI documents exactly three options: -i / --input is required, -t / --indent sets the text indent in the output SVG, and -h / --help prints the help message. There is no output flag, which is why both examples redirect stdout. If you need a raster image, the README points at a separate tool rather than adding a format option: ```bash npx wavedrom -i source.json5 | npx @resvg/resvg-js-cli - output.png ``` That pipeline is the project's documented answer for PNG. It is a second dependency, and the README does not describe any other export format. For a web page, the README gives a three-step pattern. Load the script from a CDN, call the processor on body load, and wrap the source in a script tag with a custom type: ```html ``` The README states that the script finds all script elements of type WaveDrom and inserts a timing diagram at that point. The wave strings are positional: each character is one time slot, and the data array supplies the labels for the bus slots. Getting a diagram to look right is mostly a matter of counting characters. ## The hosted SVG endpoint and what it commits you to The README documents a server at svg.wavedrom.com that renders a diagram from a URL, which is useful for Markdown files that cannot run JavaScript. The documented form takes a repository path: ```md ![signal step4](https://svg.wavedrom.com/github/wavedrom/wavedrom/trunk/test/signal-step4.json5) ``` There is also an inline form that puts the WaveJSON directly in the URL, shown in the README as an img tag containing a signal array. Both work because the server resolves the source and returns an image, so a README on any platform that renders Markdown images gets a waveform. The trade-off is that the diagram now depends on a third-party host at read time. The README does not describe a self-hosted deployment of that service, so a private repository path would be sent to it, and an outage or a change at that domain turns every embedded diagram into a broken image. For public documentation this is a reasonable convenience. For anything internal, the CLI plus committed SVG files avoids the dependency entirely, at the cost of regenerating the files when the source changes. The README does not describe a hook or build step that does that automatically. ## Where WaveDrom is the wrong choice The wave shorthand is compact, and compactness has a price. Every character in a wave string occupies one time slot, so changing the length of a signal means editing the strings of every other signal to keep them aligned. The README's own example shows a seven-character clock next to a seven-character bus; there is no documented way to declare a shared time base once and let signals refer to it. For a waveform with a few dozen slots this is fine. For a long protocol trace it becomes the main maintenance cost of the diagram. Skins are the other boundary. The README says the engine uses the WaveDromSkin mechanism to render a complete picture, and package.json exports ./skins/*, but the README does not document how to author a skin or what the skin interface looks like. The skin documentation lives in unpacked/README.md according to the link in the README, which is a directory in the repository rather than part of the main documentation. Anyone expecting to restyle the output substantially should read that file before assuming it is a supported extension point. Finally, the release history is thin. The most recent release listed in the repository is v2.1.2 from 2019-05-28, while package.json declares version 3.7.0. The README also points at standalone editor builds named wavedrom-editor-v2.4.2 for Windows, Linux and OS X, hosted on the wavedrom.github.io releases page rather than this repository. The last push to this repository was on 2026-08-31, so the code is moving, but the tagged releases and the packaged desktop editor do not track it. If your process requires a tagged release with a changelog, the project does not currently provide one. ## WaveDrom compared with drawing tools and diagram-as-code alternatives The closest alternative in spirit is a general diagram-as-code tool such as Mermaid or PlantUML. Those accept a text description and emit a diagram, and they are often already wired into the same Markdown pipeline you use for documentation. The difference is the vocabulary. Mermaid and PlantUML model sequences, flows and relationships; neither has a native concept of a clock with a period, a bus with per-slot values, or a signal that is undefined for part of the trace. WaveDrom's wave strings encode exactly those things, which is why it needs far less text for a timing diagram and far more text for anything else. Against a vector editor, the difference is where the source of truth lives. An editor gives you arbitrary placement and annotation, and it will draw a diagram WaveDrom cannot express. It also gives you a file that no reviewer can read in a diff. WaveDrom gives up the freedom and keeps the diff. The README also points to integrations rather than competitors: an impress.js example, an ObservableHQ collection, a Blogger post, and a MediaWiki extension at Martoni/mediawiki_wavedrom. Those are the realistic adoption paths if your diagrams live in a wiki or a notebook rather than a repository. ## Licence, maintenance and the cost of upgrading The repository is MIT licensed, and package.json repeats "license": "MIT". That is permissive: you can embed the engine in a commercial product, and the main obligation is keeping the copyright notice and the licence text with the distribution. The bundled browser builds ship with a banner generated by bin/header.js, so the notice travels with wavedrom.min.js. This is a description of the licence text, not legal advice; check the LICENSE file in the repository for the exact terms. Upgrade cost is low on the Node side because the public surface is small. The package exports a main entry, a package.json path, and the skins wildcard. The CLI has three flags. The README documents a single script tag pinned to major version 3, so a CDN-based page will pick up minor releases automatically, which is convenient and also means a behavioural change in rendering can reach production without a commit in your repository. Pinning the exact version in the script URL is the way to avoid that, and the README does not discuss version pinning. The maintenance signal to watch is not the release tags. The last push was on 2026-08-31, which is recent, while the newest listed release is from 2019. The repository has a CI workflow, an eslint config, and a test script that runs eslint plus c8 coverage over mocha tests, so changes are checked. But if you need a version number to justify an upgrade, you will be reading commits rather than release notes. ## Conclusion Adopt WaveDrom if your timing diagrams need to live in version control as text and you are comfortable with the WaveJSON shorthand; skip it if you need free-form vector drawing or a tool that is packaged as a desktop application for your platform. Before committing, render one of your own diagrams through the CLI and check the SVG in the browser you actually ship documentation to, since the engine targets modern browsers and the README does not describe a fallback for older ones. ## FAQ ### How do I install WaveDrom? For the command line, the README gives npm install -g wavedrom, or you can skip the install with npx wavedrom --input source.json5. For a web page, the README loads wavedrom.min.js from jsDelivr or unpkg with a script tag. ### How do I use WaveDrom? You write a WaveJSON description, which is a JSON object containing a signal array where each entry has a name and a wave string, then render it with the CLI or in the browser. In HTML the README wraps the source in a script tag of type WaveDrom and calls WaveDrom.ProcessAll() on body load. ### Is WaveDrom open source? Yes. The repository is MIT licensed, and package.json declares "license": "MIT". The README links to the LICENSE file in the repository. ### What are the alternatives to WaveDrom? General diagram-as-code tools such as Mermaid and PlantUML also render diagrams from text, but they do not have a native concept of clocks, buses or undefined signal segments the way WaveJSON does. A vector editor gives you more drawing freedom but produces files that cannot be reviewed in a diff. ### How do I draw a timing diagram online? The README points to WaveDromEditor at wavedrom.com/editor.html, described as an online real-time editor of digital timing diagrams based on the WaveDrom engine and the WaveJSON format. For pages that cannot run JavaScript, the README also documents the svg.wavedrom.com endpoint, which renders a diagram from a URL. ## Sources - [License: MIT](https://github.com/wavedrom/wavedrom/blob/trunk/LICENSE) - [Project website](https://wavedrom.com) - [README](https://github.com/wavedrom/wavedrom/blob/trunk/README.md) - [Releases](https://github.com/wavedrom/wavedrom/releases) - [wavedrom/wavedrom on GitHub](https://github.com/wavedrom/wavedrom) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wavedrom-wavedrom