maimai Music Metadata

English | 中文

maimai DX music metadata and cover images.

Usage

npm (ESM/CJS)

npm install maimai_music_metadata

import { loadFullMetadata, convertCompactedToNormal, compactMusicMetadata } from "maimai_music_metadata";

// Fetch the hosted compacted metadata and expand it to the normal shape with full typings
const metadata = await loadFullMetadata();

// Or convert a local compacted payload
const normal = convertCompactedToNormal(compactedPayload);

// Convert back to the compacted representation when you need to save bandwidth
const compacted = compactMusicMetadata(normal);

Browser <script> tag

Use the prebuilt IIFE bundle (global name MaimaiMetadata).

<script src="https://unpkg.com/maimai_music_metadata/dist/index.js"></script>
<script>
    (async () => {
        const metadata = await MaimaiMetadata.loadFullMetadata();
        console.log(metadata.musics.length);
    })();
</script>

Table of Contents

• File Types
  • meta.json / meta.unformatted.json
  • meta.compacted.json
• Cover Images
• Data Structure
  • Enums & Constants
  • Normal Format
    • Music
    • Chart
    • Version
  • Compacted Format
    • MusicCompacted
    • ChartCompacted
    • VersionCompacted

File Types

meta.json / meta.unformatted.json

URL: https://meta.salt.realtvop.top/meta.json https://meta.salt.realtvop.top/meta.unformatted.json

export interface MusicMetadata {
    musics: Music[];
    versions: Version[];
}

meta.compacted.json

URL: https://meta.salt.realtvop.top/meta.compacted.json

export interface MusicMetadataCompacted {
    musics: MusicCompacted[];
    versions: VersionCompacted[];
}

Cover Images

const getImageUrl = (id: string | number) => `http://meta.salt.realtvop.top/covers/00${id.toString().padStart(6, '0').substring(2)}.png`;

Data Structure

Enums & Constants

MusicDifficultyID

| Value | Difficulty | | :--- | :--- | | 0 | Basic | | 1 | Advanced | | 2 | Expert | | 3 | Master | | 4 | ReMaster | | 10 | Utage |

AvalibleRegion

| Value | Region | | :--- | :--- | | "jp" | Japan | | "intl" | International | | "cn" | China | | "us" | USA |

Categories

export const categories: string[] = [
    "POPS＆アニメ",
    "niconico＆ボーカロイド",
    "東方Project",
    "ゲーム＆バラエティ",
    "maimai",
    "オンゲキ＆CHUNITHM",
    "宴会場",
];

Normal Format

Corresponds to meta.json and meta.unformatted.json.

Music

interface Music {
    id: number;       // < 10000, same for sd and dx
    title: string;
    artist: string;
    bpm: number;

    aliases?: {
        cn: string[]; // Chinese aliases
    };

    category: string; // String from Categories
    isLocked: boolean; // Needs unlocking

    charts: Chart[];
}

Chart

interface Chart {
    type: "sd" | "dx" | "utage";
    difficulty: MusicDifficultyID;
    level: string; // Display level, e.g. "14+"
    internalLevel: number; // Internal level value
    version: string; // Version name
    regionVersionOverride?: Partial<Record<AvalibleRegion, string | number>>; // Region-specific version overrides when different from `version`

    noteDesigner: string;
    noteCounts: {
        tap: number;
        hold: number;
        slide: number;
        touch: number | null; // null for standard (sd) charts
        break: number;
        total: number;
    };

    avalibleRegions: AvalibleRegion[];
}

Version

interface Version {
    version: string; // Full version name
    word: string; // One-character abbreviation
    releaseDate: string; // YYYY-MM-DD
    cnVerOverride: number | null; // Year for Chinese version specific naming
}

Compacted Format

Corresponds to meta.compacted.json. Uses arrays to store data for smaller file size.

MusicCompacted

type MusicCompacted = [
    number, // 0. id
    string, // 1. title
    string, // 2. artist
    number, // 3. bpm

    number, // 4. categoryIndex (index in categories array)
    boolean, // 5. isLocked

    ChartCompacted[], // 6. charts
    string[] | null, // 7. aliasesCn
]

ChartCompacted

type ChartCompacted = [
    number, // 0. type: 0=sd, 1=dx, 2=utage
    MusicDifficultyID, // 1. difficulty
    string, // 2. levelString
    number, // 3. internalLevel
    number, // 4. versionIndex (index in versions array)
    [AvalibleRegion, string | number][] | null, // 5. regionVersionOverrides as [region, overrideVersion]

    string, // 6. noteDesigner
    [number, number, number | null, number, number], // 7. noteCounts: [tap, hold, slide, touch, break]

    AvalibleRegion[], // 8. avalibleRegions
]

VersionCompacted

type VersionCompacted = [
    string, // 0. version
    string, // 1. word
    string, // 2. releaseDate
    number | null, // 3. cnVerOverride
]