README file for Taggit Metadata Editor (taggit) application.

Copyright 2016-2020 by The Software Samurai
on the web:  http://www.SoftwareSam.us/
Software released under GPL3+, and documentation released under FDL1.3+
=======================================================================

Unpack this archive using the following command:
              tar -xjvf taggit-x.x.xx.tar.bz2

  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
This package contains the Taggit Metadata Editor (taggit) source code and 
documentation. You will need to build the application binary for your target 
system (see below).

The 'taggit' application is implemented a console dialog and enables simultaneous 
editing of tag data for multiple audio files.

   1) Taggit is written from the ground up as a multilingual application and 
      currently supports English, Spanish, Chinese (simplified) and Vietnamese.
      Adding new user interface languages for both left-to-right (LTR) languages 
      and right-to-left (RTL) languages is straightforward and requires very 
      little programming skill.

   2) All id3v2.3 (MP3) "text frames" are supported.
      All OGG/Vorbis I "comment vectors" are supported.
      All ASF v:1.20.03 text descriptors are supported.

   3) Insertion and editing of MP3 embedded images are fully supported.
      Insertion and editing of OGG/Vorbis embedded images are implemented,
      but not yet fully tested. (see below)
      Insertion and editing of ASF (WMA) images are implemented.

   4) Taggit fully supports the MP3 "Popularimeter" and "Play Counter" frames.

   5) Taggit DOES NOT access online music databases.

   6) Taggit is written specifically as a teaching tool for students as well as 
      working professionals.
      a) The C++ source code includes EXTENSIVE internal documentation.
      b) The external documentation is both comprehensive and comprehensible.
      c) The only external library needed is the NcDialog API written by the 
         same author. (The NcDialog API is based on the ncursesw C-language 
         library which is included with nearly all GNU/Linux distributions.)
      d) Taggit is built using the GNU C++ compiler (C++11 support required).
         See below for build instructions.


  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -
The directory tree of files included in this Taggit release is organized as follows.

Taggit/                 // Source code directory
   Taggit.hpp           // Taggit class definition and general definitions
   Taggit.cpp           // Startup and Taggit-class instantiation methods
   TagConfig.cpp        // Configuration and file utility methods
   TagData.hpp          // Class definitions for audio and metadata containers
   TagDialog.hpp        // Definition of the application dialog and constant data
   TagDialog.cpp        // Instantiation of the main dialog and user interface loop
   TagMp3.hpp           // MP3 (id3.v2.3.0) data classes
   TagMp3.cpp           // Methods for decoding and encoding MP3 audio files
   TagOgg.hpp           // OGG/Vorbis I data classes
   TagOgg.cpp           // Methods for decoding and encoding OGG/Vorbis audio files
   TagAsf.hpp           // ASF class definitions including low-level processing methods
   TagAsf.cpp           // Methods for decoding and encoding ASF (WMA) audio files
   Taggit.cfg           // Configuration file (modify using any text editor)
   Makefile             // Build the Taggit application
   README               // Package description, release notes (this file)
   VERSION_HISTORY      // Change log

   /Texinfo             // Taggit documentation
      taggit.info          // Taggit documentation in 'info' format
      taggit.html          // Taggit documentation in HTML format
      infodoc-styles.css   // CSS style definition required by the HTML documentation
      Taggit.texi          // Taggit documentation source (Texinfo format)
      texi_macros.texi     // General macro definitions for creating Texinfo documents
      same_author.texi     // Boilerplate for Software Sam's published software
      gpl-3.0.texi         // GNU General Public License text (from FSF)
      fdl-1.3.texi         // GNU Free Documentation License text (from FSF)
      Makefile             // Build the info and HTML documents

Note that additional files comprising the NcDialog API are required for a 
successful build. (see below for details)
   NcDialog.a           // NcDialog API library
   GlobalDef.hpp        // General definitions for the NcDialog API
   NCurses.hpp          // Primitive interface to the 'ncursesw' C-language library
   NCursesKeyDef.hpp    // Constant keycode definitions
   NcWindow.hpp         // The parent class of all NcDialog windows and controls
   NcDialog.hpp         // The NcDialog class definition
   gString.hpp          // Class definition for text formatting and internationalization


To read the full Texinfo documentation for this package, type: 
                   info -f taggit.info
or even better, open the 'taggit.html' file in your favorite browser.


  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -  -

-- =========================================
-- NOTES on the current release of Taggit  =
-- =========================================

-- Build requires the GNU C++ compiler, version 4.8.0 or higher. Current
   development version is v:10.2.1.
   -- FULL C++11 SUPPORT IS REQUIRED for a successful build.
   -- See below for a summary description of building the Taggit application 
      from source.

-- Build and testing are done on both Fedora Linux and Ubuntu Linux on 32-bit 
   and 64-bit Wintel hardware. Both GNOME and Konsole terminals (Bash shell) 
   are used during testing. If your system is configured differently from these, 
   please post us a message about your experiences.

