• Call syntax
  diascope -- [-clean] [-dry] [-recycle <forward | backward>] [-n CPUs] <file.txt>

  Without any switches diascope reads the slideshow description file from file.txt and looks for remains from a previous run over the same description file. If it finds any, diascope attempts to recycle as many bits as possible to save rendering time. If it doesn't, diascope starts from scratch. Diascope builds a (long) shell script containing all necessary commands to generate the slideshow. When done building, diascope executes that shell script. Some of diascope's behaviour can be adjusted from the command line.
• Run modes
  In "clean mode" diascope will remove any remains from a previously run and start from scratch. In "dry mode" diascope will build the full shell script but will not run it. It will tell you, however, what it would do if called without the dry parameter.
• Recycling
  The recycle switch tells diascope wether it should go forward or backward through the previous and the modified slideshow description files when comparing. Under some circumstances one way may be more sensible than the other in terms of how much diascope will be able to recycle. The brain of the user is employed to take the decision based on the information diascope prints out. Use in dry mode first to see the impact and judge.
• Parallel rendering
  You can specify the number of CPUs diascope will assume to have available, otherwise it will try to detect the number itself. Diascope will then run, where possible and sensible, twice as many commands in parallel. That is, on a dual-core machine it will run four commands in parallel using the shell's feature of backgrounding jobs. Note that even before version 0.2-beta-5, diascope was effectively running jobs in parallel whenever the output of one command was piped to another one. The speed-up is, therefore, not tremendous.

To try out diascope download the resource package, choose your example and run

Diascope will tell you what it would do and put together a shell script with all the calls to convert, sox, ffmpeg etc but it will not actually run the script.

Next, if you are ready to go, run

This can take a while.

Next, you can modify the example file and re-run

to see what diascope would do. As of diascope 0.2 you can use the recycle switch to support the recycling algorithm. Then run

again to carry out the modifications. Diascope will try to recycle your bits from the previous run, discard what is no longer needed and only calculate what is new. Note that diascope will look for your previous run by the base name of the slideshow. If you change the base name diascope will start from scratch.

If, for some reason, you want to forcibly start over you can tell diascope so by calling

For your own slideshows modify one of the examples or get started with the template file.

1. Which settings improve rendering quality?
   For the final rendering use "set resize=resize" to minimize resize artifacts. For DVD (TV) ouput use "interlaced" to avoid jumpy pans.
2. Can I edit the slideshow description file while diascope is runnning?
   Diascope works on a temporary copy of your slideshow description file. While you are putting together the slideshow description file you can run diascope once in a while in the background to render what you have to that moment in time.
3. Can I go back and forth between low-quality and high-quality rendering?
   Just keep two headers in your description file. See the template file for an example.
4. How can I use quotes, brackets or line breaks in image titles?
   Quotes and brackets must be escaped (preceded by a backslash). A line break can be expressed as \n. For example,

   create 3 DeepSkyBlue-gray title=3 "{-/ \\\-}\n\nThat\'s [so] \"cool\"! \n\(diascope\)"

   can generate something like this:
5. How can I fade in or fade out a "Ken Burns" effect?
   Do the effect as normal. For a fade-in, precede the effect with a "create" action of your desired colour. For a fade-out, append a "create" action of your desired colour. Then use a cross-fade transition between the two.
6. My video file is distorted (wrong aspect ratio)!
   Not all combinations of width and height can be combined. For some that should work see the format settings description. Unless you chose pal or ntsc, or unless you provide an "aspect" specification, then by default diascope passes the option "aspect=1:1" to ffmpeg. This may be wrong. If your W/H ratio is really 4:3, then explicitely add "aspect=4:3" to the format statement (and equivalent for 16:9) .

1. Which colours can I specify?
   At the command line, type

   convert -list color | cut -d " " -f 1

   to get a list of colours that your ImageMagick installation knows about.
2. Which fonts can I specify?
   At the command line, for newer versions of ImageMagick type

   convert -list font | cut -d " " -f 1

   or, for older versions, type

   convert -list type | cut -d " " -f 1

   to get a list of fonts that your ImageMagick installation knows about.
   
   If some fonts are missing although you know that they are present on your system, follow this procedure: Download the perl script imagick_type_gen, make it executable and then do

   mkdir -p ~/.magick
   imagick_type_gen > ~/.magick/type.xml

   Now, ImageMagick should know about your fonts.

1. But I want a GUI !?
   Me too.
2. Sox versions
   diascope does not work with sox 14.0.0 but it does work with older sox versions or with 14.2.0
3. Debian or Ubuntu Linux
   If you get error messages that look like this

   awk: diascope: line 2808: syntax error at or near ,
   line 4160: function gensub never defined
   line 4160: function asort never defined
   

   then you are probably using a different awk interpreter on your computer. You must install GNU awk (gawk) for diascope to work.