Filename Tool, v1.19.10

General Idea

Pipsqueak’s Filename Tool is an opinionated app we built to support our own workflow. We manage hundreds of thousands of files for ourselves and clients and, over time, we’ve developed practical techniques for naming files. Rather than write the world’s most boring book, we baked those techniques into this tool. We haven’t found anything else that tackles this particular problem, so we opened our tool to everyone. Perhaps better filenames can help make the world a little less chaotic!

We prefer filenames that are long, descriptive, and packed with useful details, e.g.

. If you favor terse filenames, e.g. ANNALET1.PDF, this tool isn’t aimed at you. If you’re content with filenames generated automatically by your camera or phone, e.g. IMG_3499.JPG, then this tool may feel like overkill. But if you care about the filenames you give to your files, this tool might be useful.

The Filename Tool is a free web tool that helps you create clear, descriptive, archival filenames. The tool guides you toward structured filenames that can include dates, descriptions, authors, cameras, versions, project information, and more — making your files easier to recognize, sort, and retrieve. The tool also handles the small but important fiddly bits for you (for example, replacing spaces with underscores) and runs entirely on your own device, so your work remains private and secure.

It’s safe to experiment. Paste in a filename or drag in a file, click around, try things out, and get comfortable with the tool. The tool never renames your files automatically; nothing changes unless you do it yourself. You can click any button or drag in any file without altering filenames. Once loaded, the tool can run offline, and none of the data you enter ever leaves your computer. There are no ads, hidden trackers, or marketing cruft.

Using the tool is straightforward: build a filename with the app, copy it, and then rename your file manually or use the filename to create a new file. You can start fresh, or drag in an existing file — or paste its filename — into the “Matcher” panel.

You don’t need to fill in every field in the tool — only enter what matters to you. You can make a simple filename or a complex one. While the tool enforces filenaming rules, the content is up to you. Files rarely exist in isolation; a project usually consists of many files. When those files are named well, the relationship of each to the others is clear.

🎨 For Designers:

Keep your projects tidy. The Filename Tool makes filenames that carry client, version, and status details — so you’ll never wonder which logo file is the right one again. When the inevitable change orders come in, you can backtrack from the output file to the correct revision of the original creation file. Your clients and collaborators may appreciate your professionalism as you handoff well-named assets, and your future self will definitely thank you when you’re digging through old files.

📝 For Lawyers and Writers:

Keep your documents and writing project folders organized. The Filename Tool helps you create filenames that include important details like date, project name, and revision number — so you’ll always know which draft is which, and which pdf came from which docx file. Was that contract executed? The answer is right there in the filename.

📸 For Photographers:

Image files move through a workflow, starting from the camera, then grading, then the image editor, and finally to an output that may either be uncompressed or prepared for the web. In the process, they may be cropped or scaled. They may go through rounds of revisions and corrections. The Filename Tool builds filenames with dates, cameras, dimensions, revisions, todos, flags, and compression information — keeping track of the steps in your workflow and keeping your photo library consistent and easy to search. We’ve felt the pain of spending hours tagging images in a media manager only to have that software go belly up. By embedding key info right in the filename, your work is part of your archive, no matter what software you use. If your file is still around in a hundred years, the information you included in the filename will be too.

🎬 For Production Teams:

Track every scene, shot, and take without a spreadsheet. The Filename Tool’s Logging Panel lets you embed production details right into the filename — that keeps them portable, sortable, and always tied to the media. Filenames produced with the tool never have spaces or illegal characters, so they don’t break pipelines. And because the tool can be adopted by distributed teams, it’s easier for everyone to follow a consistent naming convention.

🌳 For Archivists:

Whether you’re preserving historical documents, family records, or conducting genealogical research, clear filenames are essential to keep track of materials across generations. The Filename Tool helps you build filenames that capture dates, people, places, and project details in a consistent structure — so you’ll never lose track of which file is which. Organizing scanned photos, census records, and correspondence with strong filenames helps ensure your archive remains coherent and accessible into the future.

📁 For All Users:

A good filename lets you skip opening the file to figure out what it is. When you’re dealing with a lot of files, that’s a huge time saver. No more Final_Final_v2.xlsx chaos. The Filename Tool helps you create descriptive, consistent filenames that make files easier to find, share, and archive.

Matcher Panel: Use Existing Files

