A PHP library for reading, writing and rendering guitar tablatures and MIDI files
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/PhpTabs Fix CS Sep 17, 2018
test [Feature] Add a Voice::getTime() method to get time in seconds Sep 8, 2018
.travis.yml Fix PHPUnit version for HHVM Jun 13, 2018
CONTRIBUTING.md Add contribution guidelines Sep 1, 2017
LICENSE
README.md Fix md bold string Dec 25, 2017
composer.json [CI] Increase PHPUnit versions Dec 26, 2017
phpunit.xml.dist [CI] Run PHPUnit as vendor script instead of binary Aug 1, 2017

README.md

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 fully exploit the library, read the PhpTabs Manual.


Requirements

PhpTabs requires one of the following:

  • PHP 5.4+
  • PHP 7+
  • HHVM

Installation

Installation with Composer is required if you want to run PHPUnit tests.

From Github

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

Then add this PHP line before usage:

require_once 'src/PhpTabs/bootstrap.php';

With Composer

  • Package configuration
composer require stdtabs/phptabs:0.*

Basic Usage

require_once 'src/PhpTabs/bootstrap.php';

use PhpTabs\PhpTabs;

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

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

Options

You can get or set options before instanciating PhpTabs object with the Config component.

use PhpTabs\Component\Config;

// Setting option value
Config::set('<option name>', '<option value>');

// Getting option value
Config::get('<option name>');

type

Useful to set one specific type of analyse

Values

  • meta

    Only meta informations are read from the tablature file.

    Analyse is very fast.

  • channels

    Only meta informations and channels are read from the tablature file.

    Analyse is fast.

  • default or anything else

    The file is fully analyzed.

Example

// Setting type to meta will accelerate analyses
Config::set("type", "meta");

debug

Useful to manage Exceptions

Values

  • true

    The application stops.

    An exception message and a stack trace are printed.

  • default or anything else

    Nothing is printed and the application continues.

Example

// Setting debug to true makes Exceptions as blocking events
Config::set("debug", true);

verbose

Useful to print all logged events such as stream reads, internal notices and warnings.

Values

  • true

    The application prints all events.

  • default or anything else

    Nothing is printed.

Example

// Setting verbose to true 
Config::set("debug", true);

Methods

Error handling


hasError()

Type boolean

It returns true if an error has been set, otherwise false.

$tablature->hasError();

getError()

Type string

It returns the last error message or an empty string if no error has been set.

$tablature->getError();

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 string|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 formats are allowed:

Parameter Type Description
php://output string A binary string into the buffer
null string Same as php://output
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');

// Dump the binary into the buffer
echo $tab->save();

dump($format)

Type string|array

Parameter string $format

Dumps are made to visualize the internal music-tree or to communicate with a third-party application.

Following formats are allowed:

Parameter Type Description
array array a raw PHP array
xml string an XML string
json string a JSON string
var_export string a raw PHP array as string
serialize string a PHP serialized
text string a non standardized text
txt string same as text
yaml string a YAML representation
yml string same as yaml

Example

// Dump content into a file as XML
file_put_contents(
  'tab.xml',
  $tab->dump('xml')
);

// Dump into a variable as PHP array
$array = $tab->dump(); // array is the default format

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();