# chordbox

> A simple SVG-based guitar chord renderer.

Latest version **1.0.14** (published 2022-08-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install chordbox
pnpm add chordbox
yarn add chordbox
bun add chordbox
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.14 |
| Published | 2022-08-30 |
| First published | 2022-08-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 316.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | GastroGeek |
| Maintainers | gastrogeek |

## Links

- npm: https://www.npmjs.com/package/chordbox
- npm.io page: https://npm.io/package/chordbox

## Dependencies (2)

- [svgdom](https://npm.io/package/svgdom.md) ^0.1.10
- [@svgdotjs/svg.js](https://npm.io/package/@svgdotjs/svg.js.md) ^3.1.2

## Recent versions

- 1.0.14 (latest) — 2022-08-30
- 1.0.13 — 2022-08-30
- 1.0.12 — 2022-08-29
- 1.0.11 — 2022-08-29
- 1.0.10 — 2022-08-28
- 1.0.9 — 2022-08-28
- 1.0.8 — 2022-08-28
- 1.0.7 — 2022-08-28
- 1.0.6 — 2022-08-28
- 1.0.5 — 2022-08-25
- 1.0.4 — 2022-08-25
- 1.0.3 — 2022-08-25
- 1.0.2 — 2022-08-25
- 1.0.1 — 2022-08-25
- 1.0.0 — 2022-08-25

## README

# ChordBox

A simple SVG-based guitar chord renderer.

## Usage

I originally made ChordBox for a [Raycast](https://www.raycast.com/) extension I made - [Guitar Chords](https://www.raycast.com/GastroGeek/google-chords). It allows me to generate SVG images without the need for an actual browser/DOM (it's using [svgdom](https://github.com/svgdotjs/svgdom) and [SVG.js](https://svgjs.dev/) 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.

```js
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.

```js
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](https://github.com/svgdotjs/svgdom#fonts).

# 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 <img> 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.

---
_Source: https://npm.io/package/chordbox · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._