ChordBox

A simple SVG-based guitar chord renderer.

Usage

I originally made ChordBox for a Raycast extension I made - Guitar Chords. It allows me to generate SVG images without the need for an actual browser/DOM (it's using svgdom and SVG.js under-the-hood)

You can either create an instance and configure it with options at the same time, or set/re-set various options sometime later via setter methods.

import { ChordBox } from 'chordbox'

// at the same time
const svgBase64URI = new ChordBox({
  title: 'CMaj',
  dots: [
    { string: 5, fret: 3 },
    { string: 4, fret: 2 },
    { string: 2, fret: 1 },
  ]
})
  .render()
  .toSVGBase64URI()

// sometime later
const chordBox = new ChordBox({
  title: 'CMaj',
})

const svgBase64URI = chordBox
  .setDots([
    { string: 5, fret: 3 },
    { string: 4, fret: 2 },
    { string: 2, fret: 1 },
  ])
  .render()
  .toSVGBase64URI()

// if you want just the svg (non-base64'd)
const chordBoxSVG = chordBox
  .setDots([
    { string: 5, fret: 3 },
    { string: 4, fret: 2 },
    { string: 2, fret: 1 },
  ])
  .render()
  .toSVG()

Note

render() must be called in order to generate anything.

Fonts

You will need to ensure the font, OpenSans-Regular.ttf, is included in your project root (at ./assets/OpenSans-Regular.ttf'). There is a copy included in the dist/assets/fonts folder for your convenience.

If, however, you wish to change the location of the font, simply call setFontsDir on the ChordBox instance before rendering.

import { resolve } from 'path'
import { ChordBox } from 'chordbox'

const svgBase64URI = new ChordBox({
  title: 'CMaj'
})
  .setFontsDir(resolve(__dirname, 'somewhere/else')) // anywhere you like
  .setDots([
    { string: 5, fret: 3 },
    { string: 4, fret: 2 },
    { string: 2, fret: 1 },
  ])
  .render()
  .toSVGBase64URI()

You can also, technically, change the font itself - to do so consult the documentation for svgdom.

Methods

The main methods are:

Method	Purpose
render()	Requirement on every use and performs the actuall rendering, under-the-hood
toSVG()	Outputs the rendered content as an SVG string
toSVGBase64URI()	Outputs the rendered content as a base64 encoded svg-image string (for use with tags, for e.g)

Setter Methods

As mentioned earlier, there are some setter methods you can use depending on your requirements.

Setter	Parameter Type	Purpose
setFonts()	string	Sets the default font location
setFrets()	number	Sets the number of visible frets on the ChordBox
setBaseFret()	number	Sets the first fret shown on the ChordBox
setDots()	ChordBoxDot[]	Sets the 'dots' to show on the ChordBox
setBarres()	number[]	Sets which frets should be barred. This is automatically set to stretch from lowest fretted string to highest on the designated fret.

Documentation

At some point I will include typedoc genereated docs for developer-convenience.