Skip to content

README.md

Latest commit

 

History

History
230 lines (170 loc) · 6.63 KB

README.md

File metadata and controls

230 lines (170 loc) · 6.63 KB

🎵 Dream Lyric Parser (libdlp)

A modern C++ library for parsing common lyric file formats

License Language Platform Version Badge

✨ Features

  • 📄 Multi-format support: Parse LRC, SRT, ESLyric, ASS and more
  • ⚡ High performance: Optimized C++20 implementation
  • 🧩 Extensible architecture: Easy to add new parsers
  • 🏷️ Role assignment: Flexible lyric content role management
  • 📊 Word-level timing: Support for karaoke-style word-by-word lyrics

📋 Supported File Formats

Format Status Parser Modes Supported Role Assignment
LRC ✅ lexy Line & Word-by-word ✅
SRT ✅ lexy Line-only ✅
ESLyric ✅ lexy Line & Word-by-word ✅
ASS ✅ C++ Line & Word-by-word ❌
KRC ❌ - - -
YRC ❌ - - -
QRC ❌ - - -
LYS ❌ - - -
TTML ❌ - - -
VTT ❌ - - -

💡 Note: Missing sample files prevent development of certain formats. Contributions welcome!

🏗️ Architecture Overview

Core Components

  • FProcess: Main entry point for parsing operations
  • FLyricFile: Container for parsed lyrics and metadata
  • FLyricGroup: Groups lyrics by time periods
  • FLyricLine: Individual lyric lines with timing
  • FLyricWord: Word-level timing data
  • FLyricGroupRoleOption: Role assignment configuration
  • IParser: Abstract parser interface

Processing Flow

mermaid
graph TD
    A[User Input: Format + Lyrics + Roles] --> B[FProcess::Process]
    B --> C[Select Parser via GetParser]
    C --> D[Parse Input String]
    D --> E[Create FLyricGroups & Metadata]
    E --> F[Process Individual Lines]
    F --> G[Assign Roles via ApplyRole]
    G --> H[Return FLyricFile]

Data Structure


FLyricFile
├── FLyricMetadata (key-value pairs)
└── std::vector<FLyricGroup>
    └── FLyricGroup
        ├── Timestamps (start/end)
        ├── FLyricGroupRoleOption
        └── std::vector<FLyricLine>
            └── FLyricLine
                ├── Content & Timing
                ├── ELyricContentRole
                ├── word_by_word flag
                └── std::vector<FLyricWord>
                    └── FLyricWord
                        ├── Text content
                        └── Timestamps (start/end)

🚀 Quick Start

Installation

bash
# Clone the repository
git clone https://github.com/TypeDreamMoon/libdlp.git
cd libdlp

# Build using CMake
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

Basic Usage

cpp
#include <dlp/Process.hpp>
#include <dlp/File.hpp>

// Define content roles
std::vector<dlp::ELyricContentRole> roles{
    dlp::ELyricContentRole::Romanization,  // First priority
    dlp::ELyricContentRole::Lyric,         // Second priority  
    dlp::ELyricContentRole::Translation    // Third priority
};

// Create processor and parse
dlp::FProcess processor;
dlp::File::FLyricFile lyric_file = processor.Process(
    dlp::EFileFormat::LRC,           // File format
    "Lyric content string...",       // Input lyrics
    {roles, dlp::ELyricContentRole::Lyric}  // Role options
);

// Access parsed data
for (const auto& group : lyric_file.groups) {
    for (const auto& line : group.parsed_lines) {
        std::cout << "Role: " << static_cast<int>(line.role) 
                  << ", Content: " << line.lyric 
                  << ", Time: " << line.time_start.count() 
                  << std::endl;
    }
}

Advanced Usage - Word-by-Word Lyrics

cpp
// For karaoke-style lyrics with word-level timing
if (lyric_line.IsWordByWord()) {
    for (const auto& word : lyric_line.parsed_words) {
        std::cout << "Word: '" << word.word 
                  << "' starts at: " << word.time_start.count() 
                  << "ms, ends at: " << word.time_end.count() 
                  << "ms" << std::endl;
    }
}

🛠️ Building from Source

Prerequisites

  • C++20 compatible compiler (GCC 10+, Clang 10+, MSVC 19.28+)
  • CMake 3.16+
  • Git

Build Steps

bash
# Clone the repository
git clone https://github.com/TypeDreamMoon/libdlp.git
cd libdlp

# Configure and build
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

# Run tests (if available)
cd build && ./test_executable

🤝 Contributing

We welcome contributions! Here are some ways you can help:

Adding New Format Support

  1. Implement the IParser interface
  2. Register your parser in FProcess::GetParser
  3. Update the format table in this README

Providing Sample Files

Many formats are unimplemented due to lack of sample files. If you have sample lyric files for unsupported formats, please contribute them!

Code Improvements

  • Performance optimizations
  • Better error handling
  • Additional features

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter issues or have questions:

  • Check the Issues section
  • Open a new issue for bug reports or feature requests
  • Contribute samples for unsupported formats

ChangeLog

CHANGLOG

⭐ Star this repo if it helped you!

Dream Toolkit