/ 
Music-FretboardDiagram-0.1315
River stage zero No dependents
/ Music::FretboardDiagram

NAME

Music::FretboardDiagram - Draw fretboard chord diagrams

VERSION

version 0.1315

SYNOPSIS

use Music::FretboardDiagram;

my $dia = Music::FretboardDiagram->new(
  chord    => 'xx0232',
  frets    => 5,     # the default
  position => 1,     # the default
  outfile  => 'Dmajor',
  type     => 'png', # the default
);

$dia = Music::FretboardDiagram->new(
  chord    => [[1,'022000'], [2,'--1342'], [7,'-13321']], # Em chords
  frets    => 13,
  absolute => 1,
  size     => 50, # relative units, not pixels
  horiz    => 1,
  showname => 'Em',
  outfile  => 'fretboard',
  font     => '/path/to/TTF/font.ttf',
  verbose  => 1,
);

$dia->chord('x02220');          # set a new chord
$dia->position(7);              # set a new position
$dia->outfile('mystery-chord'); # set a new filename
$dia->showname('Xb dim');       # "X flat diminished"

$dia->draw;

$dia->spec_to_notes('x02220');  # [A E A Db E]

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');
$dia->chord([[1,'022000'], [2,'--1342'], [7,'-13321']]);
$chord = $dia->chord;

A required chord given as a string or array reference of specifications.

For a chord string, non-zero digits represent frets, x (or X) indicates a muted string, 0 (or o or O) indicates an open string, and a dash (-) means skip to the next string.

For an array-ref of chord specifications, the first element is the chord position, and the second is the chord string.

Chord string examples at position 1:

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

Cm: x3101x
Dm: xx0231
Em: 022000
Am: x02210

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

etc.

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

absolute

$absolute = $dia->absolute;

Use an absolute neck position for rendering a chord on a full length fretboard.

If not set, the chord will be rendered relative to the first fret.

Default: 0

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. The smallest visible diagram is size = 6. (This is not a measure of pixels.)

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.

Default: /usr/share/fonts/truetype/freefont/FreeMono.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;

Boolean to return the image from the draw method instead of writing it 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

showname

$dia->showname(0);        # Do not show chord names
$dia->showname(1);        # Show computed names
$dia->showname('Xb dim'); # Show a custom name
$showname = $dia->showname;

Show a chord name or not.

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

Default: 1

verbose

$verbose = $dia->verbose;

Monitor the progress of the diagram construction.

Default: 0

fretboard

$fretboard = $dia->fretboard;

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

METHODS

new

$dia = Music::FretboardDiagram->new(
  chord        => $chord,
  position     => $position,
  strings      => $strings,
  frets        => $frets,
  size         => $size,
  tuning       => $tuning,
  font         => $font,
  showname     => $showname,
  horiz        => $horiz,
  image        => $image,
  string_color => $string_color,
  fret_color   => $fret_color,
  dot_color    => $dot_color,
  outfile      => $outfile,
  type         => $type,
  verbose      => $verbose,
);

Create a new Music::FretboardDiagram object.

draw

$dia->draw;
$image = $dia->draw; # if the image attr is set

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

If the image attribute is set, return the image object instead of writing to a file.

spec_to_notes

$notes = $dia->spec_to_notes('x02220'); # A E A Db E

Convert a "spec string" to a list of named notes.

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

Or maybe:

https://www.scales-chords.com/chord-namer/guitar

AUTHOR

Gene Boggs <gene@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 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.