API Reference

General functions

guitarpro.parse(stream, encoding='cp1252')[source]

Open a GP file and read its contents.

  • stream – path to a GP file or file-like object.
  • encoding – decode strings in tablature using this charset. Given encoding must be an 8-bit charset.
guitarpro.write(song, stream, version=None, encoding='cp1252')[source]

Write a song into GP file.

  • song (guitarpro.models.Song) – a song to write.
  • stream – path to save GP file or file-like object.
  • version (tuple) – explicitly set version of GP file to save, e.g. (5, 1, 0).
  • encoding – encode strings into given 8-bit charset.


exception guitarpro.models.GPException[source]
class guitarpro.models.RepeatGroup(measureHeaders=NOTHING, closings=NOTHING, openings=NOTHING, isClosed=False)[source]

This class can store the information about a group of measures which are repeated.

class guitarpro.models.KeySignature[source]
class guitarpro.models.LyricLine(startingMeasure=1, lyrics='')[source]

A lyrics line.

class guitarpro.models.Lyrics(trackChoice=0, lines=None)[source]

A collection of lyrics lines for a track.

class guitarpro.models.Point(x, y)[source]

A point construct using floating point coordinates.

class guitarpro.models.Padding(right, top, left, bottom)[source]

A padding construct.

class guitarpro.models.HeaderFooterElements[source]

An enumeration of the elements which can be shown in the header and footer of a rendered song sheet.

All values can be combined using bit-operators as they are flags.

class guitarpro.models.PageSetup(pageSize=Point(x=210, y=297), pageMargin=Padding(right=10, top=15, left=10, bottom=10), scoreSizeProportion=1.0, headerAndFooter=<HeaderFooterElements.all: 511>, title='%title%', subtitle='%subtitle%', artist='%artist%', album='%album%', words='Words by %words%', music='Music by %music%', wordsAndMusic='Words & Music by %WORDSMUSIC%', copyright='Copyright %copyright%nAll Rights Reserved - International Copyright Secured', pageNumber='Page %N%/%P%')[source]

The page setup describes how the document is rendered.

Page setup contains page size, margins, paddings, and how the title elements are rendered.

Following template vars are available for defining the page texts:

  • %title%: will be replaced with Song.title
  • %subtitle%: will be replaced with Song.subtitle
  • %artist%: will be replaced with Song.artist
  • %album%: will be replaced with Song.album
  • %words%: will be replaced with Song.words
  • %music%: will be replaced with Song.music
  • %WORDSANDMUSIC%: will be replaced with the according word and music values
  • %copyright%: will be replaced with Song.copyright
  • %N%: will be replaced with the current page number (if supported by layout)
  • %P%: will be replaced with the number of pages (if supported by layout)
class guitarpro.models.RSEEqualizer(knobs=NOTHING, gain=0.0)[source]

Equalizer found in master effect and track effect.

Attribute RSEEqualizer.knobs is a list of values in range from -6.0 to 5.9. Master effect has 10 knobs, track effect has 3 knobs. Gain is a value in range from -6.0 to 5.9 which can be found in both master and track effects and is named as “PRE” in Guitar Pro 5.

class guitarpro.models.RSEMasterEffect(volume=0, reverb=0, equalizer=NOTHING)[source]

Master effect as seen in “Score information”.

class guitarpro.models.Song(versionTuple=None, clipboard=None, title='', subtitle='', artist='', album='', words='', music='', copyright='', tab='', instructions='', notice=NOTHING, lyrics=NOTHING, pageSetup=NOTHING, tempoName='Moderate', tempo=120, hideTempo=False, key=<KeySignature.CMajor: (0, 0)>, measureHeaders=None, tracks=None, masterEffect=NOTHING, currentRepeatGroup=NOTHING)[source]

The top-level node of the song model.

It contains basic information about the stored song.

class guitarpro.models.Tempo(value=120)[source]

A song tempo in BPM.

class guitarpro.models.MidiChannel(channel=0, effectChannel=1, instrument=25, volume=104, balance=64, chorus=0, reverb=0, phaser=0, tremolo=0, bank=0)[source]

A MIDI channel describes playing data for a track.

class guitarpro.models.DirectionSign(name='')[source]

A navigation sign like Coda or Segno.

class guitarpro.models.Tuplet(enters=1, times=1)[source]

A n:m tuplet.

class guitarpro.models.Duration(value=4, isDotted=False, isDoubleDotted=False, tuplet=NOTHING)[source]

A duration.

class guitarpro.models.TimeSignature(numerator=4, denominator=NOTHING, beams=NOTHING)[source]

A time signature.

class guitarpro.models.TripletFeel[source]

An enumeration of different triplet feels.

none = 0

No triplet feel.

eighth = 1

Eighth triplet feel.

sixteenth = 2

Sixteenth triplet feel.

class guitarpro.models.MeasureHeader(number=1, start=960, hasDoubleBar=False, keySignature=<KeySignature.CMajor: (0, 0)>, timeSignature=NOTHING, tempo=NOTHING, marker=None, isRepeatOpen=False, repeatAlternative=0, repeatClose=-1, tripletFeel=<TripletFeel.none: 0>, direction=None, fromDirection=None)[source]

