Commits

Travis Shirk committed b47b068

Docs

  • Participants
  • Parent commits a6925bf
  • Branches stable

Comments (0)

Files changed (3)

File bin/cli_examples.sh

 eyeD3 --artist="Token Entry" --title="Entities" example.id3 -Q
 # [[[endsection]]]
 
-# [[[section ALB_YR_SET]]]
-eyeD3 -A "Jaybird" -Y 1987 example.id3 -Q
-eyeD3 -G "Hardcore" example.id3 -Q
+# [[[section ALB_YR_G_SET]]]
+eyeD3 -A "Jaybird" -Y 1987 -G "Hardcore" example.id3 -Q
 eyeD3 example.id3
 # [[[endsection]]]
 
-
-# [[[section CLEAR_SET]]]
-eyeD3 --genre="" example.id3
+# [[[section NONSTD_GENRE_SET]]]
+eyeD3 --genre="New York City Hardcore" example.id3 -Q
+eyeD3 example.id3
 # [[[endsection]]]
 
-# [[[section ALL]]]
+# [[[section CONVERT1]]]
+# Convert the current v2.4 frame to v2.3
+eyeD3 --to-v2.3 example.id3 -Q
+# Convert back
+eyeD3 --to-v2.4 example.id3 -Q
+# Convert to v1, this will lose all the more advanced data members ID3 v2 offers
+eyeD3 --to-v1.1 example.id3 -Q
+# [[[endsection]]]
+
+# [[[section DISPLAY_V1]]]
+eyeD3 -1 example.id3
+# [[[endsection]]]
+
+# [[[section SET_WITH_VERSIONS]]]
 # Set an artist value in the ID3 v1 tag
 eyeD3 -1 example.id3 -a id3v1
 # The file now has a v1 and v2 tag, change the v2 artist
 eyeD3 -2 example.id3 -a id3v2
-
 # Take all the values from v2.4 tag (the default) and set them in the v1 tag.
 eyeD3 -2 --to-v1.1 example.id3
 # Take all the values from v1 tag and convert to ID3 v2.3
 eyeD3 -1 --to-v2.3 example.id3
+# [[[endsection]]]
 
-# Remove all the tags
+# [[[section IMG_URL]]]
+eyeD3 --add-image http\\://example.com/cover.jpg:FRONT_COVER example.id3
+# [[[endsection]]]
+
+
+# [[[section REMOVE_ALL_TAGS]]]
 eyeD3 --remove-all example.id3
 # [[[endsection]]]

File docs/plugins/classic_plugin.rst

 Examples
 --------
 eyeD3 can do more than edit exiting tags, it can also create new tags from
-nothing. For these examples we'll use a dummy file.
+nothing. For these examples we'll make a dummy file to work with.
 
 .. {{{cog cli_example("bin/cli_examples.sh", "SETUP", lang="bash") }}}
 .. {{{end}}}
 .. {{{cog cli_example("bin/cli_examples.sh", "ART_TIT_SET", lang="bash") }}}
 .. {{{end}}}
 
-Many options have a shorter name that can be used to save typing. Let's add
-the album name (``-A``) and the year (``-Y``) it was released.
+Most options have a shorter name that can be used to save typing. Let's add
+the album name (``-A``), the genre (``-G``), and the year (``-Y``) the
+record was released.
 
-.. {{{cog cli_example("bin/cli_examples.sh", "ALB_YR_SET", lang="bash") }}}
+.. {{{cog cli_example("bin/cli_examples.sh", "ALB_YR_G_SET", lang="bash") }}}
 .. {{{end}}}
 
-.. {{{cog cli_example("bin/cli_examples.sh", "CLEAR_SET", lang="bash") }}}
+Notice how the genre displayed as "Hardcore (id 129)" in the above tag listing.
+This happens because the genre is a recognized value as defined by the ID3 v1
+standard. eyeD3 used to be very strict about genres, but no longer. You can
+store any value you'd like.
+
+TODO: reference genres plubin
+
+.. {{{cog cli_example("bin/cli_examples.sh", "NONSTD_GENRE_SET", lang="bash") }}}
 .. {{{end}}}
 
