NAME

Music::FretboardDiagram - Draw fretboard chord diagrams

VERSION

version 0.1205

SYNOPSIS

  use Music::FretboardDiagram;

  my $dia = Music::FretboardDiagram->new(
    chord => 'x02220',
    font  => '/path/to/TTF/font.ttf',
  );
  $dia->draw;

  $dia->chord('xx0232');
  $dia->position(5);
  $dia->outfile('mystery-chord');
  $dia->showname('Xb dim'); # "X flat diminished"
  $dia->draw;

  $dia = Music::FretboardDiagram->new(
    chord    => '4442',
    position => 3,
    strings  => 4,
    frets    => 6,
    size     => 25,
    outfile  => 'ukulele-chord',
    type     => 'bmp',
    font     => '/path/to/TTF/font.ttf',
    tuning   => [qw/A E C G/],
    horiz    => 1,
    image    => 1,
    verbose  => 1,
    string_color => 'black',
    fret_color   => 'darkgray',
    dot_color    => 'blue',
  );
  my $image = $dia->draw;

DESCRIPTION

A Music::FretboardDiagram object draws fretboard chord diagrams including neck position and chord name annotations for guitar, ukulele, banjo, etc.

Here are examples of a vertical guitar diagram and a horizontal ukulele diagram:

ATTRIBUTES

chord

  $dia->chord('xx0232');
  $chord = $dia->chord;

A chord given as a string, where non-zero digits represent frets, x (or X) indicates a muted string and 0 (or o or O) indicates an open string. The default order of the strings is 654321 from lowest to highest.

Examples:

  C: x32010
  D: xx0232
  E: 022100
  F: xx3211
  G: 320003
  A: x02220
  B: x24442

  Cm: xx5543
  Dm: xx0231
  Em: 022000
  Fm: xx3111
  Gm: xx5333
  Am: x02210
  Bm: x24432

  C7: x32310
  D7: xx0212
  E7: 020100
  F7: xx1211
  G7: 320001
  A7: x02020
  B7: x21202

position

  $dia->position(3);
  $position = $dia->position;

The neck position of a chord to be diagrammed. This number is rendered to the left of the first fret in vertical mode. When drawing horizontally, the position is rendered above the first fret.

Default: 1

strings

  $strings = $dia->strings;

The number of strings.

Default: 6

frets

  $frets = $dia->frets;

The number of frets.

Default: 5

size

  $size = $dia->size;

The relative size of the diagram.

Default: 30

outfile

  $dia->outfile('chord-042');
  $outfile = $dia->outfile;

The image file name minus the extension.

Default: chord-diagram

type

  $type = $dia->type;

The image file extension.

Default: png

font

  $font = $dia->font;

The TTF font to use when rendering the diagram.

Default: /opt/X11/share/fonts/TTF/VeraMono.ttf

tuning

  $tuning = $dia->tuning;

An arrayref of the string tuning. The order of the notes is from highest string (1st) to lowest (6th). For accidental notes, use flat (b), not sharp (#).

Default: [ E B G D A E ]

horiz

  $horiz = $dia->horiz;

Draw the diagram horizontally. That is, with the first string at the top and the 6th string at the bottom, and frets numbered from left to right.

Default: 0

image

  $image = $dia->image;

Return the image from the draw method instead of writing to a file.

Default: 0

string_color

  $string_color = $dia->string_color;

The diagram string color.

Default: blue

fret_color

  $fret_color = $dia->fret_color;

The diagram fret color.

Default: darkgray

dot_color

  $dot_color = $dia->dot_color;

The diagram finger position dot color.

Default: black

fretboard

  $fretboard = $dia->fretboard;

A hashref of the string notes. This is a computed attribute based on the given tuning.

showname

  $dia->showname('Xb dim');
  $dia->showname(1); # Reset to computed names
  $dia->showname(0); # Do not show chord names
  $showname = $dia->showname;

Show a chord name or not.

Sometimes the computed chord name is not that accurate or desired. In those cases either set the showname to a string of your choosing before drawing, or to 0 for no chord name.

Default: 1

verbose

  $verbose = $dia->verbose;

Monitor the progress of the diagram construction.

Default: 0

METHODS

new

  $dia = Music::FretboardDiagram->new(%arguments);

Create a new Music::FretboardDiagram object.

draw

  $dia->draw;

Render the requested chord diagram as an image file of the given type.

THANK YOU

Paweł Świderski for the horizontal drawing and webservice suggestions

SEE ALSO

The eg/ files in this distribution

Imager

List::SomeUtils

Moo

Music::Chord::Namer

Similar modules:

GD::Tab::Guitar and GD::Tab::Ukulele

Music::Image::Chord

For a real chord analyzer:

https://www.oolimo.com/guitarchords/analyze

AUTHOR

Gene Boggs <gene@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by Gene Boggs.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Music::FretboardDiagram

perl -MCPAN -e shell
install Music::FretboardDiagram