MediaInfo - macOS Finder Sync Extension

Extension to display information about multimedia (images, videos and audio), PDF, Office, compressed archives and folders in the Finder contextual menu. Require maxOS 10.15 or higher.

MediaInfo is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY.

• Behavior
• Installation
• Settings
  • Monitored folders
  • General
  • Customize the menu items
  • Common information
  • Common actions
  • Images
  • Video files
  • Audio files
  • PDF documents
  • Office files
  • Compressed archive files
  • Folders
  • Other files
• Menu actions
  • Common actions
  • Inline actions
  • Trigger action
• Scripting support
  • Customize the menu items
    • Exposed data
    • Inline scripts
    • Global scripts
  • Triggers
    • Validate trigger
    • Before render trigger
    • Action trigger
  • Utility functions
  • Action functions
  • Common properties
  • Properties for images
  • Properties for video files
  • Properties for audio files
  • Properties for PDF files
  • Properties for Office files
  • Properties for compressed archives
  • Properties for folders
• Known bugs and limitations
• Build from source
  • Dependencies
  • Application processes
• Credits

Behavior

This application allows you to customize the context menu for supported files. When you right-click on a file within a monitored folder the extension extracts all available information for the file and generates the context menu.

Image menu example	Video menu example
Audio menu example	PDF menu example
Office menu example	Archive menu example
Folder menu example

With the main application you can customize the menu. You can compose the file properties generating the menu items. It is also possible to use a script code to format the menu items.

Remember that all rendering operations must be completed before the menu can be displayed. MacOS does not allow you to populate on-demand the menu but only before viewing, so any information extraction and formatting operation must be as fast as possible in order not to slow down the opening of the menu.

Installation

Go to the releases page to download the latest version.

Move the downloaded app on your Applications folder and launch it to set the monitored folders and the other settings.

Then you need to enable the associated Finder Sync Extension on the System Preferences / Extensions.

Now right click (or control click) on a supported file within a monitored folder to see the contextual menu with the information.

The precompiled application is not notarized or signed. The application is compiled as universal binary (Intel and Apple Silicon processor).

When you manually download the precompiled app directly you must strip quarantine flag. The first time you can launch the app with right click (or ctrl click) on the app icon and choose the open action.

Alternatively, you can open System Preferences > Security & Privacy > General (tab) then clicking the Open Anyway button.

If the system warns that the application is damaged, use the following terminal command:

$ xattr -cr "FULL PATH OF THE MediaInfo .app (you can drag the file to get the pull path)"

This will resolve the error of an unsigned/damaged application when launching the app.

When the monitored folders are changed or when the Finder Sync extension is restarted, the System may display a confirmation warning to allow read access to the files of the monitored folders. Access must be granted for the Finder extension to work.

Settings

Monitored folders

With the Application you can customize the monitored folders and the properties to be shown inside the contextual menu.

You can also auto monitor external disk.

Information is shown only for files within the monitored folders (and their subfolders).

General

The General tab allow to set some common options.

Media engines:

• Core Media: it uses the Apple CoreMedia APIs to parse media files. It is able to recognize many formats and most of their properties.
• FFMpeg: it uses the FFMpeg library to analyze multimedia files. It generally supports more files and provides more detailed information. However, it requires more resources.
• Metadata: Use Apple Core Service APIs to extract information from metadata. It requires fewer resources but handle less information.

Customize the menu items

For each managed format it is possible to customize the list of menu items. For each item you can combine plain text with the placeholder which will be filled with its file property.

When composing the menu title, all worthless placeholders are left blank. Multiple spaces or punctuation marks (comma and semicolon) or empty parentheses are automatically deleted. For this reason, it is suggested to separate placeholders whose value may not always be available with spaces, commas or semicolons.

You can also specify an explanatory icon for each item. Some icons (image, video, pdf, page, ratio, media box, bleed box, art box) respect the orientation (portrait or landscape) of the source. The color icon respects the color space (RGB, CMYK, gray scale, B/W, LAB).

Use a single dash (-) to create a menu separator. Note that for a macOS limitation the separator element will not be shown with the usual dividing line.

