1.\" Copyright (c) 2001 Yar Tikhiy <yar@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $Id: mp3ck.1,v 1.5 2005/04/03 11:44:37 yarq Exp $ 26.\" 27.Dd November 24, 2001 28.Dt MP3CK 1 29.Os 30.\" 31.Sh NAME 32.Nm mp3ck 33.Nd "MPEG stream consistency check" 34.\" 35.Sh SYNOPSIS 36.Nm 37.Op Fl dhpqsv 38.Ar 39.\" 40.Sh DESCRIPTION 41The MPEG Layer 3 (MP3) format is widely used to exchange 42digital audio data over local networks and the Internet. 43Unfortunately, data transfers may be aborted due to various 44events in the network or at the local machine. 45Further, restarting an aborted transfer may corrupt data 46because of bugs in the software. 47It is often hard to tell by eye or ear whether an 48MP3 file that came from a third party had suffered from such 49a problem in the past. 50.Pp 51The 52.Nm 53utility can check the consistency of an MPEG Layer 2 or 3 stream. 54The primary accent of the check is on the seamless flow of frames and tags 55since most MPEG defects introduced by aborted network transfers manifest 56theirselves in breakage of the flow. 57.Pp 58The following options are available: 59.Bl -tag -width ".Fl d" 60.It Fl d 61Ultimate verbosity. 62Besides all possible warnings and per-file information, 63messages will be printed for every frame 64or tag processed. 65.It Fl h 66Print a short help message and exit. 67.It Fl p 68Be pedantic about MPEG stream inconsistencies. 69See the list of detected inconsistencies for details. 70.It Fl q 71Decrease verbosity by one level. 72If specified once, warnings about trailing junk will be suppressed. 73If specified twice, it will currently be equivalent to the 74.Fl s 75option. 76.It Fl s 77Be silent completely. 78.It Fl t 79Try to print time offsets (MM:SS) instead of byte offsets 80in diagnostic messages. 81In a couple of messages, offsets may still be in bytes though. 82.It Fl v 83Increase verbosity by one level. 84If specified once, per-file information about MPEG parameters will 85be printed. 86If specified twice, it will currently be equivalent to the 87.Fl d 88option. 89.El 90.\" 91.Sh DIAGNOSTICS 92Exit status is 0 if no errors occurred and no MPEG 93stream inconsistencies were found. 94Exit status is 1 if MPEG stream inconsistencies were found. 95What is considered an inconsistency can be affected by the 96.Fl p 97option. 98Exit status is 2 if a file or system error occurred. 99.Pp 100The following MPEG stream inconsistencies are detected: 101.Bl -diag 102.It "empty file" 103A MPEG stream appeared to be of zero length. 104.It "no audio frames" 105A byte stream contained no valid MPEG frames. 106This error is likely to appear if 107.Nm 108was invoked on a non-MPEG file. 109.\" 110.It "leading junk" 111A MPEG stream did not begin with a valid frame or ID3 tag. 112In the case of a file, this is usually a sign of corruption, 113e.g., due to a poorly resumed transfer over a network when 114the beginning of the stream was lost. 115.\" 116.It "trailing junk" 117A MPEG stream was consistent (unless other warnings were issued), 118but some random bytes appeared after its last frame. 119This is mostly harmless and may be caused by an unaligned 120ID3v1 tag or some sort of application-specific data. 121No MPEG stream inconsistency will be reported in exit status 122unless the 123.Fl p 124option was specified. 125.\" 126.It "trailing junk (truncated ID3v%c tag?)" 127The same as above, but there were only one or two extra bytes 128that looked like the beginning of an ID3 tag. 129"I", "ID", "T", and "TA" are the possible values for the bytes. 130.\" 131.It "last frame incomplete" 132.It "unexpected EOF at frame header+n" 133.It "ID3v%c tag incomplete" 134These are the most common defects seen in MPEG files. 135They appear when an aborted transfer over a network remains unnoticed. 136However, a uniform or slightly varying number of bytes missing 137from the last frame over a series of files is usually 138just a sign of a quirk of the MPEG encoder/tagger used. 139.\" 140.It "sync after %ld bytes of junk" 141Normal flow of MPEG frames and ID3v2 tags was broken and then resumed 142after a portion of random bytes. 143Such a defect is likely to appear if a network transfer was resumed poorly. 144In particular, many Windows FTP clients tend to lose data when 145resuming an FTP upload because they fail to determine how many bytes 146have been delivered to the remote side successfully. 147On the other hand, such a warning appearing after an ID3v2 tag is often 148harmless and just indicates non-compliant padding of the tag. 149.\" 150.It "ID3v1 in the middle of the file" 151An ID3v1 tag should not appear in the middle of a MPEG stream. 152An obscure corruption of the stream is likely to have happened. 153.It "ID3v2.%d.%d unsupported" 154A MPEG stream contained an ID3v2 tag, but its major version was not 155recognized. 156Since the ID3v2 standard is still under development, its future 157versions may introduce features incompatible with former specifications. 158An unsupported ID3v2 tag is just skipped as junk bytes. 159.El 160.Pp 161Additionally, a number of invalid MPEG header field values 162are detected and reported accordingly. 163.\" 164.Sh BUGS 165The 166.Nm 167utility synchronizes to a stream at byte level despite MPEG streams 168being bit oriented. 169Byte level synchronization is sufficient for conventional MPEG audio files. 170.Pp 171The 172.Nm 173utility cannot check Layer 1 streams. 174.Pp 175ID3 tags are accepted in a Layer 2 stream. 176.Pp 177A CRC check of MPEG headers is not implemented yet. 178.Pp 179This manpage fails to distinguish files from streams. 180Can you? 181