CatDV Essential

Release Notes and User Manual

Copyright (C) Square Box Systems Ltd. 2006-2020. All rights reserved.

Square Box Systems Ltd

Lake View House,

Wilton Drive,


CV34 6RG

United Kingdom

Release Notes

Thank you for downloading the CatDV Essential software.

CatDV Essential combines the CatDV Worker and CatDV Server bundled together into a single easy to set up and easy to use media asset system that works “out of the box” with minimal setup. All you need to do is enter a license activation code and the location of the media volume(s) to index and press the Start button to index your media, create proxies, and provide a web interface to let you log and search your assets.


CatDV Essential consists of a number of components:

· Essential Control Panel – this is the user interface that you see when you launch the CatDV Essential application. It is mainly used by system administrors during initial set up and to monitor that the software is working as expected.

· Essential Service – most of the work is done by a system service that starts up automatically and runs in the background when the computer is restarted. The Essential Service actually has two separate processes: the “Server” provides the database that stores metadata describing your media and makes it available through a web interface, while the “Worker” scans your media volumes, analysing new files to extract metadata and create proxies and thumbnails from them.

· Essential Web Interface – most of the day to day interaction with CaDV Essential is done using its web interface, which you access by pointing a web browser such as Safari or Chrome to the web server that the Essential Service runs.

Initial Setup

1. Download the Apple Disk Image (DMG) and open it. Then drag the CatDV Essential Folder into to your Applications folder.

2. Browse to your Applications folder in Finder and locate the CatDV Essential Folder

3. Open the “CatDV Essential” application. You should now see the Essential Control Panel:

4. If CatDV Essential has not been installed previously, then both the Server and Worker will show as “Not Configured” and you will be prompted to install the service:

5. Installing the service (as well as other operations such as starting and stopping the service or uninstalling CatDV Essential) require Administrator access because they involve making changes in protected system directories.

In each case where authentication is required you will be prompted whether to proceed

before being asked to enter a macOS Administrator username and password:

6. The Control Panel should now show that the Essential service is installed, but not yet configured

7. In addition the Configuration screen should now pop up. (This will also appear whenever you press the ‘Edit Config’ button.)

8. Enter your Registration Name and Licence Code, or you can copy the entire contents of the Registration email you received and click the “Paste” button. If the code is correct you should see your licence type shown:

9. You can then set the “Web Port” to the one you desire, for example 80 (if the are no other webservers running on the machine) or leave it as the default 8081

10. You should also select the Proxy preset you wish to use, finding the right balance between file size and proxy quality for your purposes, and how to treat different audio channel layouts that might be encountered:

· ‘Smart stereo’ will use the first audio track from the source movie, unless there are two or more mono tracks, in which case the first two tracks are combined into one stereo track.

· ‘Mix down’ will mix down all the audio tracks to a single stereo track, with odd channels on the left and even channels on the right.

· ‘All channels’ will preserve the audio tracks and channel layout of the source movie but some web browsers may not cope well playing movies with more than one audio track

11. If desired you can click on the ‘Advanced’ button to change the location where proxies and backups will be saved, for example on another volume rather than the default location on the system volume:

12. Once you have finished editing the configuration press OK to come out of the config editor. If the Essential Service isn’t running you will be prompted to start the service:

13. Press the “Start” button on the CatDV Essential Control Panel to start the system. If this is the first time you are running CatDV Essential and it wasn’t installed earlier you may be prompted to create the CatDV database:

14. After a few moments you should get a green light next to Server and Worker to show that the different components of CatDV Essential are operating normally.

You are then ready to specify which media volume (or volumes) you want CatDV Essential to index.

15. If you are running under Mac OS 10.15 Catalina you will probably need to go to System Preferences give Full Disk Access to the /Library/Application Support/CatDV Essential/essentialService executable otherwise it won’t be able to access externally mounted volumes:

Configuring Media Volumes to Index

CatDV Essential is preconfigured with a workflow to to index all the media files in the location(s) you specify. These are referred to as ‘media volumes’ and correspond to directories on your system volume or on an external drive or network volume. You can have as many media volumes as you like.

An internal sample volume containing some introductory CatDV training videos is included for you but you can define your own media volumes using either the CatDV Essential control panel or using the admin web interface.

To edit media volumes using the control panel go in to the configuration editor, then click the Advanced button and use the the ‘+’ button to add one or more media locations to scan:

You can also use the ‘Volumes’ link in the CatDV Essential Server Administration web interface (see below).

Regardless of how you specify the media volumes, CatDV Essential will automatically scan all the files on the volume and add them to the Essential web browser with thumbnails, metadata, and playable proxies for most video file formats. You may need to wait a little while for files to appear in the web interface but can use the Task List to monitor what is going on.

Setting Up User Accounts

