#+TITLE: Genshiken 1
#+AUTHOR: Michael Pagan
#+DATE: 2016-12-24 Sat
#+STARTUP: showeverything
#+BEGIN_COMMENT
genshiken.1 - The manual for Genshiken
Copyright © 2015-2016 Michael Pagan
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, and with the Back-Cover Texts
as in (a) below. Please refer to the `COPYING.manual' file for full details
of the GNU Free Documentation License.
(a) Michael Pagan's Back-Cover Text is: "You have the freedom to copy and
modify this libre manual."
#+END_COMMENT
* NAME
genshiken - The free video downloader/streaming client, that can turn a website of video links into your personal playlist
* SYNOPSIS
#+COMMENT: The standard ways to invoke genshiken
*genshiken [DEBUG] Session=Anime-Type [Options]...*
#+COMMENT: Invoking genshiken with the Breaking Options
*genshiken [-V|--version] [-h|--help|--usage] [-R|--source-comments] [-E|--source-code] [--configure long-opt] [-C|--copyright] [-L|--license]*
*[-W|--warrantry] [-I|--status-report]*
#+COMMENT: Invoking genshiken with the Supplementary Options
*genshiken [[-v|--commands] [--verbose [* /seconds/ *]]] < [[-x|--get] [-y|--stream] [-i|--view]]* /{anime-sub,anime-dub,movie,ova,cartoon}/ *> [-a|--alert] [[-m|--impatient]*
/{0,1,2}/ *] [-f|--no-update] [--no-sessions] [-p|--no-pager] [--weak-signal|--no-bandwidth] [[--rgb|--colorize]* /{dark,light}/ *] [[-s|--start-at]* /number/ *]*
*[[-d|--base-dir]* /dir/ *]*
* DESCRIPTION
*Genshiken* gives the user the ability to _access online videos_ via a /bash(1)/ script. It is currently programmed to search for embedded video links, from third-party
websites, that contain episodes of an anime series the user may want to watch.
Most websites, however, usually require the user to install and use nonfree software--like "Flash"-- in order to load their videos. This code restricts the users freedom.
It's one thing for a program to behave unethically, but it's another thing for it to make /your/ programs behave that way too-- like your browser. Within the HTML tags of
your favorite website may be some nonfree code, and a browser that isn't programmed to know the difference will simply execute this code whether it's ethical or not. It's
in the very nature of proprietary software to ensure that: How it works remains a secret; and, how it's used remains restricted.
*Genshiken* is ethical and has no secrets or restrictions. It will allow you to load online videos-- without nonfree code. This behaviour is preffered on a fully-free
operating system. There's no need for a full fledged browser to accomplish all of this either. *Genshiken* works on the command-line, and uses low-level utilities
often found running on a terminal. If you are running a GNU/Linux operating system, chances are you already have all the software necessary to run *genshiken*.
* BASICS
** Main Options (A.K.A. The /Session/ Parameter)
*Genshiken* operates utilizing the below /Main Options/. A session file will be created once you are either: Downloading a video; streaming a video; or, playing a video.
Once you've finished and are prompted to continue or not, *genshiken* will consider your session to be complete and will remove the associated file. If you ever send
*genshiken* the interrupt signal-- via a /C-c/ entered on the keyboard-- whilst in the middle of a session, *genshiken* will save your current session so that you can return
to it later. Upon saving your session, *genshiken* will terminate with an exit code of 20 (/EARLY TERMINATION/).
There is no limit to how many session files you can maintain, and they will be updated automatically whenever a new anime has been detected from the website's /Anime-List/, or
whenever you download an anime. Only 1 restored session may be active at anytime. The creation of session files is a conveniance, not a requisite. The user may change this
default behaviour at anytime with the *--no-sessions* option.
Last thing-- if you were in the middle of a download when you terminated your get session, then you will be brought back to the exact episode and download position
when you restore that session. That means that if the progress bar from /wget(1)/ said it was at 61% when you terminated it, then you will start at 61% when you
continue. The same type of behaviour can be expected on other types of sessions.
+ *-x* /Anime-Type/, *--get* /Anime-Type/ ::
Download an anime series.
+ *-y* /Anime-Type/, *--stream* /Anime-Type/ ::
Watch an online anime series via your media player.
*NOTE:* video cache (if using /MPlayer(1)/, or derivitives) = 32,768 Kib-- video loads at 20% cache fill
+ *-i* /Anime-Type/, *--view* /Anime-Type/ ::
Play downloaded anime series via your media player.
** Main Option Arguments (A.K.A. The /Anime-Type/ Value)
The above /Main Options/ must be given 1 of 5 different arguments on the command-line. These are the /Main Option Arguments/. These values tell *genshiken* what kind of
/Anime-List/ to download and use to create it's menus, or which directory to go to that contains your downloaded anime.
+ /anime-sub/ English Subtitled Anime
+ /anime-dub/ English Dubbed Anime
+ /movie/ English Dubbed Anime Movies
+ /ova/ English Dubbed or Subbed OVA/Specials
+ /cartoon/ Regular Cartoon Shows
* BREAKING OPTIONS
As soon as any of the below options are found on the command-line, they are executed and are either: printed to standard output; or, piped to a pager. *Genshiken*
will then terminate upon completion, and all other options are ignored.
+ *-V, --version* ::
Print *genshiken*'s version number and legal information to standard output.
+ *-h, --help, --usage* ::
Print a basic usage summary to standard output.
+ *-R, --source-comments* ::
Send an outline of *genshiken*'s source code comments to /less(1)/; if on a dumb terminal, then it will be printed to standard output.
+ *-E, --source-code* ::
Send an outline of *genshiken*'s source code to /less(1)/; if on a dumb terminal, then it will be printed to standard output.
+ *--configure* /long-opt/ ::
Add a *genshiken* long option to a configuration file. That option will henceforth be considered to be a default argument for *genshiken*. The string /long-opt/ is
any supplementary long option that *genshiken* will normally accept; no need to worry about adding the argument that normally goes with the option, for *genshiken*
will prompt you after you've entered the command. You must specify the option without the double-dash ('--'). Use tab completion to view all possible choices (tab
completion is not supported on dumb terminals); as in: *genshiken --configure<TAB>*. Provide the *--configure* option the argument /remove/, to remove the configuration
file; a value of /remove-long-opt/, to remove a long option that exists within *genshiken*'s config file.
+ *-C, --copyright* ::
Print *genshiken*'s copyright information to standard output. I'm publishing this script under the /GNU General Public License/ (*GPL*); thus, making this program
/free software/.
+ *-L, --license* ::
Send the current version of the *GPL* to less. This option actually connects you directly to the *FSF*'s website, to their current copy of the *GPL*; whereupon, a
plain text version is dumped and piped to your pager. You may also type the following command for verification on this:
#+BEGIN_SRC bash
bash -x genshiken --license |& less
#+END_SRC
+ If reading a license is too much for you, please visit <http://www.fsf.org> for more information.
+ Also, for examples of what other /free software/ may look like, visit <http://directory.fsf.org/wiki/Main_Page>.
+ *-W, --warranty* ::
Print a short notice on the "warranty" to standard output.
+ *-I, --status-report* ::
Print a status report to standard output that shows you: How much anime you have; how much space is taken up by it; how much free space you have left on your
hard drive, etc.
* SUPPLEMENTARY OPTIONS
Supply any combination of the following *[Options]* along with the /Session/ parameter, to further tweak *Genshiken* to do your computing the way you want it to.
+ *-a, --alert* ::
Alert (*BEL*) on errors and download completions. This option requires your PC Speaker module to be loaded into the kernel, before it can work.
+ *-m* /{0,1,2}/, *--impatient* /{0,1,2}/ ::
Tired of waiting at *genshiken*'s prompts? Tell *genshiken* just how impatient you are to speed things up. When this option is not used: *genshiken* slows down
during key points of execution to allow you to read the text on your terminal, so that you can follow along. A level of *2*-- means you don't need to slow down to
read the text before a pager; *1*-- means you don't need to slow down at all during a *genshiken* process; and finally, *0*-- means you don't want a cache to be added
to a streaming video, for it may take too long to load. A restored session will set this to level *1*, if the *--impatient* option is not used.
+ *-f, --no-update* ::
Tell *genshiken* not to re-download your requested /Anime-List/; but instead, to run it's menu on *genshiken*'s last downloaded copy. This works as long as you
didn't interrupt *genshiken* while downloading the specified /Anime-List/. If you did interrupt *genshiken* during this process: Don't use this option, until you
have a complete copy of the specified /Anime-List/.
+ *--no-sessions* ::
If you don't want to save your place on exit into a session file, or if you don't want *genshiken* to prompt you to restore one of your last sessions: Issue this
option. If you want to automate *genshiken*-- /Here Document/ style: This option, plus the *--no-pager* and *--impatient* options make a great combo. *Genshiken*
already makes use of some these options to accomplish the same thing, via it's *\{Restore__Previous__Session\}* function.
+ *-p, --no-pager* ::
Provide this option if you want output, that would normally be sent to a pager, to be sent to standard output instead.
+ *--weak-signal, --limited-bandwidth* ::
Provide this option if you are streaming videos, and the network starts timing-out on you. Currently, this option only works with MPlayer and derivitives. /Wget/
is put in charge of managing network time-outs and reconnecting. This is possible due to MPlayer's network piping ability; thereby, allowing it to receive input from a
data stream. If you face a similar issue with a different media player, a different workaround must be made.
+ *--rgb* /{dark,light}/, *--colorize* /{dark,light}/ ::
The colors act as syntax highlighting, and can be used to better understand *genshiken*'s output. Each color has its own meaning: /Yellow/-- comments or external
input/output; /Red/-- function names; /Green/-- constant strings; /Magenta/-- variable strings or keystrokes to enter; /Cyan/-- Paths/URLs; /Blue/-- The name of this
script or the name of the anime network *genshiken* is using. Providing /light/ as an argument gives you bright bold colors; whereas, providing /dark/ as an argument
gives you dark subtle colors.
+ *-v, --commands* ::
MUST BE USED AS ARGUMENT 1; a *[DEBUG]* option. Output *genshiken*'s command expansions to standard output and *HOME/.config/genshiken-USER/debug.log*.
+ *--verbose=[* /seconds/ *]* ::
MUST BE USED AS ARGUMENT 1; a *[DEBUG]* option. Behaves the same as the *--commands* option, except the output is more verbose. Before each command expansion is a debug
prompt. The prompt appears as such: *(\{genshiken__file:LINE__#\}): \{FUNCTION__NAME\} - [SHELL LEVEL, SUBSHELL #, ERROR CODE]*. The more parentheses you see touching
the left side of the monitor, the deeper you are into a subshell command list. The prompt may be delayed a certain amount of seconds before each command expansion, via
the optional argument /seconds/ which represents a positive value (decimals may also be used). I've added a nice hack to control this behaviour during runtime via a file
called *HOME/.config/sleep.log*. See *FILES* for how to use it.
+ *-s* /number/, *--start-at* /number/ ::
That's right! You don't have to start at *#1*. Tell *genshiken* which video or image number you want to begin with. You may even specify the string '/latest/' as
an argument, in order to view the latest episode of an anime series.
+ *-d* /dir/, *--base-dir* /dir/ ::
Setup your *\{Genshiken__Downloads\}* directory in /dir/ instead of *HOME/*. If the specified directory is on a USB device, this device must already be mounted first;
otherwise, *genshiken* will complain. You must also be the owner of said device. _Please Note:_ If you download an anime using a different directory than the
default videos directory in *HOME/*, then you must set it the same way when you watch that anime with the *--view* option.
* EXAMPLES
These examples represent how you'll probably start using *genshiken* on day 1. There's no need to attempt to use all of *genshiken*'s options all in one go. Baby
steps... Once you learn one command: Try another! Eventually-- you may even want to look at the source code to further tweak it for efficiency, or even to adapt it
to work with your favorite websites. *Genshiken* was written using a shell-scripting language that *GNU Bash* understands. This design was intentional, to make it so
that any user could easily read and modify the source code, without having to learn a high-level programming language.
+ This command, for instance, will allow you to download anime: ::
#+BEGIN_SRC bash
genshiken --get anime-dub
#+END_SRC
+ Whereas this command, will allow you to view what you've downloaded: ::
#+BEGIN_SRC bash
genshiken --view anime-dub
#+END_SRC
+ Let's watch episode 5 of an online cartoon show that we'll select: ::
#+BEGIN_SRC bash
genshiken --stream=cartoon --start-at=5
#+END_SRC
+ Let's start a stream session, and restart *genshiken* every time we trigger an /EARLY TERMINATION/ code. This command is useful for cycling through various anime series, until you find the right one: ::
#+BEGIN_SRC bash
eval 'genshiken -y anime-dub --no-sessions'; until [[ $? -ne 20 ]]; do eval "$_ --no-update"; done
#+END_SRC
* HERE DOCUMENT EXAMPLES
Yes, *genshiken* is generic enough to be used in a /Here Document/. This may be a bit overkill, but these examples exist to show you that it is possible. The easiest way
to use this mechanism, is to let *genshiken* do it for you. That's actually what the concept of *genshiken* /Sessions/ is all about.
The following /Here Document/ examples won't work if you have a session file saved that is the same session type as the /Session/ parameter that you are currently using.
When this happens, *genshiken* will prompt you if you want to restore a session or not. This extra prompt will make you're /Here Document/ inaccurate, for it will now
require an extra newline character. To prevent this from happening: Use the *--no-sessions* option where neccessary.
_Please Note_: Your /Here Document/ can't be saved by *genshiken*. It's redirection is only seen by /bash(1)/. If you have a /Here Document/ that you use frequently with
*genshiken*, then try saving it as a bash script for later execution.
+ Let's download the 3rd subtitled anime, from the 6th series onto a USB: ::
#+BEGIN_SRC bash
genshiken --get=anime-sub -m2 -p --base-dir=/mnt/my_usb <<GET
yes
6
3
D
Q
GET
#+END_SRC
+ Let's start a random movie marathon-- in color mode: ::
#+BEGIN_SRC bash
for A in {1..10}
do genshiken --stream movie -m2 -p --colorize light <<STREAM
yes
$A
$A
S
Q
STREAM
done
#+END_SRC
+ Download a set of special episodes, and then view them upon completion: ::
#+BEGIN_SRC bash
genshiken -x ova && genshiken -i ova -m2 -p <<PLAY
$(
ls -l ~/*/*/ova/? | grep '^d' |
grep -n '.*' | grep "[ ]$(date +%b)[ ]" |
sort -k 7,7n -k 8,8n | sed -n '$ p' |
gawk -F: '{ print $1 }'
)
PLAY
#+END_SRC
* FILES
+ HOME/.config/genshiken-USER/debug.log ::
This file will store command expansions from a debugging session with *genshiken*.
+ HOME/.config/genshiken-USER/\{missing__files\}.log ::
This file will store which anime's could not be accessed during your session.
+ HOME/.config/genshiken-USER/previous-session-*.log ::
These files will store important information which will allow *genshiken* to restore your previous sessions.
+ HOME/.config/genshiken-USER/details/\{Anime__Type\}/\{series__*\}.txt ::
These files store and categorize a series of anime links alphabetically. All anime menus are based off of these files, and are created after parsing the HTML
of the downloaded /Anime-List/.
+ HOME/.config/sleep.log ::
This file can be used to control when the debug prompt, during a *[DEBUG]* session executed by the *--verbose* option, should execute and print the next command
expansion from *genshiken*. Controlling this file is simple. I've exported a /sleep(1)/ command inside the *PS4* variable, that tells bash how long *genshiken*
should stay idle for. When you execute the *--verbose* option without giving it an argument, the default value inside *HOME/.config/sleep.log* is *0*. A
value of *0* means don't wait, and a value of *1* means wait one second. If you want to change the speed during runtime: /echo(1)/ a number greater than zero into
this file to slow-down; /echo(1)/ zero to go as fast as possible. You get the picture.
* ENVIRONMENT
+ *IMAGER* :: \\
This environment variable is read by *genshiken*, and if set, will allow the user to use their image viewer of choice with *genshiken*.
+ *PAGER* :: \\
This environment variable is read by *genshiken*, and if set, will allow for output that is meant to go to a pager, to go to your pager of choice.
+ *PLAYER* :: \\
This environment variable is read by *genshiken*, and if set, will allow the user to use their media player of choice with *genshiken*.
+ *TMPDIR* :: \\
This environment variable is read by *genshiken*, and if set, will be used as the base directory to store *genshiken* data files in. The default directory is:
*HOME/.config/genshiken-USER*
* AUTHOR
Written by Michael Pagan
* COPYING
Copyright © 2015-2016 Michael Pagan
Permission is granted to copy, distribute and/or modify this document under the terms of the /GNU Free Documentation License/, Version 1.3 or any later version published
by the /Free Software Foundation/; with no Invariant Sections, and with the Back-Cover Texts as in (a) below. Please refer to the `COPYING.manual' file for full details
of the /GNU Free Documentation License/.
(a) Michael Pagan's Back-Cover Text is: "You have the freedom to copy and modify this libre manual."