batchmp 1.4__py3-none-any.whl

batchmp/tags/processors/basetp.py

@@ -0,0 +1,266 @@
+    # coding=utf8
+## Copyright (c) 2014 Arseniy Kuznetsov
+##
+## This program is free software; you can redistribute it and/or
+## modify it under the terms of the GNU General Public License
+## as published by the Free Software Foundation; either version 2
+## of the License, or (at your option) any later version.
+##
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+
+
+import sys, os, re, string
+from batchmp.fstools.dirtools import DHandler
+from batchmp.fstools.walker import DWalker
+from batchmp.fstools.rename import DirCounters
+from batchmp.tags.output.formatters import TagOutputFormatter, OutputFormatType
+from batchmp.tags.handlers.mtghandler import MutagenTagHandler
+from batchmp.tags.handlers.ffmphandler import FFmpegTagHandler
+from batchmp.tags.handlers.tagsholder import TagHolder
+from batchmp.commons.progressbar import progress_bar, CmdProgressBarRefreshRate
+from functools import partial
+
+class BaseTagProcessor:
+    ''' Base Tag Processing
+    '''
+    def __init__(self):
+        self._handler = MutagenTagHandler() + FFmpegTagHandler()
+
+    @property
+    def handler(self):
+        return self._handler
+
+    def print_dir(self, fs_entry_params, format = None, show_stats = False):
+
+        ''' Prints tags in selected media files
+        '''
+        formatter = partial(TagOutputFormatter.tags_formatter,
+                                        format = format if format else OutputFormatType.COMPACT,
+                                        handler = self.handler,
+                                        show_stats = show_stats)
+
+        DHandler.print_dir(fs_entry_params, 
+                            formatter = formatter,
+                            selected_files_description = 'media file')
+
+    def set_tags(self, fs_entry_params, total_files, total_dirs, tag_holder = None, tag_holder_builder = None):
+
+        ''' Set tags from tag_holder attributes
+        '''
+        if not tag_holder and not tag_holder_builder:
+            return
+
+        fcnt = 0
+        pass_filter = lambda fpath: self.handler.can_handle(fpath)
+
+        with progress_bar(refresh_rate = CmdProgressBarRefreshRate.FAST) as p_bar:
+            p_bar.info_msg = 'Setting tags in {} media files'.format(total_files)
+            for entry in DWalker.file_entries(fs_entry_params, pass_filter = pass_filter):
+                if tag_holder_builder:
+                    tag_holder = tag_holder_builder(entry)
+
+                self.handler.copy_tags(tag_holder)
+                self.handler.save()
+                fcnt += 1
+
+                p_bar.progress += 100 / total_files
+
+
+        # print summary
+        if not fs_entry_params.quiet:
+            print('Set tags in {0} media file{1}'.format(fcnt, '' if fcnt == 1 else 's'))
+
+    def set_tags_visual(self, fs_entry_params, 
+                            diff_tags_only = False,
+                            tag_holder = None,
+                            tag_holder_builder = None, 
+                            reset_tag_holder_builder = None):
+
+        ''' Set tags from tag_holder attributes
+            Visualises changes before proceeding
+        '''
+        if not tag_holder and not tag_holder_builder:
+            return
+
+        if fs_entry_params.quiet:
+            proceed = True
+            total_files, total_dirs, _ = DHandler.dir_stats(fs_entry_params)
+        else:
+            # visualise changes to tags and proceed if confirmed
+            preformatter = partial(TagOutputFormatter.tags_formatter,
+                                            handler = self.handler,
+                                            show_stats = False,
+                                            tag_holder = tag_holder,
+                                            tag_holder_builder = tag_holder_builder,
+                                            diff_tags_only = diff_tags_only)
+
+            formatter = partial(TagOutputFormatter.tags_formatter,
+                                            handler = self.handler,
+                                            show_stats = False,
+                                            tag_holder = tag_holder,
+                                            tag_holder_builder = tag_holder_builder,
+                                            show_tag_holder_values = True,
+                                            diff_tags_only = diff_tags_only)
+
+            proceed, total_files, total_dirs = DHandler.visualise_changes(fs_entry_params,
+                                            preformatter = preformatter, formatter = formatter,
+                                            reset_formatters = reset_tag_holder_builder,
+                                            selected_files_description = 'media file')
+        if proceed:
+            if reset_tag_holder_builder:
+                reset_tag_holder_builder()
+
+            self.set_tags(fs_entry_params, total_files, total_dirs,
+                            tag_holder = tag_holder, 
+                            tag_holder_builder = tag_holder_builder)
+
+    def copy_tags(self, fs_entry_params,  diff_tags_only = False, tag_holder_path = None):
+
+        ''' Copies metadata (including artwork) from a tag_holder file
+            then applies to all selected media files
+            Visualises changes before proceeding
+        '''
+        if self.handler.can_handle(tag_holder_path):
+            tag_holder = TagHolder()
+            tag_holder.copy_tags(self.handler.tag_holder)
+            self.set_tags_visual(fs_entry_params,
+                                    diff_tags_only = diff_tags_only,
+                                    tag_holder = tag_holder)
+        else:
+            print('Can not handle tags holder: {}'.format(tag_holder_path))
+
+    def index(self, fs_entry_params,
+                    diff_tags_only = False, start_from = 1):
+
+        ''' Indexes the tracks / tracktotal tags, per media files' respective directories
+            Visualises changes before proceeding
+        '''
+
+        counters = {}
+        def reset_counts():
+            counters.clear()
+
+        def tag_holder_builder(entry):
+            nonlocal counters
+
+            parent_dir = os.path.dirname(entry.realpath)            
+            if not counters.get(parent_dir):
+                counters[parent_dir] = DirCounters(start_from, start_from, 0, 0)
+
+            tag_holder = TagHolder()
+            tag_holder.tracktotal = len(fs_entry_params.fnames)
+            
+            tag_holder.track = counters[parent_dir].files_cnt
+            counters[parent_dir].files_cnt += 1
+
+            return tag_holder
+
+        self.set_tags_visual(fs_entry_params,
+                        diff_tags_only = diff_tags_only,
+                        tag_holder_builder = tag_holder_builder,
+                        reset_tag_holder_builder = reset_counts)
+
+    def remove_tags(self, fs_entry_params,
+                        tag_fields = None,
+                        diff_tags_only = False):
+
+        ''' Removes metadata info from selected media files
+            Can remove all metadata, or metadata from specified fields
+            Visualises targeted changes before actual processing
+        '''
+        if tag_fields is None:
+            # remove all tags
+            tag_holder = TagHolder(copy_empty_vals = True)
+        else:
+            # remove specified tags
+            tag_holder = TagHolder(nullable_fields = tag_fields)
+
+        self.set_tags_visual(fs_entry_params,
+                        diff_tags_only = diff_tags_only,
+                        tag_holder = tag_holder)
+
+    def replace_tags(self, fs_entry_params, 
+                    diff_tags_only = False,
+                    tag_fields = None, 
+                    ignore_case = False, 
+                    ind_str = None, replace_str = None):
+
+        ''' RegExp-based replace in specified fields
+            Visualises changes before proceeding
+        '''
+
+        if not (tag_fields and find_str):
+            return
+
+        flags = re.UNICODE
+        if ignore_case:
+            flags = flags | re.IGNORECASE
+        p = re.compile(find_str, flags)
+
+        def replace_transform(value):
+            match = p.search(value)
+            if match:
+                if replace_str is not None:
+                    value = p.sub(replace_str, value)
+                else:
+                    value = match.group()
+            return value
+
+        tag_holder = TagHolder(process_templates = False)
+        for tag_field in tag_fields:
+            setattr(tag_holder, tag_field, '${}'.format(tag_field))
+        tag_holder.template_processor_method = replace_transform
+
+        self.set_tags_visual(fs_entry_params, 
+                                diff_tags_only = diff_tags_only, 
+                                tag_holder = tag_holder)
+
+    def capitalize_tags(self, fs_entry_params, 
+                    diff_tags_only = False,
+                    tag_fields = None):
+
+        ''' Capitalizes words in specified fields
+            Visualises changes before proceeding
+        '''
+
+        if not tag_fields:
+            return
+
+        def capitalize_transform(value):
+            return string.capwords(value)
+
+        tag_holder = TagHolder(process_templates = False)
+        for tag_field in tag_fields:
+            setattr(tag_holder, tag_field, '${}'.format(tag_field))
+        tag_holder.template_processor_method = capitalize_transform
+
+        self.set_tags_visual(fs_entry_params, 
+                        diff_tags_only = diff_tags_only,
+                        tag_holder = tag_holder)
+
+    def detauch_art(self, fs_entry_params, target_dir = None):
+
+        ''' Detauches art from selected media files
+        '''
+
+        fcnt = 0
+        pass_filter = lambda fpath: self.handler.can_handle(fpath)
+        for entry in DWalker.file_entries(fs_entry_params, pass_filter = pass_filter):
+
+            if not target_dir:
+                target_dir = src_dir
+            else:
+                os.makedirs(target_dir, exist_ok = True)
+
+            if  self.handler.tag_holder.has_artwork:
+                self.handler.detauch_art(target_dir)
+                fcnt += 1
+
+        # print summary
+        if not fs_entry_params.quiet:
+            print('Detauched art from {0} media entries'.format(fcnt))
+
+

