stdtabs / phptabs
A PHP library for reading, writing and rendering Guitar Pro and MIDI files
Requires
- php: >=7.4
Requires (Dev)
README
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
- Testing
- Basic Usage
- Methods
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:
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:
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.