Important
This is unofficial documentation of formats used by Apple Maps on macOS 26. It is not affiliated with or endorsed by Apple. The models are Apple’s and the original artists’ work. I don’t publish any map data, and you shouldn’t redistribute what you export. The formats may change in any update.

The code is at code.lev.cx/lev/vmp4-mesh. It’s a Rust CLI that exports GLB files, with the format notes in research/.

Finding the cache

Maps doesn’t download tiles itself. A system daemon called geod does that for every app, and it keeps them in an SQLite database:

~/Library/Containers/com.apple.geod/Data/Library/Caches/com.apple.geod/Vault/MapTiles/MapTiles.sqlitedb

That Vault folder is protected by SIP, so even root can’t read it on a normal Mac. My first copy came from a macOS VM with SIP turned off. That got me started, but a VM’s cache only holds what you happened to look at in it.

The better route turned out to be asking geod itself. GeoServices, the private framework Maps uses, has a tile loader that any process can call, and geod answers from its cache, or downloads the tile if you allow it. So a small Objective-C tool can fetch one tile at a time with SIP left on, and the vault never has to be opened.

Every tile has a 128-bit key. It packs a tileset id, a zoom (6 bits, not the 7 an older tool assumed), and the tile’s x and y. Most tiles are map data in a container called VMP4. The 3D models are a separate kind of tile, and their payloads start with readable magic bytes: DVas for the models and DvMt for their materials. “DV” turns out to be DaVinci, which is Apple’s internal name for the detailed 3D map.

The model format

A DVas file starts with the magic and a version, and every file I had was version 20. Then a table of levels of detail, and the first mystery.

At offset 8 there was always either 01 00 or 03 00, followed by fa 00, and I read it as a 16-bit number. It isn’t one. It’s two bytes: a LOD count, then the id of the first LOD. The fa 00 after it is that LOD’s threshold, 250. Files with three LODs have thresholds of 250, 100 and 50, and each LOD covers the range down to the next one. I still don’t know the units.

After that comes a bounding box (a minimum and a size, rather than a minimum and a maximum), the vertex formats, the meshes, the materials and a node tree that places meshes relative to each other. That part is plain bookkeeping. The meshes are where it gets hard.

Compressed meshes

Most meshes are compressed, and the blob starts with 71 8e a2 fa, followed by a CRC32 of the rest. Inside, it’s a proper mesh codec. Connectivity is coded as triangle fans around each vertex. Each new vertex position is predicted from the triangle next to it, by completing a parallelogram, and only the difference from that guess is stored. All of it goes through an adaptive arithmetic coder.

If you know mesh compression, that sounds a lot like Open3DGC. It’s clearly the same family, but it isn’t compatible: the arithmetic coder, the set of fan operations and the contexts are all different. So no existing decoder would read it, and I worked it out from Apple’s own decoder in VectorKit, the framework that renders the map.

The check I trusted most was that a decoder has to land exactly on the end of the data. Across 42 sample files, every container parsed to its last byte, all 121 meshes decoded, and every vertex and triangle count matched the header. Wembley’s stadium comes out as 27,746 vertices and 19,448 triangles, and its decoded bounds match the header’s bounding box to the bit.

Textures live in the DvMt files as ASTC, the block-compressed format GPUs read directly. My first version shelled out to sips to convert them. It now decodes them itself, so exporting works on Linux too, as long as you bring tiles fetched on a Mac.

Asking macOS for the answers

Guessing a format from samples tells you what’s likely. For the rest of the map I wanted something stricter, and macOS already ships a decoder for every one of these tiles.

So I wrote a small tool that loads the system GeoServices, hands it a cached tile, and dumps what it decoded: vertices, triangles, rasters. Everything runs locally and offline. That made every question checkable. If my decoder disagreed with the system’s by a single vertex, it was wrong, and I knew exactly where.

That oracle is what made the next two parts possible.

It also made it safe to have help. I didn’t do this alone: I used Claude Code agents for most of the heavy lifting, reading the decompiled decoders, writing Python prototypes and porting them to Rust. I chose what to go after, steered them out of dead ends and checked the renders. An agent will happily hand you a decoder that looks right, so nothing counted as decoded until it matched macOS’s own output exactly.

