OxiGuitar

OxiGuitar is a free guitar tablature and score viewer, editor and player for Windows, macOS and Linux. It opens Guitar Pro files, shows them as standard notation and tablature, edits them, saves them as .gp and .gp5, exports them to PDF, and plays them (Playing a score) with the sound sets your system has or better ones you add (Better sounds).

The window has menus and a toolbar at the top, the player above the score, the palette on the left, the Inspector and the song’s information on the right, the score in the middle, the track list with each track’s mixer along the bottom and a line of messages at the very bottom: see The window. Shortcuts are in Keyboard and mouse.

Privacy. OxiGuitar never connects to the internet on its own and never sends anything anywhere: no telemetry, no accounts, no automatic crash reports.

Found a problem, or something missing from this manual? Open an issue or ask in Discussions.

Installing

Download the package for your system from the releases page. Each package exists for x86_64 (Intel, AMD) and ARM64 machines; the macOS app runs on both.

Linux needs glibc 2.39 or newer: Debian trixie or sid, Ubuntu 24.04, Fedora 40 or later. The .deb and .rpm also install oxiguitar-cli, a command-line tool that prints a file’s contents, converts it to Guitar Pro 7’s .gp, and engraves it to PNG and PDF (oxiguitar-cli --help), and both programs’ manual pages (man oxiguitar, man oxiguitar-cli).

Wayland and X11

The Linux packages above are the Wayland build, for today’s desktops (GNOME, KDE Plasma and most others run Wayland). A desktop that still runs only an X server needs the X11 build instead:

It is the same program, and each build carries only its own display system’s code. Installing one package replaces the other. If you start the wrong one, it says which build you need. The X11 build is deprecated and will be dropped once desktops have left X11.

The plugins

The packages above hold the program alone, and it opens files only through plugins. Install the basic plugins too, which open Guitar Pro files of every version from 3 to 8:

The .deb and .rpm work with either Linux build. OxiGuitar creates your plugin folder the first time it starts; Help → About lists every folder it searches, and Tools → Plugins the plugins it found. To leave out a plugin you don’t want, untick it in Tools → Plugins, or delete its .oxp file. (Releases up to 0.5.0 also listed every plugin as a file of its own; the zip holds them all.) Until OxiGuitar has a plugin, its footer says that nothing can be opened yet.

On macOS, if the system refuses a plugin it downloaded (“cannot be opened because the developer cannot be verified”), clear the download mark on the plugin files and start OxiGuitar again:

xattr -d com.apple.quarantine ~/Library/Application\ Support/OxiGuitar/plugins/*.oxp

The first launch

The packages are not code-signed yet, so the system warns the first time:

• Windows: SmartScreen says “Windows protected your PC”. Click More info, then Run anyway.
• macOS: Control-click the app, choose Open, then Open again. On recent macOS you may need System Settings → Privacy & Security → Open Anyway instead.

Opening Guitar Pro files with a double click

The .deb, .rpm and .dmg register the Guitar Pro file types (.gp, .gpx, .gp5, .gp4, .gp3), so double-clicking such a file opens it in OxiGuitar. The portable Windows .exe and the AppImage change nothing on your system, so you register them by hand if you want to.

Windows. Right-click a .gp file, choose Open with → Choose another app, then Choose an app on your PC (or More apps → Look for another app on this PC), pick oxiguitar.exe and tick Always use this app. Repeat for .gpx, .gp5, .gp4 and .gp3.

AppImage. Put the AppImage where it will stay, then run, with its path in the first line:

app="$HOME/Applications/OxiGuitar-x86_64.AppImage"
raw=https://raw.githubusercontent.com/mateusrdp/oxiguitar/main
id=io.github.mateusrdp.OxiGuitar
data="${XDG_DATA_HOME:-$HOME/.local/share}"
mkdir -p "$data/applications" "$data/mime/packages" "$data/icons/hicolor/256x256/apps"
curl -fsSL "$raw/assets/linux/$id.xml" -o "$data/mime/packages/$id.xml"
curl -fsSL "$raw/assets/icon/png/oxiguitar-256.png" -o "$data/icons/hicolor/256x256/apps/$id.png"
curl -fsSL "$raw/assets/linux/$id.desktop" | sed "s|^Exec=oxiguitar |Exec=\"$app\" |" > "$data/applications/$id.desktop"
update-mime-database "$data/mime"
xdg-mime default "$id.desktop" application/x-gtp

This also gives OxiGuitar its icon and an entry in your desktop’s menu. To undo it, delete the three files and run update-mime-database again. With a copy of the source code, scripts/install-desktop-entry.sh PATH-TO-APPIMAGE does the same.

macOS. Double-clicking a Guitar Pro file starts OxiGuitar but does not open the file: open it with File → Open, or drop it on the window.

The window

From top to bottom:

• Menus: File, Edit, View, Tools, Help. Help → About says which version you have and where OxiGuitar looks for plugins; it also has a Donate with PayPal button (it opens the page in your browser) and a QR code to scan with your phone, if you’d like to buy Mateus a drink.
• Toolbar: buttons in groups. File: Open, Save, Export PDF. Edit: Undo, Redo. View → Toolbar hides it. Plugins will add their own groups.
• Top panel: the Player tab, with rewind, play, play selection, pause and stop, count-in, loop, the metronome and the visual metronome, the speed, the level and the choice of output (Playing a score). They are greyed out while nothing can play the score, and the line at the bottom says why.
• Left panel, the score, right panel. The left panel holds the palette, every notation and effect tool of the editor as a button, in groups (voices and modes, bar, note, effects, notation); hover over one to see its name and key. Those that come with Guitar Pro 8’s notation (M5) are greyed out and say so. Click a group’s heading to fold it away or bring it back. The search field at its top (Ctrl + F) shows only the tools whose names hold the words you type (“slide”, “nat harm”); Escape empties it, Enter goes back to the score. The right panel holds the Inspector, with the caret’s bar, note and beat (Editing), and the Song tab, with the score’s information. The score sits on a dark background whatever the page colour, with its zoom slider in the corner (Zoom).
• Bottom panel: the Tracks tab, each track with its mixer, its notation buttons and an overview of the track across the song (Tracks and notation).
• Messages: one line at the very bottom with the latest error or warning: what went wrong opening a file, what is missing, a plugin that stopped working. It shows nothing else, so it stays quiet while everything works. Click it to see every message since OxiGuitar started; the chevron in its corner folds the list back.

Panels

Each panel has tabs. Click a tab’s name to show it; click the name of the tab that is already showing, or the chevron at the end of the tab strip, to fold the panel away to its strip, and again to bring it back. A folded side panel is a thin strip: click it to open it. Drag the edge between a panel and the score to resize it.

View → Panels hides or shows each panel altogether (F7 for the left one, F8 for the bottom one). Plugins can add tabs to any panel. They appear after OxiGuitar’s own tabs, with the plugin’s name for them, and look like the rest of the window: the plugin decides what is in them (buttons, tickboxes, sliders, lists, drawings), and OxiGuitar draws it in its own style and colours. A plugin’s tab may take a moment the first time it opens, while the plugin loads.

Opening files

Choose File → Open… (Ctrl + O), drag a file from your file manager onto the window, double-click a Guitar Pro file if your package registered them (Installing), or name the file when you start the program:

oxiguitar song.gp

OxiGuitar opens files through its format plugins, one for each format. Ours, the basic plugins (Installing), open Guitar Pro files of every version from 3 to 8:

The plugins recognise a file by its contents, so a file with the wrong extension still opens. The program shows what the file says: a tab saved without key signatures is shown in C, and each track shows the notation it was saved with (you can change this in the track list).

When no installed plugin recognises a file, OxiGuitar doesn’t open it, and the line of messages at the bottom of the window says so. If a plugin opens files with that extension but didn’t recognise this one (a damaged file, or one the plugin gets wrong), the message asks you to report a bug; otherwise it asks you to open a feature request, so we know which formats people need. Both go to the issue tracker. Plugins for MuseScore (.mscz, .mscx), MusicXML, ABC and MIDI files are planned. The same line explains what went wrong when a file cannot be read; click it to see earlier messages.

Dragging a file onto the window works on Windows, macOS and Linux desktops running X11; on Wayland desktops (the default on GNOME and KDE) it does not work; open the file with File → Open or a double-click instead. If you drop several files, the first one opens.

On Linux the Open dialog comes from your desktop through the XDG desktop portal, which GNOME and KDE install by default. Without it, the line at the bottom says so, and you can still open files from the command line.

Saving files

Choose File → Save (Ctrl + S) to write the score back to its file, or File → Save As… (Ctrl + Shift + S) to write it under another name. The window’s title shows the file’s name, with a dot before it while the score has changes not yet saved.

OxiGuitar saves through its format plugins, as it opens files. Ours write Guitar Pro 7 and 8 files (.gp), which Guitar Pro 7 and later open, and Guitar Pro 5 files (.gp5), which Guitar Pro 5 and every later version open, and TuxGuitar too. Choose the format in Save As… by the name’s extension. Save keeps a file’s own format unless that format can’t hold everything in the score, or no installed plugin writes it (Guitar Pro 3 and 4 files and .gpx are only read): then the score is saved beside the file, under the same name, as a .gp file, the fullest format OxiGuitar writes, and the original file stays as it was. OxiGuitar asks before doing so, and offers Save As… to choose another name.

What a file can’t hold

No format holds everything. Before writing a file that would lose something, OxiGuitar lists what, with the first bar and track where it happens, and asks whether to save. For a .gp file the list is usually short, such as:

• different dynamics on the notes of one beat (Guitar Pro 7 has one dynamic per beat);
• the colours of sections;
• trills at a speed other than sixteenths;
• bends with more points than Guitar Pro keeps (a bend, a hold and a release fit).

A .gp5 file loses more, because the format is older:

• the second and further staves of a track, and the third and fourth voices of a bar;
• tuplets other than the common ones (3 in the time of 2, 5 to 7 in the time of 4, 9 to 13 in the time of 8), double dots, double-whole and 128th notes;
• bars in free time, signs (segno, coda, D.S. and the like) in more than one bar, alternate endings above the eighth, repeat counts above 99, section letters and tempo names;
• tempo changes that aren’t at the start of a beat, and gradual tempos;
• left-hand tapping, feedback harmonics, artificial harmonics other than one, two or three octaves up, and bends finer than its steps;
• lyrics of more than one track or of more than five verses, and characters outside Windows-1252 (written as ?).

A few things are kept in another shape and not listed as losses, since they come back as they were: dynamic markings are written as the notes’ dynamics, and volume and pan are kept to sixteen steps.

When you save over the file the score came from, the list also names what OxiGuitar couldn’t keep when it opened the file, since those are lost from the file once it is written over.

To try a file without changing it, use Save As.

Plugins’ settings for each track

Some plugins add their own settings to a track’s Properties… (the NAM plugin’s amp model, for example). No score format holds them, so OxiGuitar keeps them in a small file beside the score, named after it: song.gp3 keeps them in song.gp3.oxg. Saving writes it and opening reads it; keep the two files together when you copy or share a song. Without the .oxg file the score opens as usual, with those settings empty. Guitar Pro and other programs ignore it.

Before closing

Opening another file, quitting, or closing the window with changes not yet saved asks first: Save, Don’t Save (the changes are lost), or Cancel.

From the command line

oxiguitar-cli convert song.gp song.gp5 writes a file in the format of the new file’s extension and prints what it couldn’t hold. It copies song.gp.oxg, if there is one, to song.gp5.oxg.

Layouts

View → Layout chooses how the staves are laid out, as in Guitar Pro 8:

Scroll with the mouse wheel, the scroll bars, the arrow keys, Page Up and Page Down, Space, Home and End. In the Horizontal layout the wheel scrolls along the line when the line fits the window’s height. Shift and the wheel zoom the score (Zoom).

Tracks and notation

The Tracks tab of the bottom panel shows every track of the song: its name, its mixer, its notation buttons and an overview of the track across the song. View → Panels → Bottom (F8) hides or shows the panel, a click on the open tab’s name folds it away, and dragging its top edge makes it taller or shorter.

• Click a name to select that track: the caret moves to it (Editing). A track is shown while its clef or TAB button is on.
• Click a hidden track’s notation button to show it with the others, lined up bar by bar in one score. There’s no separate “show all” switch: showing each track you want is enough.
• With several tracks, each system starts with the tracks’ names.
• Right-click a name for the track’s menu: Properties…, Transpose…, Add Track, Duplicate, Move Up, Move Down and Delete…. Delete asks first; Undo brings a deleted track back.

Adding, moving and deleting tracks

Add Track (also Edit → Add Track) adds a steel-string guitar in standard tuning after the track, with empty bars, and moves the caret to it. Duplicate copies the track with its notes, named “… (copy)”. Move Up and Move Down change its place in the song. The tracks you had on the page stay there wherever they move, and when the caret’s track is deleted the caret goes to the nearest track still shown.

Track properties

Properties… (also Edit → Track Properties…, or right-click on the page → Track Properties…) opens the track dialog:

• Name, and a short name for the systems after the first.
• Instrument: the General MIDI sound, or Drum Kit.
• Strings: none for an instrument without tablature, or 3 to 10. Capo and the number of frets.
• Tuning: a key and a pattern. The patterns are Standard, Drop (the lowest string a tone down, as Drop D), Open with the root on the lowest string (Open D, Open E), Open with the fifth on the lowest string (Open G, Open A), and Other, where you type the notes, lowest first (D2 A2 D3 G3 A3 D4; a note without an octave goes above the one before it). Tunings are named the same way at the top of the page: “Standard tuning”, “Tuning: Drop D”, or the notes.
• If the strings change: keep the notes’ pitches, finding new frets near the old ones, or keep the frets and let the notes change.

The dialog is one change you can undo. If the new strings or capo can’t play some notes, a question says how many before they are left out.

Notation buttons

Each track has two buttons at the end of its row: TAB for tablature and a treble clef for standard notation. A lit button is on. Tracks without strings, such as drums, have only the clef.

Clicking either button of a hidden track shows it again, with that notation. The last track shown cannot be hidden.

When a file opens, each track shows the notation it was saved with. Tablature is on only for fretted instruments (guitars, basses, banjo and the like), and keyboard tracks get a grand staff, split between the hands.

Mixer

After its name, each track has its mixer: two buttons, mute (a loudspeaker crossed out) and solo (headphones), a volume slider and a pan knob (left to right). They start as the file sets them and change the sound as you move them, while it plays (Playing a score); they are greyed out while nothing can play the score. Nothing you change there is written to the file.

Overview

The rest of each row shows the track across the whole song, from start to end, like a waveform: it is thick where the track plays a lot and a thin line where it is silent, so you can see at a glance where each instrument comes in. The mark across it is the playback position: it follows the sound while the score plays, stays where you paused, and otherwise shows where Play will start (the caret). Click an overview to move the playback there.

Editing

OxiGuitar is becoming an editor. This page grows with it: today you can move around the score, select, enter and change notes, change bars, copy and paste, add and change tracks (Tracks and notation), transpose, add effects, chords, text and lyrics, set the score’s information, undo, and find the bars that don’t add up.

The caret

A box over the page shows where the next edit goes: a beat of one voice, and on the tablature the string, framed. Click anywhere in the music to put it there, or move it with the keys, as in Guitar Pro:

When a voice is shorter than its bar, the caret has one more place after its last beat: typing there adds a beat. Click past a short voice’s last note to go there.

The page scrolls to keep the caret in view. Only the caret’s voice is drawn in full ink; the other voices are greyed, so you see which notes you are editing (a PDF prints them all in black). The palette’s voice buttons, 1 to 4 at its top, show which voice the caret is in. A click on a track’s name in the Tracks tab selects that track and moves the caret to it; the selected track’s name is highlighted.

Selecting

Hold Shift with the arrows, Home or End, or Shift + click, to select from where the caret was. Ctrl + Shift + Left / Right selects bar by bar. Within one voice of one staff a selection is a run of beats; once it reaches another track it takes whole bars of every track in between. Ctrl + A (Edit → Select All) selects everything, and Escape drops the selection.

Entering notes

Type at the caret, with Guitar Pro 8’s keys:

On the standard staff, click a line or a space: the caret marks it, and Up / Down move it a step at a time. Enter puts a note there, in the bar’s key (on a line or space the key signature sharpens, the note is sharp); on a guitar it goes on the string where its fret is lowest, nearest the caret’s string, and the caret moves to that string. A semitone up or down with Alt + Shift + Up / Down gives the notes the key leaves out. Clicking the tablature, or Tab, takes the caret back to the strings.

The Edit menu has the same commands and a few more: Insert Beat, Delete Beats, Clear Beats, Clear Bar, Move Beat Left / Right (it swaps places with its neighbour in the bar), Move Beat to Voice (into a voice that has room at that moment: a rest of its length takes its place), and Remove Unused Voices (voices after the first that hold no notes, in every bar of the track).

File → New (Ctrl + N) starts a new score: one bar of 4/4 at 120 and a steel-string guitar in standard tuning. Pressing Right at its end adds a bar. Save asks where to put it the first time.

A beat added after a voice’s last beat is as long as the beat before it. Typing into a voice that the bar doesn’t have yet starts that voice. Note lengths, dots, semitones and deleting beats act on every selected beat when a run of beats is selected.

The palette’s Note group works too: the whole to sixty-fourth note buttons set the beat’s length, and Rest, Dotted Note, Double-Dotted Note and Tie do what their keys do. They light up to show the caret’s beat: its length, its dots, whether it is a rest, whether its note is tied.

A tied note always plays the fret of the note it continues: change that note and its ties follow. Notes of a drum track are drum sounds, not frets; entering them comes later.

Every change can be undone. After typing, the bars that don’t add up are checked again (see below).

Tuplets

/ (or the palette’s Triplet) makes the beat a triplet, three in the time of two, or takes it out of one; with a run of beats selected, all of them. Custom N-tuplet (in the palette, or Edit → Custom N-tuplet…) asks for any grouping, n notes in the time of m, with the usual m filled in as you change n: 5 to 7 in the time of 4, 9 to 15 in the time of 8, and 2, 4 and 8 in the time of 3, 3 and 6. A beat added after a tuplet’s last beat is in the same tuplet, so typing on fills it.

Bars

The bar commands work on the caret’s bar or, with a selection, on its bars.

The Bar dialog (also Edit → Bar… and the palette’s Clef, Key Signature, Time Signature, Rhythmic Interpretation, Alternate Endings and Directions) shows what the bar carries and changes any of it at once, as one change to undo:

• Time signature, key and feel change from this bar until the next bar that had another, as Guitar Pro changes them. A tempo change inside a bar stays at the same point of the bar when its time signature changes.
• Clef changes the caret’s track from this bar until its next clef. A guitar’s staff sounds an octave below the written notes, and it keeps doing so in any clef (its bass clef has the small 8 too). Drum tracks keep the drums’ clef.
• Tempo is the tempo from the start of the bar: in the first bar, the song’s tempo.
• Repeat: whether a repeat opens here, and whether one closes here and how many times it is played.
• Alternate endings 1 to 8, Section (a letter and a name; empty for none), Double bar line, Free time, and the Directions: segno, coda, fine and the jumps (D.C., D.S., “to coda” and the rest).

The palette’s Repeat Start, Repeat Close, Free Time and Double Bar Line switch those at once, and light up when the caret’s bar has them; Triplet lights up on a triplet beat.

Copy, cut and paste

OxiGuitar keeps its own clipboard: copying and pasting work inside OxiGuitar, not with other programs.

• Copy (Ctrl + C) copies the selected beats or, with nothing selected, the beat at the caret. A selection across tracks copies whole bars of each selected track, with what the bars carry (time and key signatures, repeats, sections, tempo changes).
• Cut (Ctrl + X) copies, then takes the beats out of their voice, or the bars out of every track.
• Paste (Ctrl + V) puts what was copied in at the caret, or at the start of the selection. Beats go into the caret’s voice before its beat; a bar that then holds more than its time signature is marked red. Bars go in before the caret’s bar, in every track: the tracks that were copied, from the caret’s track down, get their bars, and the others get empty bars.
• Special Paste (Ctrl + Shift + V) pastes several times, or replaces what is there instead of inserting. Beats then take the place of as much music as they last, and what they don’t cover of the last beat they replace stays as rests. Bars then take the place of the bars from the caret’s on, and bars are added at the end when needed.

Beats and bars paste into any track. Between a drum track and a pitched one only the rhythm carries over, as rests. Notes on strings the track hasn’t got are left out. Chord names go with their diagrams.

Edit → Go to Section lists the score’s sections and moves the caret to the one you choose.

Transposing

Transpose… moves notes up or down, by semitones or by steps of the key, which keeps the music in its key (C, D, E up a step in C major become D, E, F). There are three ways in:

• Right-click on the page → Transpose…, or Edit → Transpose Selection…: the selection, or the caret’s beat when nothing is selected. A right-click outside the selection first moves the caret there.
• Right-click on a track’s name → Transpose…: the whole track.
• Tools → Transpose…: every track, with the key signatures.

Up is a positive number, down a negative one. Keep the fingering keeps each note on its string and moves its fret; otherwise each note goes to the fret nearest the one it had, so a run stays where your hand is. Notes that no string can play any more are left out, after a question saying how many. Drum tracks are never transposed. Undo brings everything back.

Effects

Every effect of Guitar Pro’s tablature has a key and a tool in the palette’s Effects group. Pressed once, an effect goes on; pressed again, it comes off. A note effect goes on the note on the caret’s string, and does nothing if that string has no note in the beat; on a staff without strings it goes on every note of the beat. A beat effect goes on the caret’s beat. With a selection, both go on every note (or beat) selected, unless all of them have it already: then it comes off all of them. Rests take no effects. The tools light up when the caret’s note or beat has their effect.

Guitar Pro 8’s keys, and a few of our own for effects it gives none (the effect’s first letter, with at most one modifier):

Slides in from below and from above and out upwards, popping and the semi-harmonic have tools in the palette but no keys. A note slides in one way and out one way: another slide on the same side takes the place of the first. A note has one harmonic: another kind takes its place. A grace note is a thirty-second, as Guitar Pro writes them, and takes no time in the bar.

The palette’s dynamics, ppp to fff, set the dynamic of the caret’s beat, or of every selected beat (rests too), and its notes play at it. They have no keys. View → Dynamics shows them on the page.

Bends and the whammy bar

B (or the palette’s Bend) opens the bend editor for the note on the caret’s string; Ctrl + Alt + V (or Whammy Bar) opens it for the beat’s whammy bar. Pick a type (Bend, Bend and release, Release, Prebend, Prebend and bend, Prebend and release; for the whammy bar Dive, Dip, Return, Predive, Predive and dive) and a pitch from ¼ tone to 3 tones, or drag the curve’s points on the grid: time across the note in twelfths, pitch up the side in quarter tones. A press on an empty grid starts a bend at that pitch. The curve has an origin, a middle held at one pitch between two places, and a destination, which is the shape a .gp file holds. Enter applies it, Escape cancels, and “No bend” takes the bend away. With a selection, the curve goes on every selected note (or beat).

The Inspector’s note and beat

Under the caret’s bar, the Inspector shows the note on the caret’s string and its beat, and changes them. The tickboxes switch effects as their keys do (on a selection, on every selected note or beat). The drop-downs and numbers set what the keys only start at a default: the accent, how the note slides in and out, the harmonic and how far up an artificial or tapped harmonic sounds, the trill’s speed (sixteenths, thirty-seconds or sixty-fourths) and the fret it trills with, the fingers of the left and right hands, the dynamic, the speed of tremolo picking, grace notes, the brush and how long it takes, the pick stroke, and tapping, slapping or popping. Edit… beside the bend and the whammy bar opens their editor. On a rest only its dynamic shows. Each change is one step to undo.

A .gp file keeps trills in sixteenths only: saving a faster trill as .gp names it among what the file can’t hold. A .gp5 file keeps them at any of its speeds.

Chords, text and lyrics

A (or the palette’s Chord, or Edit → Chord…) opens the chord dialog for the caret’s beat. Build the chord: its root, its type (major, minor, augmented, diminished, suspended second or fourth, power chord), a sixth, seventh or extension (6, 6/9, 7, maj7, 9, maj9, 11, 13, add9), alterations (♭5, ♯5, ♭9, ♯9, ♯11, ♭13) and a bass note. The name follows (“C7(b9)/E”), and the list beside the diagram gives the ways to play it on the track’s strings, easiest first; click one to make it the diagram. Or click on the diagram: on the grid to place or take away a note, above a string to make it open (o) or not played (×), with First fret to move up the neck; the chord your notes make is named, as Guitar Pro suggests one. A name you type is kept as you typed it. The track’s chords picks one the track already has. Show the diagram off keeps the name alone. The first time, the diagram starts from the beat’s notes. On a rest, or after the voice’s last beat, a chord with a diagram puts its notes in the beat. Remove the chord takes it off the beat. The palette’s Chords opens the same dialog.

Shift + T (or the palette’s Text, or Edit → Text…) sets the text above the caret’s beat; empty takes it away.

Lyrics are typed on the page, as in MuseScore. Put the caret on a note and press Ctrl + T (or the palette’s Lyrics, or Edit → Type Lyrics): a small field opens under the beat. Type the syllable, then:

A syllable already there shows in the field, to change; an empty field leaves the note without one. Lyrics go on the notes of the track’s first voice, on its first staff; a tied note continues the syllable before it, and rests and grace notes get none. Every syllable is one step to undo.

Lyrics are kept as Guitar Pro keeps them, and a file’s lyrics follow its rules on the page: a space or a hyphen starts the next syllable, each further space or hyphen leaves a note empty, a plus joins two words on one note (“got+to”), and text in square brackets (“[Verse 2]”) is a note to yourself, not shown.

The Inspector shows the beat’s chord and text, with Edit… to change them.

The song’s information

The Song tab, beside the Inspector on the right, holds the score’s information, in Guitar Pro’s order: title, artist, subtitle, album, words, music, copyright, transcriber, notices and instructions. Type in a field; it is set when you press Enter or leave the field, as one step to undo. The title, subtitle and artist show at the top of the page and of a PDF.

Undo and redo

Edit → Undo (Ctrl + Z) and Edit → Redo (Ctrl + Y), or the arrows in the toolbar, undo and redo every change, as many times as you like. The menu names the change: “Undo Infer Key Signatures”.

Bars that don’t add up

The Inspector, on the right, shows the caret’s bar: its time signature, and for each voice how much it holds against it, as Guitar Pro 8 shows a bar, counted in the time signature’s own unit (quarter notes in 4/4, eighth notes in 6/8): “2/4” for two quarters in 2/4 (green), “1.5/4” for a dotted quarter (red), then Full, ½ beat short or 1 beat too long, and how many notes and rests were entered. The caret’s voice is highlighted, and the last line says on which beat the caret’s beat starts. It follows every move and every change, so it is the quickest way to see what a bar still needs while composing.

A bar whose beats are longer or shorter than its time signature is laid in translucent red on the page. Such bars are allowed (many files have a few), and the PDF export shows the music without the red. When a file has any, the line at the bottom of the window says how many and where the first is. Tools → Next Bar That Doesn’t Add Up (F4, as Guitar Pro’s “Check bar duration”) moves the caret to the next one in the tracks shown, going round to the start. A voice that holds nothing (Guitar Pro fills unused voices with empty beats) doesn’t count.

Playing a score

OxiGuitar plays the open score through your sound card, with the sound sets it finds. Its controls are the Player tab at the top of the window and each track’s row at the bottom.

Play, pause and stop

A blue line moves through the music with the sound, and the beat you are hearing is lightly boxed in blue (the caret is green). The page turns by itself to keep it in sight. While a song plays, each track’s overview at the bottom shows where the sound is; click an overview to jump there.

The score can’t be edited while it plays. Pause it (Space), edit, and play on. If you type while it plays, the bottom of the window reminds you.

Practising

• Loop repeats the selection over and over, or the whole song when nothing is selected. Select the bars or beats first, then turn Loop on and press Play.
• Count-In plays a bar of clicks before the music starts.
• Metronome clicks every beat, higher on the bar’s first.
• Visual Metronome (the button with rays, next to it) flashes on every beat, brighter on the bar’s first, whether or not the metronome is heard.
• Speed plays from 25 % to 200 % of the written tempo, in steps of 5. The pitch doesn’t change.

The mixer

Each track’s row at the bottom has a mute button (the loudspeaker crossed out), a solo button (headphones: when any track is soloed, only soloed tracks are heard), a volume slider and a pan knob (drag it, or use the arrow keys; a double click centres it). They start as the file sets them and change the sound as you move them. Level, in the Player tab, is the volume of everything together. None of this is saved into the file; it lasts until you close OxiGuitar.

However loud a song is, OxiGuitar never lets the sound go past just under full scale, so it doesn’t distort when many tracks play at once.

Output

Output chooses where the sound goes: the system’s default, or one of the outputs your system lists. OxiGuitar remembers the choice. It opens the output when you press Play and lets go of it a couple of seconds after the sound stops, so other programs can use it in between.

When it can’t play

The controls are greyed out when nothing can play the score, and the line at the bottom of the window says why and what to get:

• No sound set: put one in your soundfonts folder, or install one with your package manager (Better sounds).
• No instrument or no audio output: the basic plugins hold both (the SoundFont plugin, and an audio output for your system). See Settings and plugins.

Sounds are made ready when a file opens, so Play starts at once. A SoundFont 3 set is decoded the first time it is used, which can take a few seconds.

From a terminal, oxiguitar-cli play song.gp plays a score too; oxiguitar-cli play song.gp --wav song.wav writes it to a WAV file instead (see man oxiguitar-cli).

Zoom

OxiGuitar has two zooms.

Score zoom enlarges the score only, from 25 % to 400 %:

• Hold Shift and turn the mouse wheel over the score. The point under the pointer stays where it is. The wheel alone scrolls the score.
• Or drag the slider in the bottom-right corner of the score. 100 % is in the middle of the slider and the knob snaps to it; the middle of the view stays in place. Click the percentage to go back to 100 %.

Interface zoom enlarges the whole window, menus and track list included. It has no control on screen:

The keypad’s +, − and 0 work too. The steps are those of a web browser, from 50 % to 200 %, on top of your system’s own display scaling.

Dark page and dynamics

View → Dark Interface switches the window’s own colours between dark (the default) and light.

View → Dark Page shows light notation on a dark page, which is easier on the eyes at night. It changes only the screen: a PDF is always printed on a light page. The area around the page stays dark either way. OxiGuitar remembers these choices, and the rest of the View menu, the next time it starts.

View → Dynamics shows or hides dynamics markings such as mf and pp (hidden by default, as they clutter the page; Mateus, 20 Oct 2026). Guitar Pro 3 to 5 files store loudness per note rather than as markings, so they never show any.

Tools

The Tools menu holds actions that change the open score. They only run when you choose them: OxiGuitar never changes a score on its own. A tool changes the score on screen, never the file on disk, until you save it; each tool’s change is one step that Edit → Undo takes back.

A tool that cannot run on the open score is greyed out, with the reason in brackets after its name. After OxiGuitar’s own tools come those your plugins add, if any (Settings and plugins); oxiguitar-cli tools lists them all.

Infer Key Signatures

Most tabs leave every bar in C major, so their notation is full of sharps and flats. Tools → Infer Key Signatures works out key signatures from the notes, with key changes where the music modulates, and replaces any the score already has. Music that stays chromatic is left in C.

Try it when a song’s notation looks crowded with accidentals; if you don’t like the result, undo it.

Exporting a PDF

File → Export PDF… saves the score as a PDF, next to the song unless you choose another folder.

• It contains the tracks shown on screen, with the notation each one shows.
• It is always laid out in pages (the Page layout), whichever layout the window uses, and printed in black on white even with Dark Page on. Every voice is black: the grey of voices other than the caret’s is only on screen.
• File → Paper Size chooses A4 or Letter.
• The PDF uses vector graphics and embedded fonts, so it prints sharply at any size.

To print, open the PDF in your PDF viewer and print from there.

Keyboard and mouse

Help → Keyboard and Mouse (F1) shows this list in the program. On macOS, use ⌘ where it says Ctrl.

Settings and plugins

OxiGuitar is a small program that does more with plugins: one plugin for each file format, plugins that play the score, plugins that export it in other formats than PDF, and plugins that add tabs to the window’s panels. Plugins are single files ending in .oxp. OxiGuitar opens files only through its format plugins: install ours, the basic plugins, for Guitar Pro files (Installing). A plugin is loaded only when it is first needed: the Guitar Pro 5 plugin when you open a .gp5 file, a plugin with a tab when you open its tab.

Where OxiGuitar keeps things

When it starts, OxiGuitar makes sure its settings folder, a settings.json file and your plugins folder exist (on Linux in the usual freedesktop places), and creates any that are missing, with the soundfonts folder beside plugins for sound sets (Better sounds). It never changes anything else.

To keep everything somewhere else, for example on a USB stick, start OxiGuitar with the environment variable OXIGUITAR_HOME set to that folder: settings and plugins then both live there.

OxiGuitar also keeps the View menu’s choices in settings.json, under view.

settings.json

A new settings.json is empty: {}. To look for plugins in folders of your own, list them, in the order to search:

{
  "plugin_folders": ["/home/me/oxiguitar-plugins", "/usr/lib/oxiguitar/plugins"]
}

This list replaces the usual folders. If the file isn’t valid JSON, OxiGuitar says so at the bottom of the window, leaves the file as it is and uses the usual settings.

Messages about plugins

At start, the line at the bottom of the window says what is missing:

• No output plugin is installed, so the player is off. The player’s buttons stay greyed out until a plugin that makes sound is installed.
• No read/write plugins are installed. OxiGuitar can open and save files only through format plugins, so nothing can be opened. Install the basic plugins (Installing); if they are installed, this message means they aren’t in a folder OxiGuitar searches (Help → About lists those; see plugin_folders above).

Both messages say where to download plugins: the releases page, where each release has one zip of our plugins for each system (OxiGuitar-plugins-basic-VERSION-SYSTEM-ARCH.zip; on Debian, Ubuntu and Fedora the oxiguitar-plugins-basic package). Unzip it into your plugins folder: the .oxp files go directly in the folder, not in a subfolder.

The plugin manager

Tools → Plugins… opens the plugin manager in a window of its own, which you can leave open beside the score. It lists every plugin file in the plugin folders, yours and the program’s, with its name, its version, the folder and file it is in, and what became of it:

• Loaded: it is in use.
• Not loaded yet: it loads when it is first needed.
• Disabled: you switched it off.
• Not used: another file holds the same plugin at a higher or equal version, and that one is used.
• Can’t be used, and why: the file is damaged, it is for another system, it needs a newer OxiGuitar, or its own conditions don’t hold here (a plugin only for Wayland, say).
• Stopped working, and why: it failed while OxiGuitar was running (it crashed, say). OxiGuitar stops using it until you restart and carries on as if it weren’t installed: its tabs close, and a file it would have opened goes to another plugin that opens it, if you have one. The line at the bottom of the window says so when it happens.

The tickbox beside a plugin enables or disables it. The change takes effect the next time OxiGuitar starts: a plugin can’t be unloaded while the program runs, so one you untick while it is in use stays in use until you restart. The plugin’s line says what will change, and the window reminds you to restart OxiGuitar while a change is waiting. OxiGuitar keeps the list in settings.json, under disabled.

The plugin manager only lists plugins and switches them on and off. It never downloads, copies, installs or removes anything. To install a plugin, put its .oxp file in your plugins folder (see above), or install a package that puts it in the program’s folder. To remove one, delete its file.

Safe mode

If a plugin misbehaves so badly that OxiGuitar won’t start properly, start it in safe mode:

oxiguitar --safe-mode

In safe mode no plugin is used at all, so nothing can be opened or played, but Tools → Plugins… still lists every plugin file: untick the one that causes trouble, then start OxiGuitar again normally. Help → About lists the plugin folders, in the order they are searched, so you can also find the file and delete it.

Privacy

Plugins made by the OxiGuitar project keep the program’s privacy promises: nothing is uploaded, and nothing is downloaded. We make no promises about plugins from anywhere else: a plugin can do anything a program can, so install only plugins you trust.

Writing your own

Plugins are written in Rust. The plugin developer guide shows how, from a template plugin that builds, passes our checks and opens in OxiGuitar as it is.

Better sounds

OxiGuitar plays your scores with a sound set: a file of recorded instruments, such as a SoundFont. It never downloads one. Out of the box it plays with the set your system already has, and you can give it better ones by putting their files in a folder.

The set your system has

• Windows has one, gm.dls, and macOS has one, in Core Audio. OxiGuitar plays with these when it finds nothing better.
• Linux has one when a package installs it. On Debian and Ubuntu the oxiguitar-plugins-basic package recommends fluid-soundfont-gm (FluidR3, 148 MB) or musescore-general-soundfont-small (MuseScore General, 40 MB), and your package manager installs one with it unless you told it not to; on Fedora it recommends fluid-soundfont-gm. OxiGuitar looks in /usr/share/sounds/sf2, /usr/share/sounds/sf3 and /usr/share/soundfonts.

These are General MIDI sets: one sound for each of the 128 standard instruments and a drum kit, small enough to come with a system. Windows’ and macOS’s are the smallest and plainest. The first time OxiGuitar gets a score ready to play with only your system’s sets (when you open it), the bottom of the window says so, once, with a link to this page.

Using a better set

Put the set’s file in the soundfonts folder beside your plugins folder (OxiGuitar creates it when it starts):

With OXIGUITAR_HOME set, it is the soundfonts folder in that folder. OxiGuitar reads SoundFont 2 (.sf2), SoundFont 3 (.sf3) and Downloadable Sounds (.dls) files there, and SFZ instruments: a .sfz file with its samples (WAV, FLAC or Ogg Vorbis) in folders beside it, as their makers ship them, so put the whole unpacked folder in. It looks in folders inside it too, five levels deep, and never changes anything there.

A set in your folder plays before any of the system’s, and of several, the largest plays. To choose yourself, open Tools → Plugins…, select SoundFont and press Settings…: pick a set for electric guitars, one for acoustic guitars, one for basses, one for drums and one for everything else. The choice holds for every file. “The best found” goes back to the automatic choice, which is never an SFZ instrument (below).

A SoundFont 3 file is decoded the first time it plays, which takes a few seconds for a large set; OxiGuitar keeps the decoded copy in its cache folder, so later it loads at once. That copy can be large (216 MB for the small MuseScore General, 490 MB for the full one); deleting it is harmless.

Choosing a set for each instrument

A set made for one instrument usually sounds far better than a General MIDI set’s version of it, so you can mix: recorded guitars from one set, the bass, the drums and the rest from another. Open Tools → Plugins…, select SoundFont, press Settings…, and pick a set for each of Electric guitars, Acoustic guitars, Basses, Drums and Everything else. Electric guitars are General MIDI’s six electric sounds (jazz, clean, muted, overdriven, distortion, harmonics), acoustic guitars its nylon and steel strings, and basses its eight bass sounds; banjos and the other fretted instruments go with everything else, so they keep their own sounds. A set made for one instrument only has that instrument, so pick it only for its own row and leave a General MIDI set for the others.

SFZ instruments are listed in the same rows, as their set’s folder and their own name (“… (SFZ)”). An SFZ file is one instrument, not a set of 128, so it plays only in a row you pick it for. Many SFZ sets come with several instruments (programs) for the same recording, with different microphones or articulations: try them. OxiGuitar loads an SFZ instrument’s samples into memory, whole, when you open a score, so playing never waits for the disk; a big drum kit can take a few seconds and some gigabytes of memory. If an instrument can’t load, or some of its samples are missing, the bottom of the window says so and a General MIDI set plays instead.

Sets worth getting

All of these are free to use. Download them from their makers’ pages, unpack them if they come packed (the FreePats files are .7z: 7-Zip on Windows, The Unarchiver on macOS, p7zip on Linux), then put the .sf2 or .sf3 file in your soundfonts folder.

For everything

• FluidR3_GM (MIT licence, 148 MB): a complete General MIDI set, the best sounding of those we tried. On Linux it is the fluid-soundfont-gm package.
• MuseScore General (MIT licence; SoundFont 3, 86 MB, or SoundFont 2, 490 MB): MuseScore’s set, close behind. On Debian and Ubuntu: musescore-general-soundfont (SoundFont 3) or musescore-general-soundfont-lossless.

Guitars

FreePats’ electric guitars (CC0: free for anything, no credit needed), each from its own page on GitHub (Releases, the file with SF2 in its name):

Pick one for Electric guitars in the settings window. Direct sounds thin on its own: it is the raw signal an amp model starts from, for the amp modelling (NAM) that OxiGuitar 1.0 brings; get it for then.

Recorded guitars, basses and drums (SFZ)

These SFZ sets are the ones we recommend: we listened to every reference song with each of them, and OxiGuitar knows their layouts, so they play the score’s hammer-ons, palm mutes, dead and ghost notes with their own recorded articulations. Unpack each into your soundfonts folder as a whole folder, then pick its instrument in its row of the settings window.

Get the two Karoryfer sets from their Releases, the file named in the table, not with Code → Download ZIP or git clone: their repositories ask git to treat every file as text, which corrupts the samples in those copies. The MuldjordKit has no releases, and its Download ZIP is fine.

The keyswitched programs (…_keyswitch, …_keysw) are the ones with every articulation: pick those. Black and Green’s other programs and Black and Blue’s single-articulation programs play too, without the score’s effects on their own samples. Hear them together on the Hear it page.

The MuldjordKit is under CC BY 4.0: if you publish music made with it, credit Lars Muldjord and the DrumGizmo team. Karoryfer’s sets need no credit.

Other SFZ sets

Any SFZ instrument plays. Ones OxiGuitar has no layout for play their notes as they are, palm mutes and dead notes ended early, hammer-ons carrying on the ringing string. OxiGuitar also knows the layouts of SM Drums, Naked Drums (its own programs) and Karoryfer’s Big Rusty, Swirly and Unruly Drums, so their drums play at the right keys; we found the MuldjordKit the most natural of these.

Hear it

A few of OxiGuitar’s own reference songs, played by OxiGuitar exactly as they sound in the window. They were rendered with oxiguitar-cli play SONG --wav OUT, with no effects or editing afterwards, and then encoded as MP3. Every set heard here is free and listed on Better sounds.

Recorded guitars, basses and drums

The electric guitars are Karoryfer’s Black and Green Guitars (the green Gretsch, CC0), the basses Karoryfer’s Black and Blue Basses (CC0) and the drums the MuldjordKit by Lars Muldjord and the DrumGizmo team, SFZ by kinwie (CC BY 4.0); the acoustic guitar, piano, strings and voice FluidR3_GM (MIT). All three are SFZ sets, played by the SoundFont plugin’s sampler (OxiGuitar 1.0).

A band: the same eight tracks as below, with recorded electric guitars, bass and drums.

Bass: a four-string bass line, alone.

Drums: kick, snare, hi-hat, four toms, crash and ride, written as General MIDI drums.

Guitar techniques: dead notes, ghost notes and palm mutes, with the set’s own recorded articulations.

General MIDI sets

Played by OxiGuitar 0.9: the guitars use FreePats’ Clean electric guitar (CC0) and everything else uses FluidR3_GM (MIT).

A band: three guitars, bass, drums, piano, strings and a voice, each track at its file’s volume and pan.

Bends: full, half and released bends on a guitar, each moving only its own string.

Strums and techniques: strums up and down, slap, pop and tapping.

Drums: General MIDI’s kit.

These songs are short pieces written to test OxiGuitar, not music. Amp modelling (NAM), which turns a plain guitar into a real amp’s sound, comes with OxiGuitar 1.0, and so will examples of it here.