If you need more control over the information displayed by the menu items you can also use custom scripts (see the Scripting support chapter).

Common information

For each type of file some common information is available:

Images

Available information:

Supported image formats:

• images handled by the macOS via CoreGraphics
• .webp with libwebp
• .svg files
• images handled by FFMpeg
• .pbm formats
• .bpg format (parsing the file header).

Extracting metadata is a wasteful operation that can slow down the contextual menu display. For this they are only processed if a metadata token is used. If you need to access metadata within a script, your code must have this comment at the beginning: /* require-metadata */.

Video files

Available information:

Not all properties are always available, depending on the type of file and the engine used to decode it.

* Available only for files decoded with the FFMpeg engine. ** Not Available for files decoded with the Metadata engine.

It also shows the data of all the video, audio and subtitle tracks present. This information can be viewed within submenus or in the main menu.

Supported video format:

• video handled by the macOS via CoreMedia
• video supported by FFMpeg library.

Audio files

Available information:

Not all properties are always available, depending on the type of file and the engine used to decode it.

Supported audio format:

• audio handled by the macOS via CoreMedia
• audio supported by FFMpeg library.

PDF documents

Available information:

Adobe Illustrator .ai files are also supported.

Office files

The following file formats are supported: .docx, .rtfx, .pptx, .odt, .ods, .odp (standard office files based on the XML format).

Extracting some metadata requires a deep scan of the main file. This can cause a delay in the display of the context menu of office files. For this reason, the deep scan is enabled only when requested by the chosen tokens are present. If you need to access metadata within a script, your code must have this comment at the beginning: /* require-deep-scan */

Available information:

Compressed archive files

The compressed archive files are handled by the libarchive library. The following file formats are supported: .zip, .rar, .7z, .tar, .pax, .ar, .xar, .cab.

With the Max files option, you can set the maximum number of files to process from the compressed archive. Set to zero to disable the limit. Please note that processing a lot of entries can slow down the menu generation. Furthermore, displaying many menu items is a heavy operation.

The archive file parsing operation is automatically stopped if it takes too long.

Available information:

Folders

You can handle plain folders and even macOS bundles.

You can limit the processed data with these options:

Processing the contents of a folder is a resource-intensive operation that can take time. It is recommended to limit the number of files to be processed.

Processing takes place in two steps:

• calculation of the total number of files and their occupation on disk. All files (including hidden files and those contained in bundles) are counted ignoring the settings on hidden files and bundles.
• extraction of the list of files according to the limits set in the preferences.

Each of these operations is aborted, returning a partial result, if it takes too long.

The total number of files and the folder size are acquired only if the specific token is used. If you need to access to the allocated size within a script, your code must begin with the comment /* require-deep-scan */. If is required to access only to the full size use the comment /* require-fast-scan */ as the first line.

Available information:

Other files

You can also create generic file menus to show basic information. You can use scripts to extract information from the file and place it on the menu.

It is possible to create menus for specific file formats (identified through the UTI) and also for all files not directly managed.

If a file conforms to several UTIs defined in the settings, the settings to be used will be chosen according to the order in which they were defined.

Menu actions

From the general settings you can set the action to be executed when you choose a menu item:

• do nothing
• open the file with the default application.

You can customize the action in several ways:

• Use a special menu item with custom action.
• Generate a menu item with a global script and define a custom function to be executed.
• Define a custom action trigger.

To handle custom action, see the action functions.

Common actions

For each file type there are some special menu items with a predefined action:

Inline actions

Menu items created by a global script can have a custom action. You need to set the action attribute to "custom" and set userInfo["code"] to the name (a string) of an exists function to call to handle the action. The function receives as a parameter an object with the info of the selected menu item:

• index (Int): index inside the template
• tag: tag of the associated menu item
• menuItem
  • image (String)
  • template (String)
• action (String)
• userInfo ([String: Any])

Trigger action

It is possible to define a trigger action executed when a user chooses a menu item. See below for more info.

Scripting support

You can use a javascript code to:

• Customize the menu items:
  • Output a text inside a menu item.
  • Generate multiple menu items, with the possibility to define a custom action to be executed when the user chooses an item.
