If you want to download files from the Internet it makes sense to use a download manager app that will take care of all the details for you. If you want to automate the downloading of files using Keyboard Maestro (KM), you would do well to look at the Leech download manager application from Many Tricks Software because it can be controlled through the use of AppleScript.
The TFL Leech Control Suite is a set of four third party plug in actions for KM. The actions provide an easy way for KM users who are unfamiliar with AppleScript to integrate the Leech application into their KM macros in order to automate the download process. The four plug in actions are described in the remainder of this document.
The final section provides important information regarding the recommended settings you should make to the Leech app and also presents an example of a useful KM macro demonstrating the use of the TFL Leech Control Suite.
Here is the Leech Control Suite installation file. To install, just download the file and drag it onto the KM icon in the dock:
TFL Leech Control Suite.zip (1.0 MB)
The KM macros that demonstrate the use of the Leech Control Suite are here:
Download Using Leech Demo Macros.kmmacros (23.2 KB)
TFL Leech Download URLs Action
Appearance
When added to a macro using the Keyboard Maestro Editor the action looks like this and shows the defaults for the available fields:
Purpose
This action adds the specified files to Leech’s download queue which will be saved to a specific folder on your Mac.
Parameters
The TFL Leech Download URLs action provides two fields as follows:
| Parameter | Description |
|---|---|
| From URL | One or more URLs from which the downloads are to be taken. If there is more than one URL they should be listed, one per line. |
| To Path | The path to the folder on your Mac in which the downloaded files are to be placed. By default, this is set to ~/Downloads. |
Notes
Both fields accept Keyboard Maestro text tokens. Here’s an example of a real
use of the action:
If you want to rename files as they are downloaded then you must specify just one file to download and also specify the full pathname (including the file name and extension) on your Mac, then Leech will rename the downloaded file to match that pathname.
TFL Leech Count Downloads Action
Appearance
When added to a macro using the Keyboard Maestro Editor the action looks like
this and shows the default value for the available field:
Purpose
This action returns the number of files currently in the download queue. The count includes both failed files and also yet-to-be-downloaded files.
Parameters
The TFL Leech Count Downloads action provides a single field that allows the result of the action to be saved to a variable, appended to a variable, saved to a clipboard, displayed in a window, or displayed briefly in a notification.
TFL Leech Count Failed Downloads Action
Appearance
When added to a macro using the Keyboard Maestro Editor the action looks like this and shows the default value for the available field:
Purpose
This action returns the number of files currently in the download queue that have failed to be downloaded.
Parameters
The TFL Leech Count Failed Downloads action provides a single field that allows the result of the action to be saved to a variable, appended to a variable, saved to a clipboard, displayed in a window, or displayed briefly in a notification.
TFL Leech Q Control Action
Appearance
When added to a macro using the Keyboard Maestro Editor the action looks like one of these:
Purpose
This action controls whether to start, pause or cancel the downloading of files in Leech’s download queue.
Parameters
The TFL Leech Q Control action has one setting – the Action popup menu. Use this menu to select the desired effect on Leech’s download queue: Start, Pause, or Cancel. Note that by choosing the Cancel action, the download queue will be emptied when KM executes the action.
Tips and Tricks
Recommended Settings for Leech and KM
So as to ensure your KM macros have full control over Leech, it’s recommended you make these settings in Leech.
- Firstly, choose to disable Leech’s setting to start downloads automatically:
- Next, make sure Leech launches automatically and runs in the menu bar:
- Then change the settings regarding how Leech empties its download queue as follows:
This is important as we want to be able to count the number of downloads that have failed.
- Fourthly, make sure that Leech remains running even when all downloads have completed.
Pause Your Macro Until Downloads Are Complete
Sometimes when you have a macro that downloads files from the Internet you’d like your macro to wait until the downloads are complete before continuing. While monitoring folders for new/changed files is easy in KM, it is also easy to get wrong (as seen in the many posts to the KM forum). Using Leech and the TFL Leech Control Suite makes this task both straightforward and foolproof. Here’s an example of how to do it:
This makes use of the fact that when Leech has finished downloading (provided the recommended settings are in place for the app), the count of downloads remaining in the queue is equal to the count of failed downloads.
Demonstration Macro
This macro comes in two parts:
-
A general-purpose subroutine that lets you use the TFL Leech Control Suite in a tried and tested way.
-
A demonstration macro that uses the subroutine to download image files from any web page.
Here’s the demonstration macro:
It first uses some JavaScript to get a KM array containing the URLs of all the images in the front browser’s web page. Then the macro converts that array into a list – one per line – which is then passed to the subroutine that performs the actual downloading. Finally the macro
displays the number of downloads that have failed.
Usually, you won’t get any failed downloads so if you want to try some downloads that will fail, just enable the orange action and run the macro again and see what happens!
The subroutine’s usage notes are here:
Name: [SUB] Download Using Leech
Purpose:
This subroutine enables the downloading of files from the Internet using the Leech download manager and the TFL Leech Control Suite plug ins.
Inputs:
The subroutine expects the following input parameters:
-
Local__List A list of one or more URLs (one per line) specifying the location of the files to be downloaded.
-
Local__Path The path on the Mac where the files are to be downloaded.
-
Local__Clear Queue First Set this to "y" or "yes" (case insensitive) to tell Leech to empty its download queue prior to proceeding.
Output:
The subroutine returns the count of the number of downloads that failed.
Operation:
-
After first pausing the download queue, the subroutine then empties the queue if that has been specified.
-
Then the list of URLs is added to the queue as well as the path to which they will be downloaded.
-
The queue is then started and a loop is entered that checks the number of files left in the queue against the number of failed downloads.
-
When those numbers are the same it signifies the downloads have finished and the loop exits.
-
The queue is then stopped and the subroutine returns the number of downloads that failed.
By examining both the macro and subroutine you should be able to see other ways of integrating the TFL Leech Control Suite plug ins into your macros.
And the subroutine looks like this:
