Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
288 lines (203 sloc) 5.64 KB
layout permalink title excerpt
default
phptabs.html
Music Object Model Overview
How to traverse Music Object Model

Music Object Model Overview

PhpTabs makes a song fully-traversable.

It builds a musical tree which is called the Music-Object-Model (MOM).


MOM

Song (= A PhpTabs instance)

  • []Channel

    • []ChannelParameter

    [... channels]

  • []MeasureHeader

    • Song [parent]
    • Tempo
    • TimeSignature

    [... measureHeaders ]

  • []Track

    • Song [parent]

    • Color

    • Lyric

    • []Measure

      • Track [parent]

      • Marker

      • MeasureHeader

      • TimeSignature

      • []Beat

        • Measure [parent]

        • Stroke

        • Chord

        • Text

        • []Voice

          • Beat [parent]
          • Duration
          • []Note
            • Voice [parent]
            • NoteEffect
              • EffectBend
              • EffectGrace
              • EffectHarmonic
              • EffectTremoloBar
              • EffectTremoloPicking
              • EffectTrill

          [... notes ]

        [... voices ]

      [... beats ]

    [... measures ]

    • []TabString

[... tracks ]


Traversing the tree is made simple

In this example, we read the fret value and string number, for the first note of the first track.


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

// We read a note
$note = $song
  ->getTrack(0)     # Track 0
  ->getMeasure(0)   # Measure 0
  ->getBeat(0)      # Beat 0
  ->getVoice(0)     # Voice 0
  ->getNote(0);     # Note 0


// Print fret and string numbers
echo sprintf(
  "Note: %s/%d",
  $note->getValue(),
  $note->getString()
);

It will ouput something like:

Note: 13/2 

Below, we make the same thing, for all tracks.


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

foreach ($tab->getTracks() as $track) {

  // We read a note
  $note = $track
    ->getMeasure(0)   # Measure 0
    ->getBeat(0)      # Beat 0
    ->getVoice(0)     # Voice 0
    ->getNote(0);     # Note 0

  // Print track, fret and string numbers
  echo sprintf(
    "\nTrack %d - Note: %s/%d ",
    $track->getNumber(),
    $note->getValue(),
    $note->getString()
  );
}

It will ouput something like:

Track 1 - Note: 13/2 
Track 2 - Note: 5/2

Now, we read all the beats for the first measure of all tracks.


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

foreach ($tab->getTracks() as $track) {

  foreach ($track->getMeasure(0)->getBeats() as $idxBeat => $beat) {

    // We read a note
    $note = $beat
      ->getVoice(0)     # Voice 0
      ->getNote(0);     # Note 0

    // Print Track, Beat, fret and string numbers
    echo sprintf(
      "\nTrack %d - Beat %d - Note: %s/%d ",
      $track->getNumber(),
      $idxBeat,
      null !== $note ? $note->getValue() : '-',
      null !== $note ? $note->getString(): '-'
    );
  }
}

Outputs:

Track 1 - Beat 0 - Note: -/0 
Track 1 - Beat 1 - Note: -/0 
Track 1 - Beat 2 - Note: 11/3 
Track 1 - Beat 3 - Note: 0/2 
Track 2 - Beat 0 - Note: 5/2 
Track 2 - Beat 1 - Note: 5/2 
Track 2 - Beat 2 - Note: 5/2 
Track 2 - Beat 3 - Note: 5/2 
Track 2 - Beat 4 - Note: 5/2 
Track 2 - Beat 5 - Note: 5/2

Note the first two beats, they must be rest beats.

A short but useful view of the MOM is :

You can traverse it this way:

$tab
  ->getTrack(0)
  ->getMeasure(0)
  ->getBeat(0)
  ->getVoice(0)
  ->getNote(0);

Traversing the first level

A Song object contains:

  • meta data (Name, artist, etc...)
  • channels
  • measure headers
  • tracks

Channel, MeasureHeader and Track can be accessed with following methods:


Traversing Channels

getChannels(), getChannel() and getChannelById() methods

In this example, we print the channel names.


// Working with all channels
foreach ($song->getChannels as $channel) {
  echo $channel->getName() . PHP_EOL;
}

// Accessing by index
echo $song->getChannel(0)->getName() . PHP_EOL;
// Outputs something like "Clean Guitar 1"

// Accessing by id
echo $song->getChannelById(1)->getName() . PHP_EOL;
// Outputs something like "Clean Guitar 1"

Traversing MeasureHeaders

getMeasureHeaders() and getMeasureHeader() methods

In this example, we print the tempo for each measure.


// Working with all measure headers
foreach ($song->getMeasureHeaders() as $header) {
  echo $header->getTempo()->getValue() . PHP_EOL;
}

// Accessing by index to the first header
echo $song->getMeasureHeader(0)->getTempo()->getValue() . PHP_EOL;
// Outputs something like "90"

Traversing Tracks

getTracks() and getTrack() methods

In this example, we print the number of measures by track.


// Working with all tracks
foreach ($song->getTracks() as $track) {
  echo $track->countMeasures() . PHP_EOL;
}

// Accessing by index to the first track
echo $song->getTrack(0)->countMeasures() . PHP_EOL;
// Outputs something like "4" (small tab!)

{% capture doc_url %}{{ site.github_doc_repository_url }}/docs/phptabs.md{% endcapture %} {% include edit-doc-link.html %}