• Execute a trigger:
  • Validate the file before processing the file and generate the menu.
  • Pre-render trigger to customize the menu item templates.
  • Action to be executed when the user clicks a menu item.

Customize the menu items

It is possible to customize the menu items with a javascript code.

The javascript environment is shared with all scripts defined for the menu items, thus allowing you to set values in the code to pass from one script to another. The scripts are executed in order of belonging in the menu.

Since the environment is shared among all the scripts, remember to be careful not to declare the same global variables in multiple scripts using let and const statement (If you need to redeclare a global variable you can use the var statement).

The javascript environment will be reset every time a new contextual menu generation in required. So, you cannot share data between menu generate for different files.

Exceptions thrown during code execution are indicated by an exclamation icon inside the application.

It is recommended that you enclose the code within an anonymous function:

(function() {
    let result = '';
    
    // your code here
    
    return result; // <- This will be the menu title.  
})()

There are two script tokes: inline and global.

The before render trigger can be used to customize the templates defined in the settings before the menu generation.

Exposed data

There are some common global variables.

The fileData variable is an object that contains the data representation of the currently processed file. The variable settings have the current settings.

These two variables are locked and their properties cannot be changed (in strict mode, if you try to change one of their properties an exception is raised). Any changes made to the fileData or settings will not affect the standard token process.

For a descriptions of fileData and settings properties see the Common properties.

From the Window menu you can enable the JS Console to shows the output of the console commands.

Inline scripts

The inline script token allows you to place the result of the script evaluation inside a menu item with any other tokens.

The result of the script corresponds to the last statement executed in the code. The last statement must return a string value (or null).

(function() {
    const s1 = "Hello World";

    return s1 + " from " + fileData.fileName; // <- This will be the menu title.
})()

Global scripts

The global token script allows you to create multiple menu items at once.

(function() {
    let items = new Array();
    items.push({title: "label 1", image: null});
    items.push({title: "label 2", image: "pencil"});
    items.push("-"); // This is a separator
    items.push({
        title: "submenu",
        items: [
            {title: "first"},
            "second",
        ]
    });

    return items;
})()

The last statement executed must return an array representing the menu items to add.

Each element in the returned array can be:

• A string that will be used as the title. You can use "-" to add a menu separator.
• An object with these properties:
  • title (string, required) The title of the menu item.
  • image (string, optional) The image name for the menu item. See below for a list of the available images.
  • checked (bool, optional) Set to true to add the check mark to the menu item.
  • indent (int, optional) Indentation level (from 0 to 15).
  • tag (int, optional)
  • userInfo ([string: Any]) Dictionary of custom user information.
  • action (String) Action to be performed by selecting the menu item. It can be one of these values:
    • "none": do nothing.
    • "standard": execute the action set globally in the settings.
    • "open": open the file with the default application.
    • "openWith": open the file with an application. You need to set the full path of the application in userInfo["application"].
    • "openSettings": open the MediaInfo settings application.
    • "clipboard": copy the path to the clipboard.
    • "reveal": reveal a file on the Finder. You can set userInfo["file"] with the path of the file to reveal, otherwise the current file is used.
    • "about": open the GitHub page of this project.
    • "custom": perform a custom action. You need to set the function name to be called in userInfo["code"].
  • items (Array, optional) An array of the sub-elements.

For each items inside the menu (standard and created by a global script), is required that the combination of tag and the formatted title must be unique. For the standard elements, the assigned tag is the zero index of the template used.

The image property can be:

value	image
null or "no-image"		No image, but reserve a space if is set the visibility of icon in the menu items.
no-space		No image, and do not reserve a space.
target-icon		Current file icon.
"image"		auto oriented
"image_v"
"image_h"
"aspectratio"		auto oriented
"aspectratio_h"
"aspectratio_v"
"color"		dynamic
"color_rgb"
"color_cmyk"
"color_gray"
"color_lab"
"color_bw"
"print", "printer"
"video"		auto oriented
"video_v"
"video_h"
"audio"
"speaker", "speaker_mono"
"speaker_stereo"
"txt"
"abc"
"page"		auto oriented
"page_v"
"page_h"
"pages"
"office"		auto icon (for word, excel or powerpoint)
"office" or "doc" or "docx", "word"		auto oriented
"doc_h", "word_h", "docx_h"
"doc_v", "word_v", "docx_v"
"xls", "xlsx", "excel"
"ppt", "pptx", "powerpoint"
"3D"
"3d_color"
"3d_occlusion"
"3d_lines"
"3d_normal"
"3d_points"
"3d_quads"
"3d_tangent"
"3d_triangle_stripe"
"3d_triangle"
"3d_uv"
"3d_variable"
"pdf"		auto oriented
"pdf_h"
"pdf_v"
"artbox"		auto oriented
"artbox_h"
"artbox_v"
"bleed"		auto oriented
"bleed_h"
"bleed_v"
"crop"
"zip"
"script"
"gear", "gearshape"
"calendar"
"clipboard"
"flag"
"folder"
"info"
"size"
"person"
"person_n"
"person_y"
"people"
"group_n"
"group_y"
"shield"
"tag"
"pencil"
"exclamationmark"

With macOS 11+ you can also use a standard symbol name for the image.

Triggers

You can set up triggers to run for certain events:

• trigger executed for validate the file before the info extraction.
• trigger executed before the menu generation, allows to customize the menu item templates
• trigger executed when a menu item was selected.

Validate trigger

You can define a trigger to be executed before processing the file. The script must return a Boolean value. false prevents the file to be analyzed and no menu will be generated.

// currentFile: path of the processing file
return currentFile.indexOf("test") < 0; // Skip files with "test" in the path.

Please note that the javascript context of the validate trigger is not shared with the other code inside the menu items or with the action trigger.

Before render trigger

This trigger can be used to change the menu items template defined in the settings. The script must return null to not change the settings. Otherwise, must returns an array of menu item templates:

return [
    {image: 'image', template: '[[size]]'},
    {image: 'clipboard', template: '[[clipboard]]'},
    {image: '', template: '-'}, // menu separator
    {image: '', template: ''}
];

For the image property see the Global scripts.

The trigger is evaluated inside an anonymous function, so any functions or variables are not propagated to other script.

If you need to export some data set as a property of the globalThis:

globalThis.myfunc = function() { 
    \\...
};

globalThis.myvar = 4;

return null;

There are two ways to generate a menu item template with a script token:

• define the code as a base64 encoded string (with toBase64()) and insert it into the token:

let code = "return 'hello world';";
let token = "[[script-inline:"+toBase64(code)+"]]";

• define a custom function for the globalThis and use its name for the token js attribute:

globalThis.myfunc = function {
    return "hello world";
};

let token = "[[script-inline:js:myfunc]]";

Action trigger

The user can define a custom trigger performed when a menu item is chosen.

The javascript context is the same as all the scripts called to generate the menu items.

Within the action trigger the var selectedMenuItem is set with the properties of the chosen menu item.

To manage the action, see the action functions.

Utility functions

These functions are available during the execution of a javascript code.

* Some standard tokens (such as scripts and open-width) encode the argument with the base64 standard.

Action functions

To manage the action when the user clicks on a menu item, these functions are available:

/**
 * Open the file at the specified path with the default application.
 *
 * @param {String} path Full path of the file.
 *
 * @returns {Promise} Returns a Promise.
 *
 * @example 
 * systemOpen(fileData.filePath)
 *    .then(
 *        function() {
 *            console.log("success");
 *        },
 *        function() {
 *            console.error("fail");
 *        },
 *    );
 **/
function systemOpen(path)

/**
 * Open the file path with the specified application.
 *
 * @param {String} path Full path of the file.
 * @param {String} application Full path of the macOS application.
 *
 * @returns {Promise} Returns a Promise.
 *
 * @example
 * systemOpenWith(fileData.filePath, "/Applications/TextEdit.app")
 *    .then(
 *        function() {
 *            console.log("success");
 *        },
 *        function(reason) {
 *            let error = reason; // String or Null
 *            console.error("fail: ", error);
 *        },
 *    );
 **/
