README.md

Heroku app link for the landing page: https://peaceful-river-42856.herokuapp.com/

Link to the documentation: https://peaceful-river-42856.herokuapp.com/docs/index.html

Getting Started

Setup

Static Download

Download the following source code files to your project's directory:

• Library JavaScript file: lyrichord.js
• Library CSS file: lyrichord.css

Include

Include the following scripts on your webpage (in the same order):

<link rel="stylesheet" type="text/css" href="[path to the directory in which you put the library CSS source code]/lyrichord.css">
<script defer src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script>
<script defer type="text/javascript" src='[path to the directory in which you put the library JavaScript source code]/lyrichord.js'></script>

How To Use

// Create a general song info instance
const song_info = new GeneralSongInfo('Knockin On Heaven\'s Door', 'Bob Dylan', 'The Essential Bob Dylan');
// Create the DOM element you want the song sheet to be displayed in
const song_container = document.createElement('div');
// Make the chords of the song.
const G = new Chord('G', [3, 2, 0, 0, 0, 3]);
G.add_shape([3, 5, 5, 4, 3, 3], {3: [1, 6]});
const D = new Chord('D', [-1, -1, 0, 2, 3, 2]);
const Am7 = new Chord('Am7', [-1, 0, 2, 0, 1, 0]);
const C = new Chord('Am7', [-1, 3, 2, 0, 1, 0]);
// Create a chord group
// ** Note that in each LyricChordPair instance, the chord is to be played together with the text counterpart.
const verse = new LyricChordGroup(
    'VERSE',
    [new LyricChordLine(
        [new LyricChordPair('Mama take', G),
         new LyricChordPair('this badge off', D),
         new LyricChordPair('of me', Am7)]),
     new LyricChordLine(
        [new LyricChordPair('I can\'t', G),
        new LyricChordPair('use it', D),
        new LyricChordPair('anymore...', D)])
    ]
)
// Create a song content instance
const content = new SongContent([verse]);
// Create the song sheet instance
const song = new SongSheet(song_info, content);
// Display the song sheet inside the container created above
song.display(song_container);
// Optional: add the container to the body of DOM
const body = document.querySelector('body');
body.appendChild(song_container)

Link to the documentation: https://peaceful-river-42856.herokuapp.com/docs/index.html

Documentation

• Classes
• GeneralSongInfo
• Chord
• LyricChordPair
• LyricChordLine
• LyricChordGroup
• SongContent
• SongSheet

Classes

GeneralSongInfo

Class representing the general song info.

Chord

Class representing a Chord object.

LyricChordPair

Class representing the lyric-chord pair objects of the song sheet. In terms of representation, the chord part in the pair is to be played together with the text part.

LyricChordLine

Class representing a line of lyric-chord pairs.

LyricChordGroup

Class representing a group of lyric-chord lines.

SongContent

Class representing the song content portion of the song sheet (lyrics and chords).

SongSheet

Class representing the song sheet object.

GeneralSongInfo

Class representing the general song info.

Kind: global class

• GeneralSongInfo
  • new GeneralSongInfo([name], [artist], [album], [tuning], [capo], [key], [instrument])
  • .display([container])

new GeneralSongInfo([name], [artist], [album], [tuning], [capo], [key], [instrument])

Create a general song info section.

Param	Type	Default	Description
[name]	String		The name of the song.
[artist]	String		The name of the song.
[album]	String		The album name of the song.
[tuning]	String	'eadgbe'	The tuning of the song.
[capo]	Number	0	The fret number to put the capo on.
[key]	String		The key of the song.
[instrument]	String	'Guitar'	The string instrument name of the music sheet chords (e.g. 'Guitar', 'Bass', 'Ukulele').

generalSongInfo.display([container])

Display general song info on DOM.

Kind: instance method of GeneralSongInfo

Param	Type	Default	Description
[container]	Element	document.querySelector('body')	The element object to put the display element in.

Chord

Class representing a Chord object.

Kind: global class

• Chord
  • new Chord([name], fret_nums, [barres], [display_in_popup])
  • .add_shape(fret_nums, [barres])
  • .display([container], [chords_section], [popup])

new Chord([name], fret_nums, [barres], [display_in_popup])

Param	Type	Default	Description
[name]	String		The name of the chord.
fret_nums	Array.<Number>		The fret number representation of the primary shape of 6hechord, i.e. n_i represents which fret to hold for string i. n_i = 0 represents open string. n_i = -1 represents mute string. n_i > 0 represents fret number to hold on string i. fret_nums.length = number of strings on corresponding instrument /ul>
[barres]	Object.<Number, Array.<Number>>		The barres on the primary shape of the chord with the key as the fret number and the value array as [start_string , end_string]. starting form the most top string on instrument (1) to the most bottom string (this.fret_nums.length) where start_string > 0 and end_string > start_string and end_string <= fret_nums.length e.g. {5: [2, 4]} represents a barre on fret 5 covering strings #2 to #4.
[display_in_popup]	Boolean	true	Boolean representing the initial indication of whether the chord should be displayed as popup.

chord.add_shape(fret_nums, [barres])

Add additional chord shape to a Chord to display on pages of chord's carousel.

Kind: instance method of Chord

