Documentation

You have a lot of options to rename files. You can use bash and terminal. Or you can find very user-friendly apps with complicated UI, a lot of buttons and options. But if you are a developer, you probably want to have a simple and fast way to rename files. That is the reason why I made RenameNinja. It allows you to run Regular Expression to extract the fields. Allows you to run JavaScript to run any code you want to modify the fields. And provides a final pattern where you can combine all the fields, extracted and created by you.

It is basic but very powerful. Real Ninjas can do a lot with a few tools.

Features

• Extract fields from the file name using Regular Expression.
• Modify the fields with custom JavaScript code. Use fields object to access the fields. Use context object to store context for all files (useful for custom numbering).
• Construct new file name using the fields and custom strings.
• Rename files, and Undo for rename operation.
• App extracts fields for images/photos (EXIF), video and audio files (see FAQ for the list of available fields).
• Preview of the new file names.
• Highlights the available fields, and highlights (red) fields that are not available for the file.
• See all available fields in real time for each file by navigating in the TreeView.
• App saves last 10 rename sessions, so you can switch between them (Recent menu button).
• Rename button is available only when each file did not fail the regular expression or/and JavaScript code.
• App can auto-update itself (using Sparkle framework).
• Quicklook preview for original files (double-click the file name).

Installation and configuration

1. Download application using the link above. Unzip the application and move it to the Applications folder.

2. Launch the application.

3. Drop files in the window or open files.

4. Optionally, write Regular Expression to extract fields. Using Swift Regular Expressions, you can extract fields, similar to GX(?P<number>\d+) (Example of GoPro video files) to extract numbers from the file name. The regular expression must match the whole file name (excluding extension).

5. Optionally, write JavaScript code to modify the fields. You can use any JavaScript code to modify the fields. For example, for video fields we will format video.duration to HH-MM-SS format, and save as new string video.duration.str.

fields["video.duration.str"] = formatVideoDuration(fields["video.duration"])

function formatVideoDuration(str) {
  // 1. Read and parse the duration (in seconds)
  const totalSeconds = parseInt(str, 10);
  const hours   = Math.floor(totalSeconds / 3600);
  const minutes = Math.floor((totalSeconds % 3600) / 60);
  const seconds = totalSeconds % 60;
  const pad2 = n => String(n).padStart(2, "0");
  return `${pad2(hours)}-${pad2(minutes)}-${pad2(seconds)}`;
}

6. Finally, we will construct new file name using the fields. You can use any field, including the ones you created in JavaScript. We can use the format {date} video-{number} {video.duration.str}, where we use custom strings and reference to the fields.

7. Press Rename button to rename files.

Release history

1.1 - 2025-05-09

• Global context for JavaScript to reference fields for all files
• Add field row (numbered from 1 to …)
• Insert placeholder menu under Result Pattern to quickly reference fields
• Double-click the original file name for preview

1.0.1 - 2025-05-08

• Metadata for PDF
• Metadata for Office documents (Word, Excel, Numbers, Pages). Extracted from Spotlight.

1.0 - 2025-05-08

• Initial release

FAQ

How long is the trial?

Unlimited. I really like the idea to provide the app for free, and if you have an opportunity to support the development, please do it. Otherwise, it will show you a trial popup every time you will start a new rename session. But would not limit the functionality.

How can I purchase the license?

Purchase it from Loshadki Web Store.

I have a discount code, how do I use it?

Go to Loshadki Web Store, choose the product you want to purchase, and enter the discount code in the checkout page.

Not sandboxed app, does it mean unsafe?

The developer signs our application, as long as you download it from our website, you can be sure that it is safe.

Which OS versions are supported?

macOS Sonoma (14) and later. The application is built using SwiftUI, so it is not compatible with older versions of macOS.

How can I implement custom numbering for files?

JavaScript provides a global context for all files, where you can store custom fields. For example, if you want to implement custom numbering instead of what is provided by row, you can do it like this:

