I've written before about the dubious value of functional specifications. If you want to experience the dubious value of specifications first hand, try writing a tool to read and write ID3 tags.
This is such a great point.
A similar situation arises with the TIFF specification for images. TIFF is extremely useful and well documented, and even has a great open-source reference library (libtiff) to illustrate implementation. But one still has to use Photoshop to verify compatibility and behavior 
The stupid thing is that your songs can only have one genre!
As of v2.4 this is no longer true. The frame for genre is like any other text frame and can have multiple values separated by NULs.
To be fair…:
frame sizes are stored as 4-byte “syncsafe
integers” where the 8th bit of every byte is
zeroed. Why would you store size in such an
annoying, unintuitive format? Who knows; the
spec doesn’t explain.
So the ID3 tag can be inside an MP3 stream, and the media player can detect it’s not part of the stream. I believe it does say so somewhere in the spec.
The vast majority of the things described in
the spec do not appear in any MP3 files that I
can find or create.
Well… true. Just implement those on an as-needed basis.
Check out the 147 possible values of the music
genre byte.
The music genre is an ID3v1 feature. ID3v2 replaces it by a genre string. Also, the list is so ridicilous because it has been made that way by Winamp (the original list from the ID3 spec was only 50 genres long or so). There you go with de facto standards…
Yes the spec is lacking in place but it’s not as bad as you make it out to be.
The music genre is an ID3v1 feature. ID3v2 replaces it by a genre string.
It’s not replaced, technically. The genre ID is embedded in the string within parens… ghettotastic!
The length of the original ID3v1 genre list is 79. It’s less crazy, but still includes “Christian Rap” and “Native US”. It’s in Appendix A here:
http://www.id3.org/id3v2.4.0-frames.txt
It’s really too bad that genre has become so fractured (either use a freeform string, or one of the 179 crazy-ass predefined genres), because categorizing music by genre is definitely useful. I could see myself listening to a mix of “classic rock”, “funk”, or “alternative” songs.
The stupid thing is that your songs can only have one genre!
Anyway… You make a good point. One thing I like about languages like PHP Perl, is that they basically only have one implementation, and however it behaves is implicitly all that matters no matter if there is a spec or not. Even C# counts here, although there is a spec and Mono has its own compiler, the MS implementation is the de facto standard. C++ has an amazing spec that no compiler actually implements completely, it’s painful!
If you really want to parse and write ID3 tags The Right Way, you might want to have a look at Mutagen, a FLOSS Python library that does the job (pretty well, and respecting the spec). It lives at a href="http://sacredchao.net/quodlibet/wiki/Development/Mutagen"http://sacredchao.net/quodlibet/wiki/Development/Mutagen/a
I recently had to implement some sort of ID3Tag reader, too. V1 is simple enough of course, but after browsing through the spec of V2 for a couple of hours I very quickly searched for some alternative - and found the Windows Media SDK.
You can use the WM SDK relatively simple with a few COM wrapper classes in .NET and you’re able to read and write not only ID3 Metadata but every other Metdata which is supported by WM, including of course wma/wmv.
MS even went so far and put a ready-to-use wrapper inside the WM SDK, you can find it in:
WMSDK\WMFSDK95\samples\managed\wrapper
WMSDK is supposed to be the installation folder of the SDK.
One (minor) drawback is that when writing ID3Tags the WM SDK simply writes both versions, V1 and V2 - you can’t choose.
Hello Jeff,
I couldn’t disagree more with your statement that the best functionnal spec is the behavior of a running application. I sounds tempting, but don’t let the idea fool you.
I have had this case on a previous project of mine: Migration and redesign of such an application from one technology to another. I can promise you, after a few years, without an up to date spec, NOBODY knows anymore what an application does or is supposed to do.
The truth is that in the real world not all development happens the way it should, and neither do all developers that worked on a system have the quality standard that they should. So over time many “features” (= special cases added quickly = mysterious if statements) creep in, and once the person who developed them leaves, so does the last bit of knowledge about them.
A good, kept up to date spec really saves the day. You have to get up to speed with this 100000 line program? Read the code. Eh no. A 200-page document providing a high-level overview of architecture, gui mockups and usecases is a million times more efficient.
Granted, for it to be effective, you have to keep it up to date. But when you have the displine to do so, it mores than pays off !
And let’s not even talk about the time you save designing a new app, when changing an entire subsystem just means rewriting a paragraph versus rewriting the code you banged out so quickly ( because code is the best spec of course hum hum)
Axel
I agree with Axel, although I wonder Linus is talking about enterprise apps vs … well dont know what to call it - hardware apps? Can you imagine writing a spec for Linux? That’s got to be insane compared to an Purchase Order or Banking app.
But I also agree with Linus as well when he says “I have never seen a spec that was both big enough to be useful and accurate.” This is the bane of specs and why people hate them - because writing them upfront and keeping them updated. It takes lots of discipline for an individual AND a company to maintain.
I build enterprise apps though, and I totally agree that specs are worth it in the long run
I think Linus’s statement is true for larger projects, like any nontrivial software product, where it is really difficult to nail down all the dimensions and keep them updated. But for something relatively small and simple like ID3, a clear and well-written spec. shouldn’t be too much to ask for.
If you think about it, whoever wrote the spec (whether that’s one, or more, people) has an idea of what ID3 is and how it should work. Their responsibility is to communicate that in the clearest way possible if ID3 is to become a well-implemented open standard everywhere. This means listening to programmers and helpfully adjusting to make things simpler. With several problems now identified in the spec, here’s hoping someone makes the necessary fixes.
Absolutely the best lib for tag reading is taglib. It’s open source, accurate and fast. Used by many linux players.
“…one of the possible picture types for the attached picture tag “APIC” is-- and I swear I’m not making this up-- “A bright coloured fish” ($11)…”
Oh! Oh! Mr. Kotter! Oh! I know this one!!!
It’s a Red Herring: http://en.wikipedia.org/wiki/Red_herring_(plot_device)
Indeed the ID3 spec sucks. I have thousands of MP3s, and I decided long ago that the Genre field is absolutely useless. Exactly how do I tag the “War of the Worlds” radio play? In version 1, the only appropriate genre value is null I guess; in version 2, the best value would be “speech”. The spec authors seem to assume that you would only ever make audio recordings of music and nothing else!
I realize my comment was sorta off-topic, but it’s been a pet peeve of mine that the spec has so many “genres” in it and most of them are useless to me.
I can promise you, after a few years, without an up to date spec, NOBODY knows anymore what an application does or is supposed to do.
A good, kept up to date spec really saves the day. You have to get up to speed with this 100000 line program? Read the code. Eh no. A 200-page document providing a high-level overview of architecture, gui mockups and usecases is a million times more efficient.
Ug. Yeah, these may be true, but if you’re doing something as low-level as converting an app from one language to another, you must look at the source code. There’s no other alternative. Only the code represents the true state of affairs. Everything else is merely an abstraction.
So MP3, Zip, AES, MD5, VST, TCP/IP, RAID, PostScript, ClearType, and Kerberos are all useless technical specs, right?
Judging from all the crappy, terrible, utterly hopeless implementations of these specs, yes.
I recently had the fortune to use SharpZipLib. The actual code to create and populate a zip file was easy. The amount of crap I had to do to accomodate such hapless programs such as WinZip was painful.
Where do “we” weigh in with specs like those maintained by W3C? The ECMAScript spec? PNG?
I think that the issues you raise with the ID3 spec are manifold. One is that the spec is indeed confusingly written. (I had the same reaction you did – “Am I just stupid, or what?” – although in my case that’s probably more of a contributing factor than in yours, haha.) Another is that the layout of ID3 tags themselves clearly is the result of an iterative process that has resulted in a, er, less than ideal design. And then as you note, spec or not, vendors have been implementing ID3 tagging with varying levels of thoroughness, which can at least theoretically discourage someone from fully implementing the spec – if (e.g.) iTunes won’t (or can’t) even use all the information in a completely correct ID3 tag, then what’s the point of dotting all the i’s and crossing all the t’s? (I bet you a nickel that if you talked to the people who implemented ID3 tagging at those vendors, they’d say they just bashed on because a) the spec was too confusing or difficult to implement and b) dang, they had to get a product out, like, now.)
I think Torvald’s comment is either taken out of context or should be discounted as the ruminations of a guy who works in a particular way on a particular set of problems. I doubt that even he would say “… and so we should never have specs for anything,” coz man, I doubt you’d get much traction with a development approach like that.
Specs serve other purposes besides simply being a reference document where someone can look up something up down the road. The specification process itself is a way of thinking through a problem and hopefully heading off at least some of the dead branches in a development process. A formal spec done by, say, W3C can be useful for incorporating the thoughts of a variety of people who might need to use the spec. (Clearly the genre portion of the ID3 spec did NOT enjoy the benefits of an open-comment period.)
The process of creating and maintaing a spec, as well as the mechanical process of writing it, are as subject to the usual distribution of talent as any other enterprise. Some people and institutions are really good at it; most are ok; some really suck.
And dang, no examples? Grade: F.
The layout of ID3 tags themselves clearly is the result of an iterative process that has resulted in a, er, less than ideal design.
Forgot to mention that it’s something of a truism in my job (writing) that if a design is difficult to document (i.e. describe), maybe, just maybe, it’s not such a good design. Not always; some problems are inherently hard. But for something like ID3 tags, c’mon.
I agree that specs generally end up missing the mark by a few hundred miles, but I often disagree on ‘why’ this is.
Why do specs fail? I think that most often, it’s because the spec writer is too focused on explaining ‘what’ something is, and not focused enough on ‘how’ general users can get their task completed. failing to include examples and use-scenarios are very telling symptoms of this failure.
If a non-english speaker asked me how to learn to speak english and I plopped a 3000 page websters dictionary on his lap, I’m probably not helping that much. But this is effectively what happens to developers when they are handed the w3c spec for SOAP and told to go develop a web-service, and It sounds like a similiar situation with the id3 spec.