Param	Type	Description
fret_nums	Array.<Number>	The fret number representation of the chord, i.e. n_i represents which fret to hold for string i. n_i = 0 represents open string. n_i = -1 represents mute string. n_i > 0 represents fret number to hold on string i. fret_nums.length = number of strings on corresponding instrument
[barres]	Object.<Number, Array.<Number>>	The barres on the chord with the key as the fret number and the value array as [start_string , end_string]. starting form the most top string on instrument (1) to the most bottom string (this.fret_nums.length) where start_string > 0 and end_string > start_string and end_string <= fret_nums.length e.g. {5: [2, 4]} represents a barre on fret 5 covering strings #2 to #4.

chord.display([container], [chords_section], [popup])

Display chord on DOM.

Kind: instance method of Chord

Param	Type	Default	Description
[container]	Element	document.querySelector('body')	The element object to put the display element in.
[chords_section]	Boolean	false	Boolean indicating whether it is being displayed on the song chords section of the song sheet (since they are formatted differently)
[popup]	Boolean		Boolean indicating whether the chord should be displayed as a popup.

LyricChordPair

Class representing the lyric-chord pair objects of the song sheet. In terms of representation, the chord part in the pair is to be played together with the text part.

Kind: global class

• LyricChordPair
  • new LyricChordPair([text], [chord])
  • .display([container], [format_single_chord], [popup])

new LyricChordPair([text], [chord])

Param	Type	Default	Description
[text]	String		The lyrical part of the pair.
[chord]	Chord		The chord part of the pair.

lyricChordPair.display([container], [format_single_chord], [popup])

Display the lyric-chord pair on DOM.

Kind: instance method of LyricChordPair

Param	Type	Default	Description
[container]	Element	document.querySelector('body')	The element object to put the display element in.
[format_single_chord]	Boolean	false	Format the corresponding chord's display on the song sheet. e.g. for instrumental portion of a non instrumental song
[popup]	Boolean	false	Boolean indicating whether the corresponding chord should be displayed as popup.

LyricChordLine

Class representing a line of lyric-chord pairs.

Kind: global class

• LyricChordLine
  • new LyricChordLine(pairs)
  • .addPair(pair)
  • .display([container], [popup])

new LyricChordLine(pairs)

Param	Type	Description
pairs	Array.<LyricChordPair>	Array of lyric-chord pairs to be displayed togehter on the line.

lyricChordLine.addPair(pair)

Add a lyric-chord pair to the line object.

Kind: instance method of LyricChordLine

Param	Type	Description
pair	LyricChordPair	The lyric-chord pair to be added.

lyricChordLine.display([container], [popup])

Display lyric-chord line on DOM.

Kind: instance method of LyricChordLine

Param	Type	Default	Description
[container]	Element	document.querySelector('body')	The element object to put the display element in.
[popup]	Boolean		Boolean indicating whether the chords of the lyric-chord pairs on the line should be displayed as a popup.

LyricChordGroup

Class representing a group of lyric-chord lines.

Kind: global class

• LyricChordGroup
  • new LyricChordGroup([title], lines)
  • .addLine(line)
  • .display([container], [popup])

new LyricChordGroup([title], lines)

Param	Type	Description
[title]	String	Name of the lyric-chord group (e.g. 'CHORUS', 'SOLO', etc.)
lines	Array.<LyricChordLine>	Array of lyric-chord lined to be displayed togehter in the group.

lyricChordGroup.addLine(line)

Add a lyric-chord line to the line object.

Kind: instance method of LyricChordGroup

Param	Type	Description
line	LyricChordLine	The lyric-chord line to be added.

lyricChordGroup.display([container], [popup])

Display lyric-chord group on DOM.

Kind: instance method of LyricChordGroup

Param	Type	Default	Description
[container]	Element	document.querySelector('body')	The element object to put the display element in.
[popup]	Boolean		Boolean indicating whether the chords of the lyric-chord pairs on the lines of the group should be displayed as a popup.

SongContent

Class representing the song content portion of the song sheet (lyrics and chords).

Kind: global class

• SongContent
  • new SongContent(groups)
  • .generateDOM([popup]) ⇒ Element
  • .display([container], [popup])

new SongContent(groups)

Param	Type	Description
groups	Array.<LyricChordGroup>	Array of lyric-chord groups of the song content.

songContent.generateDOM([popup]) ⇒ Element

Generates and returns the DOM element of the song content.

Kind: instance method of SongContent

Param	Type	Default	Description
[popup]	Boolean		Boolean indicating whether the chords in the song content should be displayed as popups.

songContent.display([container], [popup])

Display song content on DOM.

Kind: instance method of SongContent

Param	Type	Default	Description
[container]	Element	document.querySelector('body')	The element object to put the display element in.
[popup]	Boolean		Boolean indicating whether the chords of the song content should be displayed as a popup.

SongSheet

Class representing the song sheet object.

Kind: global class

• SongSheet
  • new SongSheet(song_info, song_content, [display_all_chords], [popup_format])
  • .display_chords() ⇒ Element | null
  • .display([container])

new SongSheet(song_info, song_content, [display_all_chords], [popup_format])

Param	Type	Default	Description
song_info	GeneralSongInfo		General song info part of the song.
song_content	SongContent		Song content part of the song.
[display_all_chords]	Boolean	true	Option to have a section on the song sheet to display all chords together.
[popup_format]	Boolean	true	Boolean indicating whether the chords of the song should be displayed as popups.

songSheet.display_chords() ⇒ Element | null

Returns the dom element of the chord section or null if there are no chords in the song.

Kind: instance method of SongSheet

songSheet.display([container])

Display song sheet on DOM

Kind: instance method of SongSheet

Param	Type	Default	Description
[container]	Element	document.querySelector('body')	The element object to put the display element in.