{"id":49,"date":"2010-12-08T21:43:16","date_gmt":"2010-12-08T20:43:16","guid":{"rendered":"http:\/\/www.idoru.be\/notes\/?p=49"},"modified":"2010-12-08T21:45:26","modified_gmt":"2010-12-08T20:45:26","slug":"atomic-parsley-manual","status":"publish","type":"post","link":"http:\/\/www.idoru.be\/notes\/atomic-parsley-manual\/","title":{"rendered":"Atomic Parsley Manual"},"content":{"rendered":"

See http:\/\/sourceforge.net\/projects\/atomicparsley<\/a><\/p>\n

AtomicParsley is distributed under the GPL “AS IS”, without any warranty; without even the implied warranty of merchantability or fitness for either an expressed or implied particular purpose.<\/p>\n

AtomicParsley is a command line program for reading & writing iTune-style metadata in mpeg4 files (m4a, m4b, m4p, m4v & mp4) whether iTMS drm protected or not. AtomicParsley can set most user accessible tags, and some that iTunes doesn’t let you change. Of particular note are the Mac OS X only image modification preferences that allow artwork to be modified prior to embedding. Artwork can be converted to jpeg, file size limited, reduced & squared through setting command line preferences.<\/p>\n

Currently, AtomicParsley lets you set these type of iTunes-style tags in MPEG-4 files:<\/p>\n

artist\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0lyrics\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0category\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0TVEpisodeNum
\ntitle\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0album artist\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0artwork\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0TVSeasonNum
\nalbum \u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0composer\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0compilation\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0podcast flag
\ngenre\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0copyright\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0advisory\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0podcast feed url
\ntracknumber\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0grouping\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0stik\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0podcast episode GUID url
\ndisknumber\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0bpm\/tempo\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0TVNetwork\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0purchase date
\ncomment\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0description\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0TVShowName\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0encoder tool
\nyear \u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0keyword\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0TVEpisode\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0play gapless<\/p>\n

3GPP & 3GPP2 files (.3gp & .3g2) have a different set of metadata tags available called assets:<\/p>\n

title\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0author\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0performer\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0genre
\nalbum\u00a0\u00a0 \u00a0*\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0year\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0copyright\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0description
\nrating\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0keyword\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0classification\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0location<\/p>\n

* album asset is only available on 3gp6 and later branded files.<\/p>\n

All mpeg-4 based files support ‘uuid’ user-defined extensions atoms & ISO copyright notices:<\/p>\n

tagtime\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0url \u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0information
\nANY user-defined atom with text\u00a0\u00a0 \u00a0\u00a0\u00a0 \u00a0ANY user-defined atom with embedded file
\nISO-copyright [at movie and\/or track level(s)]
\n______________________________________________________________________________________________
\nWorking with AtomicParsley<\/p>\n

The format for working with files is always the same:<\/p>\n

\/path\/to\/AtomicParsley \/path\/to\/your.m4a [options]<\/p>\n

Example to set a picture file into your mpeg4 file (jpeg or png only):
\nAtomicParsley \/path\/your.m4a –artwork \/path\/to\/your.jpg<\/p>\n

Exampe of setting multiple tags into your mpeg4 file:
\nAtomicParsley \/path\/your.m4a –artist “I am an Artist” –title “This is the Title” –album “The iAlbum” –genre “Progressive Zydeco” –tracknum 1\/2 –disknum 1\/2 –year 1985 –comment ‘Superlative (I made this TODAY!!!)’ –lyrics ‘Go, Go, GO! (repeat)’ –composer “I Claudius” –grouping “Ennui” –copyright “LowDown Recordings” –bpm 20 –compilation true –advisory clean –artwork \/path\/to\/your.jpg –artwork \/path\/to\/your2.jpg<\/p>\n

Example of using the artwork preferences to limit the embedded artwork size & dimensions:
\nexport PIC_OPTIONS=”MaxDimensions=400:MaxKBytes=50:AllPixJPEG=true:SquareUp:removeTempPix”
\nAtomicParsley \/path\/your.m4a –artwork \/path\/to\/your.jpg<\/p>\n

Example to change your own mpeg4 file into an iTunes TV show:
\nAtomicParsley \/path\/your.mp4 –genre “TV Shows” –stik “TV Show” –TVNetwork FOOnn –TVShowName “Some Showname” –TVEpisode “1120” –TVEpisodeNum 20 –TVSeason 11<\/p>\n

Example to change your own mpeg4 file into a Video Podcast (FrontRow requires the purl atom, iTunes doesn’t):
\nAtomicParsley \/path\/your.mp4 –podcastFlag true –stik “Movie” –podcastURL “http:\/\/www.fictionalURL.com”<\/p>\n

Example of extracting embedded artwork in your mpeg4 file to the same folder:
\nAtomicParsley \/path\/your.m4a –extractPix<\/p>\n

To see the atom tree of your mpeg4 file:
\nAtomicParsley \/path\/your.m4a -T<\/p>\n

To see the metadata tags set into your mpeg4 file:
\nAtomicParsley \/path\/your.m4a -t<\/p>\n

Note Mac users: iTunes looks at type\/creator when opening an mpeg4 file. As of AtomicParsley 0.8.1, you no longer need to change extensions to\/from anything – this is automatically determined through the information in the file itself and is set accordingly. A podcast mpeg-4 file may cause some concern at first because it shows up as being a protected file with a lock on the icon. This is nothing to be concerned about; iTunes uses the same icon\/file info for ‘M4B ‘ and ‘M4P ‘ types – that’s it. They aren’t drm’ed in any way, just a sharing of icon\/Finder info.
\nNote2: iTMS purchased media often has \u00a9day set to “2005-09-06T07:00:00Z” or something similar. This is normal and is called Coordinated Universal Time and is denoted by the Z at the end. iTunes only displays the year, but in fact there is an entire date that is there.<\/p>\n

Writing out is non-destructive – the original file is unaltered. There is a command-line option to over write the source file: use it with caution or on duplicates. Starting with version 0.9, AtomicParsley can used available padding to rapidly update tags. This option is only available with the –overWrite option.<\/p>\n

————–
\nErasing atoms with AtomicParsley<\/p>\n

To delete metadata “”:
\nAtomicParsley \/path\/your.m4a –artist “” –title “”<\/p>\n

To delete all artwork (on the covr atom):
\nAtomicParsley \/path\/your.m4a –artwork REMOVE_ALL<\/p>\n

To delete every piece of metadata (in the “moov.udta.meta.ilst” hierarchy); drm files will still play as normally:
\nAtomicParsley \/path\/your.m4a –metaEnema<\/p>\n

————–
\nSetting 3gp assets with AtomicParsley<\/p>\n

3gp metadata assets are more complicated than iTunes-style metadata. Assets can be in either utf8 or utf16, and are for a specific language. Multiple like-named tags differing in the language are supported allowing for up to around 480 tags per asset. See the AtomicParsley –3gp-help page for more. 3gp assets are only available on 3gp files – setting iTunes-style metadata is not allowed.<\/p>\n

3gp assets have more options than iTunes tags – most are hardcoded with defaults. Defaults are as follows:<\/p>\n

Default encoding: utf8 (utf16 also available)
\nDefault language: ‘eng’ (about 480 other languages supported; none are currently checked)
\nDefault Rating: entity = ‘NONE’ (4spaces); criteria = ‘NONE’ (4 spaces)
\nDefault Classification:\u00a0 entity = ‘NONE’ (4 spaces); index = 0
\nDefault Location: Longitude: = -73.98; Latitude = 40.77; Altitude = 4.3; Role = shooting location; Astronomical Body = Earth; Additional notes = ‘none’ [Central Park] – altitude is measured in meters; negative values are appended with a capital letter (S for southern latitudes, W for western longitudes, B for below sea level.)<\/p>\n

Setting a title asset for the spanish language in utf16:
\nAtomicParsley \/path\/your.3g2 –3gp-title “The Rain In Spain…” lang=spa UTF16<\/p>\n

Setting a album asset (with tracknumber) for the sve language in utf8:
\nAtomicParsley \/path\/your.3g2 –3gp-album “Bjorn Diddles His Banjo of Death” track=2 lang=sve<\/p>\n

Setting a rating asset for the japanese language in utf16:
\nAtomicParsley \/path\/your.3g2 –3gp-rating “A superlative 4-on-the-floor house anthem.” entity=MOMA criteria=PU18 lang=jpn UTF16<\/p>\n

Setting a location asset for the english language in utf16:
\nAtomicParsley \/path\/your.3g2 –3gp-location “Bethesda Terrace” latitude=40.77 longitude=73.98W altitude=4.3B role=”real” body=Earth notes=”Underground in Central Park” UTF16<\/p>\n

Setting a keyword asset for the french language in utf8:
\nAtomicParsley \/path\/your.3gp –3gp-keyword “keywords=France,Paris,Basilique du Sacr\u00e9-C\u0153ur, Sewers, stinky cheeses” lang=fra<\/p>\n

————–
\nSetting copyright notices at movie and\/or track level<\/p>\n

The only defined piece of metadata designed for descriptive annotations of the presentation\/track is the copyright notice. If your file contains 4 tracks, there are 5 places to set copyright notices, max \u2014 each of the tracks + movie level. There may be multiple notices, differing by language & may be present at any combination of movie and\/or track level in either utf8 or utf16. Defaults are lang=eng & utf8.<\/p>\n

Please note that at movie level, this notice is identical the the 3gp copyright asset, and if present for the same langauges this will overwrite the exising asset.<\/p>\n

Examples:
\nAtomicParsley \/path\/your.m4a –ISO-copyright “\u00a9 2006, Lalalandia Productions” movie UTF16
\nAtomicParsley \/path\/your.m4a –ISO-copyright “\u00a9 2006, Produ\u00e7\u00f5es Da Estrada” track lang=por
\nAtomicParsley \/path\/your.m4a –ISO-copyright “\u00a92006. USA” track=1 –ISO-copyright “\u00a92006. \u0395\u03bb\u03bb\u03ac\u03b4\u03b1” track=2 lang=gre –ISO-copyright “\u00a92006. \u0a2c\u0a23\u0a3e\u0a09\u0a1f\u0a40” track=5 lang=pun –ISO-copyright “Callaloo Prductions, \u00a92006” movie lang=car<\/p>\n

————–
\nCustom uuid atoms with AtomicParsley<\/p>\n

According the the specifications for the mpeg-4 file format, any atom not listed is reserved & is unavailable for use. However, the specification & the mpeg-4 registration authority www.mp4ra.org allow for user defined extension via a mechanism called the ‘uuid’ atom. This type of atom actually has a ‘uuid’ name, but following that is 16 bytes (the actual UUID representation itself).<\/p>\n

Because anyone or any program can implement UUID atoms, a special version of the UUID form is used – and when read back, special checks are in place to determine if any UUIDs found were created by AtomicParsley. In this way, UUIDs created by 3rd parties are ignored for reading, listings & extractions. This is all handled transparently via a simple mechanism: –meta-uuid ATOM text “Some Text”<\/p>\n

where ATOM can be any 4 letter atom name you choose – carrying any text information you choose. Support is also present for directly embedding a file via a similar mechanism: –meta-uuid ATOM file \/path\/to\/target\/file.ext<\/p>\n

Create your own atoms directly:
\nAtomicParsley \/path\/your.m4a –meta-uuid “YZAB” text “Some string value to set”
\nAtomicParsley \/path\/your.m4a –meta-uuid “\u00aeUSP” text “6125480”
\nAtomicParsley \/path\/your.m4a –meta-uuid “\u00a9212” text “CBGB OMFUG last set”
\nAtomicParsley \/path\/your.m4a –meta-uuid “docu” file ~\/Desktop\/taxes.zip
\nAtomicParsley \/path\/your.m4a –meta-uuid “inst” file \/Files\/archive.dmg description=”Installer”<\/p>\n

Deleting a custom uuid atom:
\nAtomicParsley \/path\/your.m4a –meta-uuid “\u00a9212” text “”
\nAtomicParsley \/path\/your.m4a –meta-uuid “docu” file “”<\/p>\n

Set the tagging time (the moment the tag was written) on a uuid=tdtg atom:
\nAtomicParsley \/path\/your.m4a –tagtime<\/p>\n

Set a url on a uuid=\u00a9url atom:
\nAtomicParsley \/path\/your.m4a –url “http:\/\/www.bumperdumper.com”<\/p>\n

Manually removing uuid atoms:
\nAP \/path\/your.m4a –manualAtomRemove “moov.trak[1].uuid=55534d54-21d2-4fce-bb88-695cfac9c740”
\nAP \/path\/your.m4a –manualAtomRemove “moov.udta.meta.uuid=1fed6656-d911-5385-9cb2-cb2c100f06e7”<\/p>\n

Note: any program can create a uuid atom – and are listed differently in an atom tree based on origin. Non-AP created atoms are listed slightly differently than AP-created uuid atoms:<\/p>\n

non-AtomicParsley created uuid (from a Sony PSP file):
\nAtom uuid=55534d54-21d2-4fce-bb88-695cfac9c740 @ …<\/p>\n

uuid created by AtomicParsley:<\/p>\n

Atom uuid=971451ee-0928-59f2-b81f-b1372b62565d(APuuid=ATOM) @ …<\/p>\n

Here you can see that after the hex-a-decimal representation of the uuid, AP has discovered an AtomicParsley-set uuid atom, and lists its name after APuuid).<\/p>\n

————–
\nCompiling AtomicParsley<\/p>\n

A fresh svn checkout will always be the most recent version available. AtomicParsley was developed on Mac OS X 10.4x, but should be able to compile on older versions. Only gcc4 was used to compile on Mac OS X.<\/p>\n

cd AtomicParsley && .\/build<\/p>\n

Releases of AtomicParsley are also available built using:<\/p>\n

\u2022 Debian ‘Sarge’ 31r0a-i386 with gcc\/g++4.02, libc6_2.3.5-8 & libstdc++6_4.0.2-2
\n\u2022 Microsoft Windows XP SP2 with VisualC++ 6.0<\/p>\n

————–
\nAtomicParsley & new atoms, bugs, etc….<\/p>\n

If you should come across an atom (in the moov.udta.meta.ilst hierarchy) that AtomicParsley doesn’t handle, please let me know about it – I would like to be able to support it. Note: AtomicParsley will never support iTunes-style “—-” atoms. To facilitate implementation, a sample of the new atom would be needed as it could come in a few different types – or even an entirely new type.<\/p>\n

Should you find a bug or a suspect behavior, please post to the bugs section or forum at sourceforge. A sample of the file that demonstrates the behavior would be best. Please also provide the name of the encoding program used to produce the file. Please refrain from using email as a primary means of support – it isn’t. Fun though it is to answer some questions repeatedly, imagine the fun a non-response would be.<\/p>\n

Please remember: as long as it works on Mac OS X – to me it works *perfectly* good enough. If you find a bug on another platform (probably Windows, because Linux will have most of the same encoders as on Mac OS X) or with any form of commercial encoder, a sample would probably go a long way to making AtomicParsley work on your files.<\/p>\n

————–
\nThings to watch out for & avoid with AtomicParsley<\/p>\n

\u2022 iTunes text tags (except for lyics) are restricted to 255 characters<\/p>\n

\u2022 Many of the iTMS (both drm and podcast) files have **ID atoms. What they stand for can only be guessed, but their values have meaning only to Apple – as such they are displayed in raw hex. Since all metadata can be stripped (including these **ID atoms), and a drm file still plays properly, these tags can be considered superfluous metadata.<\/p>\n

\u2022 iTunes 7 incorporates a feature called gapless playback. For unknown reason, iTunes incorporates NULL space at the end of mpeg4 files. This may (or may not) be part of the mechanism iTunes uses as part of its gapless playback. Normally, this NULL space is replicated when AP writes out. It is not if DEFAULT_PAD=0 is set.<\/p>\n","protected":false},"excerpt":{"rendered":"

See http:\/\/sourceforge.net\/projects\/atomicparsley AtomicParsley is distributed under the GPL “AS IS”, without any warranty; without even the implied warranty of merchantability or fitness for either an expressed or implied particular purpose. AtomicParsley is a command line program for reading & writing iTune-style metadata in mpeg4 files (m4a, m4b, m4p, m4v & mp4) whether iTMS drm protected […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4,6,5],"tags":[],"class_list":["post-49","post","type-post","status-publish","format-standard","hentry","category-macosx","category-manual","category-video"],"_links":{"self":[{"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/posts\/49","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/comments?post=49"}],"version-history":[{"count":2,"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/posts\/49\/revisions"}],"predecessor-version":[{"id":51,"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/posts\/49\/revisions\/51"}],"wp:attachment":[{"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/media?parent=49"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/categories?post=49"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.idoru.be\/notes\/wp-json\/wp\/v2\/tags?post=49"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}