• API
  • SongsDTA class
    • Class properties
    • Static methods
      • fromURL()
      • fromRecipes()
      • genNumericalSongID()
    • genRecipes()
    • getSongByID()
    • patchSongIDs()
    • patchEncodings()
    • update()
    • updateAll()
    • sort()
    • stringify()
  • SongUpdatesDTA class
    • Class properties
    • Static methods
      • fromURL()
    • getSongByID()
    • update()
    • sort()
    • stringify()
• More Rock Band related projects

API

The main exports of this package consists on two classes (SongsDTA() and SongUpdatesDTA()) that represents the contents of a .dta file to be processed. All secondary methods used on these classes is also available to import from dta-parser/core and dta-parser/lib.

SongsDTA class

SongsDTA is a class that represents the contents of a songs.dta file. It is initalized passing a path as an argument, this argument can be:

• A path to a songs.dta file (as string or an instantiated Path class).
• The contents of a DTA file (as string).
• A Buffer object of a DTA file.
• A parsed DTAFile object, or an array of parsed DTAFile objects.

import { SongsDTA } from 'dta-parser'

const dtaPath = 'path/to/songs.dta'
const songs = new SongsDTA(dtaPath)

console.log(songs.getSongByID('song_shortname')!.name) // <-- "Song title"

SongsDTA is more strict when parsing a song, expecting full information of a song and it will throw an Error if any song is found without all necessary values. By keeping full DTA information, the SongsDTA classes contains more methods to manipulate the songs rather than the SongUpdatesDTA class. With this class you can parse:

• Any custom song DTA generated by MAGMA when compiling a custom song.
• Any official RB3 and post-RB3 songs.

Class properties

• songs DTAFile[] An array with object that represents the contents of a DTA song entry.

Static methods

fromURL()

Asynchronously fetches a songs.dta file from an URL.

• Parameters:

  • url string The URL of the .dta file.

• Returns: Promise<SongsDTA> A new instantiated SongsDTA class.

import { SongsDTA } from 'dta-parser'

// This DTA file is found on "./assets/songs.dta"
const songsDTAURL = 'https://raw.githubusercontent.com/ruggeryiury/dta-parser/refs/heads/main/assets/songs.dta'
const songs = await SongsDTA.fromURL(songsDTAURL)

console.log(songs.getSongByID('7748motherearth')!.name) // <-- "Mother Earth"

fromRecipes()

Returns a new SongsDTA instance from complete songs' recipes.

• Parameters:

  • recipes DTAFileRecipe | DTAFileRecipe[] A DTAFileRecipe object, or an array of DTAFileRecipe objects.

• Returns: Promise<SongsDTA> A new instantiated SongsDTA class.

import { SongsDTA, type DTAFile } from 'dta-parser'

// A song recipe is very much like the DTAFile interface,
// but declaring human-readable values to keys
const songRecipe = {
  id: '7748motherearth',
  name: 'Mother Earth',
  artist: 'Keiichi Suzuki & Hirokazu Tanaka',
  master: true,
  song_id: 1774800033,
  songname: '7748motherearth',
  tracks: {
    drum: { rank: 0, channels: 2 },
    bass: { rank: 1, real_rank: 1, channels: 1 },
    guitar: { rank: 2, real_rank: 2, channels: 1, pans: [-0.2] },
    keys: { rank: 0, real_rank: 0, channels: 1, pans: [0.2] },
    backing: 2,
  },
  anim_tempo: 16,
  preview: 18668,
  song_length: 119477,
  rank_band: 0,
  rating: 1,
  genre: { genre: 'Pop/Dance/Electronic', sub_genre: 'Chiptune' },
  year_released: 1989,
  album: {
    hasArt: true,
    name: 'MOTHER (Original Soundtrack)',
    track_number: 1,
  },
  key: 'G',
  multitrack: true,
  author: 'Ruggy',
  pack_name: 'MOTHER Pack 01',
} satisfies DTAFile

