A promise-based client for the Kojioka music API, designed for ease of use and modern asynchronous workflows. This package simplifies interaction with the API, handling task creation and status polling automatically.

Table of Contents

• Features
• Important: YouTube Cookies
• Installation
• Usage
  • Importing
  • Initialization
• API Methods
  • kojioka.getStream(query, options)
  • kojioka.search(query)
  • kojioka.getStatus()
• Complete Example
• Repository
• License

Features

• Promise-Based: Modern async/await friendly methods for all endpoints.
• Automatic Polling: The getStream method handles the entire task-based workflow automatically.
• Platform Selection: Choose to search on YouTube (default), SoundCloud, or Spotify.
• Progress Tracking: Use the onProgress callback to monitor download status in real-time.
• Configurable: Set custom polling intervals and timeouts.
• ESM and CJS Support: Works seamlessly in both CommonJS and ES Module environments.
• Automatic Update Notifications: Get notified in your console when a new version is available.

Important: YouTube Cookies

[!WARNING] To ensure the highest reliability, especially for YouTube downloads, the API needs a fresh youtube-cookies.txt file. You can help keep the public API functional by uploading a valid cookie file.

• Cookie Uploader Page: https://kojioka-api.shardweb.app/cookie-uploader

It is strongly recommended to use a secondary/test Google account for this purpose.

Installation

npm install kojioka

Usage

Importing

ES Modules (ESM):

import Kojioka from 'kojioka';

CommonJS (CJS):

const Kojioka = require('kojioka');

Initialization

Initialize the client, with optional custom settings.

const kojiokaClient = new Kojioka({
  pollingInterval: 3000, // Poll every 3 seconds
  timeout: 120000        // Wait a maximum of 2 minutes
});

API Methods

kojioka.getStream(query, options)

Creates a download task and returns a promise that resolves with the final stream information when the task is complete.

• query (string, required): A search term (e.g., song title) or a direct URL from YouTube, SoundCloud, or Spotify.
• options (object, optional): Configuration for the request.
  • platform (string): The platform to search on. Can be 'youtube' (default), 'soundcloud', or 'spotify'.
  • onProgress (function): A callback function that receives status updates during the download. The function is called with the full taskData object from the API.

Example:

async function getMusic() {
  try {
    const streamInfo = await kojiokaClient.getStream('SawanoHiroyuki[nZk]:XAI - JEOPARDY', {
      platform: 'youtube',
      onProgress: (progress) => {
        console.log(`Status: ${progress.status}, Progress: ${progress.progress}%`);
      }
    });
    console.log('Download Complete! Response:', streamInfo);
  } catch (error) {
    console.error('Error fetching stream:', error.message);
  }
}

getMusic();

Sample Success Response (resolved promise):

{
    "success": true,
    "data": {
        "id": "1ed8375e-a32c-46df-8759-0629302680f1",
        "type": "download_audio",
        "status": "completed",
        "progress": 100,
        "result": {
            "streamUrl": "https://kojioka-api.shardweb.app/songs/1ae13d20-8729-485f-a44d-b14796b3697a.mp3/d084f7dc5093ae43b252778d2dfb8575696cf0e2af30011d18b8af0851f9b0641001d4e756e264674bd1b09e65a5085f040d372846551b49e896c11cf966d72cd184c104d3f21ad40179ea6435643ece",
            "message": "[YOUTUBE] 'JEOPARDY' downloaded."
        },
        "error": null,
        "createdAt": "2025-09-27T01:48:22.641Z",
        "startedAt": "2025-09-27T01:48:22.642Z",
        "completedAt": "2025-09-27T01:48:43.045Z",
        "trackInfo": {
            "id": "OIxEL9Sqx-4",
            "title": "JEOPARDY",
            "artist": "澤野弘之 / SawanoHiroyuki[nZk]",
            "duration": "3:58",
            "url": "https://youtube.com/watch?v=OIxEL9Sqx-4",
            "albumName": null,
            "thumbnailUrl": "https://i.ytimg.com/vi/OIxEL9Sqx-4/hq720.jpg",
            "genres": null,
            "platform": "youtube"
        }
    }
}

kojioka.search(query, options)

Searches for a track and returns its metadata without downloading.

• query (string, required): A search term or a direct URL.
• options (object, optional): Configuration for the request.
  • platform (string): The platform to search on. Can be 'youtube' (default), 'soundcloud', or 'spotify'.

Example:

const metadata = await kojiokaClient.search('INERTIA - To Be Hero X - Sawano Hiroyuki', { platform: 'spotify' });
console.log(metadata);

Sample Response:

{
    "id": "2joT0CjcGqc1fr8Fvk7itj",
    "title": "INERTIA",
    "artist": "SawanoHiroyuki[nZk], Rei",
    "duration": "03:19",
    "url": "https://open.spotify.com/track/2joT0CjcGqc1fr8Fvk7itj",
    "albumName": "INERTIA",
    "releaseDate": "2025-04-06",
    "thumbnailUrl": "https://i.scdn.co/image/ab67616d0000b2735345d2453cfdd82b262c6bf6",
    "genres": [
        "anime",
        "j-pop",
        "j-rock"
    ],
    "platform": "spotify"
}

kojioka.getStatus()

Fetches the current status and operational metrics of the Kojioka API server.

Example:

const status = await kojiokaClient.getStatus();
console.log(status);

Sample Response:

{
  "serverStatus": "online",
  "uptime": "1h 23m 45s",
  "cpu": {
    "model": "AMD EPYC 7B13",
    "cores": 4,
    "usage": "25.8%",
    "loadAverage": [
      0.23,
      0.18,
      0.15
    ]
  },
  "memory": {
    "total": "1.94 GB",
    "used": "534.2 MB",
    "free": "1.42 GB"
  },
  "disk": {
    "total": "4.92 GB",
    "used": "1.46 GB",
    "free": "3.46 GB"
  },
  "songsStorage": {
    "count": 15,
    "size": "75.3 MB"
  },
  "cookieStatus": {
    "status": "Valid",
    "exists": true,
    "size": 2104,
    "valid": true,
    "reason": null,
    "lastUpload": "2025-09-27T00:15:00.000Z"
  },
  "recentDownloads": []
}

Complete Example

Here is a full example demonstrating the library's usage in an ESM project.

// example.mjs
import Kojioka from 'kojioka';

const kojiokaClient = new Kojioka({
  pollingInterval: 3000, // Poll every 3 seconds
  timeout: 120000        // Wait a maximum of 2 minutes
});

async function main() {
  try {
    console.log('Getting stream for \'Nier Automata Weight of the World\'...');
    
    const streamResult = await kojiokaClient.getStream('Nier Automata Weight of the World', {
      onProgress: (p) => {
        // Show a simple progress bar in the console
        const progressBar = '[' + '#'.repeat(p.progress / 5) + '.'.repeat(20 - p.progress / 5) + ']';
        process.stdout.write(`\rStatus: ${p.status.padEnd(12)} ${progressBar} ${p.progress}%`);
      }
    });

    process.stdout.write('\n'); // New line after progress bar
    console.log('\n✅ Stream Ready:', streamResult);

  } catch (error) {
    process.stdout.write('\n'); // New line after progress bar
    console.error('\n❌ An error occurred:', error.message);
  }
}

main();

To run this example, save it as example.mjs and execute it:

node example.mjs

Repository

• GitHub: https://github.com/shindozk/kojioka

License

MIT License.