The ground

A landmark floating in black space is nice, but I wanted Wembley standing on Wembley. The ground lives in a different tileset and has three layers.

Terrain is a 64×64, 16-bit greyscale PNG embedded in the tile. Heights run from −12,000 to +12,000 metres across the 16-bit range. Wembley’s tile came out at 77.6 to 99.6 m, which is about 46 m higher than Ordnance Survey maps say. 46 m is exactly how far the geoid sits from the WGS84 ellipsoid in London, so these are almost certainly ellipsoidal heights, not heights above sea level.

Ground meshes are roads, pavements and paths, shaped to follow the terrain. They use the same mesh codec as the landmarks, plus an extra stream I hadn’t needed before: a number per triangle that says what it is, road or pavement or path.

Land cover is a 1024×1024 raster where every pixel points at a stack of material ids: a base of plain land, with overlays like park or pitch on top. The ids are just numbers, and the cache has no style sheet that names them.

The way I named them was by using the points of interest in the same tiles. Every POI has a name and a position, so I looked up which material sits under each one. The id under “APCOA”, “Pink Car Park” and “Tesco Click+Collect” is clearly parking. The one under 157 shops on Ealing Road is commercial. One id sits under the “Wembley Stadium” POI and forms a 112×71 m rectangle in the middle of the bowl, which is the pitch.

Against the system decoder, the ground meshes matched to within 4×10⁻⁹ of a tile, and 21 of 22 land cover rasters matched exactly. The one that didn’t was outside the area I cared about and uses a feature I haven’t implemented.

Putting the stadium on it

Each landmark has a placement record in the buildings tileset: a position inside the tile, a scale and a rotation. Wembley’s scale is 0.000817666. That number looked random until I noticed it’s 1/1222.99, and 1222.99 m is the width of a zoom-15 tile in Web Mercator.

So the model’s units are Mercator metres, which are stretched by latitude. At Wembley, one Mercator metre is only cos(51.56°) = 0.62 real metres across the ground. Heights aren’t stretched, so Z is in real metres. If you skip that, the stadium comes out about 60% too wide and too long.

With that fixed, the numbers line up:

• the top of the arch is 131.9 m above the model’s origin, and the real arch is 133 m tall
• the centre of the placed stadium is 4.1 m from its published coordinate
• the arch is on the north side, as it should be

The buildings around it

The ordinary buildings are their own chapter with their own codec: footprints and heights, compressed with the same family of tricks, then extruded into blocks. My decoder matches the system’s on all 31 cached tiles, down to every vertex and every height.

The best bug of the whole project was here. The ground and the buildings came out of separate investigations, and they disagreed on which way Y pointed. One had +Y as north, the other as south. Each was internally consistent, so both looked fine on their own, and the mismatch only mattered once they had to share one scene.

There was also a bug that wasn’t one. North of the stadium, the ground had white holes in it, which looked exactly like a decoder dropping tiles. It wasn’t. The VM’s cache just didn’t have them, because I’d never scrolled there. Fetching through geod returns the whole block, and the holes went away.

Where it’s at

vmp4-mesh export-asset turns any cached landmark into a textured GLB, optionally standing on its terrain with the surrounding buildings, and --night swaps in the night textures. export-ground does the same for any point on the map without a landmark.

It isn’t Apple Maps yet. Next to the real thing, a few things give it away:

• land cover edges are blocky, because I sample the raster as cells, and the real renderer clearly smooths them
• every building is a flat-topped extrusion. The format has a roof flag, but it’s 0 everywhere I’ve looked
• there are no trees, and I haven’t found where they live
• another chapter, which looks like low-detail stand-ins for the landmarks, decodes fine but I don’t know what it’s for

Each of those is one more thing to diff against the oracle, which is the nice part of this project: macOS will always tell me when I’m wrong.

Important
This is unofficial documentation of the .kine file format based on files exported by KineMaster 8.1.17.2420 on iOS. It is not affiliated with or endorsed by KineMaster. The format may change in future versions. This is about interoperability, not about unlocking anything paid.

Opening the file

unzip -l was enough to get started. A .kine is a ZIP, holding a .kmproject file named after the project, plus a contents/ folder with any imported media.