-.. {{{cog cli_example("bin/cli_examples.sh", "ALL", lang="bash") }}}
+By default writes ID3 v2.4 tags. This is the latest standard and supports
+UTF-8 which is a very nice thing. Some players are not caught up with the
+latest standards (iTunes, pfft) so it may be necessary to convert amongst the
+various versions. In some cases this can be a lossy operation if a certain
+data field is not supported, but eyeD3 does its best to convert when the
+data whenever possible.
+
+.. {{{cog cli_example("bin/cli_examples.sh", "CONVERT1", lang="bash") }}}
 .. {{{end}}}
+
+The last conversion above converted to v1.1, or so the output says. The 
+final listing shows that the tag is version 2.4. This is because tags can
+contain both versions at once and eyeD3 will always show/load v2 tags first.
+To select the version 1 tag use the ``-1`` option. Also note how the
+the non-standard genre was lost by the conversion, thankfully it is still
+in the v2 tag.
+
+.. {{{cog cli_example("bin/cli_examples.sh", "DISPLAY_V1", lang="bash") }}}
+.. {{{end}}}
+
+The ``-1`` and ``-2`` options also determine which tag will be edited, or even
+which tag will be converted when one of the conversion options is passed.
+
+.. {{{cog cli_example("bin/cli_examples.sh", "SET_WITH_VERSIONS", lang="bash") }}}
+.. {{{end}}}
+
+At this point the tag is all messed up with by these experiments, you can always
+remove the tags to start again.
+
+.. {{{cog cli_example("bin/cli_examples.sh", "REMOVE_ALL_TAGS", lang="bash") }}}
+.. {{{end}}}
+
+Complex Options
+---------------
+
+Some of the command line options contain multiple pieces of information in
+a single value. Take for example the ``--add-image`` option::
+  
+  --add-image IMG_PATH:TYPE[:DESCRIPTION]
+
+This option has 3 pieced of information where one (DESCRIPTION) is optional
+(denoted by the square brackets). Each invidual value is seprated by a ':' like
+so:
+
+.. code-block:: bash
+  
+  $ eyeD3 --add-image cover.png:FRONT_COVER
+
+This will load the image data from ``cover.png`` and store it in the tag with
+the type value for FRONT_COVER images. The list of valid image types are
+listed in the ``--help`` usage information which also states that the IMG_PATH
+value may be a URL so that the image data does not have to be stored in the
+the tag itself. Let's try that now.
+
+.. code-block:: bash
+  $ eyeD3 --add-image http://example.com/cover.jpg:FRONT_COVER
+  eyeD3: error: argument --add-image: invalid ImageArg value: 'http://example.com/cover.jpg:FRONT_COVER'
+
+The problem is the ':' character in the the URL, it confuses the format description of the option value. To solve this escape all delimeter characters in 
+option values with '\'. 
+
+.. {{{cog cli_example("bin/cli_examples.sh", "IMG_URL", lang="bash") }}}
+.. {{{end}}}
+
                 if not cmd.startswith('#'):
                     cmd_line = "$ %s\n" % cmd
                 else:
-                    cmd_line = cmd
+                    cmd_line = cmd + '\n'
 
-                cmd_line = '\n' + (' ' * 2) + cmd_line
+                cmd_line = (' ' * 2) + cmd_line
                 self.cog.gen.out(cmd_line)
                 output = sh(cmd, capture=True)
                 if output:
                     self.cog.gen.out("\n")
                 for ol in output.splitlines(True):
                     self.cog.gen.out(' ' * 2 + ol)
+                if output:
+                    self.cog.gen.out("\n")
 
 @task
 def cog(options):