Skip to content

A PHP library for reading, writing and rendering guitar tablatures and MIDI files

License

Notifications You must be signed in to change notification settings

stdtabs/phptabs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PhpTabs

Latest Stable Version Build Status License

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?

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

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.