The Matcher Panel is where you start if you have an existing file that you want to rename or use as the basis for renaming another file. You can paste in a filename or drag a file from your computer into the Matcher. The tool will parse the filename, or extract information from a dragged file, and use that to fill in the fields in the other panels. You can then adjust any of those fields and copy out the new filename.

The Matcher Panel works best with filenames previously created with this tool. It also works with some, but not all, camera original files that are dragged in. It also might work a little with other filenames; the tool will do its best, removing spaces and figuring out which text belongs in what fields. If the filename can be parsed, the tool resets all its options to match the filename. Then the filename can be adjusted in the tool and copied out again, removing all the spaces and illegal characters in the process.

If you drag in an image file, the tool will try to extract its dimensions automatically. Sometimes, it will display a preview which helps you see the width-to-height ratio. Click on an image preview to rotate it; the file dimensions will follow suit.

If you drag in a camera original file with the filename created by many (but not all) cameras, the tool will try to extract date, time, dimension, camera, and orientation information from the file. If you have a file named IMG_3499.JPG, the tool might produce a filename like:

. It’s up to you to change the INFO placeholder to something descriptive, add a creator/editor, and maybe add an “original” flag. The final filename might look like: .

Be aware that if you paste in a filename (or drag in a file), make changes elsewhere using the tool, and then edit the filename in the Matcher paste field, the tool will treat the edited filename as if it was newly pasted and will overwrite your previous changes. There's an edit button to try to stop you from doing this accidentally. The filename displayed in the pasted filename field stays as it was when pasted or dragged and doesn’t change as the tool’s options are modified. To see the filename as modified, look at the gray “result” filenames at the bottom of each panel. They’re all synchronized and update immediately with your changes. And if you click on them, they copy to your clipboard. You can also look at the Results Panel for the final filename and its various subparts.

There’s a Duplicate Matcher at the bottom of the app for convenience. You can paste a filename or drag a file in there too. It stays in sync and works identically to the top Matcher.

Dimensions Panel

The Dimensions Panel allows you to specify the width and height of the original file. In the filename, dimensions are always width first, followed by height; in the middle is an “x” character (e.g., 1000x500). You can enter these values manually or use the extracted dimensions from an image file. If you adjust the percentage dropdown, you can scale the dimensions proportionally. You can enter either a new width or a new height (bottom set of inputs) and the other will be filled in automatically. Note: dimensions use the x alphabet character rather than the more correct × multiplication sign because the latter is not universally supported in filenames.

The Rounding checkbox rounds the dimensions to the nearest whole number when it would otherwise be half a pixel. If the original width is an odd number and you are scaling it by 50%, the rounding checkbox comes in handy.

To work on a group of files from the same device, set the “Default Device” from the dropdown in this panel. We don’t have every device by a longshot, but if your device happens to be there, select the device from the dropdown and it will fill in the dimensions, format, and camera fields, and save that information between sessions. This is just a little time-saving helper when working with many files of the same type; you can always fill in those fields manually.

Units are usually in pixels, but if you use another unit — e.g. inches — for the original, a resolution input field will appear (if your units use it), and you’ll get corresponding pixels at a set resolution in the “New Width” and “New Height” fields. For example, if you choose 8x10 inches at 300 resolution per inch, you'll get 2400x3000 pixels in the bottom “New Width” and “New Height” fields. Units are reset to pixels on each file change.

The “Workflow Defaults Settings” section lets you set the default extension when the app is loaded. It also lets you set the default extensions — they have to be a recognized format — for the modified, output, and web steps when you use the Default Workflow for Images buttons. Finally, you can set the default web compression value for the workflow web step. If you prep a lot of web images, set your defaults once — the tool remembers them between sessions on the same computer and browser. The initial workflow defaults assume you use Photoshop (psd) to edit files, and use jpg as the format for originals, output, and web images. If you use something else, change the defaults. And, of course, for any individual file, you can always change the format, even to an unknown extension.

Details Panel

Other than dimensions, date, time (or sort), and flags, this panel contains the bulk of the information used in the filename. You’ll do the majority of your filenaming work in this panel, keeping in mind that you can skip most fields; the Format is the only one required and the two basename fields are the most important. The tool enforces the fiddly bits of filenaming that make the filename parsable by the tool. Dates must be in ISO 8601 format, or a subset. Hyphens separate chunks of content and spaces are replaced with underscores. Creator and Camera fields are in a particular form enforced by the tool. Reference numbers can’t have characters in them. Extensions are always in lowercase. And so on.

