The Well

Help resources in the application...
TIP: If you have downloaded The Well, possibly the best help resource is the Help pop-ups within the application itself, accessible by clicking on the question marks. Each view has its own Help pop-up that explains the app's features in detail.

Basic Setup

Bringing material into The Well will take the longest.  Get started more quickly by downloading the sample sound library provided on the Resources page.  The page offers files in two forms for practice:

  • a structured audio folder with matching metadata (just add the audio folders to your chosen Library location, then import the provided .TSV file)
  • raw audio files whose names we wish to turn in Descriptions in The Well (just use the Audio Import function in The Well)

These are the two main ways to add sounds to The Well.  Either method will get you to the destination:  a working library with some sounds in it!

From there, you can experiment with the different options and learn the library's structure, described below.

Note that the first method (metadata import) is meant to allow you to bring commercial sound library metadata into The Well and/or to share or synchronize libraries with your colleagues.  The second method (audio import) is meant to tame an unstructured set of audio files (whose filenames are nevertheless decent descriptions) into a set of structured folders within The Well that look and act like commercial libraries.

Basic Usage

Once you have set up your sound effects in The Well, you can use it to  1) search for sounds based on description, 2) mark the ones you want, and 3) export them to a folder:

1Search much like you would on Google.  Type multiple words to perform an "AND" search (descriptions containing all the words are displayed: "this" and "that").  Or you can lead words with a slash "/" to perform an "OR" search (to find both /this OR /that).  Lead a word with a minus "-" to exclude descriptions containing that -word.  Use quotes to find that whole "word" only (no partial matches), or around a phrase to find "that phrase" (instead of the words that make up that phrase).  Or use any combination of the above techniques.


2Play back the sounds you find and place a checkmark next the ones you want to export.  The Well is able to play back many file types, and will search for the correct file type if the wrong one was set:  just hit Play.  The Well figures it out.


3Export the sound effects to any folder.  By default, exported audio files will have names constructed in a way that tells you which personal or commercial library the files came from.  In addition, you can add a custom text label (Export Prefix) to the beginning of each exported file's name, as well as optionally organize the exported files in subfolders named after the prefix.  Licensing information tags can also be added to the ends of the file names.  Explore the buttons in the export section to turn these options on or off.


Updating from a Previous Version

Be sure to always observe the standard update procedure:

  1. Back up your entire Library to a single .TWB file (from the Main Menu's "Export / Backup" tab).
  2. Back up your Favorites, if any, to a single .TWF file.
  3. Once you install the new version, launch it and go through the initial setup messages.  Then:
  4. On the Restore tab of the Main Menu:
    • under "What to restore" choose "TWB (SFX)" from the upper option
    • under "With duplicates, keep..." choose "Allow Duplicates" (this skips a step and will be faster)
    • click the green button  "Restore records using backup file"
    • choose the .TWB backup you made in the old version of The Well and allow the restore process to complete
  5. Again on the Restore tab of the Main Menu:
    • under "What to restore" choose "TWF (Favorites)" from the upper option
    • under "With duplicates, keep..." choose any options
    • click the green button  "Restore records using backup file"
    • choose the .TWF Favorites backup you made in the old version of The Well and allow the restore process to complete
  6. Go to your Library and check that everything is in order.
  7. Only when you are certain that your data is completely intact will it be safe to delete the old version of The Well by dragging its complete application folder to the Trash.  But feel free to keep the old version around for a while:  any version of The Well can co-exist with any other.

How does it work?

Here's what happens when you hit "Play" in The Well:

  1. The app reads the Group, Folder, Track, and Index number of the sound effect you want to hear (for those who think of sound effects as being on CDs:  a "Group" is equivalent to a collection of CDs, "Folders" are like the individual CDs in a collection, "Tracks" are... tracks, and "Indexes" are sub-sections of a track, used in some commercial libraries and on some DAT tape libraries);
  2. Using this data, the app pieces together the expected file name and location on disk of that sound effect file;
  3. It then checks whether that file is online (and if not, marks it offline);
  4. It then tells a sound playback function where that file is, and to play it;
  5. It also detects the file's duration and stores that number in the database (you see the duration appear if it wasn't already present).

Exporting an audio file happens in much the same way, but instead of playing the file, the app copies it to the folder you choose and optionally adds extra information to the filename.

Where are things stored?

1) All sound effects metadata – meaning the searchable Library descriptions, together with each sound effect's Group/Folder/Track/Index information – are stored inside the application itself (this is how FileMaker's internal database engine operates). So if you were to delete The Well's application folder for some reason, you deleted your information, too!  So be sure to use The Well's backup or export features before you delete the app, should you decide to upgrade The Well or to move your library's metadata to another app or system.