1. Using the web browser on the CatDV Essential machine go to http://localhost:8081/ remember to change the port if you selected a different one during installation. You can also use the “Open Web Interface” command from the File menu of the control panel.

2. You should be presented with the login screen.

The default username to log in with is “Administrator” and there is no password set, so leave this field blank.

3. You should now set a password for the Administrator: in the top right hand corner of the webpage, click on your username “Administrator” and select the “Change Password” option.

4. You can now click on the “Admin” section, next to your username

5. You can now add additional users to the system, click on the “Users” link

6. You should see two users by default, “Administrator” and “Essential Worker”. Do not remove or modify these users as they are required for the system to function correctly. Instead a new user.

7. Click the “Add” button at the bottom right of the page, and enter their details.

Configuring the Metadata fields

When CatDV Essential imports your media, it tags the clips with metadata based on their filename and path name.

So if you file your media as: YEAR -> SHOW NAME -> EPISODE ->EPISODETITLE_AUTHOR.MXF

You would see the following on the “Auto-Tagged Fields” panel:

You can customise the names of these fields as follows:

1. You need to be logged in as an administrator, either the built in Administrator account or a new user you have created with the role “System Administrator”

2. Click on the “Admin” link in the top right of the page. If you can’t see, make sure you are logged in as administrator, and click on the “CatDV” logo in the top left of the page. It should then appear.

3. Click on “Fields”, then “Automated Tagging”

4. Click on one of the fields, for example “Name Part 1”

5. Then you can update the “Display Name”, for example change it to “Episode Title”

6. This will now reflect in the panel.

You can also add your own custom metatdata fields, this would allow users to add additional metadata to your clips.

Using CatDV Essential

Once you have set CatDV Essential up it will start indexing your media volumes and display the files in the web interface:

· Direct your web browser to <hostname>:<portnumber> you have set up, eg. http://localhost:8081/catdv/

· Log in (as Administrator, or one of the user accounts you created)

· Browse clips by Catalogs (which correspond to media volumes and folders within those volumes)

· View clips as a thumbnail grid, a list, or film strips

· Apply filters to narrow the results to clips of a particular type, date, etc.

· Select a clip, play the proxy (for video files), and enter log notes or markers describing the clip

· Search for clips based on any log notes you have entered, based on technical metadata, or on metadata fields that are extracted from the file path (that might correspond to customer and project for example)

· Set up smart folders to quickly run a query (for example, to display all clips whose status is Awaiting Review)

· Create a clip list (either private to you or shared with other users) of selected clips of interest, for example to use in a new project

· Press the Select button to select clips for further processing, for example to download the media file(s) to your local machine, then use the Actions popup

· Use the CatDV Plugin Panel for Adobe Premiere, or the CatDV Workflow Extension for Apple Final Cut Pro X, to search for assets from within your editing software and bring them into your project

Database Notes

If you use the built-in H2 database the worker will perform daily backups.

By default, database backups go to /Library/Application Support/CatDV Essential/Backups but you can configure this so they go to another directory, preferably on another volume. You should check this folder occasionally to make sure backups are being created as expected and remove old files as required if you are running low on disk space.

The built-in H2 database is intended to demonstrate the capabilties of CatDV Essential but is not recommended for use in heavy duty production environments as in certain circumstances the database can become corrupted.

Instead, after initial proof of concept, we suggest you migrate the database to MySQL.

Migrating to MySQL

It is possible to re-configure CatDV Essential to use MySQL or another database instead. To do this you need to:

· Shut down the CatDV Essential service using Shutdown Service from the File > Installation menu

· Download and install MySQL

· Download and install CatDV Server 8.0.6

· Install a fresh MySQL database, which we suggest you call ‘essential’:

· Use the CatDV Server control panel and run the Tools > Migrate Data command to migrate from /Library/Application Support/CatDV Essential/db/catdv to the blank ‘essential’ database you created

· Quit the CatDV Server control panel and uninstall the CatDV Server (by removing /Library/LaunchDaemons/com.squarebox.catdv.server.plist and /usr/local/catdvServer, but first make a note of the catdv.database line in /usr/local/catdvServer/catdv.properties)

· Edit the Essential Configuration and add a line such as the following to Advanced Properties section (all on one line). If you copy the text from catdv.properties earlier remember to remove the \ characters before the = signs.

catdv.database = dbType=mysql,db=essential,host=localhost, port=3306,user=catdv,pwd=1PATBtUOo75uCwWg7ug%3D

· Restart the Essential Service using the File > Installation menu

· Run File > Installation > Check Schema to verify all is working

Please contact the Square Box helpdesk for assistance with performing these steps.

Advanced Notes

Below are some brief technical notes for users who are already familiar with the CatDV product family and want to know how CatDV Essential differs, and also some troubleshooting notes for advanced users.