The media handling is inconsistent in a way that matters later. Video and audio are copied in byte for byte, but renamed to a numeric id such as 1000.mov. Images are re-encoded as JPEG, and may keep their original name or be given a UUID depending on where they were imported from. Solid colours are not stored as files at all. So the file names can’t be trusted, and anything reading these files should resolve media through the reference in the project rather than by looking at contents/.

The .kmproject container

The .kmproject opens with f3 4b 4d ea, which shows up as .KM. in a hex dump. It isn’t a single blob; it’s a small chunked container:

f3 4b 4d ea               magic
00 00 00 01               version, big-endian uint32
repeated chunk:
  4-byte tag              "KHDR" -> project header
                          "TLIN" -> timeline
                          "FTRX" -> end marker, always length 0
  big-endian uint32       payload length
  payload                 (no checksum)

The tags appear to be abbreviations: header, timeline, and presumably a footer. The chunk lengths chain exactly to the end of the file, which makes a nice integrity check, and there is no checksum anywhere.

The payloads inside KHDR and TLIN turned out to be Protocol Buffers. There’s no schema shipped with the file, of course, so protoc --decode_raw gives you field numbers and values but no names:

2: 2420
8: 4500
101: "com.nexstreaming.kinemaster.basic"
109: "example"

That is enough to start guessing. Field 8 was 4500 in a project that was 4.5 seconds long, 109 was the project name, and 101 was clearly the app id.

Seventeen samples

Guessing field by field from one file gets you nowhere, so I made 17 sample projects, each changing exactly one thing from a baseline: a black screen with nothing else. One sample trimmed a video. One added a crossfade. One rotated some text by 37 degrees. One changed the font.

Then it’s just diffing. The trimmed video sample changed exactly two fields, 128 and 129, to 1913 and 1180. The source video was 5000 ms, and the header duration in that sample was 1907. 5000 − 1913 − 1180 = 1907, so 128 and 129 are the trims taken off the start and end, and the played length is what remains. No guesswork needed.

The crossfade sample was similar. A 5000 ms clip and a 4500 ms clip, with a 1500 ms crossfade between them, gave a project 8000 ms long: 5000 + 4500 − 1500. So transitions overlap their neighbours rather than sitting between them, which also explains why clips don’t store a start time anywhere. Each clip’s position falls out of the durations and overlaps before it.

Setting speed to 2x changed one field from 100 to 200 and halved the header duration. Volume at 37% changed one field to 37. Those are percentages, which is unremarkable but worth knowing.

The timeline

The timeline chunk has two lists. One is the primary track, in playback order, alternating clip, transition, clip, transition — every clip gets a transition slot after it, holding an asset id of none when you haven’t set one. The other is the layers: text, images, videos and audio, listed bottom to top. Unlike clips, layers carry absolute start and end times, and a layer is allowed to run past the end of the primary track.

Each item carries a 128-bit id, a type, and a body that depends on the type:

Types 5 and 6, with bodies 8 and 10, are presumably stickers and handwriting. I didn’t sample those: KineMaster’s stickers are their own artwork and you can’t import your own, so there was nothing I could make a sample from without copying theirs.

Media is referenced by URI rather than by path:

That’s also why the black screen sample has no media file in it at all. The clip just points at kmm://color/FF000000.

Units that surprised me

Pan and zoom, the Ken Burns effect, is stored as two rectangles: where the view starts and where it ends. The values are in 1/100000 of the source image, so the default full frame is (0, 100000, 100000, 0). Zooming out pushes values outside that range, which is how I ended up staring at -33718.

Working out the field order took a while. What settled it: if the order is left, bottom, right, top, then both rectangles come out exactly as wide as they are tall in these units. That’s what a 16:9 view of a 16:9 image should give, and it held for both the zoomed-out start and the zoomed-in end. Any other ordering gave nonsense aspect ratios.

Keyframe times are the other trap. I expected milliseconds; they’re a fraction of the layer’s duration. My three-keyframe sample stored 0, 0.2278 and 0.4591, which against a 4500 ms layer works out to 0, 1025 and 2066 ms.

Everything else is what you’d expect. Positions are in canvas pixels, so 640, 360 is the centre of a 1280x720 project. Rotation is in degrees, which the 37 degree sample confirmed exactly. Colours are ARGB. Other times are milliseconds.

