@DataBase AmTAGID3.guide @Author Georges 'Melkor' Goncalves @Index Index @$VER: AmTAGID3.guide 1.5 (20.05.98) @Macro Ver "1.5" @Macro _Contents "................... @{FG Highlight}$1@{FG Text}" @Macro _Section "@{u}@{b} $1 @{ub}@{uu}" @Node Main "AmTAGID3 - AmigaGuide documentation" @{u}@{b} Table of contents @{uu}@{ub} @{FG Highlight}___________________________________________________@{FG Text} Welcome to the @{b}AmTAGID3@{ub} @{Ver} AmigaGuide, © 1998 by Georges 'Melkor' Goncalves @{FG Highlight}___________________________________________________@{FG Text} If you have installed `SearchGuide' by Gérard Cornu, you can @{" Search " System "Run >Nil: SearchGuide AmTAGID3.Guide"} for a word or sentence in this guide. @{" Introduction " Link Intro } @{_Contents "What does AmTAGID3 do?"} @{" Disclaimer " Link Disclaim} @{_Contents "What AmTAGID3 can not do."} @{" Author " Link Author } @{_Contents "Who should you write?"} @{" Requirements " Link Requirements } @{_Contents "How do I install AmTAGID3?"} @{" Usage " Link Usage } @{_Contents "How should I use AmTAGID3?"} @{" Future plans " Link FuturePlans } @{_Contents "What's coming next?"} @{" History " Link History } @{_Contents "Where the program has been!"} @{" Credits " Link Credits } @{_Contents "Who do I thank?"} @{" Glossary " Link Glossary } @{_Contents "What are you talking about?"} This guide will not appear correctly if you do not have AmigaGuide_DT V40+ @EndNode @Node Intro "AmTAGID3 / Introduction" @{_Section "AmTAGID3"} @{b}@{u}AmTAGID3@{uu}@{ub} is a useful program to edit the @{" TAG ID3 " link Glossary} part of a @{" MPEG Audio " link Glossary} file, with features as follows : @{b} · @{ub} Read the TAG ID3 info from any MPEG Audio file. @{b} · @{ub} @{" Write " Link Write} the TAG ID3 info to any MPEG Audio file. @{b} · @{ub} @{" Wipe " Link Wipe} the TAG ID3 info of any MPEG Audio file. @{b} · @{ub} @{" Displays " Link MP3Duration} the duration of the MPEG Audio file. See @{" Note " link MP3Duration}. @{b} · @{ub} @{" Show & edit " Link ADOSComment} the AmigaDOS comment of the MPEG Audio file. @{b} · @{ub} Press « Help » over the gadgets to get context sensitive online help. @{b}AmTAGID3@{ub} is Shell only but this was intended from the start :) This programs is @{B}NOT@{UB} FreeWare... It's @{B}@{U}EMailWare@{UB}@{UU} and/or @{B}@{U}PostCardWare@{UB}@{UU}. This means that if you like and use this program, you have the moral obligation to send an @{U}EMail@{UU} and/or a @{U}PostCard@{UU} (your country, city, etc...) to the @{" author " link author} :-) @EndNode @Node Disclaim "AmTAGID3 / Disclaimer: Blah, blah, blah..." @{_Section "Disclaimer"} There is no warranty for this program to the extent permitted by applicable law. Except where otherwise stated in writing the copyright holder and/or other parties provide the program "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary service, repair, or correction. In no event, unless required by applicable law or agreed to in writing, will any copyright holder, or any other party who may redistribute the program as permitted above, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the program (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages. It is @{b}NOT@{ub} to be distributed on magazine coverdisks or similar without the owner's explicit written consent. Contact @{" Georges 'Melkor' Goncalves " Link Author}, author. @EndNode @Node Author "AmTAGID3 / Author" @{_Section "Author"} @{B}AmTAGID3@{UB} was designed and programmed for the @{U}Amiga@{UU} by : Georges 'Melkor' Goncalves 22 rue Morand F-75011 Paris France EMail: melkor@lords.com @EndNode @Node Requirements "AmTAGID3 / Requirements" @{_Section "Requirements"} @{FG Highlight}@{B}AmTAGID3@{UB} requires :@{FG Text} Kickstart V39 (OS 3.x) or above. @{" Magic User Interface " Link MUI} V3.8 or above. @{" BetterString.mcc " link betterstring} V11.2 or above. @{FG Highlight}Install @{B}AmTAGID3@{UB} :@{FG Text} Anywhere in your path :) @{FG Highlight}MUI :@{FG Text} If you do not have @{U}MUI@{UU} you will have to download it from somewhere and install it. The latest version on Aminet is 3.8. @{U}MUI@{UU} is much too large to be included here. @EndNode @Node Usage "AmTAGID3 / Usage" @{_Section "Usage"} @{b}AmTAGID3@{ub} @{" The command line " Link CmdLineArgs} @{_Contents "Giving arguments via the Shell"} @{" The famous GUI " Link GUI} @{_Contents "Visual part of the iceberg."} @EndNode @Node CmdLineArgs "Command line arguments" @{_Section "Command line arguments"} Pretty simple. As @{B}@{U}AmTAGID3@{UB}@{UU} uses the @{U}ReadArgs@{UU} function from the @{U}dos.library@{UU}, the command line arguments are really easy to use and understand both for the user (you) and for the programmer (me) ;-) The template is as follows : MPEGFILE/A,NQR=NOQUITREQUEST/S @{FG Highlight}MPEGFILE/A@{FG Text} (ARGUMENT, mandatory entry) The name of the MPEG Audio file. You MUST enter a name, otherwise @{B}AmTAGID3@{UB} won't run. @{FG Highlight}NQR=NOQUITREQUEST/S@{FG Text} (SWITCH, optional) This option makes @{B}AmTAGID3@{UB} react differently when quitting. By default it asks you if you really want to quit. This requester avoid quitting the the program by accidentaly pressing ESC (which is the default hotkey to close @{U}MUI@{UU} windows). This option removes this safety requester in case it bores you :) NQR is short for NOQUITREQUEST. @{U}ReadArgs()@{UU} does its job so well that you can use the short or the long version of the option name. @{B}@{U}Note :@{UB}@{UU} Any error regarding the command line (ie: no filename supplied, non existing file, etc...) generates an error message which is displayed on the default output (most of the time, the shell console) @EndNode @Node GUI "The user interface" @{_Section "The user interface"} @{" Menus " link Menus } @{FG Highlight}------------------@{FG Text} MP3 file @{FG Highlight}-----------------@{FG Text} @{" Amiga forever.MP3 " link MP3File}@{" 3:10 " link MP3Duration} @{FG Highlight}------------------@{FG Text} TAG ID3 @{FG Highlight}------------------@{FG Text} Title @{"Amiga forever " link MP3Title} Artist @{"Paula " link MP3Artist} Album @{"Amiga is born " link MP3Album} Year @{" 1985 " link MP3Year} Genre @{" Other " link MP3GenreText}@{" P " link MP3GenrePopup} Comment @{"In memory of Jay Miner " link MP3Comment} @{FG Highlight}--------------@{FG Text} AmigaDOS comment @{FG Highlight}-------------@{FG Text} @{"[ 3:18 ] by Paula. Album « Amiga is born" link ADOSComment}@{" P " link PopupListView} @{FG Highlight}---------------------------------------------@{FG Text} @{" TAG ID3 successfully loaded... " link StatusText} @{FG Highlight}-----------------@{FG Text} Controls @{FG Highlight}------------------@{FG Text} @{" Okay " link Okay} @{" Write " link Write} @{" Wipe... " link Wipe} @{" Cancel " link Cancel} @{B}@{U}Note :@{UB}@{UU} Pressing @{i}ESC @{ui}(@{u}MUI@{uu} default key to close windows) or selecting the menu item « @{u}QUIT@{uu} » exits @{b}AmTAGID3@{ub} without warning you about writing the TAG ID3 in case you have modified some fields. The only warning you get is the "Are you sure to quit ?" in case you have not used the NQR=NOQUITREQUEST/S in the command line arguments. @{B}@{U}Note :@{UB}@{UU} Any error regarding the user interface (ie: couldn't write the TAGID3, couldn't read, wipe, etc...) generates an error message which is displayed on a @{U}MUI@{UU} requester. @EndNode @Node Menus "GUI / Menus" @{_Section "Menus"} @{BG Text} @{FG Highlight}Project@{BG Text} @{BG back}@{FG Text} @{b}+-----------------------+@{ub} @{b}|@{ub} About... @{b}|A|@{ub} ? @{b}|@{ub} @{_Contents "Shows the about window."} @{b}|@{ub} About MUI... @{b}|@{ub} @{_Contents "Calls the MUI about window."} @{b}| ~~~~~~~~~~~~~~~~~~~~~ |@{ub} @{b}|@{ub} MUI settings... @{b}|@{ub} @{_Contents "Calls the MUI prefs program."} @{b}| ~~~~~~~~~~~~~~~~~~~~~ |@{ub} @{b}|@{ub} Quit... @{b}|A|@{ub} Q @{b}|@{ub} @{_Contents "Quits AmTAGID3."} @{b}+-----------------------+@{ub} @EndNode @Node MP3File "GUI / MP3 file" @{_Section "MP3 file"} This text gadget only displays the MPEG Audio filename, without the path. @EndNode @Node MP3Duration "GUI / MP3 duration" @{_Section "MP3 duration"} This text gadget only displays the duration of the MPEG Audio file. @{B}@{U}Note :@{UB}@{UU} Not every MPEG Audio file is supported for the duration calculation. Quite all the MPEG 1 Layer III files are supported. MPEG 1 Layer I & II, MPEG II (all layers) are NOT supported (I have no docs, sorry :) I have 'stolen' the recognition data of MPEG Audio files from the @{" MPTool " link Credits} source (which also doesn't support every MPEG Audio formats). @EndNode @Node MP3Title "GUI / MP3 title" @{_Section "MP3 title"} This string gadget allows you to view/change the TAG ID3 title. @{B}@{U}Note :@{UB}@{UU} If you alter the contents of this gadget and press RETURN, then a requester will prompt you to write the TAG ID3 in case you press « @{U}Okay@{UU} » or « @{U}Cancel@{UU} ». @EndNode @Node MP3Artist "GUI / MP3 artist" @{_Section "MP3 artist"} This string gadget allows you to view/change the TAG ID3 artist. @{B}@{U}Note :@{UB}@{UU} If you alter the contents of this gadget and press RETURN, then a requester will prompt you to write the TAG ID3 in case you press « @{U}Okay@{UU} » or « @{U}Cancel@{UU} ». @EndNode @Node MP3Album "GUI / MP3 album" @{_Section "MP3 album"} This string gadget allows you to view/change the TAG ID3 album. @{B}@{U}Note :@{UB}@{UU} If you alter the contents of this gadget and press RETURN, then a requester will prompt you to write the TAG ID3 in case you press « @{U}Okay@{UU} » or « @{U}Cancel@{UU} ». @EndNode @Node MP3Comment "GUI / MP3 comment" @{_Section "MP3 comment"} This string gadget allows you to view/change the TAG ID3 comment. @{B}@{U}Note :@{UB}@{UU} If you alter the contents of this gadget and press RETURN, then a requester will prompt you to write the TAG ID3 in case you press « @{U}Okay@{UU} » or « @{U}Cancel@{UU} ». @EndNode @Node MP3Year "GUI / MP3 year" @{_Section "MP3 year"} This string gadget allows you to view/change the TAG ID3 year. @EndNode @Node MP3GenreText "GUI / MP3 genre text" @{_Section "MP3 genre text"} This text gadget allows you to view the TAG ID3 genre. @{B}@{U}Note :@{UB}@{UU} If you alter the contents of this gadget and press RETURN, then a requester will prompt you to write the TAG ID3 in case you press « @{U}Okay@{UU} » or « @{U}Cancel@{UU} ». @EndNode @Node MP3GenreList "GUI / MP3 genre list" @{_Section "MP3 genre list"} This list gadget allows you to view all the TAG ID3 possible genres. @{B}@{U}Note :@{UB}@{UU} If you alter the contents of this gadget and press RETURN, then a requester will prompt you to write the TAG ID3 in case you press « @{U}Okay@{UU} » or « @{U}Cancel@{UU} ». @EndNode @Node MP3GenrePopup "GUI / MP3 genre popup" @{_Section "MP3 genre popup"} This popup gadget allows you to display the list of TAG ID3 genres. @EndNode @Node ADOSComment "GUI / AmigaDOS comment" @{_Section "AmigaDOS comment"} This string gadget allows you to view/change the AmigaDOS comment. You can press the hotkey "Control + p" inside the string gadget, in order to display the @{" Popup ListView " link PopupListView}. @{B}@{U}Note :@{UB}@{UU} If you alter the contents of this gadget and press RETURN, then an AmigaDOS comment will be written to the file. A requester will popup in case of a problem. @EndNode @Node PopupListView "GUI / AmigaDOS comment Popup ListView" @{_Section "AmigaDOS comment Popup ListView"} This ListView allows you to insert some TAG ID3 fields in the AmigaDOS comment string gadget. The list only contains the available TAG ID3 fields. Press @{i}RETURN @{ui}to insert an item and @{i}ESC @{ui}to leave the list without changing the AmigaDOS comment string. @{B}@{U}Note :@{UB}@{UU} In order to SET the AmigaDOS comment to the MPEG Audio file, you'll have to press @{i}RETURN @{ui}in the AmigaDOS comment string gadget. This list only inserts a chosen TAG ID3 field in the string, nothing more. @EndNode @Node StatusText "GUI / Status text" @{_Section "Status text"} This text gadget allows you to view the status of the program. It'll be filled up when you'll perform actions such as reading, writing and wiping the TAG ID3. It'll warn you if @{b}AmTAGID3@{ub} isn't able to calculate the duration of the MPEG Audio file. @EndNode @Node Okay "GUI / Okay" @{_Section "Okay"} This button gadget simply quits AmTAGID3. @{b}@{u}Note :@{ub}@{uu} If you have altered the contents of @{u}Title@{uu}, @{u}Artist@{uu}, @{u}Album@{uu}, @{u}Genre@{uu} or @{u}Comment@{uu}, then a requester will ask you if you want to write the TAG ID3 before quitting. @EndNode @Node Write "GUI / Write" @{_Section "Write"} This button gadget writes TAG ID3 to the MPEG Audio file. @{B}@{U}Note :@{UB}@{UU} If any problem occurs, a requester will popup. @EndNode @Node Wipe "GUI / Wipe" @{_Section "Wipe"} This button gadget wipes the TAG ID3 out of the MPEG Audio file. A requester will ask you for confirmation first. @{B}@{U}Note :@{UB}@{UU} If any problem occurs, a requester will popup. @EndNode @Node Cancel "GUI / Cancel" @{_Section "Cancel"} This button gadget simply quits @{b}AmTAGID3@{ub} but generating an error code level of @{u}40@{uu}. This big level is bigger than RETURN_FAIL (which is 20) to ensure that the command will @{u}STOP@{uu} the current script (if any). This behaviour is very useful on scripts. ie: If you're using a filemanager (like DOpus or any other), select several files to process with @{b}AmTAGID3@{ub} and for some reason want to stop, then pressing « @{u}Cancel@{uu} » will STOP the script (or you have at the top of the script a @{u}FailAt@{uu} command with more than 40 as fail level !!!) @{b}@{u}Note :@{ub}@{uu} If you have altered the contents of @{u}Title@{uu}, @{u}Artist@{uu}, @{u}Album@{uu}, @{u}Genre@{uu} or @{u}Comment@{uu}, then a requester will ask you if you want to write the TAG ID3 before quitting. @EndNode @Node History "AmTAGID3 / History" @{_Section "History"} @{FG Highlight}Versions 1.0, 1.1, 1.2, 1.3@{FG Text} - Internal @{FG Highlight}Version 1.4@{FG Text} - First public release, waiting the flames :) @{FG Highlight}Version 1.5@{FG Text} - Fixed cosmetic bug with time display. "1:02" would be displayed "1:2" - Added more safety checks for MPEG Audio files. Should be a lot harder to fool now :) - Now using the @{" BetterString.mcc " link betterstring} from @{" Allan Odgaard " link credits}. - Added a @{" Popup ListView " link PopupListView} which contains some of the TAG ID3 fields to insert in the AmigaDOS Comment string gadgetstring gadget. - Fixed some cosmetic bugs on this guide :-P - Few internal minor changes/fixes. @EndNode @Node FuturePlans "AmTAGID3 / Future plans" @{_Section "Future plans"} AmTAGID3's future looks something like this: · Any idea from you as long as I can do it ;-) @EndNode @Node Credits "AmTAGID3 / Credits" @{_Section "Credits"} My sincere thanks go out to: @{b}·@{ub} @{u}Stefan Stuntz@{uu} for his @{b}MARVELLOUS@{ub}, @{b}WONDERFUL@{ub}, @{b}AMAZING@{ub} & @{b}STUNNING@{ub} @{" MUI " link MUI} @{b}·@{ub} @{u}David 'Lestat' Goncalves@{uu}, my brother for his moral support, help and movation @{b}·@{ub} @{u}Patrick Heinrich@{uu} for his @{b}MPTool@{ub} where I grabbed the list of genres and the recognition data to extract the bitrate of MPEG Audio files. @{b}·@{ub} @{u}Allan 'Duff' Odgaard@{uu} for his (updated :) @{" BetterString.mcc " link betterstring} & for the @{b}Daywatch@{ub} guide done by @{u}Rand Fredricksen@{uu} of which most the parts were stolen for this one :) @{b}·@{ub} @{u}Eric 'NamkraD' Kemp@{uu} for creating the TAG ID3 info. @{b}·@{ub} @{u}Fraunhoffer IIS@{uu} for creating and improving the MPEG Audio formats. Without these people, @{b}AmTAGID3@{ub} wouldn't exist or would be useless :-) @{b}·@{ub} My close friends for being who they are, very special guys :) @{u}Christopher 'Topher' Guez@{uu}, @{u}Pierre 'Tracker' Garel@{uu}, @{u}Sonny Beaumont@{uu}, @{u}Stephane 'Katov' Bunel@{uu}, @{u}Stephane 'Woodstock' Derisbourg@{uu} & the others. @{i}And last but not least, Amiga, the computer who gives you the biggest fun !@{ui} @EndNode @Node MUI "MUI - Magic User Interface" @{b}MUI - Magic User Interface@{ub} © 1993/98 by Stefan Stuntz MUI is a system to generate and maintain graphical user interfaces. With the aid of a preferences program, the user of an application has the ability to customize the outfit according to his personal taste. MUI is distributed as shareware. To obtain a complete package containing lots of examples and more information about registration please look for a file called "muiXXusr.lha" (XX means the latest version number) on your local bulletin boards or on public domain disks. If you want to register directly, feel free to send DM 30.- or US$ 20.- to Stefan Stuntz Eduard-Spranger-Straße 7 80935 München Germany @EndNode @Node BetterString "BetterString.mcc" @{b}BetterString.mcc@{ub} © 1998 by Allan Odgaard BetterString is a stringgadget replacement. It is created for @{" MUI " link MUI}, so using it should eliminate the problems with the original BOOPSI StringClass. The class offers the user to do number arithmetic, like increase, decrease and BIN<->HEX conversion. It has filename completion, ability to mark, cut, copy and paste text - Both via mouse and keyboard. The length of the contents buffer will dynamically be expanded to hold all of what the user type (unless a maximum length is given) Allan Odgaard Dagmarsgade 36 DK-2200 Copenhagen EMail : Duff@DIKU.DK http://www.DIKU.DK/students/duff/ @EndNode @Node Glossary "Glossary" @{_Section "TAG ID3"} The TAG ID3 is a number of fields with fixed size that you can find at the very end of the MPEG Audio files. These fields are useful to give info about the MPEG Audio file. They look like this : TAG Identifier : 3 bytes (must match "TAG") Title : 30 bytes Artist : 30 bytes Album : 30 bytes Year : 4 bytes Comment : 30 bytes Genre : 1 byte (from 0 - Blues, to 114 - Folklore and 255 is a special entry which means : Unset) This gives you a total of 128 bytes. @{_Section "MPEG Audio"} @{u}MPEG@{uu} stands for @{u}M@{uu}ovie @{u}P@{uu}icture @{u}E@{uu}xperts @{u}G@{uu}roup. The MPEG Audio is a special compression format which achives very high compression rates (from 10:1 to 12:1) while maintaining a very high audio quality. It is based on perceptual coding which is basically the action of removing the sounds you CAN'T hear in a music to just retain the useful information. MPEG Audio is found in various versions (MPEG 1, MPEG 2 and forthcoming MPEG 4) which each one is also divided in Layers (I, II and III). Of course, the more the layer is high, the more the calculations & compression are complex. The most used version and layer is the MPEG 1 Layer III (reduced to MP3 by common use) which offers almost CD quality music (44100Hz, 16bit, stereo) with a compression rate of 12:1 and a bitrate of 128kbits/s. For more info, check out big web sites like : http://www.mp3.com or http://www.layer3.org @EndNode