Move images by updating RELATIVE_PATH

[flexagoon]

Guidelines

• I have read the guidelines to open issues

Use case

Currently, Aves moves images by writing the source bytes to the new file stream. This works, but takes a long time when moving a lot of images. When using the "preserve dates" option, which currently works by modifying Exif metadata, it takes even longer.

Proposal

Android apparently provides a way to update the RELATIVE_PATH field of a media file directly, which moves it to the new location instantly and doesn't change the modification date.

I am not very knowledgeable about this, but here is the AI output from analyzing https://github.com/IacobIonut01/ReFra which uses this method, which could provide some guidance:

Slop explanation

Here's how it works:

The trick: using MediaStore.RELATIVE_PATH instead of copy+delete

The critical code is in MediaRepositoryImpl.kt:

override suspend fun <T : Media> moveMedia(
    media: T,
    newPath: String
): Boolean {
    val (destVolume, destRelPath) = resolveMediaStoreVolume(newPath)
    val sourceVolume = media.mediaStoreVolumeName

    if (destVolume == sourceVolume) {
        return context.updateMedia(
            media = media,
            contentValues = relativePath(destRelPath)
        )
    }

    return crossVolumeMove(media, destVolume, destRelPath)
}

The relativePath helper (same file, bottom) just creates:

private fun relativePath(newPath: String) = ContentValues().apply {
    put(MediaStore.MediaColumns.RELATIVE_PATH, newPath)
}

This is the key. On Android 10+ (API 29+, scoped storage), RELATIVE_PATH is a virtual column in MediaStore. When you call ContentResolver.update() with just RELATIVE_PATH set to a new directory, Android itself moves the file on disk — without ever opening, reading, or writing the file's contents. The file's mtime (last-modified timestamp) is left untouched because it's just a filesystem-level rename/move, not a copy.

Contrast this with naive gallery apps that do a manual "read source → write to destination → delete source" pipeline. That creates a brand new file at the destination, which gets the current time as its modification date.

The cross-volume exception

For moves between different storage volumes (e.g., internal storage → SD card), the app does fall back to a copy+delete in crossVolumeMove(), and it explicitly sets DATE_MODIFIED to current time there. This is unavoidable — you can't do a zero-cost rename across volumes. But for the common case of moving photos between albums on the same storage device, the RELATIVE_PATH trick preserves the original date perfectly.

---

Alternatives

Changing the modification date via Exif does have major advantages over this method, since it also preserves the date during file synchronization, etc.

However, even if you want to keep the Exif method of automatically preserving dates, using this API would still make the file moving much faster and would greatly improve the user experience

Additional context

No response

[deckerst]

Yes, it's something I had on my mind and intended to try. A long time ago media store API was more limited (it wouldn't work on Sd card, etc), but now i might make it the default way (and use the other API as fall back).

[deckerst]

Regarding the rationale for preferring the SAF API over the Media Store API, I found notes to myself from 2020:

Relying on DocumentFile, we can create an item via DocumentFile.createFile(), but:

• we need to scan the file to get the Media Store content URI
• the underlying document provider controls the new file name

Relying on the Media Store, we can create an item via ContentResolver.insert()
with a path, and retrieve its content URI, but:

• the Media Store isolates content by storage volume (e.g. MediaStore.Images.Media.getContentUri(volumeName))
• the volume name should be lower case, not exactly as the StorageVolume UUID
  cf new method in API 30 StorageVolume.getMediaStoreVolumeName()
• inserting on a removable volume works on API 29, but not on API 25 nor 26 (on which API/devices does it work?)
• there is no documentation regarding support for usage with removable storage
• the Media Store only allows inserting in specific primary directories ("DCIM", "Pictures") when using scoped storage

Preferring the Media Store API for file creation/move would be for Android API 30+, and I'd need to check the limitations on the target directories.