The Details Panel covers the essentials: date (and optional sort/time), two-part basename, format, compression, color space, versioning, creator/editor, camera, ref and version numbers. For images you can add a retina suffix (@2x), and for formats recognized as time-based, you can set the duration.

Checkboxes across the app are disabled when the field they control is empty. For example, if there are no dimensions, the “Use Dimensions?” checkbox is disabled. If you enter dimensions, the checkbox becomes enabled and checked automatically. If you then uncheck the box, the dimensions are not used in the filename. There are many other checkboxes in the tool that work similarly.

File Date

Dates must be in ISO 8601 format: YYYY-MM-DD with leading zeros, e.g. 2025-09-07. In a folder of images, these will sort the files correctly in chronological or reverse chronological order. An ISO 8601 date eliminates MM-DD-YY or DD-MM-YY ambiguity. Dates are usually the creation date of a file, but if that date needs to be estimated, or the date is when the file was modified or received, there are nearby radio buttons to make that clear. Uncheck the Use Date box if you don’t want to use a date for a file; commonly the date is not used on web image files, for example.

A date range can be specified using a second date. The two dates can be separated by “to”, “thru”, “through”, or “and”, e.g. 2025-06-01 to 2025-06-30. A date can be just the year, or just the year and month. For example, a date can be 2025-06.

Sort/Time

A sort or time value is optionally appended after the date. A sort number’s length is a minimum of three numeric digits, leading zeros will be used to pad it. A time is exactly six digits (HHMMSS) in 24 hour format. If the value is six digits, then the labels change to “time”, otherwise “sort”. The incrementer − and + buttons do what you’d expect. The “Sort First” checkbox will optionally place the sort value before the date at the beginning of the filename. This can be helpful, for example, to force a sort order when creating a slideshow out of photos taken on different dates. Sort First isn’t available for time. Even if a sort or time is entered, the Use Sort? (or Use Time?) checkbox can remove it from the filename.

File Basename

The basename is important and is used by almost every filename; it’s where you describe the contents of the file. The basename consists of two fields in the tool. When you’re writing in the fields, you can use either and put hyphens where you like. On a matched file, the part up to the first hyphen is placed in the first field and the rest of the basename is in the second field. Often the first field is used to identify the project and the second field identifies particulars about this file. Some characters are illegal in filenames, or because they interfere with other features of this tool (e.g. equal signs used for logging), and cannot be typed. If you type content in both fields, they will be separated by a hyphen.

We recommend using descriptive file basenames that convey the content and purpose of the file. This makes it easier to search for files later or look through a folder of files and find what you need. We like to order information from bigger to smaller categories in the file basename, separated by hyphens. This helps maintain a clear hierarchy and makes it easier to find specific details. The client initials or other short descriptor often comes first, followed by a project name and then specific information about the file, e.g. “UCLA-Logo-Page Topper”. We use title case, but you don’t have to. Once the other fields and custom flags are added, the whole filename tells the rest of the story:

2025-08-20-UCLA-Logo-Page_Topper-CW-proxy-output-from_illust-for_web-unapproved-fgGreen-bgTrans-32-1000x500-v02.png

There’s an advanced feature in the basename field. At the end, you can use standard tags for shots and, when the file is parsed again, they will remain with the basename field. These tags are: 2Shot, Aerial, BG, CG, CU, DAY, Detail, ECU, EFX, ELS, FG, FS, Group, INT, LS, MCU, MLS, MO, MS, NIGHT, OTS, POV, SFX, VFX, VO, VWS, Wide, WS, XCU, and XLS.

For certain default camera files, the tool will add the INFO place­holder in the first basename field. It’s intended that you change it.

Logging Section

There’s a button to open and close the Logging Section. Logging information is used by production companies to organize their footage. Think of what might be written on a slate: “Scene 34, Take 1.” In a filename, logging information is always separated from the rest of the file information with a pair of equal signs. See the “Logging Section”.

Format^*