(Note that, starting with v0.4.0.0, The Well will nag you to make a backup of all your metadata as you quit the application whenever your Library data has changed.)

2) Your Library's audio files are stored in a folder, anywhere separate from the application.  The files must be stored in this single location, but that location can be on a network share or SAN (the app was tested and appears to work well with Avid Nexis/Unity/ISIS, for example).  In other words, The Well can exist on a completely separate drive, device, or computer from the audio files it is accessing.

For the audio files, the structure of subfolders and the naming of files follow a strict hierarchy, as follows:

LibraryFolder > Group > Folder > Folder_t0001_i01.wav

As you can see, the audio files' names include their parent-Folder's name, as well as their Track and Index numbers (denoted by the "_t" and "_i" prefixes, with leading zeros mandatory).  The folder hierarchy and naming conventions are requirements of The Well.  This is how the app finds files for playback and export.

The Well can also add audio files to the Library using this same hierarchy, automatically, making The Well a great way to tame the chaos of random files you may have recorded or collected over the years (in this case, it offers to use your audio files' file names as their descriptions).  See below.

Note that The Well only adds to the Library's physical folders – it cannot delete audio files or folders.  This is to protect the Library when it's in use by multiple people on shared storage.

Getting stuff in:

The Well allows you to load sound effects in two ways:

  • Import metadata for sound effects to The Well via tab-separated value (.TSV, .TAB, .TXT) text files, also known as "tab-delimited" files.  These text files follow a given format that is easy to create in, say, Google Sheets before being exported as a .TSV file.  In a second step, you rename the actual sound files on disk to match up to the metadata given in the .TSV file.  The Well then makes the link, on the fly, between the metadata and the sound files to allow you to play them back and export them from the Library.  The new file names must follow a strict convention for the link to work, and the subfolder structure is equally strict (see above).  This enforces a uniform organizational hierarchy for your entire Library.
  • Import audio files.  The app sequentially renames any audio files it imports, discarding the original file names and re-purposing them as Descriptions. The Well checks for and avoids duplicate Group/Folder/Track numbers to prevent collisions in the Library. And it strictly structures any "physical" folders it creates in the Library using the chosen Group and Folder names, maintaining the Library folder's hierarchy.  This is a great way to take a messy collection of sound effects whose filenames are decent descriptions of the sounds and turn them into structured collections just like commercial libraries.  When importing, the app can search for all audio files contained within multiple levels of subfolders, in any recognized audio format, meaning you don't have to tidy things up before import.

Getting stuff out:

Once metadata is in the database and files are in their respective folders (properly named), the app allows Google-like search based on description (see above).  You can also search by individual Folder (like a CD) or Group (like a collection of CDs).  Or you can collect individual effects into Favorites Lists, which much like the Library itself are organized by Favorites Group > Favorites Project > Favorites List so you can carry your commonly-used effects from project to project.

The emphasis is on speed:  find and audition quickly, mark what works, and export.  The exported files can then be drag-and-dropped into, for example, Avid Media Composer.

Export file naming options include:

  • Add a text prefix to the exported filenames in order to label a group of exported effects, say, "car chase Act 2" or "cat meows."  This can also help to sort region lists if you happen to be working in ProTools.
  • Add a prefix that specifies the Group (the collection of sound effects Folders) that a sound came from, for example: "HollywoodEdge."
  • Add licensing information at the end of the filename, to help post sound teams figure out what they can re-use from your temp.

Using all options, an exported file name might look like this:


In this case, you chose to add "dog barks" as the Export Prefix for your organizational purposes;  when you first set up your Library, you had added "HollywoodEdge" as a Group Export Prefix for the Group to which the sound effect belongs;  the middle part of the filename, starting with "PE02," contains its Folder/Track/Index information so your post sound team knows which sound effect you pulled (in this case:  Premiere Edition Disc 02, Track 31, Index 1);  and lastly the "Not Licensed" tag tells your sound team that you do not own a license to use this sound effect, so they will have to either obtain a license or replace the sound.

The Design Philosophy of The Well

In creating a database out of a chaotic collection of files, the main issue is conformity:  how do you get a search program to recognize the file that it needs to play back when the file could be named anything and placed anywhere?

Modern librarians seem to be placing an emphasis on embedded tags, since audio files with, say, description tags can be searched from any accessible location.  However, tagging can get messy and require maintenance (there are different standards of ID3 tag for mp3 files, for example, and they can contain contradictory information – which one should be considered valid?).

The Well's philosophy is instead to use file names to match metadata to the corresponding audio file.  It imposes a consistent format (Group>Folder>Track>Index) on the Library's audio file names.  There is a large up-front cost to this, but there are several reasons for this approach.

To understand why The Well adopted this solution, it may help to explore some of the alternatives:

One simple solution would have been to force all of the audio files into FileMaker, which offers to store audio data directly in its tables, linked directly to each file's description (this is already more than most other database applications offer).  The price is high, though:  the audio, the metadata, and the program are the same file in the FileMaker data model, meaning the program itself would mushroom in size and likely become unusable, or at least difficult to back up.  In an attempt to resolve this sort of situation, FileMaker offers the possibility of using an external folder as its media pool, but imposes restrictions on its placement and its folder structure.  Inadvertent changes to the external pool would have unpredictable results.  And most of all, by allowing FileMaker to run the show, the files cannot be freely moved to another location, and any one copy of the database cannot be easily duplicated or synchronized with another.  This makes a proper backup difficult or impossible, and that is a deal-breaker in post production.

The Well instead takes a more open and transparent approach to data.  Metadata goes into and out of The Well in a very universal, human-readable form:  the TAB-delimited file (aka tab-separated value file, or TSVs).  TSVs are not pseudo-human-readable like an XML or a JSON file, but truly human-readable, like a spreadsheet.  In fact, one of the best ways to create a .TSV for The Well is in Google Sheets, which can directly create a TSV using File >Download As > .TSV.  The spreadsheet, or table, is one of the oldest, simplest, and longest-lived forms in which to store data, which means it will be around long after fancier formats have lost favor.

Similarly, once in the Library, the audio files remain in their original state.  There is no hidden tagging happening, no sidecar data file to worry about.  As long as the name and placement remain as established when the files were first added to The Well, the files will behave as expected.  Backups are simple:  just mirror you entire Library (audio) folder to a backup disk.  That backup disk can immediately be used as another copy, by the way, by just pointing The Well to the new location (see the Settings tab on the main home screen).  The Well even offers a function to store a .TSV at every level of your library (Library, Groups, and Folders) so that if the original program were to be lost you could import the metadata for any part, or the entire Library, to a fresh copy of The Well – or to another platform entirely (assuming the .TSV data format can be adapted to it).  This way of dealing with data also makes it very easy to move chunks of your Library from location to location or machine to machine.

While the folder structure and naming conventions of The Well are very strict and uniform, that structure offers transparency.  On the Finder level, it is very quick and easy to understand what is present in a library's physical folders, how The Well is seeing it, or to copy just one Group into or out of a Library's folders, for example.

Within The Well itself, the structure of Group > Folder >Track > Index allows you to search not only based on descriptions, but separately based on which Group you might remember a sound being in (e.g.: a specific commercial or personal library).

Storing audio files in a simple folder tree has another advantage:  they can be located on a network share.  Avid's shared storage has worked transparently so far, with several years' of post production experience keeping the Library folder on Avid Nexis.  That means one copy of the audio files can serve and entire team, with obvious advantages.

Another design philosophy of The Well was to make it free. I have yet to meet the post producer who is willing to buy commercially-available sound librarian software for a picture editorial team, and allow paid time for an assistant editor to properly set it up.  The Well is freely available, and so it can be used by an entire post team and carried from project to project.

The Well does not "phone home" or otherwise require Internet access, meaning it can be used on high-security projects.

Plus, a large mp3 library and the program itself can all fit on, and run from, portable storage.

So why not just store sound effects in the editing system?  Most importantly in my experience, searching through a large sound effects database in the editing system is cumbersome.  The presence of so many extra files can bog down the entire editing environment and clog up shared storage.  The search method offered in picture editing systems is not as sophisticated, meaning if the library is large, the results are harder to sift through.  The file formats used in editing systems tend to be uncompressed and sometimes proprietary (for example MXF audio).  That means the library will be about ten times larger than necessary for mere temp work and may not be easily portable.  In the end, it's probably better to have a small, core set of common effects in the editing system, with a very large external library that can supply what's needed for any given episode or project.  That keeps the picture editing systems lean and fast.

But all is not roses...

The Well's disadvantage is that metadata has to be shared manually.  If a team is often ingesting many new sound effects to a library shared by a large team of editors, then they will quickly tire of going to each machine and importing many TSVs or TWBs.  However, this may be an advantage in some people's eyes:  your copy of The Well is specific to you, and you can guard it from getting too big.

The Well is not for everyone, but for the right situations it will be a good solution, or at least another Swiss army knife for your toolset.

More to come?

This page is a stub.  If time permits or someone volunteers to create some tutorials, the Help section may expand in the future.  But nothing beats poking around the software yourself.  ;o)