Synopsis

This guide provides step-by-step instructions for installing MediaKeg and performing your first import operation.

Overview

This guide is for persons installing and running MediaKeg for the first time. After installation is complete, we recommend experimenting with and familiarizing yourself with MediaKeg's features and capabilities so you can determine the optimal library configuration(s) meeting your needs.

The default library configuration organizes multimedia assets by year and month captured or created. Library templates enable you to customize the default configuration. A small amount of time invested upfront will keep you from needing to re-import your assets into another library should you later decide something other than the default configuration is preferred.

The Beta version of MediaKeg provides a command-line interface (CLI) to the MediaKeg runtime. Even if you are uncomfortable with a CLI, this guide covers the basic commands needed to create libraries and perform import operations. For a list of all commands, see the MediaKeg CLI Reference guide. A version of MediaKeg with a graphical user interface (GUI) will become available later.

Installation

Visit the download page to download MediaKeg for your operating system. MediaKeg is supported on the following operating systems:

• macOS Catalina and higher
• Windows 10 and higher
• Desktop Linux systems (tested on Ubuntu 20.x LTS)

The remainder of this section provides installation instructions for each system.

macOS Installation

The macOS download is an Apple Disk Image (DMG) file, a popular method for distributing macOS applications. Double-click the DMG and drag the MediaKeg icon to the Applications folder shortcut, as shown below. After verifying MediaKeg appears in LaunchPad, you can safely eject MediaKeg in Finder and delete the image download.

Windows Installation

The Windows download is a standalone setup executable. Double-click the executable to install MediaKeg onto your system.

Linux Installation

The Linux download is an AppImage. Copy or move the downloaded AppImage to your system's preferred location and double-click it to run MediaKeg.

Note: Search the web for details on how to reate a shortcut to an AppImage for your Linux distro.

Running MediaKeg

Running MediaKeg involves entering a command from the command-line interface (CLI). Typically this involves opening a Terminal (macOS, Linux) or Command window (Windows) and then entering commands. To eliminate additional configuration steps often associated with installing a command-line binary, the MediaKeg CLI hosts your operating system's command-line interpreter for you so that no further configuration is needed.

To launch MediaKeg CLI, use the shortcut created during installation (macOS, Windows) or double-clicking the AppImage (Linux). The version number and an ASCII banner are displayed each time the MediaKeg CLI launches, as shown below.

Note: When running launching the MediaKeg CLI for the first time, you may notice a message Unpacking redistributables..., which are external dependencies needed by MediaKeg to run. For more information, see the redistributables section.

Note: The MediaKeg CLI interface shown above is as it appears on macOS. The window will appear slightly different depending on your operating system and how customized.

If running MediaKeg for the first time (or after each upgrade to a new version), we recommend you run the diagnostics command by typing mkeg diag and then pressing the enter/return key at the CLI prompt ($):

$ mkeg diag

If everything goes OK, you will see the following output: If all tests pass, then you are ready to go! If not, then please report the issue.

Library Creation

Before you can start importing multimedia assets (photos, videos, audio), you must create a library. A library is an ordinary folder on your system (or a network share) that you create and serves at an import destination. To create a new library, enter the following command:

$ mkeg make <path>

Set the path argument to the location where you'd like for MediaKeg to create the new library. If the folder already exists, then it must be empty for the make command to succeed. If all goes well, you should see something like this:

Note: The <path> specifier is a required argument for the command, as indicated by the angle brackets. Optional arguments (not shown here) are specified in square brackets ([]) when providing command-line examples.

Note: The make command is a short-form version (alias) of the make-library command. Many of the MediaKeg CLI commands have aliases, which can be determined by using the command-line help option.

The make command has several options associated with it. To get basic help about a command and its options, enter the command name followed by the -h option, as shown here for the make command:

$ mkeg make -h

For additional details about a command, refer to the corresponding section in the MediaKeg CLI Reference.

Refer to the File System Paths section below for details on how file paths are specified, including tips on how to copy them using your operating system's GUI.

Import Operation

To perform an import operation, enter the following command:

$ mkeg i <source> [<target>]

The <source> argument specifies the the folder path containing the media asset(s) to import.

The [<target>] argument specifies the library to receive the assets. The target can be a directory path or a library alias, which is discussed below in the Library Aliases section. For now, just think of it as a directory path. The [<target>] argument is conditionally required unless a default alias is set.

Note: Command-line arguments enclosed in double square/angle brackages ([<>]) are conditionally required, meaning they required unless some other condition is met.

Note: The i command is an alias for the import command.

