mediafragmenter is a tool for working with file fragments.
A fragment pointer is a JSON file with the ".fp.json" extension
that stores the fragment boundaries, the path to the source file,
its type, and other data.

The program works in conjunction with a number of external
applications used to open fragments.
The current version supports fragments of video and audio files,
plain text documents (txt, xml, source code files, etc.),
as well as (limited support for) PDF and DJVU.

---

Command format for creating a fragment pointer:

mediafragmenter -f <file> [-t|--type <file-type>] \
                          [-b <boundary-type>] \
                          [-s|--start <start>] \
                          [-e|--end <end>] \
                          [-o|--output <output_file>]
    Only the path to the file for which the fragment pointer
    is being created is required; all other parameters are optional.

    The '-t' ('--type') option specifies the file types:
    'video', 'audio', 'text', 'pdf', 'djvu'.
    If omitted, the type is detected automatically.

    The '-b' option specifies the boundary type:

        for 'audio' and 'video' types, the available option is 'by-time';

        for the 'text' type, two values are available:
        'by-line-and-column' (default) and 'by-phrase';

        for 'pdf' and 'djvu', the available option is 'by-page'.

    The '-s' ('--start') and '-e' ('--end') options specify boundaries:

        for 'audio' and 'video', boundaries are timestamps
        in the format 'HH:MM:SS' (hours, minutes, seconds separated
        by colons); seconds may include a fractional part with up to
        four decimal places;

        for 'text', the the default boundaries are line number
        and column number separated by a comma without spaces;
        boundaries are inclusive, meaning the specified positions
        are included in the fragment;
        the column (character number in the line) may be omitted,
        i.e, only the line number may be specified;
        alternativaly, boundaries may be phrases from the text —
        in this case, the end phrase is searched for after the start phrase;
        for this mode, the option '-b by-phrase' must be specified;

        for 'pdf' and 'djvu', only positioning by page number is supported;
        the end of the fragment is not specified;

        if the start and/or end value is omitted,
        the corresponding boundary is considered absent.

    The '-o' ('--output') option specifies the path of the output fragment
    pointer. By default, a fragment pointer is created in the current directory
    with the original file name and the ".fp.json" extension.

    Examples:

    mediafragmenter -f ~/Concert.mkv -s 01:43:14 -e 01:47:38 -o song.fp.json
        A fragment pointer to the video will be created with
        the name 'song.fp.json'.

    mediafragmenter -f ~/Notes.txt -s 45,4 -e 59
        A fragment pointer named 'Notes.fp.json' will be created for
        the interval from the 4th character of line #45 to line #59 inclusive.

    mediafragmenter -f ~/cartoon.avi -e 00:00:59 -o intro.fp.json
        A fragment pointer will be created from the beginning of the video
        up to the 59-second mark.

    mediafragmenter -f /mnt/stor/Book.pdf -s 15 -o chapter4.fp.json
        A fragment pointer for the PDF file will be created,
        starting from page 15.

---

mediafragmenter -p <fragment_pointer> [-a|--app <application>]

    Plays/opens the file fragment.
    By default, video and audio files opened with mpv;
    vlc and ffplay can also be used.
    The application for text files is determined by the ufo utitily,
    but a specific program may be explicitly specified.
    PDF and DJVU files are opened with atril by default;
    evince, okular and zathura are also supported.

---

Other commands

mediafragmenter --version
    Displays the program version.

mediafragmenter --help
    Displays the help message.