const songs = SongsDTA.fromRecipes(songRecipe)

console.log(songs.getSongByID('7748motherearth')!.name) // <-- "Mother Earth"

genNumericalSongID()

Generates a numberic song ID based on any non-numeric string. If the given value is already a number, it will simply return the provided ID.

See the original C# function on GitHub Gist, coded by Emma (InvoxiPlayGames).

import { SongsDTA } from 'dta-parser'

const nonNumericalSongID = 'example'
console.log(SongsDTA.genNumbericalSongID(nonNumericalSongID))

genRecipes()

Creates an array of DTAFileRecipe objects from each songs entry of this class.

• Returns: DTAFileRecipe[]

getSongByID()

Returns a specific song contents based on its song ID (shortname). If no song if found, it will returns as undefined.

• Parameters:

  • id string The unique shortname ID of the song you want to fetch.

• Returns: DTAFile | undefined

import { SongsDTA } from 'dta-parser'

const dtaPath = 'path/to/songs.dta'
const songs = new SongsDTA(dtaPath)

// The following code line might return a DTAFile object
// or undefined if no song with provided unique song ID
// (shortname) is found.
console.log(songs.getSongByID('song_shortname'))

patchSongIDs()

Patches non-numerical song IDs to numerical ones, using specific CRC32 hashing method.

See the original C# function on GitHub Gist, coded by Emma (InvoxiPlayGames).

import { SongsDTA } from 'dta-parser'

const dtaPath = 'path/to/songs.dta'
const songs = new SongsDTA(dtaPath)

// All songs IDs will be patched to numerical IDs, if no
// numerical ID is found for the song.
songs.patchSongIDs()

patchEncodings()

Patches the encoding values of each song.

import { SongsDTA } from 'dta-parser'

const dtaPath = 'path/to/songs.dta'
const songs = new SongsDTA(dtaPath)

// All songs string values will be checked if any non-ASCII characters
// is found on any string value of the song. If non-ASCII characters
// is found, the song encoding will be set to UTF-8, simulating the
// behavior of single song packs and fixing the song's values to be
// displayed correctly, specially on Rock Band 3 Deluxe.
songs.patchEncodings()

update()

Updates a song contents based on its song ID (shortname).

• Parameters:

  • id string The unique shortname ID of the song you want to update.
  • update DTAUpdateOptionsForExtend An object with updates values to be applied on the DTAFile song entry.

import { SongsDTA } from 'dta-parser'

const dtaPath = 'path/to/songs.dta'
const songs = new SongsDTA(dtaPath)
console.log(songs.getSongByID('7748motherearth')!.name) // <-- "Mother Earth"
songs.update('7748motherearth', {
  // Change the name of the custom which the unique string ID
  // (shortname) is "7748motherearth".
  name: 'New Name',
})
console.log(songs.getSongByID('7748motherearth')!.name) // <-- "New Name"

updateAll()

Updates all songs with provided update values.

• Parameters:
  • update DTAUpdateOptionsForExtend update An object with updates values to be applied on each DTAFile song entry.

sort()

Sorts all songs entries using several sorting methods.

• Parameters:
  • sortBy SongSortingTypes The sorting method type.

import { SongsDTA } from 'dta-parser'

const dtaPath = 'path/to/songs.dta'
// The songs sorting will be inherit from the songs.dta file.
const songs = new SongsDTA(dtaPath)

// Now, the whole songs.dta will be sorted by song title.
songs.sort('Song Title')

stringify()

Stringifies all songs from this class to .dta file contents.

• Parameters:

  • options ? SongStringifyOptions An object with values that changes the behavior of the stringify process.

• Returns: string

import { SongsDTA } from 'dta-parser'

const dtaPath = 'path/to/songs.dta'
const songs = new SongsDTA(dtaPath)
console.log(songs.stringify({ type: 'rb3_dlc', guitarCores: true }))

SongUpdatesDTA class