This is a dropdown that chooses the extension for the file. This is a required field. The dropdown allows you to search for a particular extension, filter the list by file type, choose from recent choices, or just scroll through the alphabetical list. It defaults to the default format (changable in the Dimensions Panel’s Workflow Defaults Settings) if you’re starting from scratch, otherwise it uses the format (extension) of a dragged or pasted-in file. Extensions are always rendered in lowercase in the filename you build.

Compression Type & Quality

The choices in this dropdown change depending on the Format chosen. Some file formats don’t use compression; you can leave it “unspecified” or uncheck the “Use Compression” checkbox. But, when you choose an option, the “Use Compression” checkbox will automatically become checked.

Color Space/Profile

The choices in this dropdown also change depending on the Format chosen. If you don’t wish to include this information in a filename, leave it “unspecified” or uncheck the “Use Color Space” checkbox.

Retina Suffix

This is used for web image files and will add an optional retina suffix in the form of “@2x” to the end of the filename before the extension. In the “Dimensions Panel”, if you take a large image and sufficiently shrink its size in New Width and New Height, you’ll be shown a set of dimensions appropriate for different retina images. For example, if you start with 3000x3000 and choose 10%, the New Width and Height will be 300x300; you'll also be shown Retina Version @2x 600 × 600, Retina Version @3x 900 × 900, Retina Version @4x 1200 × 1200, and Retina Version @5x 1500 × 1500. When the numbers are not as even, this can be a handy guide.

Hour/Minute/Second Control

When a time-based video or audio format is chosen, an hour/minute/second input control replaces Retina Suffix. A video length of 49 seconds will be shown in the filename as 0m49s while 1 hour, 2 minutes, and 3 seconds is 1h2m03s. The incrementer − and + buttons do what you’d expect.

Creator/Editor

This is the person (or people) who created or edited the file. To make a filename that can be parsed with this tool, this should be either uppercase initials, e.g. “CW” or “CRW”, first initial and last name, e.g. “CWerby”, or a full name prefixed with “by”, e.g. “by Christopher Werby”. If there are two or more artists, a plus sign can be used between them. If you write a full name with a space, but forget the "by", the tool will add it for you when you move focus away from the field.

Our own convention is to use the photographer’s name (or initials) for camera original files, and the modification editor’s name (or initials) for corrected files.

Camera

Camera is meant broadly — it’s the equipment used to capture any computer-based media, audio, or video. The tool has an internal list of cameras it recognizes. If it doesn’t recognize the camera or brand, a red box will surround the field. When you have a red box and you move focus from the field, the tool will add “Cam” as a prefix to make it legal. You can always use the word “Cam” or “Camera” followed by a number or word if your camera make or model isn’t recognized.

Ref

This is a number associated with the file. It can only consist of numeric digits of any reasonable length. If the original filename is IMG_7687.CR2, then 7687 would be the ref number. When images go from original → corrected → output → web using the “Default Workflow Buttons,” the ref is preserved across all versions to provide a search string so that all can be found. Sometimes an image needs two refs, e.g. an image composite; you can enter the two refs separated by a plus sign. This works for three or more refs too.

Version

The version is a minimum of two numeric digits, a leading zero will be prefixed if necessary. It is appended near the end of the filename and always has a lowercase “v” before it, automatically added.

The “Use” Checkboxes

These checkboxes allow you to enable or disable the use of certain metadata in the filename. For example, you can uncheck “Use Dimensions” and the dimensions won’t be included. These checkboxes start disabled but turn on automatically when you edit the corresponding input fields. If you add a ref number, the Use Ref checkbox will become active and be checked automatically. Similarly, for “Use Artist” and “Use Camera,” if there’s nothing in the corresponding input field, the checkmark will be disabled.

Note that the checkboxes for “Use Date,” “Use Sort/Time,” and “Sort First” are up near the date input fields to which they refer at the top of the Details Panel. “Use Dimensions” is both in the Dimensions Panel and with the other checkboxes in the Details Panel; the two mirror each other.

The Default Workflow for Images Buttons

There are four buttons in this group: “Original”, “Corrected”, “Output”, and “Web”. Each of these make choices about what information to turn on and off that are appropriate to a different step in an image processing workflow. For example, if you press Original, the “original” flag will turn on and the version will be turned off; if there’s no basename, INFO will be added to remind you. Similarly, if there’s no reference number, 9999 will be displayed; change it. If you press Corrected, the original flag will turn off and the version number will be turned on. You can always override these choices in any way you please. The buttons use the defaults set in the “Dimensions Panel”. Copy a camera original sample file,