· CatDV Essential is for Mac only

· The CatDV Essential app combines the functionality of the Worker UI and the CatDV Server control panel.

· When you run the CatDV Essential app the first thing you need to do is install the service. This copies files to /Library/Application Support/CatDV Essential and you need to authenticate as an administreator. (This is exactly the same process as installing the Worker background servcice).

· Next, you need to create the database. CatDV Essential uses an updated version of the H2 built in database using the Check/Create Schema command in the menu. Initially it installs a pre-built database but if the schema changes it will run the regular schema install/update scripts as per the CatDV Server Control Panel.

· Then, edit the Essential Configuration. This edits the catdv.properties file both with data for the CatDV Server process and to configure CatDV Essential service. You need to enter your CatDV Essential license code, choose a proxy quality setting, and select one or more media volumes.

· The worker config is generated automatically by combining the essential config (proxy settings and media volumes) with the EssentialTemplate.catdv template. You can view the worker config and make temporary changes but as soon as you edit the essential config or restart the worker service it will be regenerated and overwritten.

· When you start the Essential Service this will automatically start the CatDV Server process. This runs as an anonymous background process in the same way that worker helper processes run so there is no need to stop and start both worker and server processes separately.

· Normally the Essential Service will start up automatically and be left running (from /Library/LaunchDaemons/com.squarebox.catdv.essential.plist) just like the regular background worker and CatDV Server services.

· The worker engine can be in stopped or started (threads running) states. Press Stop once to stop the engine (eg. to edit the config, or to pause the worker while still leaving the web interface running) and again to completely stop the entire service (including the CatDV server and web interface).

· You need to restart the engine after changing the configuration (eg. adding a new media volume).

· There is no need to enter an RMI port (for the worker service or CatDV Server) as it is only used internally for communication between the Essential UI and the Essential Service, and then between the Worker Engine and CatDV Server processes. There is only one RMI port and both the CatDV Server and Essential Service remote objects are registered with the same JNDI naming service. A dynamic (randomly assigned) port number is used.

· For debugging you can connect a CatDV Pro/Pegasus client to the CatDV Server but you need to look up the port from /Library/Application Support/CatDV Essential/catdv.essential.port.

· The task list is accessible from File > Worker > Task List or double clicking the failed/completed rows in the summary.

· The log files are in /Library/Logs/Square Box/CatDV Essential.

· The log file for the control panel (the UI process) are in ~/Library/Logs/Square Box/CatDV Essential

· The database is in /Library/Application Support/CatDV Essential/db

· CatDV Essential uses the predefined ‘Essential Worker’ user to connect to the server. Do not remove this user or change the password!

· Because it uses its own file locations, own port numbers etc. it is possible to try out CatDV Essential completely independently from a regular CatDV Server and/or CatDV Worker installation on the same machine.

· To migrate from CatDV Essential to Enterprise Server and Enterprise Worker move the catdv.properties, worker.xml, workset.db and h2 db files out of /Library/Application Support/CatDV Essential to their correct standalone locations and then review the configuration (mainly to enter new license codes, and make sure the worker config points to the new tasklist db file). You might also need to check permissions and file ownerships.

Version History

1.0.2 12 May 2020

Fix an issue with fresh installations and that prevented you entering a license after a previous evaluation expired.

1.0.1 6 Apr 2020

Fix an issue with the backup task not working. Fix a licensing issue. Added some important database notes to the documentation, including how to migrate to another database.

1.0.0 6 Dec 2019

Minor fixes (related to storing task bookmarks, reducing size of binary by removing unnecessary copy of Java, and add support for entering advanced properties to configure server archiving plugins).

1.0rc2 29 Nov 2019

Automatically check if the installed service is out of date and prompt to update it if necessary. Support for running under Catalina. Fix the “no proxy” setting. Other fixes and improvements.

1.0rc1 11 Sept 2019

Official release candidate. Tidy up menu, including commands to restore database, empty recycle bin, and perform housekeeping.

1.0b5 4 Sept 2019

Improvements to guide users through initial setup. Automatically scan all media volumes without having to edit the configuration whenever there is a change. Allow the proxy directory to be specified. Updates to the user manual.

1.0b4 12 July 2019

Various fixes (missing path for still proxies, make sure WebUploads folder is created, fix an issue with editing views and panels in the web interface, don’t scan the internal tutorials folder, give the User role access to newly created media volumes, etc.) Add a menu command to open the web interface. Add some extra fields and panels that illustrate CatDV’s metadata features to the sample database.

1.0b3 1 July 2019

Add integration with media volumes. Update the logo, documentation, etc.

1.0b2 26 June 2019

Initial beta including predefined database, Essential web theme, and sample tutorial media files.

1.0b1 (8.0.3b) 10 June 2019

Internal alpha release