API Reference
General functions
- guitarpro.parse(stream, encoding='cp1252') Song [source]
Open a GP file and read its contents.
- Parameters:
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: Song, stream, version: tuple | None = None, encoding='cp1252')[source]
Write a song into GP file.
- Parameters:
song – a song to write.
stream – path to save GP file or file-like object.
version – explicitly set version of GP file to save, e.g.
(5, 1, 0)
.encoding – encode strings into given 8-bit charset.
Models
- class guitarpro.models.RepeatGroup(measureHeaders: List[MeasureHeader] = _Nothing.NOTHING, closings: List[MeasureHeader] = _Nothing.NOTHING, openings: List[MeasureHeader] = _Nothing.NOTHING, isClosed: bool = False)[source]
This class can store the information about a group of measures which are repeated.
- class guitarpro.models.KeySignature(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
- class guitarpro.models.Song(versionTuple: Tuple[int, int, int] | None = None, clipboard: Clipboard | None = None, title: str = '', subtitle: str = '', artist: str = '', album: str = '', words: str = '', music: str = '', copyright: str = '', tab: str = '', instructions: str = '', notice: List[str] = _Nothing.NOTHING, lyrics: Lyrics = _Nothing.NOTHING, pageSetup: PageSetup = _Nothing.NOTHING, tempoName: str = 'Moderate', tempo: int = 120, hideTempo: bool = False, key: KeySignature = KeySignature.CMajor, measureHeaders: List[MeasureHeader] = _Nothing.NOTHING, tracks: List[Track] = _Nothing.NOTHING, masterEffect: RSEMasterEffect = _Nothing.NOTHING, currentRepeatGroup: RepeatGroup = _Nothing.NOTHING)[source]
The top-level node of the song model.
It contains basic information about the stored song.
- class guitarpro.models.LyricLine(startingMeasure: int = 1, lyrics: str = '')[source]
A lyrics line.
- class guitarpro.models.Lyrics(trackChoice: int = 0, lines: List[LyricLine] = _Nothing.NOTHING)[source]
A collection of lyrics lines for a track.
- class guitarpro.models.Padding(right: int, top: int, left: int, bottom: int)[source]
A padding construct.
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 = Point(x=210, y=297), pageMargin: Padding = Padding(right=10, top=15, left=10, bottom=10), scoreSizeProportion: float = 1.0, headerAndFooter: HeaderFooterElements = HeaderFooterElements.all, title: str = '%title%', subtitle: str = '%subtitle%', artist: str = '%artist%', album: str = '%album%', words: str = 'Words by %words%', music: str = 'Music by %music%', wordsAndMusic: str = 'Words & Music by %WORDSMUSIC%', copyright: str = 'Copyright %copyright%\nAll Rights Reserved - International Copyright Secured', pageNumber: str = '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.MidiChannel(channel: int = 0, effectChannel: int = 1, instrument: int = 25, volume: int = 104, balance: int = 64, chorus: int = 0, reverb: int = 0, phaser: int = 0, tremolo: int = 0, bank: int = 0)[source]
A MIDI channel describes playing data for a track.
- class guitarpro.models.Duration(value: int = 4, isDotted: bool = False, tuplet: Tuplet = _Nothing.NOTHING)[source]
A duration.
- class guitarpro.models.TimeSignature(numerator: int = 4, denominator: Duration = _Nothing.NOTHING, beams: List[int] = _Nothing.NOTHING)[source]
A time signature.
- class guitarpro.models.TripletFeel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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: int = 1, start: int = 960, hasDoubleBar: bool = False, keySignature: KeySignature = KeySignature.CMajor, timeSignature: TimeSignature = _Nothing.NOTHING, marker: Marker | None = None, isRepeatOpen: bool = False, repeatAlternative: int = 0, repeatClose: int = -1, tripletFeel: TripletFeel = TripletFeel.none, direction: DirectionSign | None = None, fromDirection: DirectionSign | None = None)[source]
A measure header contains metadata for measures over multiple tracks.
- class guitarpro.models.Marker(title: str = 'Section', color: Color = Color(r=255, g=0, b=0))[source]
A marker annotation for beats.
- class guitarpro.models.TrackSettings(tablature: bool = True, notation: bool = True, diagramsAreBelow: bool = False, showRhythm: bool = False, forceHorizontal: bool = False, forceChannels: bool = False, diagramList: bool = True, diagramsInScore: bool = False, autoLetRing: bool = False, autoBrush: bool = False, extendRhythmic: bool = False)[source]
Settings of the track.
- class guitarpro.models.Track(song: Song, number: int = 1, fretCount: int = 24, offset: int = 0, isPercussionTrack: bool = False, is12StringedGuitarTrack: bool = False, isBanjoTrack: bool = False, isVisible: bool = True, isSolo: bool = False, isMute: bool = False, indicateTuning: bool = False, name: str = 'Track 1', measures: List[Measure] = _Nothing.NOTHING, strings: List[GuitarString] = _Nothing.NOTHING, port: int = 1, channel: MidiChannel = _Nothing.NOTHING, color: Color = Color(r=255, g=0, b=0), settings: TrackSettings = _Nothing.NOTHING, useRSE: bool = False, rse: TrackRSE = _Nothing.NOTHING)[source]
A track contains multiple measures.
- class guitarpro.models.GuitarString(number: int, value: int)[source]
A guitar string with a special tuning.
- class guitarpro.models.MeasureClef(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
An enumeration of available clefs.
- class guitarpro.models.LineBreak(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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: Track, header: MeasureHeader, clef: MeasureClef = MeasureClef.treble, voices: List[Voice] = _Nothing.NOTHING, lineBreak: LineBreak = LineBreak.none)[source]
A measure contains multiple voices of beats.
- class guitarpro.models.VoiceDirection(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Voice directions indicating the direction of beams.
- class guitarpro.models.Voice(measure: Measure, beats: List[Beat] = _Nothing.NOTHING, direction: VoiceDirection = VoiceDirection.none)[source]
A voice contains multiple beats.
- class guitarpro.models.BeatStrokeDirection(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
All beat stroke directions.
- class guitarpro.models.BeatStroke(direction: BeatStrokeDirection = BeatStrokeDirection.none, value: int = 0)[source]
A stroke effect for beats.
- class guitarpro.models.SlapEffect(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Characteristic of articulation.
- none = 0
No slap effect.
- tapping = 1
Tapping.
- slapping = 2
Slapping.
- popping = 3
Popping.
- class guitarpro.models.BeatEffect(stroke: BeatStroke = _Nothing.NOTHING, hasRasgueado: bool = False, pickStroke: BeatStrokeDirection = BeatStrokeDirection.none, chord: Chord | None = None, fadeIn: bool = False, tremoloBar: BendEffect | None = None, mixTableChange: MixTableChange | None = None, slapEffect: SlapEffect = SlapEffect.none, vibrato: bool = False)[source]
This class contains all beat effects.
- class guitarpro.models.TupletBracket(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
- class guitarpro.models.BeatDisplay(breakBeam: bool = False, forceBeam: bool = False, beamDirection: VoiceDirection = VoiceDirection.none, tupletBracket: TupletBracket = TupletBracket.none, breakSecondary: int = 0, breakSecondaryTuplet: bool = False, forceBracket: bool = False)[source]
Parameters of beat display.
- class guitarpro.models.Octave(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Octave signs.
- class guitarpro.models.BeatStatus(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
- class guitarpro.models.Beat(voice: Voice, notes: List[Note] = _Nothing.NOTHING, duration: Duration = _Nothing.NOTHING, text: str | None = None, start: int | None = None, effect: BeatEffect = _Nothing.NOTHING, octave: Octave = Octave.none, display: BeatDisplay = _Nothing.NOTHING, status: BeatStatus = BeatStatus.empty)[source]
A beat contains multiple notes.
- class guitarpro.models.ArtificialHarmonic(pitch: PitchClass | None = None, octave: int | None = None)[source]
- class guitarpro.models.GraceEffectTransition(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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.GraceEffect(duration: int = 32, fret: int = 0, isDead: bool = False, isOnBeat: bool = False, transition: GraceEffectTransition = GraceEffectTransition.none, velocity: int = 95)[source]
A grace note effect.
- property durationTime
Get the duration of the effect.
- class guitarpro.models.TrillEffect(fret: int = 0, duration: Duration = _Nothing.NOTHING)[source]
A trill effect.
- class guitarpro.models.TremoloPickingEffect(duration: Duration = _Nothing.NOTHING)[source]
A tremolo picking effect.
- class guitarpro.models.SlideType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
An enumeration of all supported slide types.
- class guitarpro.models.Fingering(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Left and right hand fingering used in tabs and chord diagram editor.
- open = -1
Open or muted.
- thumb = 0
Thumb.
- index = 1
Index finger.
- middle = 2
Middle finger.
- annular = 3
Annular finger.
- little = 4
Little finger.
- class guitarpro.models.NoteEffect(accentuatedNote: bool = False, bend: BendEffect | None = None, ghostNote: bool = False, grace: GraceEffect | None = None, hammer: bool = False, harmonic: HarmonicEffect | None = None, heavyAccentuatedNote: bool = False, leftHandFinger: Fingering = Fingering.open, letRing: bool = False, palmMute: bool = False, rightHandFinger: Fingering = Fingering.open, slides: List[SlideType] = _Nothing.NOTHING, staccato: bool = False, tremoloPicking: TremoloPickingEffect | None = None, trill: TrillEffect | None = None, vibrato: bool = False)[source]
Contains all effects which can be applied to one note.
- class guitarpro.models.NoteType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
- class guitarpro.models.Note(beat: Beat, value: int = 0, velocity: int = 95, string: int = 0, effect: NoteEffect = _Nothing.NOTHING, durationPercent: float = 1.0, swapAccidentals: bool = False, type: NoteType = NoteType.rest)[source]
Describes a single note.
- class guitarpro.models.Chord(length: int, sharp: bool | None = None, root: PitchClass | None = None, type: ChordType | None = None, extension: ChordExtension | None = None, bass: PitchClass | None = None, tonality: ChordAlteration | None = None, add: bool | None = None, name: str = '', fifth: ChordAlteration | None = None, ninth: ChordAlteration | None = None, eleventh: ChordAlteration | None = None, firstFret: int | None = None, strings: List[int] = _Nothing.NOTHING, barres: List[Barre] = _Nothing.NOTHING, omissions: List[bool] = _Nothing.NOTHING, fingerings: List[Fingering] = _Nothing.NOTHING, show: bool | None = None, newFormat: bool | None = None)[source]
A chord annotation for beats.
- class guitarpro.models.ChordType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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: int, start: int = 0, end: int = 0)[source]
A single barre.
- Parameters:
start – first string from the bottom of the barre.
end – last string on the top of the barre.
- class guitarpro.models.ChordAlteration(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]
Tonality of the chord.
- perfect = 0
Perfect.
- diminished = 1
Diminished.
- augmented = 2
Augmented.
- class guitarpro.models.ChordExtension(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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: str | int, accidental: int | None = None, value: int | None = None, intonation: str | None = 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):
- Parameters:
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) Eb >>> p = PitchClass(4, -1, intonation='sharp') >>> p PitchClass(just=4, accidental=-1, value=3, intonation='sharp') >>> print(p) D#
Second, semitone number can be directly passed to constructor:
- Parameters:
semitone – integer of semitone.
>>> p = PitchClass(3) >>> print(p) Eb >>> p = PitchClass(3, intonation='sharp') >>> print(p) D#
And last, but not least, note name:
- Parameters:
name – string representing note.
>>> p = PitchClass('D#') >>> print(p) D#
- class guitarpro.models.MixTableItem(value: int = 0, duration: int = 0, allTracks: bool = False)[source]
A mix table item describes a mix parameter, e.g. volume or reverb.
- class guitarpro.models.MixTableChange(instrument: MixTableItem | None = None, rse: RSEInstrument = _Nothing.NOTHING, volume: MixTableItem | None = None, balance: MixTableItem | None = None, chorus: MixTableItem | None = None, reverb: MixTableItem | None = None, phaser: MixTableItem | None = None, tremolo: MixTableItem | None = None, tempoName: str = '', tempo: MixTableItem | None = None, hideTempo: bool = True, wah: WahEffect | None = None, useRSE: bool = False)[source]
A MixTableChange describes a change in mix parameters.
- class guitarpro.models.BendType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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
Prebend.
- 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: int = 0, value: int = 0, vibrato: bool = False)[source]
A single point within the BendEffect.
- class guitarpro.models.BendEffect(type: BendType = BendType.none, value: int = 0, points: List[BendPoint] = _Nothing.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)
- class guitarpro.models.RSEMasterEffect(volume: float = 0, reverb: float = 0, equalizer: RSEEqualizer = _Nothing.NOTHING)[source]
Master effect as seen in “Score information”.
- class guitarpro.models.RSEEqualizer(knobs: List[float] = _Nothing.NOTHING, gain: float = 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.Accentuation(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[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.