PhpTabs Documentation Build Status

Parse and write GuitarPro and MIDI files

Home Manual GitHub

PhpTabs basics

Table of contents


Features

PhpTabs basics are the read, write, convert, dump, import and render operations.

This document describes the best way to use these tools.

^ Table of contents


Read from a file

Files are binary resources such Guitar Pro or MIDI files.

A read operation involves reading and parsing the entire file.

All elements are represented in the internal data model.

A read operation is automatically made when instanciating a PhpTabs object.

Example


// A read operation is made
$tab = new PhpTabs('mytabs.gp4');

After a read operation, the instance is containing the entire song.

^ Table of contents


Save to a file

A PhpTabs instance is containing all data.

It’s possible to save this data to the disk or to the buffer with the save() method.

Example


// Instanciating
$tab = new PhpTabs('mytabs.gp4');

// Saving to the buffer with the default format
echo $tab->save();

// Saving to the disk
$tab->save('new_filename_for_mytabs.gp4');

^ Table of contents


Convert

When saving data, an implicit conversion is made if needed.

Example


// Instanciating
$tab = new PhpTabs('mytabs.gp4');

// Converts and save with gp5 format
echo $tab->save('mytabs.gp5');

Printing data to the buffer with another format is possible with an explicit conversion.

Example


// Instanciate a gp4 file
$tab = new PhpTabs('mytabs.gp4');

// Explicit conversion and print with gp5 format
echo $tab->convert('gp5');

Note

Available file formats are .gp3, .gp4, .gp5, .mid and .midi.

^ Table of contents


Dump and import data

Dump operation are made to put all internal data to a machine readable format (XML, JSON, YML, PHP array).

It’s useful to transport data and make some debug, some caching, etc…

After data has been dumped, it’s possible to import it with import methods.

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

$tab = new PhpTabs('mytabs.gp4');

// Get as a PHP array
$data = $tab->dump();
$data = $tab->dump('array');

// Get as an XML string
echo $tab->dump('xml');

// Get as a JSON string
echo $tab->dump('json');

// Get as a YAML string
echo $tab->dump('yml');
echo $tab->dump('yaml');

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

Import

Not yet implemented

Planned for 0.6.0

^ Table of contents


Render

Not yet implemented

Planned for 0.5.0 (testable in the master branch)

Render is made in 2 steps:

  1. Get a specific renderer with getRenderer($type)

    Following renderer types are allowed:

    Parameter Type Description
    vextab string A vextab string
  2. Render as string with render() method

Example

First, create a renderer instance. Then, render all tracks.


$tab = new PhpTabs('mytabs.gp4');

// Get a vextab renderer
$renderer = $tab->getRenderer('vextab');

// Render all tracks one-by-one
for ($i = 0; $i < $tab->countTracks(); $i++) {

  echo $renderer->render($i);

}

It’s easy to make the same thing with one line.


$tab = new PhpTabs('mytabs.gp4');

// Render all tracks one-by-one
for ($i = 0; $i < $tab->countTracks(); $i++) {

  echo $tab
    ->getRenderer('vextab')
    ->render($i);

}

See another example of the VexTab renderer

^ Table of contents


Architecture

Component schema

Component roles

With the internal model, you can easily convert files from one type to another.

^ Table of contents


Traversing

Starting from one point, you can find your way with the Music-Object-Model reference.

Traversing data is made by getter/setter/counter methods.

A traversal is done in read-write mode

Getter/setter/counter rules

There are 4 rules for getter names:

  1. get + {objectName} + ()

    It’s a property getter method. ie: there can be only one Tempo per MeasureHeader, so the method name to get the tempo for a given measure is $header->getTempo().

  2. count + {objectName} + s()

    It’s a child nodes counter method. ie: there can be several measures per Track, so the method name to count them is $track->countMeasures().

  3. get + {objectName} + s()

    It’s a child-nodes getter method, it returns an array with all child-nodes. ie: there can be several measures per Track, so the method name to get them is $track->getMeasures().

  4. get + {objectName} + ($index)

    It’s a child-node getter by index, it returns one child resource. $index is starting from 0 to n-1, with n=child count (returned by the counter method) ie: there can be several measures per Track, so the method name to get one measure(the first) is $track->getMeasure(0).

When in doubt, reference should be made to the Music-Object-Model reference.

^ Table of contents


Traversing, a naive example

In the following example, all notes will be printed.


$tab = new PhpTabs('mytab.gp4');

# Get all tracks
foreach ($tab->getTracks() as $track)
  # Get all measures
  foreach ($track->getMeasures() as $measure)
    # Get all beats
    foreach ($measure->getBeats() as $beat)
      # Get all voices
      foreach ($beat->getVoices() as $voice)
        # Get all notes
        foreach ($voice->getNotes() as $note)
          
          printNote($note);


/**
 * Print all referential
 *
 * @param \PhpTabs\Music\Note $note
 */
function printNote($note)
{
  echo sprintf(
    "\nTrack %d - Measure %d - Beat %d - Voice %d - Note %s/%s",
    $note->getVoice()->getBeat()->getMeasure()->getTrack()->getNumber(),
    $note->getVoice()->getBeat()->getMeasure()->getNumber(),
    $note->getVoice()->getBeat()->getStart(),
    $note->getVoice()->getIndex(),
    $note->getValue(),
    $note->getString()
  );
}

will output something like

Track 1 - Measure 1 - Beat 6240 - Voice 0 - Note 11/3
Track 1 - Measure 1 - Beat 6480 - Voice 0 - Note 0/2

[...]

Track 2 - Measure 1 - Beat 960 - Voice 0 - Note 5/2
Track 2 - Measure 1 - Beat 1920 - Voice 0 - Note 5/2
Track 2 - Measure 1 - Beat 2880 - Voice 0 - Note 5/2
Track 2 - Measure 1 - Beat 3840 - Voice 0 - Note 5/2

[...]

All referential can be accessed starting from a note.

This example does not take into account some aspects of the referential such as rest beats, durations, dead notes, note effects and chord beats.

^ Table of contents


Edit this document on GitHub