Checking CHAT files with phon-chat-check

phon-chat-check is a command installed in Phon's bin folder, inside the application's install directory. It reads CHAT (.cha) files and checks the four dependent tiers that Phon writes — %modsyl, %phosyl, %phoaln and %phoint — against the Phon tier specification published at github.com/speechmetrics/phon-chat-tiers. Each rule of the specification has a number; the command prints the number of every rule a file breaks. It reports and never repairs. The superseded tier names %xmodsyl, %xphosyl, %xphoaln and %xphoint are checked under the same rules.

The command checks the Phon tiers only. General CHAT validity — the main line, the headers, %mod and %pho — is checked by Chatter, the TalkBank validator, which Phon also bundles and runs when publishing a project.

Usage

phon-chat-check [--format text|json] [--] <file.cha>...
phon-chat-check --spec-version
phon-chat-check --help

The first form checks one or more files. With --format text (the default) the command prints one line per broken rule and nothing for a file that breaks no rule:

<file>:<line>: error[<rule>] <title>: <message>

For example, session.cha:42: error[3.4] Start before the previous end: %phoint start 50 is before the previous end 200. The rule number and title are those of the specification's rule index (its Appendix C), so a line can be read beside the specification. With --format json the command prints one JSON object per file holding the file name, its status (valid or invalid), the specification version, a link to that version's rule index and the list of violations; each violation carries the rule number, its title, its status (error or error, repairable), the line and the message. The second form prints the version of the specification the command implements, and the third prints this usage.

Exit status

  • 0 — no file breaks a rule.
  • 1 — at least one file breaks at least one rule.
  • 2 — a usage error, or a file that could not be read. The other files named on the command line are still checked.

From an MCP client

The same check is available to AI agents as the check_chat_tiers tool of Phon's MCP server. The tool takes a file parameter naming the CHAT file, absolute or relative to the directory the phon-mcp-stdio command was started in, and an optional format of text (the default) or json. The text report is one verdict line followed by the lines the command prints; the JSON report is the object the command prints. The tool needs no running Phon instance and no project, and a file that cannot be read is returned as an error.