Skip to main content

 

tja2fumen – TJA chart converter
tja2fumen is a tool that allows you to convert TJA charts (.tja) to fumen charts (.bin).

Test status (main branch) GitHub release (with filter) MIT License Linting pylint Linting flake8 Linting mypy


Features

tja2fumen is designed to be an open source alternative to the closed source tja2bin tool that has been floating around various Discord servers. tja2fumen fixes several outstanding tja2bin issues, while providing an open source codebase to modify and learn from.

  • Command line tool to convert .tja chart files to official fumen .bin files.
  • Decodes official fumen .bin files (to inspect metadata and note data).
  • Fix .bin files that were previously converted by tja2bin (WIP, see #65).
  • Uses strong development practices (thorough test suite with example charts, type checking).
  • Provides an open source resource for the Taiko no Tatsujin fumen file format.

Usage

TJA conversion

To convert a .tja file to .bin files, simply download tja2fumen.exe and run:

tja2fumen.exe "file.tja"

TJA + Audio conversion

tja2fumen.exe only converts TJA files. If you want to convert both TJAs and audio (.OGG or .WAV files) to .bin files, you can use the TakoTako plugin for the PC version of Taiko no Tatsujin. However, if you don't want to install and run Taiko no Tatsujin on PC, then you can use this simpler method instead:

  1. Download the latest release of TakoTako.
  2. Extract the TJAConvert.exe program into a separate folder.
  3. Download the newest version of tja2fumen.exe. Rename it tja2bin.exe, then place it in the same folder as TJAConvert.exe.
  4. Run the following command:
TJAConvert.exe "path_to_folder_containing_both_tja_and_audio/"

TJAConvert.exe will convert the audio to CRIWARE HCA packed into ACB container, and then it will call tja2fumen.exe to convert the chart files. (This is the exact same conversion you would get by running TakoTako as a BepInEx plugin -- you just have more control.) Note that the output audio is unencrypted, and that ACB audio files are incompatible with any NUS3BANK-based games.

Decoding fumen charts in Python scripts

If you want to explore the song structure of existing .bin files or .tja files using Python scripts, run:

pip install tja2fumen

Then, you can use tja2fumen's Python API as follows:

# parse song files
from tja2fumen.parsers import parse_fumen, parse_tja
fumen = parse_fumen("path/to/fumen_file.bin")
tja = parse_tja("path/to/tja_file.tja")

# convert tja data to fumen data
from tja2fumen.converters import convert_tja_to_fumen
fumen_converted = convert_tja_to_fumen(tja)

# modify the FumenCourse object
# - e.g.1: change the timing window header metadata
from tja2fumen.constants import TIMING_WINDOWS
fumen.header.b000_b431_timing_windows = TIMING_WINDOWS['Easy']*36
# - e.g.2: change the note offset values
for measure in fumen.measures:
    measure.offset_start += 1_000  # 1000ms == 1s
    measure.offset_end += 1_000

# write the modified fumen back to a .bin file
from tja2fumen.writers import write_fumen
write_fumen("path/to/file.bin", fumen)

Please refer to src/__init__.py for further example usage of the Python API.

TJA Support

If there is an unsupported feature that you would like support for, please make a request by opening a new issue.

Supported file formats

Legend: ✅ = Fully supported, ❌ = Not supported

tja 2 fumen tja 2 bin Comment
UTF-8 (with BOM) ✅ ❌  
UTF-8 (without BOM) ✅️ ✅  
Shift-JIS ✅ ✅  

Supported metadata

Legend: ✅ = Fully supported, ⚪️ = Ignored, ⚠️ = Incorrect behavior, ❌ = Not supported

tja 2 fumen tja 2 bin Comment
BPM:, OFFSET: ✅ ✅  
TITLE:, SUBTITLE:, WAVE:,
DEMOSTART:, etc.
⚪️ ⚪️ The only global metadata needed are BPM: and OFFSET:.  
COURSE:, LEVEL:, BALLOON:,
SCOREINIT:, SCOREDIFF:
✅ ✅  
STYLE: (Single, Double) ✅ ❌  
EXAM1:, GAUGEINCR:, TOTAL:, etc. ⚪️ ⚪️ Other simulator-specific metadata fields are currently ignored. 

Supported notes/commands

Legend: ✅ = Fully supported, ⚪️ = Ignored, ⚠️ = Incorrect behavior, ❌ = Not supported

tja 2 fumen tja 2 bin Comment
0, 1, 2, 3, 4 ✅ ⚠️ tja2fumen will write proper SENOTES (ド, コ, ドン, カ, カッ), see #41.
5008,, 6008,, 7008, ✅ ✅
9008, ✅ ⚠️
9000,
9008,
⚪️ ⚠️ Double Kusudama note treated as 1 drumroll by tja2fumen, but 2 overlapping drumrolls by tja2bin.
A, B ✅ ❌ Multiplayer "hands" notes are valid in fumens, but unrecognized by tja2bin.
C, D, E, F, G, H, I ⚠️ ❌ Replaced by normal notes/rolls in tja2fumen.
#SENOTECHANGE ✅ ❌ Recently added. See #69 and #81 for details.
#START, #END ✅ ✅
#START P1, #START P2 ✅ ❌
#BPMCHANGE ✅ ⚠️ See #16
#MEASURE ✅ ✅
#SCROLL ✅ ✅
#GOGOSTART, #GOGOEND ✅ ✅
#BARLINEOFF, #BARLINEON ✅ ✅
#DELAY ✅ ❌ See #27
#BRANCHSTART, #BRANCHEND ✅ ✅
#N, #E, #M ✅ ✅
#SECTION ⚠️ ❌ See #53, #27
#LEVELHOLD ✅ ❌
#BMSCROLL, #LYRIC,
#DIRECTION, etc.
⚪️ ❌ Other simulator-specific chart commands are currently ignored.

Reporting bugs

If you've found a .tja file that tja2fumen converts incorrectly, please open a new issue on the tja2fumen repo.

It is especially important that you attach the song files to the issue. You can do this by adding the song files to a .zip (Select files -> Right click -> "Send to" -> "Compressed (zipped) folder"), and then uploading the .zip to the issue. This greatly helps me to reproduce and fix any issues.

Building on top of tja2fumen

If you are a developer looking to add tja2fumen to your project, you have two options:

  1. For non-Python projects, you can download tja2fumen.exe and call it via a system call.
  2. For Python projects, you can install tja2fumen via pip install tja2fumen.

tja2fumen uses a very permissable license (MIT License). You are free to distribute and modify tja2fumen, but please include a copy of the MIT License alongside the tja2fumen.exe executable if you copy it into your project.

Attribution

  • The fumen-parsing code in this project is based off of a modified copy of the readFumen() function from the fumen2osu.py found in @KatieFrogs' fumen-tools project.
  • The TJA-parsing code in this project is a Python translation of the parseTJA.js file from @WHMHammer's tja-tools.
  • sakurada0291, DDDDDD, U-ros, and others in the Discord for helping to test tja2fumen. :)

Metadata

Release files for tja2fumen 0.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tja2fumen 0.9.0
File Size Uploaded Provenance Actions
tja2fumen-0.9.0.tar.gz 58.9 kB Without provenance Details for tja2fumen-0.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tja2fumen 0.9.0
File Interpreter ABI Platform Actions
tja2fumen-0.9.0-py3-none-any.whl Python 3 none any Details for tja2fumen-0.9.0-py3-none-any.whl

Total release size: 114.1 kB

Release files / tja2fumen-0.9.0.tar.gz

Download URL tja2fumen-0.9.0.tar.gz
Size 58.9 kB
Tags Source
SHA-256 checksum
How to use checksums
09889089f02ef55c1b69ba5eeb5f50bd54cd8b613e43ec6fe6c18defd99cc1b7
BLAKE2b-256 checksum
How to use checksums
fc810f8f5ddd68a2f33d63cb8fe2d99d85917b8dda4d6e2613fd3ba8881b0ab3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.1.1 CPython/3.8.10

Release files / tja2fumen-0.9.0-py3-none-any.whl

Download URL tja2fumen-0.9.0-py3-none-any.whl
Size 55.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6d7ab4fd5d75492d271a75fd9dbbcbb5e41408db67736bbf2ddb497f58e004f1
BLAKE2b-256 checksum
How to use checksums
596e1c96e8eb0b015f4c94654913b4c3325ecc18aab9b6534da6fd95ed492f9f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/5.1.1 CPython/3.8.10

Security for tja2fumen 0.9.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.9.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page