slackbuilds_ponce/multimedia/AtomicParsley/Using_AtomicParsley.txt

Welcome to AtomicParsley
https://github.com/wez/atomicparsley
(converted from the RTF using Ted.  Contains long lines and tabs.)

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 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.

Currently, AtomicParsley lets you set these type of iTunes-style tags in MPEG-4 files:

artist			lyrics			category			TVEpisodeNum
title			album artist		artwork			TVSeasonNum
album 		composer		compilation			podcast flag
genre			copyright		advisory			podcast feed url
tracknumber		grouping		stik				podcast episode GUID url
disknumber		bpm/tempo		TVNetwork			purchase date
comment		description		TVShowName		encoder tool
year 			keyword		TVEpisode			play gapless

3GPP & 3GPP2 files (.3gp & .3g2) have a different set of metadata tags available called assets:

title			author			performer			genre
album	*		year			copyright			description
rating			keyword		classification			location

* album asset is only available on 3gp6 and later branded files.

All mpeg-4 based files support 'uuid' user-defined extensions atoms & ISO copyright notices:

tagtime		url 			information
ANY user-defined atom with text		ANY user-defined atom with embedded file
ISO-copyright [at movie and/or track level(s)]
______________________________________________________________________________________________
Working with AtomicParsley

The format for working with files is always the same:

/path/to/AtomicParsley /path/to/your.m4a [options]

Example to set a picture file into your mpeg4 file (jpeg or png only):
AtomicParsley /path/your.m4a --artwork /path/to/your.jpg

Exampe of setting multiple tags into your mpeg4 file:
AtomicParsley /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

Example of using the artwork preferences to limit the embedded artwork size & dimensions:
export PIC_OPTIONS="MaxDimensions=400:MaxKBytes=50:AllPixJPEG=true:SquareUp:removeTempPix"
AtomicParsley /path/your.m4a --artwork /path/to/your.jpg

Example to change your own mpeg4 file into an iTunes TV show:
AtomicParsley /path/your.mp4 --genre "TV Shows" --stik "TV Show" --TVNetwork FOOnn --TVShowName "Some Showname" --TVEpisode "1120" --TVEpisodeNum 20 --TVSeason 11

Example to change your own mpeg4 file into a Video Podcast (FrontRow requires the purl atom, iTunes doesn't):
AtomicParsley /path/your.mp4 --podcastFlag true --stik "Movie" --podcastURL "http://www.fictionalURL.com"

Example of extracting embedded artwork in your mpeg4 file to the same folder:
AtomicParsley /path/your.m4a --extractPix

To see the atom tree of your mpeg4 file:
AtomicParsley /path/your.m4a -T

To see the metadata tags set into your mpeg4 file:
AtomicParsley /path/your.m4a -t

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.
Note2: iTMS purchased media often has ©day 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.

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.

--------------
Erasing atoms with AtomicParsley

To delete metadata "":
AtomicParsley /path/your.m4a --artist "" --title ""

To delete all artwork (on the covr atom):
AtomicParsley /path/your.m4a --artwork REMOVE_ALL

To delete every piece of metadata (in the "moov.udta.meta.ilst" hierarchy); drm files will still play as normally:
AtomicParsley /path/your.m4a --metaEnema

--------------
Setting 3gp assets with AtomicParsley

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.

3gp assets have more options than iTunes tags - most are hardcoded with defaults. Defaults are as follows:

Default encoding: utf8 (utf16 also available)
Default language: 'eng' (about 480 other languages supported; none are currently checked)
Default Rating: entity = 'NONE' (4spaces); criteria = 'NONE' (4 spaces)
Default Classification:  entity = 'NONE' (4 spaces); index = 0
Default 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.)

Setting a title asset for the spanish language in utf16:
AtomicParsley /path/your.3g2 --3gp-title "The Rain In Spain..." lang=spa UTF16

Setting a album asset (with tracknumber) for the sve language in utf8:
AtomicParsley /path/your.3g2 --3gp-album "Bjorn Diddles His Banjo of Death" track=2 lang=sve

Setting a rating asset for the japanese language in utf16:
AtomicParsley /path/your.3g2 --3gp-rating "A superlative 4-on-the-floor house anthem." entity=MOMA criteria=PU18 lang=jpn UTF16

Setting a location asset for the english language in utf16:
AtomicParsley /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

Setting a keyword asset for the french language in utf8:
AtomicParsley /path/your.3gp --3gp-keyword "keywords=France,Paris,Basilique du Sacré-Cœur, Sewers, stinky cheeses" lang=fra

--------------
Setting copyright notices at movie and/or track level

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 — 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.

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.

Examples:
AtomicParsley /path/your.m4a --ISO-copyright "© 2006, Lalalandia Productions" movie UTF16
AtomicParsley /path/your.m4a --ISO-copyright "© 2006, Produções Da Estrada" track lang=por
AtomicParsley /path/your.m4a --ISO-copyright "©2006. USA" track=1 --ISO-copyright "©2006. Ελλάδα" track=2 lang=gre --ISO-copyright "©2006. ਬਣਾਉਟੀ" track=5 lang=pun --ISO-copyright "Callaloo Prductions, ©2006" movie lang=car

--------------
Custom uuid atoms with AtomicParsley

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).

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"

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

Create your own atoms directly:
AtomicParsley /path/your.m4a --meta-uuid "YZAB" text "Some string value to set"
AtomicParsley /path/your.m4a --meta-uuid "®USP" text "6125480"
AtomicParsley /path/your.m4a --meta-uuid "©212" text "CBGB OMFUG last set"
AtomicParsley /path/your.m4a --meta-uuid "docu" file ~/Desktop/taxes.zip
AtomicParsley /path/your.m4a --meta-uuid "inst" file /Files/archive.dmg description="Installer"

Deleting a custom uuid atom:
AtomicParsley /path/your.m4a --meta-uuid "©212" text ""
AtomicParsley /path/your.m4a --meta-uuid "docu" file ""

Set the tagging time (the moment the tag was written) on a uuid=tdtg atom:
AtomicParsley /path/your.m4a --tagtime

Set a url on a uuid=©url atom:
AtomicParsley /path/your.m4a --url "http://www.bumperdumper.com"

Manually removing uuid atoms:
AP /path/your.m4a --manualAtomRemove "moov.trak[1].uuid=55534d54-21d2-4fce-bb88-695cfac9c740"
AP /path/your.m4a --manualAtomRemove "moov.udta.meta.uuid=1fed6656-d911-5385-9cb2-cb2c100f06e7"

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:

non-AtomicParsley created uuid (from a Sony PSP file):
Atom uuid=55534d54-21d2-4fce-bb88-695cfac9c740 @ ...

uuid created by AtomicParsley:

Atom uuid=971451ee-0928-59f2-b81f-b1372b62565d(APuuid=ATOM) @ ...

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).

--------------
Compiling AtomicParsley

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.

cd AtomicParsley && ./build

Releases of AtomicParsley are also available built using:

• Debian 'Sarge' 31r0a-i386 with gcc/g++4.02, libc6_2.3.5-8 & libstdc++6_4.0.2-2
• Microsoft Windows XP SP2 with VisualC++ 6.0

--------------
AtomicParsley & new atoms, bugs, etc....

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.

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.

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.

--------------
Things to watch out for & avoid with AtomicParsley

• iTunes text tags (except for lyics) are restricted to 255 characters

• 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.

• 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.