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

NAME

Music::FretboardDiagram - Draw fretboard chord diagrams

VERSION

version 0.1304

SYNOPSIS

use Music::FretboardDiagram;

my $dia = Music::FretboardDiagram->new(
  chord    => 'xx0232',
  frets    => 5,     # the default
  position => 1,     # the default
  font     => '/path/to/TTF/font.ttf',
  outfile  => 'Dm',
  type     => 'png', # the default
);

$dia = Music::FretboardDiagram->new(
  chord    => [[1,'022000'], [2,'--1342'], [7,'-13321']], # Em chords
  frets    => 13,
  absolute => 1,
  outfile  => 'fretboard',
  horiz    => 1,
  verbose  => 1,
);

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

$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');
$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. The default order of the strings is 654321 from lowest to highest.

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

Chord string 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

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.

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;

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 before drawing, 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;

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.

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) 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.