silica-viewer/README.md

# Silica Viewer

(This project is no longer maintained. While it may still work, see [this blog post](https://redstrate.com/blog/2023/03/future-of-silica-viewer/) for alternatives and more information.)

This is a macOS app to view [Procreate](https://procreate.art) documents, and it also contains [QuickLook](https://support.apple.com/guide/mac-help/preview-files-with-quick-look-mh14119/mac) and thumbnail extensions to allow you to
quickly preview your files as well!

![screenshot](misc/screenshot.png)

I created this app because I frequently store backups of my Procreate documents on my computer, but you can't actually preview them! And if you're like me, your files have nonsense or unusable names like "Untitled" or "Untitled 1", which makes file management harder.

## Installation

I stopped [distributing the application on the App Store](https://redstrate.com/blog/2023/03/future-of-silica-viewer/) but there's nothing stopping you from compiling it on your Mac!

## Usage

Installing this app is simple, just open it at least once to register the QuickLook and thumbnail extensions to Finder. Although it's still experimental, you can view Procreate files in-app.

For user's interested, this app registers the `com.procreate` [UTI](https://developer.apple.com/documentation/uniformtypeidentifiers) into your system. This is registered for all `.procreate` files (they are detected via file extension).

## Dependencies

Swift Package Manager is used to handle our only Swift dependency, [ZipFoundation](https://github.com/weichsel/ZIPFoundation). This is automatically fetched when you open the project in XCode.

[MiniLZO](http://www.oberhumer.com/opensource/lzo/) is used to decode image data but has already been included in the repository for convenience.

## Reverse Engineering Notes

When looking at `.procreate` files, it's important to note that they are actually standard ZIP files. If you want to take a
quick look at the file contents, simply extract them. Here's a sample directory listing: 
```
- (Layer folders named by their UUID)
  - Contains .chunk files, the raster canvas data for the document.
- QuickLook
  - Thumbnail.png - Low-quality screenshot generated by Procreate.
- video
  - segments
    - segment-X.mp4, where X is a number starting from 1.
- Document.archive - NSKeyedArchive containing layer information along with other document information like canvas size.
```

### Raster Canvas Data

Reading back the actual raster information is extremely easy, most of this work as already been pioneered by  [jarmovogel's Procreate Viewer](https://github.com/jaromvogel/ProcreateViewer) and simply adapted to Swift. In short, each of the `.chunk` files is compressed via [LZO](https://en.wikipedia.org/wiki/Lempel–Ziv–Oberhumer). When uncompressed, it is just raw rgba data.

### Thumbnails

When the document is modified in Procreate, they generate a PNG thumbnail automatically. This is located in the `QuickLook/Thumbnail.png`. This is used by Procreate's own thumbnail extension on iOS/iPadOS. Even though it's a thumbnail image, is actually pretty decent quality. This is also used by this app's QuickLook and Thumbnail extensions.

### Timelapse Video

Procreate, just like with thumbnails and image data - continue to use standard formats for storing data. This is no exception for timelapse video, which is simply a series of mp4's starting at `segment-1.mp4`. As far as I know, you can't glean the number of segments required for a full video ahead of time, so you must resort to listing the segments in the `video/segments` folder beforehand.

### Document Data

Layer names, time spent and other data is located in `Document.archive`. This is the only hard-to-read file in Procreate documents, but it is a [NSKeyedArchive](https://developer.apple.com/documentation/foundation/nskeyedarchiver). Here, we just use the [PropertyListSerialization](https://developer.apple.com/documentation/foundation/propertylistserialization) object to decode this in Swift.