A measure header contains metadata for measures over multiple tracks.

class guitarpro.models.Color(r, g, b, a=1)[source]

An RGB Color.

class guitarpro.models.Marker(title='Section', color=Color(r=255, g=0, b=0, a=1))[source]

A marker annotation for beats.

class guitarpro.models.TrackSettings(tablature=True, notation=True, diagramsAreBelow=False, showRhythm=False, forceHorizontal=False, forceChannels=False, diagramList=True, diagramsInScore=False, autoLetRing=False, autoBrush=False, extendRhythmic=False)[source]

Settings of the track.

class guitarpro.models.Accentuation[source]

Values of auto-accentuation on the beat found in track RSE settings.

none = 0

No auto-accentuation.

verySoft = 1

Very soft accentuation.

soft = 2

Soft accentuation.

medium = 3

Medium accentuation.

strong = 4

Strong accentuation.

veryStrong = 5

Very strong accentuation.

class guitarpro.models.Track(song, number=1, fretCount=24, offset=0, isPercussionTrack=False, is12StringedGuitarTrack=False, isBanjoTrack=False, isVisible=True, isSolo=False, isMute=False, indicateTuning=False, name='Track 1', measures=None, strings=None, port=1, channel=NOTHING, color=Color(r=255, g=0, b=0, a=1), settings=NOTHING, useRSE=False, rse=NOTHING)[source]

A track contains multiple measures.

class guitarpro.models.GuitarString(number, value)[source]

A guitar string with a special tuning.

class guitarpro.models.MeasureClef[source]

An enumeration of available clefs.

class guitarpro.models.LineBreak[source]

A line break directive.

none = 0

No line break.

break_ = 1

Break line.

protect = 2

Protect the line from breaking.

class guitarpro.models.Measure(track, header, clef=<MeasureClef.treble: 0>, voices=None, lineBreak=<LineBreak.none: 0>)[source]

A measure contains multiple voices of beats.

class guitarpro.models.VoiceDirection[source]

Voice directions indicating the direction of beams.

class guitarpro.models.Voice(measure, beats=NOTHING, direction=<VoiceDirection.none: 0>)[source]

A voice contains multiple beats.

class guitarpro.models.BeatStrokeDirection[source]

All beat stroke directions.

class guitarpro.models.BeatStroke(direction=<BeatStrokeDirection.none: 0>, value=0)[source]

A stroke effect for beats.

class guitarpro.models.SlapEffect[source]

Characteristic of articulation.

none = 0

No slap effect.

tapping = 1


slapping = 2


popping = 3


class guitarpro.models.BeatEffect(stroke=NOTHING, hasRasgueado=False, pickStroke=<BeatStrokeDirection.none: 0>, chord=None, fadeIn=False, tremoloBar=None, mixTableChange=None, slapEffect=<SlapEffect.none: 0>, vibrato=None)[source]

This class contains all beat effects.

class guitarpro.models.TupletBracket[source]
class guitarpro.models.BeatDisplay(breakBeam=False, forceBeam=False, beamDirection=<VoiceDirection.none: 0>, tupletBracket=<TupletBracket.none: 0>, breakSecondary=0, breakSecondaryTuplet=False, forceBracket=False)[source]

Parameters of beat display.

class guitarpro.models.Octave[source]

Octave signs.

class guitarpro.models.BeatStatus[source]
class guitarpro.models.Beat(voice, notes=NOTHING, duration=NOTHING, text=None, start=None, effect=NOTHING, index=None, octave=<Octave.none: 0>, display=NOTHING, status=<BeatStatus.empty: 0>)[source]

A beat contains multiple notes.

class guitarpro.models.HarmonicEffect[source]

A harmonic note effect.

class guitarpro.models.NaturalHarmonic[source]
class guitarpro.models.ArtificialHarmonic(pitch=None, octave=None)[source]
class guitarpro.models.TappedHarmonic(fret=None)[source]
class guitarpro.models.PinchHarmonic[source]
class guitarpro.models.SemiHarmonic[source]
class guitarpro.models.GraceEffectTransition[source]

All transition types for grace notes.

none = 0

No transition.

slide = 1

Slide from the grace note to the real one.

bend = 2

Perform a bend from the grace note to the real one.

hammer = 3

Perform a hammer on.

class guitarpro.models.Velocities[source]

A collection of velocities / dynamics.

class guitarpro.models.GraceEffect(duration=1, fret=0, isDead=False, isOnBeat=False, transition=<GraceEffectTransition.none: 0>, velocity=95)[source]

A grace note effect.


Get the duration of the effect.

class guitarpro.models.TrillEffect(fret=0, duration=NOTHING)[source]

A trill effect.

class guitarpro.models.TremoloPickingEffect(duration=NOTHING)[source]

A tremolo picking effect.

class guitarpro.models.SlideType[source]

An enumeration of all supported slide types.

class guitarpro.models.Fingering[source]

Left and right hand fingering used in tabs and chord diagram editor.

unknown = -2

Unknown (used only in chord editor).

open = -1

Open or muted.