-- Current Release
   -- All documented functionality is fully implemented; however, see list of 
      outstanding issues, below.
   -- To date, the application's metadata formatting has been verified on only 
      a small number of media players, all of them GNU/Linux players. If you 
      are updating your music files for use on a phone, tablet or (gasp!!) the 
      evil OS from Redmond, Washington, please drop us a note about your 
      experiences.
   -- Programmers always believe that our work is totally bug-free, and we 
      are always wrong. Please report all bugs or suspected bugs via the 
      website.

-- See VERSION_HISTORY for details on updates made for this release.


   -- ============================
   -- Known bugs and other issues:
   -- ============================
   -- We are currently testing the MP3 Popularimeter and Playback Counter 
      with various media players. These may not be fully functional at this time.
   -- Media players have difficulty with images embedded in OGG/Vorbis files, 
      even the ones which claim to fully support the OGG format..
      The smarter players will complain about invalid formatting, but most 
      players will simply discard the comment header entirely and will set up 
      the audio output incorrectly causing playback errors.
      -- Our guess is that player which claim to support OGG embedded images 
         are actually supporting the obsolete, ad-hoc image format and not the 
         FLAC format specified by the OGG/Vorbis standard.

   -- Planned updates:
      -- All current user-interface language translations are complete EXCEPT:
         -- the tag-field help messages
         These translations require more language skill than we can claim, 
         but will be completed as soon as possible.
      -- Implement an additional user interface language. This will be one of 
         the RTL user interface languages (probably Hebrew or Yiddish).
         Verify that all RTL hooks are fully functional.
         -- Update the Help About dialog and sub-dialog to support RTL languages.
      -- Audio files which contain URL links to external images may lose those 
         URL links when edited metadata are written to the target file. 
         Retention of URL image links is under development. Insertion of _new_ 
         URL image links is not supported at this time. Although we believe that 
         linked image files is a poor design decision, we may support them in 
         a later release.


-- =====================================
-- Building the 'taggit' applications: =
-- =====================================
   This is just a quick reference.
   See the Taggit online documentation for full details.
   Open a terminal window and navigate to the documentation 
   directory.
            Example:  cd Taggit/Texinfo
   Then open the documentation file to the 'Building from Source' chapter.
            info -f taggit.info -n 'Building from Source'
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
   IMPORTANT: Before building Taggit, you must first download and build the 
   =========  NcDialog API library. The NcDialog directory should be installed 
              at the same directory level as the Taggit directory.
              Example: /home/sam/SoftwareDesign/NcDialog
                       /home/sam/SoftwareDesign/Taggit
              See the NcDialog API documentation for details.
   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   1) Open a terminal window.

   2) Navigate to the directory where you want to unpack the archive.
            Example: cd ~/sam/SoftwareDesign

   3) Copy the compressed archive to the target directory.
            Example: cp ~/Downloads/taggit-0.0.05.tar.bz2

   4) Unpack the archive:
      a) If your target directory already contains a 'Taggit' directory, 
         then rename it before unpacking the new archive.
            Example:  mv Taggit Taggit_OLD
      b) All contents of the compressed archive will be unpacked into a tree 
         whose base directory is 'Taggit'. 
      c) Unpack the archive.
            tar -xjvf taggit-0.0.05.tar.bz2

   5) Navigate to the directory which contains the source code.
            cd Taggit

   6) Copy the necessary components from the NcDialog library:
            gmake refreshlib
            (see above for a list of necessary NcDialog files)

   7) Build the 'taggit' application.
      a) Be sure that your compiler version is 4.8.0 or greater.
            g++ --version
      b) Build the application.
            gmake clean
            gmake
      c) The build should be clean with no errors and no warnings.
         If there are errors, then the most likely cause would be that the 
         compiler cannot find a necessary header file or library.
         Check your LIB_PATH and other environment variables.

   8) Once you have a clean build, invoke with a request for version number.
            ./taggit --version
      a) If the application successfully reports the version number and 
         copyright notice, then the application has been built correctly.
      b) If the application does not run, then verify that all necessary libraries 
         are installed on your system. Run the 'ldd' command to list the 
         necessary libraries. The needed libraries should look something like 
         the following. These are all standard libraries which should be 
         installed on your system by default.

         [Taggit]$ ldd taggit
            linux-vdso.so.1 =>  (0x00007fff1bdf9000)
            libncursesw.so.5 => /lib64/libncursesw.so.5 (0x0000003a1a400000)
            libtinfo.so.5 => /lib64/libtinfo.so.5 (0x0000003a2fc00000)
            libstdc++.so.6 => /lib64/libstdc++.so.6 (0x0000003a28000000)
            libm.so.6 => /lib64/libm.so.6 (0x0000003a1a000000)
            libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x0000003a1bc00000)
            libc.so.6 => /lib64/libc.so.6 (0x0000003a19000000)
            libdl.so.2 => /lib64/libdl.so.2 (0x0000003a19400000)
            /lib64/ld-linux-x86-64.so.2 (0x0000003a18c00000)

   9) Please see the Taggit documentation for notes on installation of the 
      binary executable file and the online documentation.