2025-06-02-Modern_Penthouse-Living_Area_and_Kitchen-INT-by_Isabella_Rosa-5D_Mark_IV-2969-original-select-UNC-6720x4480.jpg

and paste it into the “Matcher” field. Then press each of the Default Workflow buttons to see how they alter the filename.

Buttons for Tools

These should be self explanatory. “Date to Today” resets the date to today. “Flip Dimensions” swaps width for height.

Buttons for Resets

“Reset Flags” clears all the currently chosen flags. “Reset All But Dim” resets everything except for the dimensions. “Reload” reloads the page and resets everything except for items in local storage.

Rating Stars

This is a specialized feature for a particular workflow; useful when grading a folder of images and separating the wheat from the chaff. If you had a folder of photos from a wedding, you might give all the good ones a rating of one star each. Then the best of that group might get two or more stars.I think of a one-star file as better than most, and then I go up from there.

Flags Panel

The Flags Panel allows flags to be applied to filenames in a consistent way so that they fully identify the content of the file and can easily be sorted and filtered in the Finder or other file managers.

Flags make the filenames expressive without becoming chaotic. They’re grouped into broad file categories (code, docs, images, media) plus a handful of sensible filters (Grade, Modification, To Do, and Type). You can search, pick from a grid, or reuse recent choices. Some flags accept free text — like background or foreground color — so specific details make it into the name without breaking the structure.

A matched filename with flags will activate the corresponding flags in the tool. The Recents group shows the last sixteen flags chosen or matched. They persist between sessions. Flags that contain text — those with an ellipsis — retain that text so it can easily be reused.

Files are grouped broadly into four categories: code, docs, images, and media. One of the four will initially be applied as a flag filter based on your file format, although you can always choose another filter or press the “All” filter.

The four other filter categories; Grade, Modification, To Do, and Type; are a little less obvious about the flags they display. Click on each to become familiar with the filters.

Grade Filter

A judgment or status about the file’s suitability.Examples: Approved, As Sent, As Used, Select, Outtake, Unapproved, Not Used, Superseded, Trash, plus quality notes like Bad or Unfocused.

Modification Filter

What was done to the original.Examples: Cropped, Adjusted, Edited, Retouched, Filtered, Composited, Stitched, Patched, Rotated, Trimmed, Scaled, Upsize, Isolated, Shaped, Outlined.

To Do Filter

Tasks or actions that should be performed on the file. Uses present tense verbs with a “To” prefix (e.g. “To Edit” to indicate work that remains, rather than past tense flags like “Edited” used in Modifications). “Add Text” is an exception.Examples: To Crop, To Filter, To Rotate, To Patch, To Stitch, To Convert, To Annotate, To Isolate, To Trim, Add Text.

Type Filter

The file’s kind or role and its intended stage or purpose in the workflow.Examples: Photo, Video, Audio, Screenshot, Scanned, Rendered, Live Photo, RAW, Layered, Layout, Motion Graphic, Rephotographed, Recto, Verso, Original, Revision, Output, Markup; and workflow uses such as For Web, For Print, Master, Production, Intermediate, Proxy, Reference, Sample, Proof, Concept, Mockup, Mechanical, Element, Alt, Tmp, Backup, Internal, Test.

Flags display in a particular order in a filename without regard to the order in which they are selected. This helps ensure consistency between filenames. The “Backup” flag is always displayed last, for example.

There are some flags which use additional text supplied by the user. These have an ellipsis at the end. For example, the “Background Color …” flag expects that you’ll enter a color when you select it. Enter “White” or “FFF” in the text field that appears when you click it.

Results Panel

As the filename is created, it is displayed in the Results Panel. Clicking on the filename there, or the nearby “Copy” button, will copy the filename to the clipboard. The “Full Filenames” portion at the top of the Results Panel is probably what you want, but the “Other Useful Partial Filename Bits” are, well, useful too. The Results Panel, and the clickable gray “result” filename at the bottom of each panel, show realtime feedback on the filename being created so you can keep an eye on the filename as you make modifications.

Logging Section