function systemOpenWith(path, application)

/**
 * Open the specified application.
 *
 * @param {String} path Full path of the macOS application.
 *
 * @returns {Promise} Returns a Promise.
 *
 * @example
 * systemOpenApp("/Applications/TextEdit.app")
 *    .then(
 *        function() {
 *            console.log("success");
 *        },
 *        function(reason) {
 *            let error = reason; // String or Null
 *            console.error("fail: ", error);
 *        },
 *    );
 **/
function systemOpenApp(path)

/**
 * Execute an external `command` passing the arguments as an array of strings.
 *
 * @param {String} command Full path of the command to be executed.
 * @param {String[]} arguments List of arguments for the command.
 *
 * @returns {Promise} Returns a Promise.
 *
 * @example
 * systemExec("command", ["arg1", "arg2"])
 *    .then(
 *        function (reason) {
 *            let output = reason; // String
 *            console.log("success: ", output);
 *        },
 *        function (reason) {
 *            let exit_code = reason[0]; // Int
 *            let output = reason[1]; // String
 *            console.error("fail: ", exit_code, output);
 *        },
 *    );
 *
 **/
function systemExec(command, arguments)

/**
 * Copy a text into the clipboard.
 *
 * @param {String} text 
 *
 * @returns {Bool} True on success.
 *
 * @example
 * systemCopyToClipboard("Hello world");
 *
 **/
function systemCopyToClipboard(text)

These function are only available inside an action trigger or when executing a custom action from an item generated by a global script.

Common properties

Settings

fileData

Properties for images

If a script require the metadata, add at the begin of the code the comment /* require-metadata */. Depending on the image type, not all metadata properties will be populated.

Every metadata group is an array of objects. Each object has three string properties: code, value and label. For a list of metadata codes see ImageIO - CGImageProperties.h on the Apple documentation.

Properties for video files

Every item in the fileData.audioTracks is an object with these properties:

Every item in the fileData.chapters is an object with these properties:

Every item in the fileData.subtitles is an object with these properties:

Properties for audio files

Properties for PDF files

Properties for Office files

Properties for compressed archives

Every item in the fileData.files array has these properties:

Properties for folders

Known bugs and limitations

• A managed folder placed in the Finder sidebar uses a wrong icon. This only happens for directly managed folders, not for subfolders. This is a common issue for many Finder Extension due to a macOS API limitation. A temporary workaround is to manage the parent folder of the one located in the sidebar.

• Menu item separators are not rendered as usual. This is a limitation of the Apple API.

• The Apple API allow to set only few option for each menu items: title, tag, image (automatically resized to 16x16 px), indentationLevel, enabled, state, action (the target is always the FIFinderSync instance). When the menu image is passed from the code to the System it will be reprocessed ad lose the template attribute. This prevent the B/W image to change the color from black to white when the menu item is selected.

• When multiple Finder Extensions are enabled, there is no way to set in witch order the menu of every extension is positioned.

• All menu items generated by Finder extensions are available only when all extensions complete their processing stage.

• Files/Folder inside CloudStorage (GoogleDrive, Dropbox, …) cannot be handled.

Build from source

Clone the repository (do not download the source code because break the required git submodule):

git clone https://github.com/sbarex/MediaInfo.git 

Then open the Xcode project, change the signing team and build. First time the build process can be slow due to the compilation of the dependencies libraries.

The required libraries are linked inside the extension and compiled within Xcode, so no others external dependencies are required.

Dependencies

This app uses these libraries:

• FFMpeg
• WebP
  • libpng
  • jpeg-turbo (require CMake to build)
• libarchive
  • liblz4
  • libb2
  • zstd
  • xz
• LineNumberTextView

Application processes

The application uses two XPC processes:

• MediaInfo Settings XPC: used by the main application to store the settings. This bypass the AppGroup functionality that require a signed app to works.
• MediaInfo Helper XPC: used by the Finder Extension to read the settings an analyze the selected file. The XPC process can access to files within mounted disks (external or network disks) that would not be accessible by the MediaInfo Finder Extension.

Credits

Developed by sbarex with ❤️.