# lrc-utils

Parse enhanced LRC files that provided by ESLyric and mainland SMS provider. Store those LRC in an internal format for later use.

## Usage

Use `Lrc.parse` method to parse LRC file. There are 2 formats of ESLyric's enhanced LRC files so you need to indicate the type of LRC before parsing.

**Legacy**: Use normal time tags. Defined by some karaoke subtitle maker in Japan.

Though output of [LyricTools](https://gitee.com/ying32/MakeLyric) is why we support `lrc-legacy`, using it for `lrc-legacy` files is not recommended: The timelines of the files through this way may not be accurate (in parsing QRC files).

```ts
import Lrc from 'lrc-utils';

const lrc = '[ar:幽闭星光 (幽閉サテライト)]\n[ti:幻想症候群 (with) Marcia]\n\n[00:00.00]幻[00:00.66]想[00:01.33]症[00:02.33]候[00:02.99]群[00:03.66]';

const lyric = Lrc.parse(lrc, 'lrc-legacy');
Lrc.log(lyric);
console.log(lyric.offset, lyric.meta, lyric.lines);
```

**Modern**: Use `<mm:ss.ff>` fragment tags, as Wikipedia defined, supported by ESLyric and many players.

```ts
import Lrc from 'lrc-utils';

const lrc = '[al:幻想症候群]\n[offset:0]\n[00:00.00]<00:00.00>幻<00:00.66>想<00:01.33>症<00:02.33>候<00:03.00>群<00:03.66> [<00:04.00> <00:04.33>Marcia - <00:04.66>幽<00:05.00>闭<00:05.33>星<00:05.66>光<00:06.00><00:06.33>幽<00:07.00>閉<00:07.66>サ<00:08.00>テ<00:08.33>ラ<00:08.66>イ<00:09.00>ト<00:09.33>)<00:09.66>\n[00:09.66]<00:09.66>词<00:10.00>：<00:10.33>Marcia<00:10.66>';

const lyric = Lrc.parse(lrc);
Lrc.log(lyric);
console.log(lyric.offset, lyric.meta, lyric.lines);
```

Normal LRC files that accurate to line can also use `Lrc.parse` without additional parameters.

In some LRC files, there may be multiple lines corresponding to a certain time-tag. This package considers those additional lines as comments. Some softwares use this syntax to store translation and subscripts. `Lrc.parse` will identify primary and secondary content by the order in which they appear in the LRC files.

Parsing of comments will not proceed in `lrc-legacy` mode.

### Edit and save

You can edit the meta info by APIs class `Lyric` provided. As for texts, only new rows can be appended currently, related APIs are coming soon...

```ts
const lyric = Lrc.parse('...[offset:0]...');
lyric.set('offset', '+500');
const new_lyric = lyric.pan();
console.log(new_lyric.offset);  /* 0, but all time tags has been aligned. */
```

After editing, you can use `Lyric.toLrc` to stringify the lyric.

```ts
const new_lrc = Lyric.toLrc('lrc');
```

This method has 3 parameters:

- `type`: which can set to `lrc`, `lrc-legacy` and `lrc-compressed`
  - `lrc` and `lrc-legacy` are same to above-mentioned, which will return enhanced or simple LRC.
  - `lrc-compressed` means same text lines will be merged to a single line with a plurality of tags just as the syntax specification dictates. If Lyric contains fixed information, it will be lost.
- `blank`: which is optional, indicates if keep blank-lines with only time tags in product.  
- `ref`: If a line contains comments, generate them in product. 

## Update Log

### 1.0.0

Published at 2022/9/11

Implemented almost all the features of LRC files in Wikipedia.

### 1.1.0

Published at 2022/9/25

Support at-marks of LRC files, which is defined in those Japanese karaoke subtitle maker.

API change: Export `TimeStamp` utils.

Fixed an issue where the end time-stamp of a line might accidentally be `0` during the conversion of Enhanced-LRC files.

### 1.2.0

Published at 2022/9/26

API change: `Lrc.parse` use `ParseOptions` as secondary parameter to specific parse mode. Old parse mode now is a member of options object.

Support kana string in `qrc` format. Use the kana string to assign furigana to kanji in lyrics. Furigana fields are add to `Lrc.Fragment` sup.

Fixed an issue where `Lyric.toLrc` convert nothing as return.

#### 1.2.1

Fixed: `Lyric.pan` now move furigana syllable together. Export `Lyric.align` as a new alias for `Lyric.pan`. 

#### 1.2.2

Fixed: `TimeStamp.toString` will round milisecond may cause an issue in carrying.

API change: Re-export `TimeStamp` as `Time` to avoid possible confusion due to naming conflicts.

#### 1.2.3

Fixed: Now parsing katakana in furigana string of qrc correctly.

#### 1.2.4

Fixed: Now kana string will match zenkaku letters and numbers in qrc lyrics.