🎵 Zhlyr — Audio Recognition & Synchronized Lyrics Engine

Zhlyr is a lightweight, asynchronous Python library designed for audio fingerprint recognition, song metadata extraction, and millisecond-accurate synchronized lyrics retrieval with SRT formatting support.

---

⚡ Installation

pip install zhlyr

---

🚀 Usage Guide

1. 🔍 Acoustic Track Recognition from Audio File

Identify any song from an audio snippet or file asynchronously:

import asyncio
from zhlyr import Recognize

async def main():
    audio_path = "sample.mp3"
    
    # Initialize recognition with file path or bytes
    reco = Recognize(audio_path)
    
    # Retrieve structured JSON metadata
    track_info = await reco.json()
    print("Identified Track:", track_info.get("track", {}).get("title"))

if __name__ == "__main__":
    asyncio.run(main())

---

2. 🎼 Fetch Synchronized Lyrics (with Millisecond Timestamps)

Fetch line-by-line synchronized lyrics for karaoke systems or media players:

from zhlyr import ZhLyr

# Fetch synchronized lyrics formatted with SRT timestamps
lyrics = ZhLyr.GetByTitle(title="Save Your Tears", srt=True)

for timestamp, line in lyrics.items():
    print(f"[{timestamp}] {line}")

Query with Track Details (High Precision):

lyrics = ZhLyr.GetByDetails(
    title="Save Your Tears",
    artist="The Weeknd",
    duration="3:35",
    srt=True
)

for timestamp, line in lyrics.items():
    print(f"[{timestamp}] {line}")

---

3. ℹ️ Data Serialization

Easily convert raw nested JSON responses into dynamic dot-accessible Python objects:

from zhlyr import Serializer

raw_data = {
    "track": {
        "title": "Blinding Lights",
        "artist": "The Weeknd"
    }
}

serialized = Serializer(raw_data)
print(serialized.track.title)  # Output: Blinding Lights

---

🛠️ Architecture & Features

• Asynchronous Execution: Built on modern Python asyncio for non-blocking I/O in high-throughput applications.
• SRT & Plain Text Formatting: Toggle between synchronized timestamps and plain lyrics with a single boolean flag (srt=True/False).
• Robust Error Handling: Automatic fallback and parameter normalization.

---

👨‍💻 Author

• Hussain Ibrahim Ahmed (Gaoc3)
  Systems & Backend Software Engineer
  GitHub • LinkedIn