batchmp-1.4.dist-info/METADATA

@@ -0,0 +1,422 @@
+Metadata-Version: 2.4
+Name: batchmp
+Version: 1.4
+Summary: Command-line tools for batch media processing
+Home-page: https://github.com/akpw/batch-mp-tools
+Author: Arseniy Kuznetsov
+Author-email: k.arseniy@gmail.com
+License: GPL-2.0-or-later
+Keywords: batch processing media video audio CLI rename tags ID3
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Multimedia :: Sound/Audio :: Conversion
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Utilities
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mutagen>=1.27
+Requires-Dist: pygtrie>=2.3.2
+Requires-Dist: filetype>=1.0.7
+Requires-Dist: mediafile>=0.13.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+
+**Status:**
+A rainy weekends project under occasional development :)
+
+#### Requirements:
+- [Python 3.4.x](https://www.python.org/download/releases/3.4.1/) or later
+
+#### Install:
+- from [PyPI](https://pypi.python.org/pypi/batchmp): `$ pip install batchmp`
+- latest from source repository: `$ pip install git+https://github.com/akpw/batch-mp-tools.git`
+
+#### Blogs:
+- [Practical BatchMP](https://akpw.github.io//tags.html#BatchMP+Tools)
+- [Renamer Organize & Virtual Views](https://akpw.github.io/articles/2025/09/22/Print-and-Organize.html)
+- [BatchMP Tools Tutorial](https://akpw.github.io//articles/2015/04/10/batchmp-tutorial-part-i.html)
+- [The BatchMP Tools Project](https://akpw.github.io//articles/2015/03/21/the-batchmp-project.html)
+- [Parallel batch media processing with FFmpeg and Python](https://akpw.github.io//articles/2014/11/24/batch-media-processing-ffmpeg-python.html)
+
+## Description
+
+Batch management of media files, from base properties such as file names through tags / artwork metadata to advanced operations on the media content.
+
+The project is written in [Python 3.4](https://www.python.org/download/releases/3.4.1/) and currently consists of three main command-line utilities. All three share the core concept of various transformations applied to generated stream of file system entries, and consequently they also share the same set of global options. A quick way to check on that is to run:
+```
+    $ renamer -h
+    $ tagger -h
+    $ bmfp -h
+```
+That will show the global options along with specific commands for each tool. Getting more info on the commands level can be done using a similar approach, e.g. to learn more about the `renamer replace` command:
+```
+    $ renamer replace -h
+```
+By default the tools always visualize targeted changes (whenever possible) before actual processing.
+
+A little bit more details on each utility:
+
+[**Renamer**](https://github.com/akpw/batch-mp-tools#renamer) is a multi-platform batch rename tool. In addition to common operations such as regexp-based replace, adding text / dates, etc. it also supports advanced operations such as expandable template processing during replace, multi-level indexing across nested directories, flattening folders, organizing files by type or date, etc. The enhanced print command now supports virtual views to preview organization without moving files.
+At its simplest, Renamer can be used to print out the content of current directory:
+```
+    $ renamer
+```
+Without command arguments, renamer uses `print` as the default command. This is also the case for both `$ tagger` and `$ bmfp`, with each of the tool showing info which is relevant to its intended purpose.
+A little bit more advanced, to see what's lurking at the 7th nested folder level:
+```
+    $ renamer print -sl 7
+```
+For multi-level indexing of all M4A files in all sub-directories of the current folder:
+```
+    $ renamer -r -in '*.m4a' index
+    /Desktop/_test/Gould
+      |-/1
+        |- 01 Glenn Gould French Suite 1 In D, BWV812 1 Allemande.m4a
+        |- 02 Glenn Gould French Suite 1 In D, BWV812 2 Courante.m4a
+        |- 03 Glenn Gould French Suite 1 In D, BWV812 3 Sarabande.m4a
+      |-/2
+        |- 01 Bach, Johann Sebastian French Suite 5 In G Major, BWV816 1 Allemande.m4a
+        |- 02 Bach, Johann Sebastian French Suite 5 In G Major, BWV816 2 Courante.m4a
+        |- 03 Bach, Johann Sebastian French Suite 5 In G Major, BWV816 3 Sarabande.m4a
+      |-/_Art
+    6 files, 3 folders
+
+    Proceed? [y/n]:
+```
+Sequential indexing is supported as well using the `-sq` switch.  An important detail here, by default Renamer is visualizing the targeted changes and asking for permission to proceed before actually doing anything.
+
+For organizing files by media type:
+```
+    $ renamer organize -b type
+    ~/Downloads
+      |- image/
+        |- photo1.jpg
+        |- screenshot.png  
+      |- video/
+        |- movie.mp4
+      |- audio/
+        |- song.mp3
+    
+    Proceed? [y/n]:
+```
+
+Or preview how files would look organized by date without moving them:
+```
+    $ renamer print -b date --date-format "%Y/%m"
+    Virtual view by date:
+    ~/Downloads
+      |- 2025/
+        |- 01/
+          |- document.pdf
+          |- photo.jpg
+        |- 02/
+          |- video.mp4
+```
+
+
+
+[**Tagger**](https://github.com/akpw/batch-mp-tools#tagger) manages media metadata, such as tags and artwork. Setting those in selected media file over multiple nested directories now becomes a breeze, with just a few simple commands working uniformly over almost any practically imaginable audio / video media formats. While easy to use, Tagger supports advanced metadata manipulation such as regexp-based replace, expandable template processing, etc. For example, to set the title tag to respective file names followed by the values of track and tracktotal tags:
+```
+    $ tagger -r -in '*BWV816 1*' set --title '$filename, $track of $tracktotal'
+    Targeted after processing:
+    /Desktop/_test/Gould
+      |-/1
+      |-/2
+        |- Bach, Johann Sebastian French Suite 5 In G Major, BWV816 1 Allemande.m4a
+            Title: Bach, Johann Sebastian French Suite 5 In G Major, BWV816 1 Allemande, 1 of 26
+            Album: Bach French Suites BWV 812-817 Vol. II; Glenn Gould
+            Artist: Glenn Gould
+            Album Artist: Glenn Gould
+            Genre: Classical
+            Composer: Johann Sebastian Bach (1685-1750)
+            Year: 1994
+            Track: 1/26
+            Disk: 2/2
+      |-/Art
+    1 files, 3 folders
+
+    Proceed? [y/n]: n
+```
+The commands above show some of the available global options:  `-r` for recursion into nested folders and `-in` to select media files. In the example above just one file was selected (for the sake of output brevity), which also could be achived via using `-f` for the file source mode.
+
+
+[**BMFP**](https://github.com/akpw/batch-mp-tools/blob/master/README.md#bmfp-requires-ffmpeg) is all about efficient media content processing, such as conversion between various formats, normalizing sound volume, segmenting / fragmenting media files, denoising audio, detaching individual audio / video streams, etc. As processing media files can typically be resource consuming, BMFP is designed to take advantage of multi-core processors. By default, it automatically breaks up jobs into individual tasks that are then run as separate processes on available CPU cores.
+**BMFP is built on top of [FFmpeg](http://ffmpeg.org/download.html), which needs to be installed and available in the command line**. BMFP can be thought of as a batch FFmpeg runner, intended to make common uses of FFmpeg easy while not restricting its full power.
+
+For example, to convert all files from the above example from M4A to FLAC:
+```
+    $ bmfp -r convert -la -tf FLAC
+```
+The `-tf` switch specifies the target format, while `-la` explicitly tells BMFP to do a lossless conversion.
+
+To check on the result, lets's just use the [tagger's](https://github.com/akpw/batch-mp-tools#tagger) ability to print media files info:
+```
+    $ tagger -r -in '*BWV816 1*' print -st -ss
+    /Users/AKPower/Desktop/_test/Gould
+      |-/1
+      |-/2
+        |-  7.4MB Bach, Johann Sebastian French Suite 5 in G major, BWV816 1 Allemande.flac
+            Title: French Suite 5 in G major, BWV 816 - 1 Allemande
+            Album: Bach French Suites BWV 812-817 Vol. II; Glenn Gould
+            Artist: Glenn Gould
+            Album Artist: Glenn Gould
+            Genre: Classical
+            Composer: Johann Sebastian Bach (1685-1750)
+            Year: 1994
+            Track: 1/26
+            Disk: 2/2
+            Format: FLAC
+            Duration: 0:01:48, Bit rate: 548kb/s, Sample rate: 44100Hz, Bit depth: 16
+        |-/_backup_15Mar25_094341
+          |-  7.9MB Bach, Johann Sebastian French Suite 5 in G major, BWV816 1 Allemande.m4a
+              Title: French Suite 5 in G major, BWV 816 - 1 Allemande
+              Album: Bach French Suites BWV 812-817 Vol. II; Glenn Gould
+              Artist: Glenn Gould
+              Album Artist: Glenn Gould
+              Genre: Classical
+              Composer: Johann Sebastian Bach (1685-1750)
+              Year: 1994
+              Track: 1/26
+              Disk: 2/2
+              Format: ALAC
+              Duration: 0:01:48, Bit rate: 579kb/s, Sample rate: 44100Hz, Bit depth: 16
+      |-/Art
+    2 files, 4 folders
+    Total size: 15.2MB
+```
+From a brief glance, all looks OK. BMFP used FFmpeg to do the actual conversion, while taking care of all other things like preserving tags / artwork, etc.
+
+I will follow up with more examples and common use-cases in future blogs.
+
+
+## Brief Description of CLI Commands (use -h to expand on details for individual commands)
+### renamer
+    Batch renaming of files and directories
+      . source directory or source file modes
+      . visualises original / targeted folders structure before actual processing
+      . supports recursion, can optionally stop at specified end_level
+      . supports flattening folders beyond specified target_level
+      . supports include / exclude patterns (Unix style)
+      . display sorting:
+          .. by size/date, ascending/descending
+      . action commands:
+          .. print      Prints source directory. Enhanced with virtual organization views:
+                          $ renamer print -b type          # Preview organize by media type
+                          $ renamer print -b date -df "%Y/%m"  # Preview organize by date
+          .. flatten    Flatten all folders below target level, moving the
+                        files up at the target level. By default, deletes all empty flattened folders
+          .. index      Adds index to files and directories names
+          .. replace    RegExp-based replace in files and directories names. Supports expandable templates, 
+                        such as $dirname, $pardirname, $atime, $ctime, etc. For media files, also can process 
+                        tag-based templates such as $title, $album, $artist, $albumartist, $genre, $year, $track, 
+                        etc.
+          .. add_date   Adds date to files and directories names
+          .. add_text   Adds text to files and directories names
+          .. remove     Removes n characters from files and directories names
+          .. capitalize Capitalizes words in files / directories names
+          .. delete     Delete selected files and directories
+          .. organize   Organizes files into subdirectories based on their attributes:
+                          $ renamer organize -b type                    # By media type (image/, video/, audio/)
+                          $ renamer organize -b date -df "%Y-%m"         # By date (2025-01/, 2025-02/)
+                          $ renamer organize -b date -df "%Y/%m" -td ~/Sorted  # To target directory
+
+    Usage: renamer [-h] [-d DIR] [-f FILE] [Global Options] {Commands} [Commands Options]
+    Global Options:
+      Input source mode:
+        [-d, --dir]                 Source directory (default is the current directory)
+        [-f, --file]                File to process
+
+      Recursion mode:
+        [-r, --recursive]           Recurse into nested folders
+        [-el, --end-level]          End level for recursion into nested folders
+
+      Filter files or folders:
+        [-in, --include]            Include: Unix-style name patterns separated by ';'
+        [-ex, --exclude]            Exclude: Unix-style name patterns separated by ';'
+                                      (excludes hidden files by default)
+        [-fd, --filter-dirs]        Enable  Include/Exclude patterns on directories
+        [-af, --all-files]          Disable Include/Exclude patterns on files
+                                      (shows hidden files excluded by default)
+      Miscellaneous:
+        [-s, --sort]{na|nd|sa|sd}   Sort order for files / folders (name | date, asc | desc)
+        [-ni, nested-indent]        Indent for printing nested directories
+        [-q, --quiet]               Do not visualise changes / show messages during processing
+
+      Commands:
+        {print, index, add_date, add_text, remove, replace, capitalize, flatten, delete, organize, version, info}
+        $ renamer {command} -h  #run this for detailed help on individual commands
+
+### tagger
+###### Supported formats:
+'MP3', 'MP4', 'M4A', M4V', 'AIFF', 'ASF', 'QuickTime / MOV',
+'FLAC', 'MonkeysAudio', 'Musepack',
+'Ogg FLAC', 'Ogg Speex', 'Ogg Theora', 'Ogg Vorbis',
+'True Audio', 'WavPack', 'OptimFROG' <p>
+Support via FFmpeg: 'AVI', 'FLV', 'MKV', 'MKA'
+
+    Batch management of media files metadata (tags & artwork)
+      . source directory / source file modes
+      . visualises original / targeted files metadata structure
+      . supports recursion, can optionally stop at specified end_level
+      . include / exclude patterns (Unix style)
+      . display sorting:
+          .. by size/date, ascending/descending
+      . action commands:
+          .. print      Prints media info
+          .. set        Sets tags in media files, including artwork, e.g:
+                                $ tagger set --album 'The Album' -art '~/Desktop/art.jpg'
+                            Supports expandable templates. To specify a template value,
+                            use the long tag field name preceded by $:
+                                $ tagger set --title '$title, $track of $tracktotal'
+                            In addition to tag fields templates, file system names are also supported:
+                                $ tagger set --title '$filename' --album '$dirname' --artist '$pardirname'...
+          .. copy       Copies tags from a specified media file
+          .. index      Indexes Track / Track Total tags
+          .. remove     Removes tags from media files
+          .. replace    RegExp-based replace in specified tags
+                          e.g., to remove the first three characters in title:
+                                $ tagger replace -tf 'title' -fs '^[\s\S]{0,3}' -rs ''
+          .. capitalize Capitalizes words in specified tags
+          .. detauch    Extracts artwork
+
+    Usage: tagger [-h] [-d DIR] [-f FILE] [Global Options] {Commands} [Commands Options]
+    Global Options:
+      Input source mode:
+        [-d, --dir]                 Source directory (default is the current directory)
+        [-f, --file]                File to process
+
+      Recursion mode:
+        [-r, --recursive]           Recurse into nested folders
+        [-el, --end-level]          End level for recursion into nested folders
+
+      Filter files or folders:
+        [-in, --include]            Include: Unix-style name patterns separated by ';'
+        [-ex, --exclude]            Exclude: Unix-style name patterns separated by ';'
+                                      (excludes hidden files by default)
+        [-fd, --filter-dirs]        Enable  Include/Exclude patterns on directories
+        [-af, --all-files]          Disable Include/Exclude patterns on files
+                                      (shows hidden files excluded by default)
+      Miscellaneous:
+        [-s, --sort]{na|nd|sa|sd}   Sort order for files / folders (name | date, asc | desc)
+        [-ni, nested-indent]        Indent for printing nested directories
+        [-q, --quiet]               Do not visualise changes / show messages during processing
+
+      Commands:
+        {print, set, copy, index, remove, replace, capitalize, detauch, version, info}
+        $ tagger {command} -h #run this for detailed help on individual commands
+
+### bmfp (requires [FFmpeg](http://ffmpeg.org/download.html))
+    Batch processing of media files
+      . Uses multiprocessing to utilize available CPU cores
+      . source directory / source file modes
+      . recursion to specified end_level
+      . include / exclude patterns (Unix style)
+      . action commands:
+          .. print          Prints media files
+          .. convert        Converts media to specified format
+                                For example, to convert all files in current directory
+                                    $ bmfp convert -la -tf FLAC
+          .. normalize      Nomalizes sound volume in media files
+                                Peak normalization supported, RMS normalizations TBD
+          .. fragment       Extract a media file fragment
+          .. segment        Splits media files into segments
+                                For example, to split media files in segments of 45 mins:
+                                    $ bmfp segment -d 45:00
+          .. silencesplit   Splits media files into segments via detecting specified silence
+                                    $ bmfp silencesplit
+          .. cuesplit       Splits media files into parts with specified output format,
+                            according to their respective cue sheets
+                                For example, to split all cue files in the current directory
+                                    $ bmfp cuesplit -tf mp3
+          .. denoise        Reduces background audio noise in media files
+
+          .. adjust volume  TDB: Adjust audio volume
+          .. speed up       TDB: Uses Time Stretching to increase audio / video speed
+          .. slow down      TDB: Uses Time Stretching to increase audio / video speed
+
+    Usage: bmfp [-h] [-d DIR] [-f FILE] [GLobal Options] {Commands}[Commands Options]
+      Input source mode:
+        [-d, --dir]                 Source directory (default is the current directory)
+        [-f, --file]                File to process
+
+      Recursion mode:
+        [-r, --recursive]           Recurse into nested folders
+        [-el, --end-level]          End level for recursion into nested folders
+
+      Filter files or folders:
+        [-in, --include]            Include: Unix-style name patterns separated by ';'
+        [-ex, --exclude]            Exclude: Unix-style name patterns separated by ';'
+                                      (excludes hidden files by default)
+        [-fd, --filter-dirs]        Enable  Include/Exclude patterns on directories
+        [-af, --all-files]          Disable Include/Exclude patterns on files
+                                      (shows hidden files excluded by default)
+
+        Target output Directory     Target output directory. When omitted, will be
+        [-td, --target-dir]         automatically created inside the parent level of
+                                    the input source. For recursive processing,
+                                    the processed files directory structure there
+                                    will be the same as for the original files.
+      FFmpeg General Output Options:
+        [-ma, --map-all]            Force including all streams from the input file
+        [-cc, --copy-codecs]        Copy streams codecs without re-encoding
+        [-vn, --no-video]           Exclude video streams from the output
+        [-an, --no-audio]           Exclude audio streams from the output
+        [-sn, --no-subs]            Exclude subtitles streams from the output
+        [-fo, --ffmpeg-options]     Additional FFmpeg options
+
+      FFmpeg Commands Execution:
+        [-q, --quiet]               Do not visualise changes / show messages during processing
+        [-se, --serial-exec]        Run all task's commands in a single process
+
+      Commands:
+        {print, convert, normalize, fragment, segment, silencesplit, cuesplit, denoise, version, info}
+        $ bmfp {command} -h  #run this for detailed help on individual commands
+
+
+## Installing Development version
+- Clone the repo, then run: `$ python -m pip install .`
+
+## Running Tests
+
+**Using pytest (recommended):**
+```bash
+$ pytest -v --tb=short                              # Run all tests with verbose output
+$ pytest tests/                                     # Run all tests  
+$ pytest tests/fs/test_fs_organize.py              # Test organize functionality
+$ pytest tests/fs/test_fsutils.py                  # Test core filesystem utilities
+$ pytest tests/cli/test_renamer_cli.py             # Test renamer CLI
+$ pytest -k "test_organize"                        # Run tests matching pattern
+```
+
+**Using unittest (fallback):**
+```bash
+$ python -m unittest discover tests -v             # Run all tests with verbose output
+$ python -m unittest tests.fs.test_fs_organize     # Run specific test module
+```
+
+
+
+
+
+