One nice detail: each layer stores a base size as a fraction of the canvas, and for text that’s the measured text box. Switching the font from Times New Roman to Arial nudged it from 0.1039 to 0.1070, because Arial renders “Hello, world!” slightly wider.

Writing one back

Documenting a format is one thing; the real test is whether the app accepts what you write.

I wrote a protobuf schema naming every field I’d seen, then checked something that turns out to matter a lot: decode a file and re-encode it, and you should get byte-for-byte identical output. Getting there took two adjustments. Every field has to be declared, including the ones whose meaning is a mystery, because an encoder appends unrecognised fields at the end and reorders the file. And KineMaster writes zero values explicitly, so a schema that treats zero as “absent” silently drops them. Once both were handled, all 17 samples round-tripped exactly.

Then I generated three files: one that only changed the project name, one with different text in a different colour, and one shortened from 4500 to 2000 ms. I AirDropped them over and opened them.

All three worked. The text sample showed my new text in orange; the shortened sample really was 2 seconds. The duration one was the interesting check, because a project’s length is written in several places at once, and a missed one would have shown up as a 4.5 second clip. It didn’t.

I also left the thumbnail in the header stale, still showing the old project, and the app didn’t care. It re-rendered it after the first edit.

Future work

Plenty is still unmapped. My favourites, in the sense of most annoying:

• Two more rectangles sitting next to the pan and zoom ones, identical in all 17 samples at (-108024, 100000, 208024, 0). They never moved, so I have nothing to diff.
• Six floats on image and video layers holding 0.72, 0.5, 0.25, 0.25, 0.75, 0.75, which look like chroma key settings, including the two control points from the key curve.
• A field that always equals the clip’s source duration, and has to be updated alongside it, for reasons I can’t explain.
• A second transform-shaped block on every layer that isn’t one of the keyframes.

Each of those would fall out of one more sample changing one more setting, which is the whole method really: change one thing, diff, write down what moved.

Important
This is an unofficial documentation of the .widgy file format based on files exported by Widgy. It is not affiliated with or endorsed by Widgy. The format may change in future versions.

I am a fan of their app, and I have even purchased the expansion slots for home screen widgets, so I am familiar with the app. There is a feature which lets you export your widgets as a .widgy file. I made a sample widget and exported it, then transferred it to my Mac.

Decoding the .widgy file

I tried opening it in a text editor, but I was met with binary and unreadable text. I popped it into CyberChef, and used their Magic operation, but that led to no results.

After a bit of messing around in CyberChef, I got a recipe that worked: Raw Inflate. There is no need to change any parameters, as the default parameters worked, but it did give me a readable JSON.

The JSON format

The JSON format was odd. There weren’t readable keys, instead there were these shortened keys such as 0 and d0. This JSON appeared to be generated from a compact internal schema, with short keys being used instead of descriptive names, but I am not going to go too far to extract the schema.

The following root-level fields have been identified:

Layer object

The layer object is confusing at first, but I have been able to map some of its fields, including the layer type, names, and handling of groups.

The layer name was stored in the s key. The layer type (z key) appears to be an enum with the following values:

Group handling

The group layer type (value 13) is a special case. When a group layer is encountered, the 1 key contains an array of nested layers (just like in the widget root).

Sharing widgets

QR codes

Widgy also supports sharing widgets through QR codes. After investigating the QR code data, I found that it contains the widget data itself rather than simply pointing to a download URL.

The QR code payload appears to be a Base64 encoded raw DEFLATE stream containing the same JSON structure used by the .widgy file format.

The process appears to be:

Widget JSON
    ↓
Raw DEFLATE compression
    ↓
Base64 encoding
    ↓
QR code payload

Unlike some Base64 implementations used in URLs, this does not appear to use URL-safe Base64 encoding. The standard Base64 alphabet is used.

This means a QR code can contain a complete widget without requiring an external server or download link.

Future work

There are still many unknown fields, including positioning, styling, and data sources. I may continue documenting these as I investigate the format further.

Since I don’t have much use for it as a tracker, I decided to find out how it works.

Try it yourself