By default, the import operation does not include assets in subfolders of source. To import assets from source and all of its subdirectories, use the -r option as shown here:

$ mkeg i -r <source> [<target>]

The following screenshot illustrates what you can expect to see after importing files into a new library:

To bypass the confirmation prompt, use the -y option. To see the full list of import command options, enter the following command:

$ mkeg i -h

Note: From here on, this guide will not indicate that the -h option can be used to get help about a command.

One of the features of MediaKeg is fast duplicate detection without the need for external files or databases. To see duplicate detection in action, rerun the same command on the source and target as a previous import operation, as shown here (this time with the -y option to bypass the confirmation prompt):

In this example, no assets were imported because they already exist in the library. By default, MediaKeg uses an MD5 message digest algorithm to detect duplicates. Other digest algorithms can be specified as a command-line option, including a fast-digest option that significantly improves import performance without practically compromising duplicate detection. The downside of the fast-digest option is that digest values are also calculated for purposes of detecting bit errors in the file copy process. If bit error detection is a feature you care about, then use the default MD5 digest option or better (SHA1, SHA256, or SHA512).

Library Aliases

There is no limit to the number of libraries you can work with using MediaKeg. The library aliases feature lets you assign a label to a library, which can be used in place of the directory path when performing an import operation.

Use the alias command to create a new alias:

$ mkeg alias <alias> <path>

Note: The alias command is an alias for the add-alias command.

For example, to assign the label demo the the library used in the previous examples, enter the command as follows:

$mkeg alias demo /Volumes/Keg/Library

Upon successfully creating a new alias, the command-line output should be similar to this:

After creating the alias, the following import commands are equivalent:

$mkeg i /Volumes/EOS_DIGITAL demo
$mkeg i /Volumes/EOS_DIGITAL /Volumes/Keg/Library

You can create as many aliases as you like, including multiple alias for the same library.

Note: The reason for creating multiple aliases to the same library is that aliases also allow you to associate user tag values that are passed to the import operation to provide greater control over how assets are organized. Refer to the add-alias doumentation for more details.

To see the list aliases at anytime by entering the following command:

$ mkeg aliases

MediaKeg also provides the option to specify an alias as the default alias. This can be performed with the alias command using the -d, --default option. The default can also be set anytime on an existing alias using the set-default command. The default alias has an asterisk (*) appearing before its label, as shown here when listing aliases using the aliases command:

Only one default alias can be set at a time. If a default already exists when targeting a different alias as default, then the default setting automatically switches to the new target.

Building on the previous examples, the import command can be further simplified as shown below if importing into the default library, where the following commands are equivalent.

$mkeg i /Volumes/EOS_DIGITAL
$mkeg i /Volumes/EOS_DIGITAL demo
$mkeg i /Volumes/EOS_DIGITAL /Volumes/Keg/Library

Note: The library assocaited with the default alias is called the default library.

File System Paths

This section is for persons with little or no experience working with a command-line interface but still want to use the MediaKeg CLI. For most operations, can just enter commands as listed here and in the CLI Reference and be successful. However, since MediaKeg works with the file system, you must be comfortable expressing folder locations as directory paths. How to express file system paths varies by operating system, and this section covers each separately following a brief overview.

Note: If you are a seasoned CLI user then you can skip this section.

Overview

The files on your computer are organized using folders (also called directories) that can be nested to form a tree-like structure, much like an org chart for a large company. The physical disk for storing files is partitioned into one or more volumes and the underlying software that supports reading, writing, organizing, and controlling access to files is called a file system. When you format a "disk," you're actually preparing a volume to use a particular file system such as FAT32, NTFS, APFS, EXT4, etc. If none of this sounds familiar to you, it's because this is all handled for you when buying a new system, and removable devices such as USB drives and SD cards are usually pre-partitioned into a single volume formatted for FAT32, which is supported by all major operating systems.

File paths are a way of expressing the location of a file or directory on a volume. With MediaKeg, you're generally working with directories. Again, directory is another word for folder, except that folder is the more approrpiate term when representing a location using a graphical user interface (GUI). The term directory is more often used when working with command-line interfaces (CLI). For all practial purposes, the terms can be used interchangeably.

File system paths consist of tokens (or nodes) delimited by path separators. Each token represents a folder or a file, and you can think of path separators as the branches in an org chart. If the path refers to a file, then it is called a file path. If the path refers to a directory, then it is called a directory path. The following example shows the directory path for the DCIM folder on an SD card inserted into a macOS system:

/Volumes/EOS_DIGITAL/DCIM

macOS and Linux use the forward-slash character (/) as the path separator. Windows, on the other hand, uses the backslash character (\) as the path separator, as shown here:

