uraniacast_treatment — What treatment scripts are all about.
Uraniacast’s treatment is a name given to a procedure that performs some operation over downloaded enclosures.
Say your player supports only mp3 format, but delivered podcast files are in iTunes audio (m4a). By providing a treatment for such podcast feed you can automatically convert downloaded m4a files into mp3.
Treatment is also an executable that takes 1 or more command line arguments.
For each feed you can add 1 treatment. If you need to perform a series of treatments (convert to mp3, then edit tags in resulted files) it’s your job to write a script that combines several different operations.
Uraniacast ships with 3 ready to use scripts:
uraniacast_t_convert.sh
uraniacast_t_mp3tag.sh
uraniacast_t_rename.sh
Those scripts are usual sh files symlinked to /usr/bin at the installation time.
Converts any possible combination of audio files that your ffmpeg installation supports.
Usage: uraniacast_t_convert.sh [-D] [-f format] -t format file
Example: uraniacast_t_convert.sh -f audio/mp4 -t mp3 %f
Argument for -f options is MIME type but for -t option is a file
extension. To discover exact MIME type, run "exiftool -T -mimetype
file".
In the example above, the script checks that %f is indeed m4a and performs a conversion to mp3. After successful operation it deletes the original file. To keep originals, use -D option.
Usage: uraniacast_t_mp3tag.sh file artist album song year comment
Example: uraniacast_t_mp3tag.sh %f %a %A %s %y %c
Useful when podcast provider uses for its enclosures ugly, unreadable names like accidentally encoded with percent-encoding.
Usage: uraniacast_t_rename.sh file desired_file_ext artist album song year
Example: uraniacast_t_rename.sh %f mp3 %a %A %s %y
The only requirement is that a script return 1 on error and 0 on success, otherwise uraniacast will not be able to properly count which file was treated nice.
Look into uraniacast_t_mp3tag.sh for an example. That script loads
helper.sh "library" with some useful functions.
prerequisites() function checks for all external required programs.
treatment_begin() puts small message that indicates user how file
is going to be treated.
treatment_log() return a file name for a log file. (It doesn’t
create a file.)
treatment_end() checks exit code of the last command, prints
ok/failed message & exits with proper exit code.
errx() & warnx() are handy functions for displaying an error or a
warning correspondingly. errx() aborts the subshell with exit code
1.
Before executing any treatment program, uraniacast exports 2 env variables to each child process:
URANIACAST_LOGS--that holds a directory name where log files can be
placed.
URANIACAST_FEED_CUR--current feed name (e.g. comp.foobar, not a
URI).
To test your scripts, run uraniacast with 2 -vv command line options—in that case it only prints (after all usual work) what program with what parameters will be executed.