mediacurator/docs/usage/manual.html
Fabrice Quenneville 5ba0f84d12 **Summary:**
This release introduces a major overhaul of the `mediacurator` command-line interface (CLI) and comprehensive updates to the documentation. The CLI has transitioned from a custom argument parsing system to utilizing Python's `argparse` and `argcomplete` libraries, greatly enhancing usability and flexibility. Due to these significant changes, the version is incremented from **0.0.13** to **1.0.1**.

- **Refactored** `tools.py` for standardized command-line argument handling using `argparse` and `argcomplete`.
- **Improved** user interaction with structured arguments and built-in help, error handling, and validation.
- **Consolidated** video detail printing logic into a reusable method within the `Video` class.
- **Enhanced** `MediaLibrary` class with better clarity, functionality, and expanded support for video formats.
- **Reorganized** `main.py` to streamline argument handling and improve error feedback.
- **Updated** `setup.py` for release preparation, including new classifiers and dependencies.

- **Revised** README.md for clarity, including structured command usage and improved descriptions.
- **Moved** and improved old documentation, removing outdated content and adding new screenshots.
- **Maintained** legacy commands for backward compatibility while enhancing usability with clear examples.

- **Removed** non-existent `bcolors` from the public API.
- **Upgraded** requirements.txt to include `argcomplete` for command-line completion.
- **Updated** docstrings and function documentation for clarity on functionality and parameters.
2024-10-20 23:19:42 -04:00