E:\EOS_DIGITAL\DCIM

It is also worth noting that macOS locates volumes under /Volumes in the directory structure, which the same place as Computer when viewed from macOS Finder. Windows, on the other hand, assigns volumes a drive letter, suce as C:, D:, E:, etc.

macOS

An easy way to get the path to a file or folder in macOS is to use Finder. Simply select the file or folder, and press Control key (or right-click if your mouse is right-click enabled). This causes the context menu to appear, which you're proabably already familar from performing common tasks such as copying and moving files and folders. Once the context menu appears, press the Option key. Whie causes the Copy task to change to Copy as Pathname to the clipboard, as shown here:

Once copied to the clipboard, you can paste the pathname into the MediaKeg CLI window using Command+V when entering commands that accept file and directory path arguments.

If entering the pathname directly into the CLI (instead of pasting the value), pressing Tab invokes autocomplete for the current node entered, if unambiguous. For example, entering /V + Tab autocompletes your input to /Volumes/. If the partial entry is ambiguous and thereore cannot be autocompleted, pressing Tab again prints a list of directory entries matching the input for the current node.

Windows

An easy way to get the path to a file or folder in Windows is to use File Explorer. Simply select the file or folder, and then click in address bar to reveal the directory path for the item, as shown here:

Once selected, you can copy (Ctrl + C) and paste (CTRL+V) the pathname into the MediaKeg CLI window when entering commands that accept file and directory path arguments.

If entering the pathname directly into the CLI (instead of pasting the value), pressing Tab invokes autocomplete for the current node entered. For example, entering C:\Win + Tab autocompletes your input to C:\Windows. If there are multiple items matching the input, then the first match from from the alphabetical sort ordered list is selected. Pressing Tab again cycles through the list enabling you to quickly work through the list until the correct entry autocompletes.

Linux

If you're a Linux user then we assume you're comfortabe working with CLIs.

Reporting Issues and Feature Requests

To report issues and make feature requests, please visit our GitHub page:

https://github.com/appyture/mediakeg-issues

Redistributables

The following software is redistributed with MediaKeg:

• ExifTool

ExifTool is a popular command-line utility used for reading and writing ExifMetadata. There is no reason for you to install ExifTool separately to use MediaKeg. If you already have ExifTool installed, MediaKeg still unpacks and uses the version of ExifTool redistributed with MediaKeg.

The redistributables are automatically unpacked when MediaKeg first runs. Entering the following command reveals the directory path into which the redistributables are copied:

$ mkeg dirs

If the redistributed files are deleted or compromised in some way, you can retsore them using the diag command with the repair (-r) option set:

$ mkeg diag -r

Uninstalling MediaKeg

This section provides instructions for cleanly uninstalling MediaKeg and related files from your system.

Special Folders

Before removing MediaKeg from your system, run the following command:

$ mkeg dirs

The output reveals the locations of the following special folders:

• Preferences
• Redistributables

These folders must be manually removed if you want them gone after uninstalling MediaKeg.

The preferences folder contains single file named aliases.json, which is where library alias information is stored. Any library aliases created for your system will be lost if this file is deleted.

Note: The aliases.json file is not required for MediaKeg to function and is a convenience feature to reduce the amount of typing needed when working with the MediaKeg CLI. Copying the file to another system is not recommended because it may not have access to the same file system resources. If a shared resource, the file paths associated with the alias may differ as accessed from the other system.

The redistributables folder contains the files covered in the Redistributables. This folder can be safely deleted without losing any user data.

MediaKeg Libraries

MediaKeg Libraries contain a small hidden file at their root named .keg. If you have no intention of using MediaKeg again, you can safely delete this file. If you think you might want to use MediaKeg again in the future, then it's best to keep this file.

MediaKeg Libraries also contain a hidden folder named .logs at their root. The logs directory contains detail information about each import operation. MediaKeg does not require the .logs directory to function, except as noted here:

• Import rollback
• Reports generation (future feature)

The information in the .logs is intended primarily for record-keeping purposes (traceability of assets back to the source, consistency checking, etc.) and troubleshooting. It's at your discretion to determine if the log files have value or not.

Application Uninstall

The procedure for uninstalling the MediaKeg application varies by operating system.

macOS

Drag the MediaKeg icon in your Applications folder to the Trash.

Windows

Uninstall MediaKeg from Add or remove programs located in System settings.

Linux

Delete the MediaKeg AppImage file from your system.

Related Guides

• MediaKeg Concepts Guide
• MediaKeg CLI Reference
• MediaKeg Recipes
• MediaKeg FAQ