Fabrice Quenneville
5ba0f84d12
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.
334 lines
18 KiB
HTML
334 lines
18 KiB
HTML
<!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 — 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>
|
|
<div class="admonition warning">
|
|
<p class="admonition-title">Warning</p>
|
|
<p>The following documentation is for versions prior to 1.0.1. It may contain features and usage instructions that are incompatible with the current version of mediacurator.</p>
|
|
</div>
|
|
<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><command><span class="w"> </span><span class="o">[</span>options<span class="o">]</span>
|
|
|
|
mediacurator<span class="w"> </span><span class="o">[</span>list,convert<span class="o">]</span><span class="w"> </span><span class="o">[</span>-del<span class="o">]</span>
|
|
<span class="w"> </span><span class="o">[</span>-in:any,avi,divx,flv,m4v,mkv,mp4,mpg,ogm,vid,webm,wmv<span class="o">]</span>
|
|
<span class="w"> </span><span class="o">[</span>-filters:fferror,old,lowres,hd,720p,1080p,uhd,mpeg,mpeg4,x264,wmv3,wmv,vob<span class="o">]</span>
|
|
<span class="w"> </span><span class="o">[</span>-out:mkv/mp4,x265/av1<span class="o">]</span>
|
|
<span class="w"> </span><span class="o">[</span>-print:list,formated,verbose<span class="o">]</span>
|
|
<span class="w"> </span><span class="o">[</span>-dirs/-files:<span class="s2">"/mnt/media/"</span>,,<span class="s2">"/mnt/media2/"</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>: Delete found results after successful operations. <strong>Use with caution</strong>.</p></li>
|
|
<li><p><cite>-in <input></cite>: Specify input file formats (default: <cite>any</cite>).</p></li>
|
|
<li><p><cite>-filters <filter></cite>: Apply filters to the selection of videos.</p></li>
|
|
<li><p><cite>-out <output></cite>: Specify output formats (default: <cite>mkv</cite>, <cite>x265</cite>).</p></li>
|
|
<li><p><cite>-print <print_option></cite>: Set print options (default: <cite>list</cite>).</p></li>
|
|
<li><p><cite>-files <file></cite>: Specify files to process.</p></li>
|
|
<li><p><cite>-dirs <directory></cite>: Specify directories to process.</p></li>
|
|
</ul>
|
|
<p><strong>For multiple files or filenames, use double comma separated values (,,).</strong></p>
|
|
<p><strong>Default options (if not specified):</strong></p>
|
|
<ul class="simple">
|
|
<li><p><cite>-in</cite>: <cite>any</cite></p></li>
|
|
<li><p><cite>-filters</cite>: (none)</p></li>
|
|
<li><p><cite>-out</cite>: <cite>mkv</cite>, <cite>x265</cite></p></li>
|
|
<li><p><cite>-print</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="del">
|
|
<h3>-del:<a class="headerlink" href="#del" title="Link to this heading">¶</a></h3>
|
|
<blockquote>
|
|
<div><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="in">
|
|
<h3>-in:<a class="headerlink" href="#in" title="Link to this heading">¶</a></h3>
|
|
<blockquote>
|
|
<div><p>[<strong>any</strong>, avi, divx, flv, m4v, mkv, mp4, mpg, ogm, vid, 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>[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 >= 2160)</p></li>
|
|
<li><p><strong>1080p</strong>: Select Full-HD videos (1440 <= width < 2160 or 1080 <= height < 2160)</p></li>
|
|
<li><p><strong>720p</strong>: Select HD videos (1280 <= width < 1440 or 720 <= height < 1080)</p></li>
|
|
<li><p><strong>sd</strong>: Select standard-definition videos (480 <= height < 720)</p></li>
|
|
<li><p><strong>subsd</strong>: Select substandard-definition videos (height < 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="out">
|
|
<h3>-out:<a class="headerlink" href="#out" title="Link to this heading">¶</a></h3>
|
|
<blockquote>
|
|
<div><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="print">
|
|
<h3>-print:<a class="headerlink" href="#print" title="Link to this heading">¶</a></h3>
|
|
<blockquote>
|
|
<div><p>[<strong>list</strong>, formated, 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>formated</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>[“/mnt/media/”,,”/mnt/media2/”]</p>
|
|
<p>Specifies directories to scan, separated by <strong>double commas</strong> (,,).</p>
|
|
</div></blockquote>
|
|
</section>
|
|
<section id="files">
|
|
<h3>-files:<a class="headerlink" href="#files" title="Link to this heading">¶</a></h3>
|
|
<blockquote>
|
|
<div><p>[“/mnt/media/video.avi”,,”/mnt/media2/video2.mp4”]</p>
|
|
<p>Specifies individual video files to process, separated by <strong>double commas</strong> (,,).</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:old<span class="w"> </span>-print:formated<span class="w"> </span>-dirs:<span class="s2">"/mnt/media/"</span>,,<span class="s2">"/mnt/media2/"</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>-del<span class="w"> </span>-filters:mpeg4<span class="w"> </span>-out:av1,mp4<span class="w"> </span>-dirs:<span class="s2">"/mnt/media/"</span>,,<span class="s2">"/mnt/media2/"</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>-del<span class="w"> </span>-in:avi,mpg<span class="w"> </span>-print:formated,verbose<span class="w"> </span>-dirs:<span class="s2">"/mnt/media/"</span>,,<span class="s2">"/mnt/media2/"</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>-in</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>
|
|
<li class="toctree-l1"><a class="reference internal" href="../usage/warnings.html">Warnings</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../usage/installation.html">Installation</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../usage/quickstart.html">Quickstart</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../usage/manual.html">Manual</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../usage/use_cases.html">Use cases</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="../usage/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 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></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">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">
|
|
©2020, Fabrice Quenneville.
|
|
|
|
|
|
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 7.4.7</a>
|
|
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
|
|
|
|
|
|
<a href="../_sources/legacy_usage/manual.rst.txt"
|
|
rel="nofollow">Page source</a>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
</body>
|
|
</html> |