README.md

Clop SDK

Image, video, PDF and clipboard optimiser

Software Development Kit

ClopSDK is a Swift Package that optimizes images, videos, and PDFs by sending them to the Clop macOS app.

Installation

You can install ClopSDK using the Swift Package Manager. To add it to your Xcode project, go to File > Swift Packages > Add Package Dependency and enter the URL of this repository.

You can also add it to a standalone Swift package by adding it to your Package.swift file:

let package = Package(
    name: "MyPackage",
    dependencies: [
        .package(url: "https://github.com/FuzzyIdeas/ClopSDK.git", from: "1.0.0")
    ],
    targets: [
        .target(
            name: "MyPackage",
            dependencies: ["ClopSDK"])
    ]
)

Usage

To use ClopSDK, simply import it into your Swift file:

import ClopSDK

Then, you can use the ClopSDK class to send file paths to the Clop app:

// Optimise a single file
try ClopSDK.shared.optimise(path: "/path/to/image.jpg")

// Optimise multiple files
try ClopSDK.shared.optimise(paths: ["/path/to/image.jpg", "/path/to/video.mp4", "/path/to/document.pdf"])

// Send a file to be optimised in background by Clop (don't wait for a response, return immediately)
try ClopSDK.shared.optimise(path: "/path/to/image.jpg", inTheBackground: true)

The optimise method will connect to a local mach port (CFMessagePort) that Clop is listening to, and send the file paths to the app through it.

To make sure the app is running before sending the file paths, you can use the waitForClopToBeAvailable method:

// Wait for Clop to be available for 5 seconds
let clopIsAvailable = ClopSDK.shared.waitForClopToBeAvailable(for: 5)

Stop running optimisations

You can stop currently running optimisations by calling the stopOptimisations method:

ClopSDK.shared.stopOptimisations()

Options

You can also pass options to the optimise method to change the way Clop optimises the files, or to add additional functionality like cropping, downscaling, changing playback speed etc.

func optimise(
    urls                   : [URL],
    aggressive             : Bool       = false,
    downscaleTo            : Double?    = nil,
    cropTo                 : CropSize?  = nil,
    changePlaybackSpeedBy  : Double?    = nil,
    hideGUI                : Bool       = false,
    copyToClipboard        : Bool       = false,
    inTheBackground        : Bool       = false
) throws -> [OptimisationResponse]

// There are various overloads of the method for convenience in path passing

optimise(path  : FilePath, ...)
optimise(path  : String, ...)
optimise(url   : URL, ...)

optimise(paths : [FilePath], ...)
optimise(paths : [String], ...)
optimise(urls  : [URL], ...)

The response will contain the optimised file path, which can be different if the file had to be converted to a more compatible format (depending on how the app is configured by the user).

struct OptimisationResponse {
    let path: String // The optimised file path
    let forURL: URL // The original file URL
    var convertedFrom: String? = nil // File that started the conversion

    var oldBytes = 0 // File size before optimisation
    var newBytes = 0 // File size after optimisation

    var oldWidthHeight: CGSize? = nil // Dimensions before optimisation
    var newWidthHeight: CGSize? = nil // Dimensions after optimisation
}

For more examples on how to use the SDK, check out the tests.

Objective-C

ClopSDK is also available in Objective-C:

bool clopIsAvailable = [ClopSDKObjC.shared waitForClopToBeAvailableFor:5];
if (!clopIsAvailable) {
    NSLog(@"Clop is not available");
    return;
}

OptimisationResponseObjC* response = [ClopSDKObjC.shared optimiseWithPath:@"/path/to/image.png" error:nil];
if (response) {
    NSLog(@"File optimised at %@", response.path);
}

License

ClopSDK is available under the MIT license. See the LICENSE file for more info.