houou-logs

Tools to download Houou (Phoenix) logs from tenhou.net

Warning

Tenhou allows only one session to download logs at a time.
Running multiple instances (e.g., via multiple terminals or background processes) violates Tenhou's terms of use and may result in access restrictions or bans.

This tool is designed to operate with a single session only, in accordance with Tenhou's policy.
While it does not prevent concurrent execution at the system level,
do not attempt to run multiple sessions simultaneously.

References:

• https://tenhou.net/sc/raw/
• https://x.com/tsuno_s/status/1804487739657580636

Implementation concept diagram

Installation

# With pip.
houou-logs$ pip install .
# With uv.
houou-logs$ uv tool install .

Usage

Import log IDs from an archive (per year)

Import a list of log IDs into the database.

Note

Houou (Phoenix) games are available starting from 2009.

houou-logs import <db-path> <archive-path>

Example:

Import log IDs for the year 2009.

1. Download the archive file manually: https://tenhou.net/sc/raw/scraw2009.zip
2. Place the file in the current working directory.
3. Run:

houou-logs import db/2009.db scraw2009.zip

Fetch latest log IDs

Fetch a list of log IDs into the database.

This command skips log files that are already fetched and have the same size, and only adds new log IDs to the database.

Fetch log IDs from the latest 7 days (default mode)

Note

In this mode, if executed again within 20 minutes from the last run, the process will be cancelled because there are no updates.

houou-logs fetch <db-path>

Example:

houou-logs fetch db/latest.db

Fetch log IDs from January 1 of the current year until 7 days before the current day (archive mode)

houou-logs fetch <db-path> --archive

Example:

houou-logs fetch db/latest.db --archive

Fetch yakuman log IDs

Fetch log IDs where a yakuman occurred for a specific year and month.

Note

• Yakuman logs are available starting from October 2006.
• Only four-player game logs are available. Three-player games are not included.
• Yakuman logs include all tables (four-player only), not just the Houou (Phoenix) table.

houou-logs yakuman <db-path> <year> <month>

Example:

houou-logs yakuman db/yakuman/2007/01.db 2007 01

Download log contents

Download the log contents (mjlog) into the database using previously fetched log IDs.

This command skips logs that are already downloaded and stored, and only fetches log contents for undownloaded IDs that match the specified conditions.

houou-logs download <db-path> [--players <PLAYERS>] [--length <LENGTH>] [--limit <LIMIT>]

Options:

• -p, --players <PLAYERS>
  Number of players (4 or 3). If omitted, both are included.
• -l, --length <LENGTH>
  Game length: t for tonpu (East Only), h for hanchan (Two-Wind Match). If omitted, both are included.
• --limit <LIMIT>
  Max number of logs to download. If omitted, all available logs are downloaded.

Example:

houou-logs download db/2024.db --players 3 --length h --limit 50

Validate that downloaded logs can be parsed

Validate that all downloaded mjlog XML in the database can be parsed correctly.

In addition to validation, this command also serves as a practical example of how to parse mjlog XML at the tag level.

houou-logs validate <db-path>

Example:

houou-logs validate db/2024.db

Export raw log contents (xml) from DB

Export downloaded log contents (mjlog in XML format) from the database into files.

This command writes each log as an individual .xml file under the specified output directory. It skips logs that do not match the given conditions, and supports paging with --limit and --offset for batch processing.

houou-logs export <db-path> <output-dir> [--players <PLAYERS>] [--length <LENGTH>] [--limit <LIMIT>] [--offset <OFFSET>]

Options:

• -p, --players <PLAYERS>
  Number of players (4 or 3). If omitted, both are included.
• -l, --length <LENGTH>
  Game length: t for tonpu (East Only), h for hanchan (Two-Wind Match). If omitted, both are included.
• --limit <LIMIT>
  Max number of logs to download. If omitted, all available logs are downloaded.
• --offset <OFFSET>
  Number of logs to skip before starting export. Default is 0. Ignored if --limit is not specified.

Example:

houou-logs export db/2024.db xml/2024/4p/tonpu --players 4 --length t --limit 100 --offset 50

Acknowledgments

This project is heavily inspired by:

• phoenix-logs, created by Aleksei Lisikhin.

License

Copyright (c) Apricot S. All rights reserved.

Licensed under the MIT license.