I also made a small Web Bluetooth tool that connects directly to an iTAG. It can detect button presses and control the tracker’s alarm. Make sure you’re using a compatible browser, such as Chrome or Edge.

Open the iTAG Web Bluetooth tool →

Contents

• The iSearching app
• BLE advertising
• GATT services
• Taking it apart
• Decompiling iSearching
  • Starting with an older version
  • Multiple generations of iTAG
  • A newer protocol
  • Which protocol does my iTAG use?
  • The Tesco iTAG protocol

The iSearching app

The recommended app, iSearching, provides a camera remote, last-connected location history, disconnection alarms, voice recording and a button to make the iTAG ring.

• iSearching on the Apple App Store: iSearching App - App Store
• iSearching on the Google Play Store: iSearching - Apps on Google Play

The tag itself doesn’t contain GPS, a microphone or a camera. Most of those features are implemented by the phone.

BLE advertising

I used LightBlue on my Mac to inspect the device.

That manufacturer data becomes important later.

GATT services

These are the useful characteristics I’ve identified:

Writing 00 to 1802/2A06 stops the buzzer, while 01 or 02 starts it.

The Link Loss characteristic at 1803/2A06 accepts the same values. Curiously, it initially reads:

3C

That’s not a valid standard Alert Level. Writing 00, 01 or 02 makes subsequent reads return that value until the iTAG is restarted, when it returns to 3C.

The physical button is simpler. Subscribing to notifications from FFE1 produces:

01

when the button is pressed. Holding the button powers the iTAG off.

FFE3 contains:

4F0F02545348

which is exactly the first six bytes of the advertised manufacturer data:

4F0F025453486602010300

Its final three bytes are ASCII TSH, although I don’t yet know what that means.

There are also several unidentified proprietary characteristics:

FFE0
├── FFE1
├── FFE2
├── FFE3
├── FFE4
├── FFE5
├── FFE6
└── FFE7

FF01
├── FF02
└── FF03

AE00
├── AE01
└── AE02

Rather than blindly writing arbitrary data to them, I decided to find out what the official app does.

Taking it apart

Naturally, I also opened the tracker.

The PCB is extremely simple. Unfortunately, the main Bluetooth controller uses chip-on-board construction: the silicon is hidden beneath black epoxy, leaving no conventional chip marking to identify.

There are test pads labelled DP, DM, VDD and GND. I don’t yet know whether DP and DM are USB, a programming interface or something else.

I don’t currently have the hardware needed to probe them or attempt a firmware dump, so I took another route: decompiling iSearching.

Decompiling iSearching

The Android app can be opened in JADX, allowing its BLE implementation to be searched for the UUIDs exposed by the tracker.

Starting with an older version

I started with iSearching 1.3.2. Searching for FFE0 quickly found:

public static String c = "0000ffe0-0000-1000-8000-00805f9b34fb";
public static String d = "0000ffe1-0000-1000-8000-00805f9b34fb";
public static String e = "00001802-0000-1000-8000-00805f9b34fb";
public static String f = "00001803-0000-1000-8000-00805f9b34fb";
public static String g = "00002a06-0000-1000-8000-00805f9b34fb";

The app enables notifications on FFE1, and its notification handler recognises two values:

01
A1

For 01, it waits 500 ms for another event to distinguish a single click from a double click. In camera mode, it takes a photo immediately.

The old app also writes 00, 01 or 02 directly to 1802/2A06 to control the alarm, matching my experiments.

Useful confirmation, but it didn’t explain the unidentified proprietary characteristics.

The current version did.

Multiple generations of iTAG

The current iSearching BLE implementation lives under:

com.zoqin.iSearchingPro.ble

Its BleCodeToDataUtil class contains:

public static final int DEVICE_TYPE_ITAG = 1;
public static final int DEVICE_TYPE_MYTAG = 2;
public static final int DEVICE_TYPE_OLD_ITAG = 0;

So iSearching doesn’t have one universal iTAG protocol. It supports multiple generations.

The old-iTAG profile maps its operations to these characteristics:

That finally gives FFE2 a purpose.

The application’s protocol table contains:

public static final String[] BLE_SEND_DISCONNECT_ALARM = {
    "555501",
    "5A510301",
    "01"
};