context["fileno"] = (parseInt(context["fileno"] ?? "0") + 10);
fields["fileno"] = context["fileno"];

Where we start from 10 and increment by 10 for each file. And assign it to the field fileno. And you can use this field in the Result Pattern, for example {date} {fileno} {name}.

What fields are extracted from the files?

• filename - the name of the file
• date - the date of the file (YYYY-MM-DD)
• time - the time of the file (HH-MM-SS)
• moddate - the modification date of the file (YYYY-MM-DD)
• modtime - the modification time of the file (HH-MM-SS)
• row - the row number of the file in the list (1-based)

Image Fields:

• image.width - width of the image in pixels
• image.height - height of the image in pixels
• image.make - manufacturer of the camera (e.g., “Canon”, “Nikon”)
• image.model - model of the camera
• image.lens - lens model used to capture the image
• image.exposure - exposure time in decimal format (e.g., “0.0080”)
• image.exposure.frac - exposure time in fractional format (e.g., “1-125” for 1/125 second)
• image.aperture - aperture value with “f” prefix (e.g., “f2.8”)
• image.fnumber - f-number value without prefix (e.g., “2.8”)
• image.iso - ISO sensitivity value
• image.focal_length - focal length in millimeters
• image.focal_length_35mm - equivalent focal length in 35mm format
• image.date - original capture date from EXIF data (YYYY-MM-DD)
• image.time - original capture time from EXIF data (HH-MM-SS)
• image.latitude - GPS latitude in decimal degrees
• image.longitude - GPS longitude in decimal degrees
• image.altitude - GPS altitude in meters

Video files:

• video.duration - length of the video in seconds
• video.width - width of the video in pixels
• video.height - height of the video in pixels
• video.fps - frame rate of the video (frames per second)
• video.resolution - categorized resolution (“8K”, “4K”, “1080p”, “720p”, “480p”, or “SD”)
• video.audio_tracks - number of audio tracks in the video
• video.date - creation date of the video (YYYY-MM-DD)
• video.time - creation time of the video (HH-MM-SS)

Audio files:

• audio.duration - length of the audio in seconds
• audio.title - title of the audio track
• audio.artist - artist/performer of the audio track
• audio.album - album name
• audio.genre - genre of the audio track
• audio.track_number - track number within album
• audio.disc_number - disc number for multi-disc albums
• audio.year - release year of the audio
• audio.sample_rate - sample rate in Hz
• audio.bit_depth - bit depth (8, 16, 24, or 32)
• audio.channels - number of audio channels
• audio.channel_type - audio channel configuration (“mono”, “stereo”, or “multi”)

PDF files:

• pdf.title - title of the PDF document
• pdf.author - author of the PDF document
• pdf.subject - subject of the PDF document
• pdf.creator - software used to create the PDF document
• pdf.producer - software used to produce the PDF document
• pdf.date - creation date of the PDF document (YYYY-MM-DD)
• pdf.time - creation time of the PDF document (HH-MM-SS)
• pdf.moddate - last modification date of the PDF document (YYYY-MM-DD)
• pdf.modtime - last modification time of the PDF document (HH-MM-SS)
• pdf.page_count - number of pages in the PDF document

Office files (Word, Excel, PowerPoint, Numbers, Pages, Keynote):

Spotlight provides data, so it may not be available for all files.

• doc.title - title of the document
• doc.authors - author of the document
• doc.creator - creator of the document
• doc.desciption - creator of the document
• doc.subject - subject of the document

Privacy Policy

We believe very strongly in our customers’ right to privacy. Our customer records are not for sale or trade, and we will not disclose our customer data to any third party except as may be required by law.

Any information that you provide to us in the course of interacting with our sales or technical support departments is held in strict confidence. This includes your contact information (including, but not limited to your email address and phone number), as well as any data that you supply to us in the course of a technical support interaction.

Support

Please email us any suggestions, ideas, questions or discover bugs to support+renameninja@loshadki.app