README.md

PhpTabs

PhpTabs is a PHP library for reading and writing scores and MIDI files. It provides direct methods to read a song name, get a list of instruments or whatever be your needs.

PhpTabs currently supports the following file formats:

• Guitar Pro 3 (.gp3)
• Guitar Pro 4 (.gp4)
• Guitar Pro 5 (.gp5)
• MIDI (.mid, .midi)

Any questions?

• Read the PhpTabs Manual
• Open an issue on github
• Contribute code
• Contribute documentation in the /docs

Table of contents

The documentation below contains only basic examples. If you want to see more examples and the complete API behind the library, read the PhpTabs Manual.

Before version 1.0.0, the old manual PhpTabs Manual

• Requirements
• Installation
  • Composer
  • Alternative
• Testing
• Basic Usage
• Methods
  • Accessing metadata
    • getName()
    • getArtist()
    • getAlbum()
    • getAuthor()
    • getCopyright()
    • getWriter()
    • getComments()
    • getTranscriber()
    • getDate()
  • Accessing tracks
    • countTracks()
    • getTracks()
    • getTrack()
  • Accessing channels
    • countChannels()
    • getChannels()
    • getChannel()
  • Accessing instruments
    • countInstruments()
    • getInstruments()
    • getInstrument()
  • Accessing measure headers
    • countMeasureHeaders()
    • getMeasureHeaders()
    • getMeasureHeader()
  • Saving data
    • save()
    • export()
    • convert()

---

Requirements

PhpTabs requires PHP 7.4+ and 8.0+.

Until PhpTabs 1.0.5, it was maintained for PHP versions 7.2 and 7.3.

Until PhpTabs 0.6.1, it was maintained for PHP versions 7.0 and 7.1.

Until PhpTabs 0.6.0, it was maintained for PHP versions 5.4, 5.5, 5.6 and HHVM.

---

Installation

Composer

composer require stdtabs/phptabs

Alternative

Download and extract an archive from https://github.com/stdtabs/phptabs/releases

Then add this PHP line before usage:

// Use standalone bootstrap
require_once 'src/PhpTabs/bootstrap.php';

---

Testing

To run tests, you should install PHPUnit first.

composer require phpunit/phpunit

Then run the test suite with:

vendor/bin/phpunit

---

Basic Usage

require_once 'src/PhpTabs/bootstrap.php';

use PhpTabs\PhpTabs;

// Instanciates a tablature
$tablature = new PhpTabs("mytabs.gp3");

// Reads information
echo $tablature->getName();

---

Methods

Accessing metadata

---

getName()

Type string

The name of the song.

Example

$tablature->getName();

---

getArtist()

Type string

The interpreter of the song.

Example

$tablature->getArtist();

---

getAlbum()

Type string

The name of the album.

Example

$tablature->getAlbum();

---

getAuthor()

Type string

The author of the song.

Example

$tablature->getAuthor();

---

getCopyright()

Type string

The copyright of the song.

Example

$tablature->getCopyright();

---

getWriter()

Type string

The songwriter.

Example

$tablature->getWriter();

---

getComments()

Type string

The tablature comments. They are compounded of several lines separated by a line break (PHP_EOL).

Example

$tablature->getComments();

---

getTranscriber()

Type string

Person who has transcribed tablature

Support

Guitar Pro >= 4

Example

$tablature->getTranscriber();

---

getDate()

Type string

Date when tablature has been transcribed

Support

Guitar Pro >= 4

Example

$tablature->getDate();

---

Accessing tracks

---

countTracks()

Type integer

The number of tracks

Example

$tablature->countTracks();

---

getTracks()

Type array

An array of Track objects

There is one track object for each instrument of the song.

Example

$tablature->getTracks();

---

getTrack($index)

Type object

Parameter integer $index

The music sheet for one instrument.

Example

// Get the first track
$tablature->getTrack(0);

---

Accessing channels

---

countChannels()

Type integer

The number of channels

Example

$tablature->countChannels();

---

getChannels()

Type array

An array of Channel objects

There is one channel object for each track of the song.

Example

$tablature->getChannels();

---

getChannel($index)

Type object

Parameter integer $index

The instrument and sound parameters for one track.

Example

// Get the first channel
$tablature->getChannel(0);

---

Accessing instruments

---

countInstruments()

Type integer

The number of instruments

Example

$tablature->countInstruments();

---

getInstruments()

Type array

A list of instrument arrays

array(
  'id' => <integer InstrumentId>,
  'name' => <string InstrumentName>
)

Example

$tablature->getInstruments();

---

getInstrument($index)

Type array

Parameter integer $index

An instrument array

array(
  'id' => <integer InstrumentId>,
  'name' => <string InstrumentName>
)

Example

// Get the first instrument
$tablature->getInstrument(0);

---

Accessing measure headers

---

countMeasureHeaders()

Type integer

The number of measure headers

Example

$tablature->countMeasureHeaders();

---

getMeasureHeaders()

Type array

An array of MeasureHeader objects

Example

$tablature->getMeasureHeaders();

---

getMeasureHeader($index)

Type object

Parameter integer $index

Measure header contains global informations about the measure.

Example

// Get the first measure header
$tablature->getMeasureHeader(0);

---

Saving data

---

save($filename)

Type bool

Parameter string $filename

This method records data as binary to the disk or buffer. It implicitly converts filetype if the specified file extension is different from the original (see examples below).

Following parameters are allowed:

Parameter	Type	Description
filename.ext	bool	A file_put_contents() return

Example

// Instanciate a GP3 tab
$tab = new PhpTabs('mytab.gp3');

// Save as GP3
$tab->save('newfile.gp3');

// Convert and save as GP5
$tab->save('newfile.gp5');

---

convert($type)

---

Type string

Parameter string $type

This method returns data as a binary string into a specified format.

Following formats are allowed:

Parameter	Type	Description
null	string	A binary string, original format
gp3	string	A binary string, GP3 formatted
gp4	string	A binary string, GP4 formatted
gp5	string	A binary string, GP5 formatted
mid	string	A binary string, MIDI formatted
midi	string	A binary string, MIDI formatted

Example

// Instanciate a GP3 tab
$tab = new PhpTabs('mytab.gp3');

// Convert as GP3
echo $tab->convert('gp3');

// Convert as GP5
echo $tab->convert('gp5');

// Convert as MIDI
echo $tab->convert('mid');

// Render as original format
// Should be equal as file_get_contents('mytab.gp3')
echo $tab->convert();

A lot more examples on PhpTabs Manual.