SongUpdatesDTA is a class that represents the contents of a songs_updates.dta file. It is initalized passing a path as an argument, this argument can be:

• A path to a songs_updates.dta file (as string or an instantiated Path class).
• The contents of a DTA update file (as string).
• A Buffer object of a DTA update file.
• A DTAUpdateOptions object, or an array of DTAUpdateOptions objects.

SongUpdatesDTA parses incomplete DTA information. With this class you can parse:

• Pre-RB3 songs.
• Any songs_updates.dta file type.

Class properties

• updates PartialDTAFile[] An array with object that represents the contents of a DTA updates song entry.

Static methods

fromURL()

Asynchronously fetches a songs_updates.dta file from an URL.

• Parameters:

  • url string The URL of the .dta file.

• Returns: Promise<SongUpdatesDTA> A new instantiated SongUpdatesDTA class.

import { SongUpdatesDTA } from 'dta-parser'

// This DTA file is found on RB3DX repo.
const songsDTAURL = 'https://raw.githubusercontent.com/hmxmilohax/rock-band-3-deluxe/refs/heads/main/_ark/dx/song_updates/vanilla.dta'
const songs = await SongUpdatesDTA.fromURL(songsDTAURL)

console.log(songs.getSongByID('gimmethreesteps')!.album_name) // <-- "(pronounced 'leh-'nérd 'skin-'nérd)"

getSongByID()

Fetches a specific song updates contents based on its song ID (shortname). If no song if found, it will returns as undefined.

• Parameters:

  • id string The unique shortname ID of the song update you want to fetch.

• Returns: PartialDTAFile | undefined

import { SongUpdatesDTA } from 'dta-parser'

const dtaUpdPath = 'path/to/songs_updates.dta'
const updates = new SongUpdatesDTA(dtaUpdPath)

// The following code line might return a PartialDTAFile object
// or undefined if no song with provided unique song update ID
// (shortname) is found.
console.log(updates.getSongByID('song_shortname'))

update()

Updates a song updates contents based on its song ID (shortname).

• Parameters:

  • id string The unique shortname ID of the song you want to update.
  • update DTAUpdateOptionsForExtend An object with updates values to be applied on the PartialDTAFile song updates entry.

import { SongUpdatesDTA } from 'dta-parser'

const dtaUpdPath = 'path/to/songs_updates.dta'
const updates = new SongUpdatesDTA(dtaUpdPath)
console.log(updates.getSongByID('anysong')!.name) // <-- "Any Song Title"
updates.update('anysong', {
  // Change the name of the custom which the unique string ID
  // (shortname) is "anysong".
  name: 'New Name',
})
console.log(updates.getSongByID('anysong')!.name) // <-- "New Name"

sort()

Sorts all songs updates entries using several sorting methods.

• Parameters:
  • sortBy SongSortingTypes The sorting method type.

import { SongUpdatesDTA } from 'dta-parser'

const dtaUpdPath = 'path/to/songs_updates.dta'
// The updates sorting will be inherit from the songs.dta file.
const updates = new SongUpdatesDTA(dtaPath)

// Now, the whole songs.dta will be sorted by their unique string ID (shortname)
updates.sort('ID')

stringify()

Stringifies all songs updates from this class to .dta file contents.

• Parameters:

  • options ? SongUpdatesStringifyOptions An object with values that changes the behavior of the stringify process.

• Returns: string

import { SongUpdatesDTA } from 'dta-parser'

const dtaUpdPath = 'path/to/songs_updates.dta'
const updates = new SongUpdatesDTA(dtaUpdPath)
console.log(updates.stringify({ allSongsInline: true }))

More Rock Band related projects

• RBTools-JS: A highly typed module package to manipulate several Rock Band game files.
• My Customs Projects: All my customs projects.
• C3 Library Patch: A metadata patch for many released customs.
• PRO Guitar/Bass Guide: My famous PRO Guitar/Bass guide.