NhacCuaTui Client

Unofficial API client for NhacCuaTui music streaming service. Built by reverse engineering the official API.

Installation

npm install nhaccuatui-client

Quick Start

import NhacCuaTuiClient from 'nhaccuatui-client';

const client = new NhacCuaTuiClient();

// Search songs
const results = await client.search('sóng gió');

// Get song detail
const song = await client.getSong('songKey');

// Get lyrics
const lyric = await client.getLyric('songKey');

// Get chart
const chart = await client.getChart('1-5-d360-2025');

✅ Đã hoạt động

• ✅ getChart(key) - Lấy bảng xếp hạng/Top songs
• ✅ search(keyword, correct) - Tìm kiếm bài hát
• ✅ searchPrefix(prefix) - Tìm kiếm gợi ý/autocomplete
• ✅ getSimilarSongs(songKey, limit) - Lấy bài hát tương tự

🚧 Chưa test/implement

• ⏳ getSong(key) - Lấy chi tiết bài hát (có code, chưa test)
• ⏳ getLyric(key) - Lấy lời bài hát (có code, chưa test)
• ⏳ getPlaylist(key) - Lấy playlist detail (có code, chưa test)
• ⏳ getHome() - Lấy dữ liệu trang chủ (cần tìm endpoint)

Cài đặt

cd /root/nhaccuatui-client
npm install

Sử dụng

Basic usage

import NhacCuaTuiClient from './src/index.js';

const client = new NhacCuaTuiClient();

// ✅ Lấy Top 50 Bài Hát Thịnh Hành
const chart = await client.getChart('1-5-d360-2025');
console.log(chart.name); // "Cập nhật 26/12/2025"
console.log(chart.items.length); // 50

// ✅ Tìm kiếm bài hát
const results = await client.search('sóng gió');
// results có thể là object với songs array hoặc array trực tiếp
const songs = Array.isArray(results) ? results : (results.songs || []);

// ✅ Tìm kiếm gợi ý
const suggestions = await client.searchPrefix('sóng');

// ✅ Lấy bài hát tương tự
const similar = await client.getSimilarSongs('songKey', 20);

// ✅ Lấy lời bài hát
const lyricData = await client.getLyric('songKey');
console.log(lyricData.content); // Lời bài hát
console.log(lyricData.timedLyric); // URL timed lyric (.lrc file)

// ✅ Lấy chi tiết bài hát
const songDetail = await client.getSong('songKey');
console.log(songDetail.name); // Tên bài hát
console.log(songDetail.artistName); // Nghệ sĩ
console.log(songDetail.streamURL); // Array stream URLs
console.log(songDetail.duration); // Thời lượng

// Mỗi song object có:
// - key: song key (dùng để get song detail)
// - name: tên bài hát
// - artistName: tên nghệ sĩ
// - duration: thời lượng (giây)
// - streamURL: array các stream URLs (128kbps, 320kbps, lossless)
// - image: thumbnail
// - ... và nhiều fields khác

Response Format

{
  id: 5,
  name: "Cập nhật 26/12/2025",
  title: "Top 50 Bài Hát Thịnh Hành",
  items: [
    {
      key: "jQjwLvlhKazj",
      name: "CHỜ ANH VỀ",
      artistName: "ANH TRAI \"SAY HI\", B Ray, AMEE",
      duration: 214,
      streamURL: [
        {
          type: "128",
          stream: "https://...",
          download: "https://...",
          onlyVIP: false
        },
        // ... 320kbps, lossless
      ],
      image: "https://image-cdn.nct.vn/...",
      // ... nhiều fields khác
    }
  ]
}

Test

# Test getChart (đã hoạt động ✅)
npm run test:chart

# Test search (đã hoạt động ✅)
npm run test:search

# Test song detail và lyric
npm run test:song

# Test tất cả
npm run test:all

🔍 Tìm thêm endpoints

Xem các file hướng dẫn:

• HOW-TO-FIND-SONG-DETAIL.md - Hướng dẫn chi tiết tìm Get Song Detail endpoint
• QUICK-GUIDE.md - Hướng dẫn nhanh
• TODO.md - Danh sách các endpoints cần tìm

API Endpoints (Đã tìm được)

• ✅ Chart: https://graph.nhaccuatui.com/api/v1/playlist/charts/{key}?key={key}&timestamp={timestamp}
• ✅ Search: https://graph.nhaccuatui.com/api/v3/search/all?keyword={keyword}&correct=false&timestamp={timestamp}
• ✅ Search Prefix: https://graph.nhaccuatui.com/api/v1/search/prefix-word?prefix={prefix}&timestamp={timestamp}
• ✅ Similar Songs: https://graph.nhaccuatui.com/api/v1/song/similar/{key}?key={key}&rn={limit}&timestamp={timestamp}
• ✅ Lyric: https://graph.nhaccuatui.com/api/v1/song/lyric/detail?songKey={songKey}&timestamp={timestamp}
• ✅ Song Detail: https://graph.nhaccuatui.com/api/v1/song/detail/{key}?key={key}&isDailyMix=false&timestamp={timestamp}

Các Chart Keys phổ biến

• 1-5-d360-2025 - Top 50 Bài Hát Thịnh Hành (tuần hiện tại)
• Tìm thêm các keys khác từ website để lấy các chart khác

Tìm thêm endpoints

Xem file reverse-engineer.md để biết cách tìm các endpoints khác (search, song detail, lyric, etc.)

Methods

• ✅ getChart(key) - Lấy bảng xếp hạng (đã hoạt động)
• ✅ search(keyword, correct) - Tìm kiếm bài hát (đã hoạt động)
• ✅ searchPrefix(prefix) - Tìm kiếm gợi ý (đã hoạt động)
• ✅ getSimilarSongs(songKey, limit) - Lấy bài hát tương tự (đã hoạt động)
• ✅ getLyric(songKey) - Lấy lời bài hát (đã hoạt động)
• ✅ getSong(songKey, isDailyMix) - Lấy chi tiết bài hát (đã hoạt động)
• ⏳ getPlaylist(playlistKey) - Lấy playlist detail (có code, chưa test)
• ⏳ getHome() - Lấy dữ liệu trang chủ (cần tìm endpoint)