thumb = 0


index = 1

Index finger.

middle = 2

Middle finger.

annular = 3

Annular finger.

little = 4

Little finger.

class guitarpro.models.NoteEffect(accentuatedNote=False, bend=None, ghostNote=False, grace=None, hammer=False, harmonic=None, heavyAccentuatedNote=False, leftHandFinger=<Fingering.open: -1>, letRing=False, palmMute=False, rightHandFinger=<Fingering.open: -1>, slides=NOTHING, staccato=False, tremoloPicking=None, trill=None, vibrato=False)[source]

Contains all effects which can be applied to one note.

class guitarpro.models.NoteType[source]
class guitarpro.models.Note(beat, value=0, velocity=95, string=0, effect=NOTHING, durationPercent=1.0, swapAccidentals=False, type=<NoteType.rest: 0>)[source]

Describes a single note.

class guitarpro.models.Chord(length, sharp=None, root=None, type=None, extension=None, bass=None, tonality=None, add=None, name='', fifth=None, ninth=None, eleventh=None, firstFret=None, strings=NOTHING, barres=NOTHING, omissions=NOTHING, fingerings=NOTHING, show=None, newFormat=None)[source]

A chord annotation for beats.

class guitarpro.models.ChordType[source]

Type of the chord.

major = 0

Major chord.

seventh = 1

Dominant seventh chord.

majorSeventh = 2

Major seventh chord.

sixth = 3

Add sixth chord.

minor = 4

Minor chord.

minorSeventh = 5

Minor seventh chord.

minorMajor = 6

Minor major seventh chord.

minorSixth = 7

Minor add sixth chord.

suspendedSecond = 8

Suspended second chord.

suspendedFourth = 9

Suspended fourth chord.

seventhSuspendedSecond = 10

Seventh suspended second chord.

seventhSuspendedFourth = 11

Seventh suspended fourth chord.

diminished = 12

Diminished chord.

augmented = 13

Augmented chord.

power = 14

Power chord.

class guitarpro.models.Barre(fret, start=0, end=0)[source]

A single barre.

  • start – first string from the bottom of the barre.
  • end – last string on the top of the barre.
class guitarpro.models.ChordAlteration[source]

Tonality of the chord.

perfect = 0


diminished = 1


augmented = 2


class guitarpro.models.ChordExtension[source]

Extension type of the chord.

none = 0

No extension.

ninth = 1

Ninth chord.

eleventh = 2

Eleventh chord.

thirteenth = 3

Thirteenth chord.

class guitarpro.models.PitchClass(just, accidental=None, value=None, intonation=None)[source]

A pitch class.

Constructor provides several overloads. Each overload provides keyword argument intonation that may be either “sharp” or “flat”.

First of overloads is (tone, accidental):

  • tone – integer of whole-tone.
  • accidental – flat (-1), none (0) or sharp (1).
>>> p = PitchClass(4, -1)
>>> p
PitchClass(just=4, accidental=-1, value=3, intonation='flat')
>>> print(p)
>>> p = PitchClass(4, -1, intonation='sharp')
>>> p
PitchClass(just=4, accidental=-1, value=3, intonation='sharp')
>>> print(p)

Second, semitone number can be directly passed to constructor:

Parameters:semitone – integer of semitone.
>>> p = PitchClass(3)
>>> print(p)
>>> p = PitchClass(3, intonation='sharp')
>>> print(p)

And last, but not least, note name:

Parameters:name – string representing note.
>>> p = PitchClass('D#')
>>> print(p)
class guitarpro.models.BeatText(value='')[source]

A text annotation for beats.

class guitarpro.models.MixTableItem(value=0, duration=0, allTracks=False)[source]

A mix table item describes a mix parameter, e.g. volume or reverb.

class guitarpro.models.MixTableChange(instrument=None, volume=None, balance=None, chorus=None, reverb=None, phaser=None, tremolo=None, tempoName='', tempo=None, hideTempo=True, wah=None, useRSE=False, rse=NOTHING)[source]

A MixTableChange describes a change in mix parameters.

class guitarpro.models.BendType[source]

All Bend presets.

none = 0

No Preset.

bend = 1

A simple bend.

bendRelease = 2

A bend and release afterwards.

bendReleaseBend = 3

A bend, then release and rebend.

prebend = 4


prebendRelease = 5

Prebend and then release.

dip = 6

Dip the bar down and then back up.

dive = 7

Dive the bar.

releaseUp = 8

Release the bar up.

invertedDip = 9

Dip the bar up and then back down.

return_ = 10

Return the bar.

releaseDown = 11

Release the bar down.

class guitarpro.models.BendPoint(position=0, value=None, vibrato=False)[source]

A single point within the BendEffect.


Gets the exact time when the point need to be played (MIDI).

Parameters:duration – the full duration of the effect.
class guitarpro.models.BendEffect(type=<BendType.none: 0>, value=0, points=NOTHING)[source]

This effect is used to describe string bends and tremolo bars.

semitoneLength = 1

The note offset per bend point offset.

maxPosition = 12

The max position of the bend points (x axis)

maxValue = 12

The max value of the bend points (y axis)