There is no license information available for the latest version (0.12.2) of this package.

A batch rename tool for media files

0.12.2 2018-04-29 18:07 UTC


pipeline status coverage report


A batch rename tool for media files (audio, video and images). Move, or create an hardlink, with a new name based on meta information extracted from the file.


mediasort source/ destination/
  • destination is optional.
  • --format=":year/:month/:date :time" default format of new filenames

Common options

  • -r for recursive
  • --link for using hardlinks
  • -n for no interaction (autoconfirm)
  • -q quiet
  • See more options
├── IMG_20170331_180220.jpg
├── IMG_20170802_183621.jpg
├── IMG_20170802_183630.jpg
├── IMG_20170802_183634.jpg
└── VID_20171002_084709.mp4

Files are moved into destination/ (create hardlinks with --link)

└── 2017
    ├── 03 - March
    │   └── 2017-03-31 18:02:20.jpg
    ├── 08 - August
    │   ├── 2017-08-02 18:36:22.jpg
    │   ├── 2017-08-02 18:36:30.jpg
    │   └── 2017-08-02 18:36:35.jpg
    └── 10 - October
        └── 2017-10-02 08:47:09.mp4


See the wiki page.


  • PHP 7.0.24+
    • ext-exif. For precise meta information (dates), and more.
    • ext-phar For composer (build from source), or to execute phar file

Arch Linux

Mediasort is available through AUR: mediasort.

Composer (global)

composer global require eigan/mediasort



--format            Reformat the path
                    Example: --format=":year/:month/:date :time" (default)
                    Possible formatters:
                        :original (original path)
                        :date (alias ":year-:monthnum-:day")
                        :time (alias ":hour::minute::second")
                        :month (alias ":monthnum - :monthname")
                        :ext (not needed, always appended)
                        :name (original filename)
                        :dirname (name of original parent directory)
                    Exif is mostly used if available

-r, --recursive     Look for files recursively in source

--only              Only files with the given extensions
                    Example: --only="jpg,gif"
--only-type         Only files with the given filetype
                    Example: --type="image,video,audio" (default)
--link              Create hardlink instead of moving

-v                  Show additional information
-vv                 Show even more info (result for all formatters)

-n                  Disable interaction (Will autoconfirm)

--ignore            Ignore certain file extensions
                    Example: --ignore="db,db-journal"
--dry-run           Do not execute move/link

--no-exif           Do not read exif meta information

--log-path          Specify where to put mediasort.log
                    Default: null (no logging)

Note: shortcuts cannot be combined, -nv will not work. This is a limitation of the CLI library used.



For a structure with 3494 files (41.6GB), it took 0.29 seconds.

Date and time from files

Date is retrieved from files in the following order:

  • exif meta information (image)
  • id3 meta information (video/audio)
  • Date in path matching pattern:
    • YYYY-MM-DD HH.mm.ss
    • YYYY-MM-DD HH:mm:ss

If no dates are found, then the format fails and file is skipped.

File name collision

When a file is identical, it gets ignored, otherwise we append an index to the filename.

Step by step (internal)

- Takes two arguments
  - `source`: Read files from here
  - `destination` (optional): Directory to populate. If not set, uses `source`
- Takes several options, see list above

-  Start look for media files in source
  - Skip files if:
    - Not a media file
    - Filtered by options
    - Is in built in ignorelist:
      - .nomedia, @eaDir
  - Generate a name based on the `--format` option
  - Check if the generated name exists
    - Check if duplicate
    - append an available "index" to the name
  - Move or link the media file into destination


Remove empty directories

find . -type d -empty -delete


These are things I would like to do sometime, but I don't really need right now.

  • Split code into more files.
  • More formatters
    • :type-s
    • :exif(ExifProp)
    • :path full original path
  • --filter=":size>10 & :name~/regex/ & :weekday=monday
  • I18n
  • Test Mac (travis) / Windows (tea-ci)
  • symlink