The Logging Section was built for productions that track scene/shot/take and similar metadata. Not everyone will need this feature, but it’s useful for those who do. Open it only when it’s needed, and it will stay out of your way when it’s not. Matched files that contain logging information will automatically open and reveal logging fields populated with values.

Every production has their own approach to logging their footage, so the Logging Section is designed to be flexible and customizable, with label/value pairs, settable in any order, that can be set as defaults and are preserved between sessions. Logging information is always set off with a pair of equal signs in the filename; those delimiters are added automatically.

Labels can’t have spaces. Values can’t have hyphens, but can have spaces that are converted to underscores. Illegal characters will be stripped out. You can edit any of the labels or the values, or remove or add to them as needed.

If a matched file has logging information, the Logging Section will open automatically with the correct label/value pairs displayed. Those will be retained for the next file, or they can be cleared with the buttons in the panel. Up to fifteen label/value pairs can be set in the filename. Paste in a file containing logging information to see how it works.

Logging labels are customizable by project. The current set will be saved between sessions unless changed by user action. The user can set the local default for current labels and then restore that local default to reset subsequent changes. If a file using desired logging labels is matched with the tool, then the user can set the local defaults to the matched logging labels; this makes it easy to use different sets of logging labels for different projects. Any labels without a value won’t be part of the current filename but the labels will remain available in the logging panel for future filenames.

The “Add Between” checkbox deserves some explanation. There are two basename fields. Checked, the logging information is placed between the two basename field values. Unchecked, the information is placed after both of them. Checking the option is useful for identifying a show in the first basename input and still have the files for that show sort based on logging information. Useful information can be added to the second basename input; it will appear after the logging information and won’t disturb the sort order. In the Apocalypse Now example above, with the checkbox on, that second basename input value was “Remaster Effects”. A set of Apocalypse Now files would sort by project first, then by shooting day, location, unit, and camera, given this particular order of logging fields.

Usage Tips

When we start a file, we often create the filename first using this tool. This solves a number of problems: we will quickly save the file with the new filename so we won’t be working on an unsaved file; this avoids data loss. It also helps focus on exactly what the file will do. If we change our minds later, it’s easy to drag the filename into the tool and change it. If the file is a revision, we can drag in the old filename and update it to reflect the new version. Maybe the old filename should gain a “superseded” flag; this is a good time to do that.

A helpful use case is for periodic files, like monthly bank statements. Drag an old statement file into the tool to capture its filename, update the date, and use the revised filename for the new file. Everything stays very consistent and organized that way:

We find the tool especially valuable for tracking an image or media file through different stages of creation, editing, and production. By giving the camera original a clear name, you can drag in updated versions of the file at any point in its lifecycle and use the “Default Workflow Buttons” to generate and modify the corresponding versions. This makes it easy to follow changes while maintaining a consistent naming convention that captures important production details. This sample filename for a camera original is a good one to try out the different workflow buttons:

.

Roadmap

We plan to enhance the tool over time. In particular, we want to allow users to customize the tool by adding their own flags, cameras, and formats. This is tricky using current technology because the tool is compiled into a web application when it is built, not when it is run. But we have some ideas on how to make this work.

Beyond that, we’d also like to add an opt-in feature where a user could click a button that sends a preview image to an artifical intelligence model to suggest a basename for images which don’t have one. This would need to be done in a way that respects user privacy and data security, of course. And, since this is a free tool, we’d need to figure out how to provide that service without breaking our bank. Also, the round trip to the AI model can’t take longer than just a few seconds, or its value is diminished. Finally, the quality of the descriptions must be high enough to be genuinely useful.

On our own system, we have other tools which can transform a folder of images into our consistent naming convention. This includes batch renaming tools and scripts that can apply our naming rules across multiple files at once. They’re very useful, but they’re powerful tools that require careful handling to avoid unintended changes; we always make a copy of the folder first which we retain until we’re satisfied with the results. We may eventually integrate some of that functionality into this tool, but we want to be cautious and ensure that any batch operations are safe and user-friendly.

If you have suggestions or feature requests, or if you find the tool to be useful, please email us at info@pipsqueak.com. We will probably be willing to add another file format or a new camera default for an interested user. New flags need to be of general interest; too many flags make the tool unwieldy. And you can already use the “Other Flag”, “Other Action”, and “Other Attribute” buttons to incorporate custom flags into your filename. But if you have a suggestion, we’d like to hear it.