349 lines
21 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Manual &#8212; mediacurator documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d1102ebc" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=12dfc556" />
<link rel="stylesheet" type="text/css" href="../_static/custom.css?v=d9b65b63" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9a2dae69"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Use cases" href="use_cases.html" />
<link rel="prev" title="Quickstart" href="quickstart.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="manual">
<h1>Manual<a class="headerlink" href="#manual" title="Link to this heading"></a></h1>
<section id="name">
<h2>Name<a class="headerlink" href="#name" title="Link to this heading"></a></h2>
<p>mediacurator</p>
</section>
<section id="synopsis">
<h2>Synopsis<a class="headerlink" href="#synopsis" title="Link to this heading"></a></h2>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mediacurator<span class="w"> </span>&lt;command&gt;<span class="w"> </span><span class="o">[</span>options<span class="o">]</span>
mediacurator<span class="w"> </span><span class="o">[</span>list<span class="w"> </span>convert<span class="o">]</span><span class="w"> </span><span class="o">[</span>-del/--delete<span class="o">]</span>
<span class="w"> </span><span class="o">[</span>-i/--inputs<span class="w"> </span>any<span class="w"> </span>3gp<span class="w"> </span>asf<span class="w"> </span>avi<span class="w"> </span>divx<span class="w"> </span>dv<span class="w"> </span>f4v<span class="w"> </span>flv<span class="w"> </span>gif<span class="w"> </span>m2ts<span class="w"> </span>m4v<span class="w"> </span>mkv<span class="w"> </span>mov<span class="w"> </span>mp4<span class="w"> </span>mpeg<span class="w"> </span>mpg<span class="w"> </span>mts<span class="w"> </span>ogm<span class="w"> </span>ogv<span class="w"> </span>rm<span class="w"> </span>swf<span class="w"> </span>ts<span class="w"> </span>vid<span class="w"> </span>vob<span class="w"> </span>webm<span class="w"> </span>wmv<span class="o">]</span>
<span class="w"> </span><span class="o">[</span>-fl/--filters<span class="w"> </span>fferror<span class="w"> </span>old<span class="w"> </span>lowres<span class="w"> </span>hd<span class="w"> </span>720p<span class="w"> </span>1080p<span class="w"> </span>uhd<span class="w"> </span>mpeg<span class="w"> </span>mpeg4<span class="w"> </span>x264<span class="w"> </span>wmv3<span class="w"> </span>wmv<span class="o">]</span>
<span class="w"> </span><span class="o">[</span>-o/--outputs<span class="w"> </span>mkv/mp4<span class="w"> </span>x265/av1<span class="o">]</span>
<span class="w"> </span><span class="o">[</span>-p/--printop<span class="w"> </span>list<span class="w"> </span>formatted<span class="w"> </span>verbose<span class="o">]</span>
<span class="w"> </span><span class="o">[</span>-d/--dirs<span class="w"> </span><span class="s2">&quot;/mnt/media/&quot;</span><span class="w"> </span><span class="s2">&quot;/mnt/media2/&quot;</span><span class="o">]</span>
<span class="w"> </span><span class="o">[</span>-f/--files<span class="w"> </span><span class="s2">&quot;file1.ext&quot;</span><span class="w"> </span><span class="s2">&quot;file2.ext&quot;</span><span class="o">]</span>
</pre></div>
</div>
<p><strong>Available commands:</strong>
- <cite>list</cite>: List all videos with specified filters.
- <cite>convert</cite>: Convert videos to specified formats.</p>
<p><strong>Options:</strong></p>
<ul class="simple">
<li><p><cite>-del</cite> or <cite>delete</cite>: Delete found results after successful operations. <strong>Use with caution</strong>.</p></li>
<li><p><cite>-i &lt;input&gt;</cite> or <cite>inputs &lt;input&gt;</cite>: Specify input file formats (default: <cite>any</cite>).</p></li>
<li><p><cite>-fl &lt;filter&gt;</cite> or <cite>filters &lt;filter&gt;</cite>: Apply filters to the selection of videos.</p></li>
<li><p><cite>-o &lt;output&gt;</cite> or <cite>outputs &lt;output&gt;</cite>: Specify output formats (default: <cite>mkv</cite>, <cite>x265</cite>).</p></li>
<li><p><cite>-p &lt;print_option&gt;</cite> or <cite>printop &lt;print_option&gt;</cite>: Set print options (default: <cite>list</cite>).</p></li>
<li><p><cite>-f &lt;file&gt;</cite> or <cite>files &lt;file&gt;</cite>: Specify files to process.</p></li>
<li><p><cite>-d &lt;directory&gt;</cite> or <cite>dirs &lt;directory&gt;</cite>: Specify directories to process.</p></li>
</ul>
<p><strong>For multiple files or filenames, use space-separated values ( ).</strong></p>
<p><strong>Default options (if not specified):</strong></p>
<ul class="simple">
<li><p><cite>-i/inputs</cite>: <cite>any</cite></p></li>
<li><p><cite>-fl/filters</cite>: (none)</p></li>
<li><p><cite>-o/outputs</cite>: <cite>mkv</cite>, <cite>x265</cite></p></li>
<li><p><cite>-p/printop</cite>: <cite>list</cite></p></li>
</ul>
</section>
<section id="description">
<h2>Description<a class="headerlink" href="#description" title="Link to this heading"></a></h2>
<p><strong>mediacurator</strong> is a Python command-line tool designed to manage a media database. It allows you to:</p>
<ul class="simple">
<li><p>List all videos and their metadata, optionally filtered by specified criteria.</p></li>
<li><p>Batch find, repair, or convert videos with encoding errors.</p></li>
<li><p>Batch recode videos to modern codecs (e.g., x265, AV1) based on filters (e.g., container, codec, resolution).</p></li>
</ul>
</section>
<section id="options">
<h2>Options<a class="headerlink" href="#options" title="Link to this heading"></a></h2>
<section id="list">
<h3>list<a class="headerlink" href="#list" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Search and list videos filtered by the user-provided parameters.</p>
</div></blockquote>
</section>
<section id="convert">
<h3>convert<a class="headerlink" href="#convert" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Search and convert all videos filtered by the user-provided parameters.</p>
</div></blockquote>
</section>
<section id="delete">
<h3>delete<a class="headerlink" href="#delete" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Short form: <cite>-del</cite></p>
<p>Deletes the original videos after successful completion of operations (e.g., conversion or listing). <strong>Use with caution</strong>.</p>
<p>See <a class="reference internal" href="warnings.html"><span class="doc">Warnings</span></a></p>
</div></blockquote>
</section>
<section id="inputs">
<h3>inputs<a class="headerlink" href="#inputs" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Short form: <cite>-i</cite></p>
<p>[<strong>any</strong>, 3gp, asf, avi, divx, dv, f4v, flv, gif, m2ts, m4v, mkv, mov, mp4, mpeg, mpg, mts, ogm, ogv, rm, swf, ts, vid, vob, webm, wmv]</p>
<p>Filters videos by file format (container extensions). The default is <cite>any</cite>, meaning all formats are included.</p>
</div></blockquote>
</section>
<section id="filters">
<h3>filters<a class="headerlink" href="#filters" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Short form: <cite>-fl</cite></p>
<p>[fferror, old, lowres, hd, 720p, 1080p, uhd, mpeg, mpeg4, x264, wmv3, wmv]</p>
<p>Filters videos based on specific criteria:</p>
<ul class="simple">
<li><p><strong>fferror</strong>: Select videos with encoding errors (see <a class="reference internal" href="errors.html"><span class="doc">Errors</span></a>)</p></li>
<li><p><strong>old</strong>: Select videos using outdated codecs (anything except hevc or av1)</p></li>
<li><p><strong>hd</strong>: Select videos in HD (720p, 1080p, UHD)</p></li>
<li><p><strong>lowres</strong>: Select videos that are not in HD</p></li>
<li><p><strong>uhd</strong>: Select Ultra-HD videos (width or height &gt;= 2160)</p></li>
<li><p><strong>1080p</strong>: Select Full-HD videos (1440 &lt;= width &lt; 2160 or 1080 &lt;= height &lt; 2160)</p></li>
<li><p><strong>720p</strong>: Select HD videos (1280 &lt;= width &lt; 1440 or 720 &lt;= height &lt; 1080)</p></li>
<li><p><strong>sd</strong>: Select standard-definition videos (480 &lt;= height &lt; 720)</p></li>
<li><p><strong>subsd</strong>: Select substandard-definition videos (height &lt; 480)</p></li>
<li><p><strong>mpeg, mpeg4, x264, wmv3, wmv, vob</strong>: Filter by video codec</p></li>
</ul>
</div></blockquote>
</section>
<section id="outputs">
<h3>outputs<a class="headerlink" href="#outputs" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Short form: <cite>-o</cite></p>
<p>[<strong>mkv</strong>/mp4, x265/av1]</p>
<p>Specifies the output format for video conversions:</p>
<ul class="simple">
<li><p><strong>mkv</strong>: (<strong>Default</strong>) Package the output video in a <a class="reference external" href="https://en.wikipedia.org/wiki/Matroska">Matroska</a> container.</p></li>
<li><p><strong>mp4</strong>: Package the output video in an MP4 container.</p></li>
<li><p><strong>x265</strong> or <strong>hevc</strong>: (<strong>Default</strong>) Encode the video using <a class="reference external" href="https://en.wikipedia.org/wiki/X265">x265</a> (HEVC).</p></li>
<li><p><strong>av1</strong>: Encode the video using <a class="reference external" href="https://en.wikipedia.org/wiki/AV1">AOMedia Video 1</a> (AV1).</p></li>
</ul>
</div></blockquote>
</section>
<section id="printop">
<h3>printop<a class="headerlink" href="#printop" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Short form: <cite>-p</cite></p>
<p>[<strong>list</strong>, formatted, verbose]</p>
<p>Specifies how the output should be displayed:</p>
<ul class="simple">
<li><p><strong>list</strong>: (<strong>Default</strong>) Prints video info in a concise, single-line format.</p></li>
</ul>
<a class="reference internal image-reference" href="../_images/Screenshot-print_list-single.png"><img alt="List videos (single-line output)" src="../_images/Screenshot-print_list-single.png" style="width: 600px;" />
</a>
<ul class="simple">
<li><p><strong>formatted</strong>: Prints video info in a more readable format with line breaks.</p></li>
</ul>
<a class="reference internal image-reference" href="../_images/Screenshot-print_formatted-single.png"><img alt="List videos (formatted output)" src="../_images/Screenshot-print_formatted-single.png" style="width: 400px;" />
</a>
<ul class="simple">
<li><p><strong>verbose</strong>: Prints the FFmpeg output during conversions.</p></li>
</ul>
</div></blockquote>
</section>
<section id="dirs">
<h3>dirs<a class="headerlink" href="#dirs" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Short form: <cite>-d</cite></p>
<p>[“/mnt/media/”, “/mnt/media2/”]</p>
<p>Specifies directories to scan, separated by spaces.</p>
</div></blockquote>
</section>
<section id="files">
<h3>files<a class="headerlink" href="#files" title="Link to this heading"></a></h3>
<blockquote>
<div><p>Short form: <cite>-f</cite></p>
<p>[“/mnt/media/video.avi”, “/mnt/media2/video2.mp4”]</p>
<p>Specifies individual video files to process, separated by spaces.</p>
</div></blockquote>
</section>
</section>
<section id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Link to this heading"></a></h2>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># This command lists all videos in the specified directories that use old codecs and</span>
<span class="c1"># formats the output.</span>
mediacurator<span class="w"> </span>list<span class="w"> </span>--filters<span class="w"> </span>old<span class="w"> </span>--printop<span class="w"> </span>formatted<span class="w"> </span>--dirs<span class="w"> </span><span class="s2">&quot;/mnt/media/&quot;</span><span class="w"> </span><span class="s2">&quot;/mnt/media2/&quot;</span>
<span class="c1"># This command converts all MPEG4 videos found in the specified directories to AV1 format</span>
<span class="c1"># in MP4 containers and deletes the originals.</span>
mediacurator<span class="w"> </span>convert<span class="w"> </span>--delete<span class="w"> </span>--filters<span class="w"> </span>mpeg4<span class="w"> </span>--outputs<span class="w"> </span>av1<span class="w"> </span>mp4<span class="w"> </span>--dirs<span class="w"> </span><span class="s2">&quot;/mnt/media/&quot;</span><span class="w"> </span><span class="s2">&quot;/mnt/media2/&quot;</span>
<span class="c1"># This command converts AVI or MPG videos, displays detailed output during conversion, and</span>
<span class="c1"># deletes originals.</span>
mediacurator<span class="w"> </span>convert<span class="w"> </span>--delete<span class="w"> </span>--inputs<span class="w"> </span>avi<span class="w"> </span>mpg<span class="w"> </span>--printop<span class="w"> </span>formatted<span class="w"> </span>verbose<span class="w"> </span>--dirs<span class="w"> </span><span class="s2">&quot;/mnt/media/&quot;</span><span class="w"> </span><span class="s2">&quot;/mnt/media2/&quot;</span>
</pre></div>
</div>
<p>For more examples, see <a class="reference internal" href="use_cases.html"><span class="doc">Use cases</span></a></p>
</section>
<section id="see-also">
<h2>See Also<a class="headerlink" href="#see-also" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://ffmpeg.org/">FFmpeg</a></p></li>
</ul>
</section>
<section id="glossary">
<h2>Glossary<a class="headerlink" href="#glossary" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p><strong>Codec</strong>: A program or device that compresses and decompresses digital media.</p></li>
<li><p><strong>Container</strong>: A file format that holds video, audio, and metadata.</p></li>
<li><p><strong>UHD</strong>: Ultra High Definition, refers to video resolutions of 3840x2160 pixels or higher.</p></li>
</ul>
</section>
<section id="error-handling">
<h2>Error Handling<a class="headerlink" href="#error-handling" title="Link to this heading"></a></h2>
<p>Common issues users might encounter include:</p>
<ul class="simple">
<li><p><strong>Encoding Errors</strong>: If videos have encoding errors, they can be filtered using the <cite>filters fferror</cite> option.</p></li>
<li><p><strong>Unsupported Formats</strong>: Ensure that input formats specified in <cite>inputs</cite> are supported by mediacurator.</p></li>
</ul>
</section>
<section id="author">
<h2>Author<a class="headerlink" href="#author" title="Link to this heading"></a></h2>
<p>Fabrice Quenneville</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/mclogo4x.png" alt="Logo of mediacurator"/>
</a></p>
<h1 class="logo"><a href="../index.html">mediacurator</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Usage:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="warnings.html">Warnings</a></li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Manual</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#name">Name</a></li>
<li class="toctree-l2"><a class="reference internal" href="#synopsis">Synopsis</a></li>
<li class="toctree-l2"><a class="reference internal" href="#description">Description</a></li>
<li class="toctree-l2"><a class="reference internal" href="#options">Options</a></li>
<li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a></li>
<li class="toctree-l2"><a class="reference internal" href="#see-also">See Also</a></li>
<li class="toctree-l2"><a class="reference internal" href="#glossary">Glossary</a></li>
<li class="toctree-l2"><a class="reference internal" href="#error-handling">Error Handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="#author">Author</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="use_cases.html">Use cases</a></li>
<li class="toctree-l1"><a class="reference internal" href="errors.html">Errors</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Release Notes:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/1.0.1-changelog.html">mediacurator 1.0.1 Release Notes</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Legacy Usage:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../legacy_usage/warnings.html">Warnings</a></li>
<li class="toctree-l1"><a class="reference internal" href="../legacy_usage/installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../legacy_usage/quickstart.html">Quickstart</a></li>
<li class="toctree-l1"><a class="reference internal" href="../legacy_usage/manual.html">Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../legacy_usage/use_cases.html">Use cases</a></li>
<li class="toctree-l1"><a class="reference internal" href="../legacy_usage/errors.html">Errors</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Legacy Release Notes:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.13-changelog.html">MediaCurator 0.0.13 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.12-changelog.html">MediaCurator 0.0.12 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.11-changelog.html">MediaCurator 0.0.11 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.10-changelog.html">MediaCurator 0.0.10 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.9-changelog.html">MediaCurator 0.0.9 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.8-changelog.html">MediaCurator 0.0.8 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.7-changelog.html">MediaCurator 0.0.7 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.6-changelog.html">MediaCurator 0.0.6 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.5-changelog.html">MediaCurator 0.0.5 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.4-changelog.html">MediaCurator 0.0.4 Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releasenotes/0.0.1-changelog.html">MediaCurator 0.0.1 Release Notes</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../index.html">Documentation overview</a><ul>
<li>Previous: <a href="quickstart.html" title="previous chapter">Quickstart</a></li>
<li>Next: <a href="use_cases.html" title="next chapter">Use cases</a></li>
</ul></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&#169;2020, Fabrice Quenneville.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 7.4.7</a>
&amp; <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/usage/manual.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>