public static final String[] BLE_SEND_DISCONNECT_NOT_ALARM = {
    "555500",
    "5A510300",
    "00"
};

The old-iTAG profile selects index 2:

FFE0 / FFE2

01 = enable disconnection alarm
00 = disable disconnection alarm

This also explains something odd from my earlier experiments.

Although the tracker exposes the standard Link Loss characteristic at 1803/2A06, current iSearching doesn’t use it to configure the old iTAG’s disconnection alarm. It writes to FFE2 instead.

So the mysterious initial 3C value in 1803/2A06 appears to be a separate firmware quirk.

A newer protocol

DEVICE_TYPE_ITAG and DEVICE_TYPE_MYTAG use a newer protocol. FFE1 becomes the command/configuration characteristic and FFE2 becomes the notification characteristic.

Most packets begin with 5A 51:

The generic protocol class also contains commands for a Hall alarm and connection verification, but neither iTAG profile actually assigns those fields. Their presence isn’t evidence that the Tesco tracker supports them.

Which protocol does my iTAG use?

This was the interesting part.

During BLE scanning, iSearching extracts the Manufacturer Specific Data (0xFF) from each advertisement and passes it to a method wonderfully named:

Warehousing()

For devices named iTAG, it performs this check:

i = (
    bArr.length != 0 &&
    (bArr[4] ^ 18) == bArr[9] &&
    (bArr[5] ^ 18) == bArr[10]
) ? 1 : 0;

18 decimal is 0x12, so:

manufacturer[9]  == manufacturer[4] XOR 0x12
manufacturer[10] == manufacturer[5] XOR 0x12

If both comparisons succeed, the tracker is type 1, using the newer protocol. Otherwise it’s type 0, DEVICE_TYPE_OLD_ITAG.

Remember the Tesco tracker’s manufacturer data?

4F 0F 02 54 53 48 66 02 01 03 00

The relevant bytes are:

manufacturer[4]  = 53
manufacturer[5]  = 48
manufacturer[9]  = 03
manufacturer[10] = 00

Now apply the XOR:

53 XOR 12 = 41
48 XOR 12 = 5A

Neither matches:

41 != 03
5A != 00

So current iSearching identifies the £3.50 Tesco tracker as:

DEVICE_TYPE_OLD_ITAG = 0

The Tesco iTAG protocol

We can now reconstruct the part of the protocol that current iSearching actually uses:

FFE0 / FFE1
  Notify
  01 = button/check event

FFE0 / FFE2
  Write
  00 = disconnection alarm disabled
  01 = disconnection alarm enabled

1802 / 2A06
  Write
  00 = stop alarm
  02 = start/check alarm

The physical tracker exposes considerably more than this, including Battery, Tx Power, Link Loss, FFE3 through FFE7, FF01 and AE00.

That’s an important distinction: decompiling iSearching tells us what iSearching uses, not necessarily everything the firmware can do.

Still, several independent pieces of evidence now agree. The alarm commands from the APK work on the physical tracker. FFE1 matches its button events. FFE2, previously unidentified, controls iSearching’s disconnection-alarm setting. And the advertising data captured over the air goes through the exact classification algorithm that selects this protocol.

At this point, the protocol isn’t much of a black box anymore.

Which raises a more entertaining possibility.

Instead of writing software that talks to an iTAG, there is now enough information to write software that pretends to be one.

An emulator would only need to reproduce the advertising data and the small GATT server expected by iSearching. Incoming writes could be logged instead of activating a buzzer, while a virtual button could send the same FFE1 notification as the physical tracker.

If iSearching connects to it and behaves as though it were the £3.50 Tesco tracker, that would be a rather nice final test of the protocol recovered from the app.

That’s probably what I’m going to try next.

And, somehow, after all of this, the real tracker still works.

Text formatting

This is bold text.

This is italic text.

This is inline code.

This is a link to example.com.

Lists

Unordered

• First item
• Second item
• Third item

Ordered

1. Step one
2. Step two
3. Step three

Code block

function hello() {
  console.log("Hello, world!");
}

hello();

Inline code

To serve the page, run jekyll serve.

Quote

Good software is built one small improvement at a time.

Table

Final thoughts

This is the end of the test post.