README

A simple tool to parse, transpose & format ChordPro songs with lyrics & chords. Compatible with PHP 8.1 and above.

Forked from https://github.com/nicolaswurtz/chordpro-php by Nicolaz Wurtz, on LGPL-3 license.

The following output formats are currently supported

• HTML (verses contain blocks with embedded span for aligning chords with lyrics).
• JSON (verses are arrays of chords and lyrics for alignment purposes).
• Plain text (chords are aligned with monospace text thanks to whitespace).

The library provides some extra functionality

• 通过半音或目标调来转调和弦。
• 解析和显示各种和弦符号
  • 法语 (Do, Ré, Mi).
  • 德语 (Fis, a).
  • 使用UTF字符 (A♭, F♯).
• 猜测歌曲的调性。

安装

通过composer

composer require intelektron/chordpro-php

用法

查看 web/example.php 以获取具有CSS样式的演示。

<?php

require __DIR__ . '/vendor/autoload.php';

$txt = "{t:A Nice Sample Song}
{st:Grzegorz Pietrzak}
{key:C}

# Let's start it!
[C]Let's sing this [G]song [Am]together [Em]aloud
[F]It's an [C]example [Dm]with some nice [G]sound

{soc: Chorus}
[Bb]Whenever you [Am7]need to [Bb]format your [Am7]chords
[Dm]The solution to your [F]problems [G]is very close
{eoc}

{comment: Now we recite some text}
Sometimes you write text
And there's no more room for chords

{comment: Sometimes you play music without any words}
[C] [G] [Am] [Em]

You don't know where the chords are? ~ [F] [C]
You don't have to know ~ [G] [G/F#]

{sot: Outro}
E-12---------------------|
B----11-12---------------|
G----------11s13-14------|
D-------------------10-12|
A------------------------|
E------------------------|
{eot}

{comment: The end}
Let's finish this song. [G] It's the end of the show.";

$parser = new ChordPro\Parser();

// Choose one of these formatters according to your needs.
$htmlFormatter = new ChordPro\Formatter\HtmlFormatter();

// Create song object after parsing $txt.
$song = $parser->parse($txt);

// You can transpose your song.
$transposer = new ChordPro\Transposer();

// Define how many semitones you want to transpose by.
// $transposer->transpose($song, -5);

// If the song key is known, you can also transpose from key to key.
// $transposer->transpose($song,'Abm');

// The formatter has some options
$options = [
    'ignore_metadata' => 'copyright',
];

// Render !
$html = $htmlFormatter->format($song, $options);

格式化选项

只需提供一个数组，其中每个键/选项的值为true或false。

[
    'ignore_metadata' => ['title', 'subtitle'], // Do not render these types of metadata.
    'no_chords' => true // Render text without chords.
    'notation' => new ChordPro\Notation\GermanChordNotation(), // Choose output chord notation.
];

歌曲键

键可以通过以下方式设置/更改

• 手动，通过调用 $song->setKey('A')。
• 通过解析具有元数据的歌曲，例如 {key:A}。
• 通过将歌曲转调到另一个调。

您可以通过以下方式获取键

• $song->getKey() - 如果通过 setKey() 定义了键，则获取该键，否则，使用元数据中的键。
• $song->getMetadataKey() - 从元数据中获取键。

如果歌曲未定义键，则有可能猜测它。此功能是实验性的且不可靠（20%的错误率，在约1000首歌曲中测试），但可能非常有用。

$guess = new ChordPro\GuessKey();
$key = $guess->guessKey($song);

和弦符号

库支持多种和弦符号。您也可以创建自己的（通过实现ChordNotationInterface.php）。符号用于解析和格式化。因此，您可以在德语符号中解析歌曲，并将其显示为法语。

$txt = 'A typical [fis]German [a]verse';
$parser = new ChordPro\Parser();
$notation = new ChordPro\Notation\GermanChordNotation();
$song = $parser->parse($song, [$notation])

在此阶段，fis 被识别并内部保存为 F#m，而 a 被保存为 Am。请注意，您可以将多个符号传递给解析器，并按优先级排序。如果您的一首歌中混入了不同的和弦符号，这可能很有用。

现在，要显示这首歌曲的法语版本

$monospaceFormatter = new ChordPro\Formatter\MonospaceFormatter();
$html = $monospaceFormatter->format($song, [
    'notation' => $frenchNotation
]);

//           Fa♯m   Lam
// A typical German verse

UtfChordFormatter 提供了带有 ♭ 和 ♯ 符号的和弦，而不是ASCII字符，看起来很漂亮。

对HTML代码进行样式化

歌曲行

行由块组成。每个块由文本和和弦组成。和弦具有 chordpro-chord 类，而文本具有 chordpro-text 类。

一首典型的歌曲行如下所示

<div class="chordpro-line">
    <span class="chordpro-block">
        <span class="chordpro-chord" data-chord="C">C</span>
        <span class="chordpro-text">This is the </span>
    </span>
    <span class="chordpro-block" data-chord="Dm">
        <span class="chordpro-chord">Dm</span>
        <span class="chordpro-text">beautiful song</span>
    </span>
</div>

data-chord 属性存储了和弦的英文表示，无论输出符号如何。

歌曲部分

ChordPro格式允许您将歌曲组织成部分。以下歌曲片段

{start_of_verse Verse 1}
...
{end_of_verse}

{start_of_foobar}
...
{end_of_foobar}

将被转换为

<div class="chordpro-section-label chordpro-verse-label">Verse 1</div>
<div class="chordpro-section chordpro-verse">
    ...
</div>

<div class="chordpro-section chordpro-foobar">
    ...
</div>

您可以使用任何东西来替换 foobar。但是，以下快捷键是被支持的

• {soc} → {start_of_chorus}
• {eoc} → {end_of_chorus}
• {sov} → {start_of_verse}
• {eov} → {end_of_verse}
• {sob} → {start_of_bridge}
• {eob} → {end_of_bridge}
• {sot} → {start_of_tab}
• {eot} → {end_of_tab}
• {sog} → {start_of_grid}
• {eog} → {end_of_grid}

元数据

库读取 ChordPro 元数据，并按以下方式将其渲染为 HTML

{title: Let's Sing!}
{c: Very loud}
{key: C}

变为

<div class="chordpro-metadata chordpro-title">Let's Sing!</div>
<div class="chordpro-metadata chordpro-comment">Very loud</div>
<div class="chordpro-metadata chordpro-key">
    <span class="chordpro-metadata-name">Key: </span>
    <span class="chordpro-metadata-value">C</span>
</div>

元数据的名称没有限制，但是 ChordPro 格式定义了一些标准名称。以下快捷键被支持

• {t} → {title}
• {st} → {subtitle}
• {c} → {comment}
• {ci} → {comment_italic}
• {cb} → {comment_box}

ChordPro 6.x 的扩展

库提供了一些非标准功能，这些功能对于歌集制作者可能很有用。

行内和弦

如果您不知道如何将和弦分配给音节，或者这并不重要，您可以使用分配给歌词行的行内和弦

You don't know where the chords are? ~ [F] [C]
You don't have to know ~ [G] [G/F#]

和弦出现在行上方（在 HTML 格式化器中）或行右侧（在等宽格式化器中）。