1# mediatool工具 2 3mediatool是一个轻量级的命令行工具集合，开发者可通过此工具操作媒体库资源。媒体库为图库提供和管理数据，媒体库中的图片视频会在图库界面呈现。 4 5mediatool工具为系统自带工具，不需要安装，内置在/bin文件夹中，可以通过hdc shell直接调用。 6 7## 前置条件 8 9- 正常连接设备 10- 系统设置中开启开发者模式 11- 使用hdc shell进入命令行执行模式 12 13## 命令行说明 14 15<!--Del--> 16 17### mediatool send 18 19```shell 20mediatool send <path-to-local-media-file> [-ts] [-tas] [-rf] [-urf] 21``` 22 23该命令能够将设备`<path-to-local-media-file>`路径下的图片视频文件推入媒体库中保存。支持保存图片、视频和音频文件。文件在媒体库中会保留原有的名字。`<path-to-local-media-file>`可以为文件夹，mediatool会将文件夹里的所有文件置入媒体库中。保存成功后会打印成功置入的资源的uri。 24 25默认情况下，将媒体文件保存进媒体库是以同步方式创建缩略图，并且置入后```<path-to-local-media-file>```下的文件会被删除。 26 27 | 选项 | 说明 | 28| ---- |--------------- | 29| -ts | 保存图片视频时以同步方式创建缩略图。能够保证缩略图正常生成之后图片视频才会显示，但是会导致保存耗时较长。（默认） | 30| -tas | 保存图片视频时以异步方式创建缩略图。不能与-ts选项同时使用。图片视频保存后会立即显示，不会等待缩略图先生成。保存耗时较短。 | 31| -rf | 媒体文件置入后删除源文件。（默认） | 32| -urf | 媒体文件置入后不删除源文件。不能与-rf选项同时使用。 | 33 34**使用示例：** 35 36```shell 37> mediatool send /data/tmp/MyImage.jpg 38file://media/Photo/3/IMG_1721381297_001/MyImage.jpg # 推图成功，打印推入资源的uri 39``` 40 41### mediatool list 42 43```shell 44mediatool list <resource-uri> 45``` 46 47该命令能够将`<resource-uri>`指定uri对应的媒体库内资源信息以csv格式打印出来。 48例如媒体库内图片资源A的uri为file://media/Photo/3/IMG_1721381297_001/MyImage.jpg, `mediatool list file://media/Photo/3`或者`mediatool list file://media/Photo/3/IMG_1721381297_001/MyImage.jpg`都能成功打印出该资源信息。 49 50所打印信息包含： 51 52- uri: 媒体资源的uri。 53- display_name: 媒体资源的名字。 54- data: 媒体资源的源文件在设备中的物理路径。 55 56还可以将`<resource-uri>`指定为`all`。`mediatool list all`会将媒体库内所有资源的信息打印出来。 57 58**使用示例：** 59 60```shell 61# 使用存在的uri查询 62> mediatool list file://media/Photo/3 63Table Name: Photos 64uri, display_name, data 65"file://media/Photo/3/IMG_1721381297_001/MyImage.jpg", "MyImage.jpg", "/storage/cloud/100/files/Photo/2/IMG_1721381297_001.jpg" 66 67# 使用格式错误的uri查询 68> mediatool list file://media/Photo/ 69[FAIL] uri invalid. uri:file://media/Photo/ 70``` 71 72<!--DelEnd--> 73 74### mediatool recv 75 76```shell 77mediatool recv <media-target> <dest-path> 78``` 79 80该命令能够将`<media-target>`指定的媒体库资源的源文件内容导出到`<dest-path>`指定的设备路径下。 81 82`<media-target>`可以为以下两种形式： 83* 系统媒体目录下的文件路径。（可通过[mediatool ls -l](#mediatool-ls--l)获取。不支持指定文件夹路径。） 84* 媒体库uri。（参考[媒体库uri介绍/获取方式](#媒体库uri介绍获取方式)） 85 86如果`<media-target>`指定文件路径，只支持以下几种路径，以下几种路径存在映射关系，访问的目录相同，均访问当前用户的系统媒体目录： 87* /storage/media/local/files/Photo 及以下的文件路径。 88* /storage/media/\<uid\>/local/files/Photo 及以下的文件路径。\<uid\>必须为当前用户的id，否则报错路径不合法。 89 90`<dest-path>`为待创建文件路径或者文件夹路径。若为文件夹路径则会导出到该文件夹下，文件保留媒体库中的名字。当`<dest-path>`指定待创建文件路径时，不能是已经存在文件的路径。<!--Del-->`<dest-path>`需要指定有权限访问的路径。<!--DelEnd--><!--RP1--><!--RP1End--> 91 92文件导出成功后会打印导出文件的路径。 93 94将`<media-target>`指定为`all`则能够将所有媒体库资源的源文件导出。当`<media-target>`为`all`时，`<dest-path>`必须为文件夹路径。 95 96该命令无法导出隐藏相册内的媒体资产。 97 98**使用示例：** 99 100```shell 101# 使用uri将对应媒体资源导出 102> mediatool recv file://media/Photo/3 /data/local/tmp/out.jpg 103Table Name: Photos 104/data/local/tmp/out.jpg 105 106# 使用路径将对应媒体资源导出 107> mediatool recv /storage/media/local/files/Photo/16/IMG_1748435796_000.jpg /data/local/tmp/out.jpg 108Table Name: Photos 109/data/local/tmp/out.jpg 110 111# 导出所有媒体资源文件 112> mkdir /data/local/tmp/outmedia 113> mediatool recv all /data/local/tmp/outmedia 114Table Name: Photos 115/data/local/tmp/outmedia/IMG_20250528_203454.jpg 116/data/local/tmp/outmedia/IMG_20250528_221028.jpg 117/data/local/tmp/outmedia/IMG_20250528_221851.jpg 118/data/local/tmp/outmedia/IMG_20250528_221930.jpg 119/data/local/tmp/outmedia/IMG_20250528_221944.jpg 120... 121 122Table Name: Audios 123 124``` 125 126### mediatool delete 127 128```shell 129mediatool delete <resource-uri> 130``` 131 132该命令能够彻底删除`<resource-uri>`指定uri的媒体库资源。被删除的资源无法恢复，请谨慎执行。 133 134媒体库资源uri的获取可参考[媒体库uri介绍/获取方式](#媒体库uri介绍获取方式)。 135 136将`<resource-uri>`指定为`all`则指定删除所有媒体库资源，并重置媒体库的所有数据。 137 138**使用示例：** 139 140```shell 141> mediatool delete file://media/Photo/3 142[SUCCESS] delete success. 143 144> mediatool delete all # delete all 执行成功不会有任何打印 145``` 146 147### mediatool query 148 149```shell 150mediatool query <display-name> [-p] [-u] 151``` 152 153该命令能够查询出所有图库中显示名字为`<display-name>`的媒体库资源，返回资源源文件真实路径或媒体资源uri。默认返回源文件真实路径。 154 155该命令无法查询出隐藏相册内的媒体资产。 156 157 | 选项 | 说明 | 158| ---- |--------------- | 159| -p | 返回媒体资源源文件在设备中的真实路径。（默认） | 160| -u | 返回媒体资源uri。不能与-p选项同时使用。 | 161 162**使用示例：** 163 164```shell 165# 所查询媒体资源存在 166> mediatool query MyImage.jpg 167find 1 result: 168path 169/storage/cloud/100/files/Photo/2/IMG_1721381297_001.jpg 170 171# 所查询媒体资源不存在 172> mediatool query non_exist.jpg 173find 0 result 174 175# 查询的名字格式不正确 176> mediatool query IMG_001 177find 0 result 178The displayName format is not correct! 179 180# 查询媒体资源源文件路径 181> mediatool query MyImage.jpg -p 182find 1 result: 183path 184/storage/cloud/100/files/Photo/2/IMG_1721381297_001.jpg 185 186# 查询媒体资源uri 187> mediatool query MyImage.jpg -u 188find 1 result: 189uri 190"file://media/Photo/2/IMG_1721381297_001/MyImage.jpg" 191``` 192 193### mediatool ls -l 194 195```shell 196mediatool ls -l <media-path> 197``` 198 199列举出`<media-path>`所指定的系统媒体路径下的所有文件。效果类似文件系统`ls -l`。 200 201`<media-path>`只支持以下几种路径，以下几种路径存在映射关系，访问的目录相同，均访问当前用户的系统媒体目录： 202 203* /storage/media/local/files/Photo 及以下的路径。 204* /storage/media/\<uid\>/local/files/Photo 及以下的路径。\<uid\>必须为当前用户的id，否则报错路径不合法。 205 206`-l`为强制选项。不指定`-l`选项命令会报错。 207 208该命令不可见用户隐藏相册内的媒体资产。 209 210**使用示例：** 211 212```shell 213> mediatool ls -l /storage/media/local/files/Photo 214drwxrwx--x 2 user_data_rw user_data_rw 3440 2025-05-29 05:45 16 215drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 05:45 1 216drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 11:15 2 217drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 05:56 3 218drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 05:56 4 219drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 11:21 5 220drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 11:59 6 221drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 05:57 7 222drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 05:59 8 223drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 06:00 9 224``` 225 226## 使用指导 227 228以下使用指导说明了一些常见的mediatool使用场景。 229 230### 导出特定媒体库资产 231 232示例导出图库中名字叫MyImage的jpg图片： 233 234```shell 235> hdc shell mediatool query -u MyImage.jpg 236find 1 result 237uri 238"file://media/Photo/1/IMG_1743078145_000/MyImage.jpg" 239 240> hdc shell mediatool recv file://media/Photo/1 /data/local/tmp/out.jpg 241Table Name: Photos 242/data/local/tmp/out.jpg 243 244> hdc file recv /data/local/tmp/out.jpg . 245FileTransfer finish, Size:10015455, File count = 1, time:679ms rate:14750.30kB/s 246``` 247 248示例根据媒体文件路径导出媒体库资产： 249 250```shell 251> hdc shell mediatool ls -l /storage/media/local/files/Photo 252drwxrwx--x 2 user_data_rw user_data_rw 3440 2025-05-29 05:45 16 253drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 05:45 1 254drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 11:15 2 255drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 05:56 3 256drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 05:56 4 257drwxrwx--x 2 user_data_rw user_data_rw 0 2025-05-29 11:21 5 258 259> hdc shell mediatool ls -l /storage/media/local/files/Photo/16 260-rw-rw---- 1 user_data_rw user_data_rw 6107481 2025-05-28 20:34 IMG_1748435794_000.jpg 261-rw-rw---- 1 user_data_rw user_data_rw 839323 2025-05-28 23:06 IMG_1748444892_016.jpg 262-rw-rw---- 1 user_data_rw user_data_rw 9614937 2025-05-28 23:41 IMG_1748446677_032.jpg 263-rw-rw---- 1 user_data_rw user_data_rw 3004885 2025-05-29 00:43 IMG_1748450699_048.jpg 264-rw-rw---- 1 user_data_rw user_data_rw 1915961 2025-05-29 01:18 IMG_1748452814_064.jpg 265-rw-rw---- 1 user_data_rw user_data_rw 13078 2025-05-29 02:41 IMG_1748457806_080.jpeg 266 267> hdc shell mediatool recv /storage/media/local/files/Photo/16/IMG_1748435794_000.jpg /data/local/tmp/out.jpg 268Table Name: Photos 269/data/local/tmp/out.jpg 270 271> hdc file recv /data/local/tmp/out.jpg . 272FileTransfer finish, Size:10015455, File count = 1, time:679ms rate:14750.30kB/s 273``` 274 275### 导出所有媒体库资产 276 277```shell 278> hdc shell mkdir /data/local/tmp/media 279> hdc shell mediatool recv all /data/local/tmp/media 280Table Name: Photos 281/data/local/tmp/media/MyImage.jpg 282 283Table Name: Audios 284 285> hdc shell tar -cvf /data/local/tmp/media.tar /data/local/tmp/media/* 286removing leading '/' from member names 287data/local/tmp/media/MyImage.jpg 288 289> hdc file recv /data/local/tmp/media.tar . 290FileTransfer finish, Size:10017280, File count = 1, time:664ms rate:15086.27kB/s 291``` 292 293### 删除特定媒体库资产 294 295示例删除图库中名字叫MyImage的jpg图片： 296 297```shell 298> hdc shell mediatool query -u MyImage.jpg 299find 1 result 300uri 301"file://media/Photo/1/IMG_1743078145_000/MyImage.jpg" 302 303> hdc shell mediatool delete file://media/Photo/1/IMG_1743078145_000/MyImage.jpg 304[SUCCESS] delete success. 305``` 306 307### 彻底重置媒体库数据库 308```shell 309> hdc shell mediatool delete all 310``` 311 312## 媒体库uri介绍/获取方式 313 314uri是媒体库资产的唯一标识符，每个uri都对应一个媒体资产。mediatool使用uri来判断需要操作的媒体资产对象。 315 316可使用以下方式获取uri： 317* mediatool query 加上 -u 的选项可以返回对应媒体资产的uri。需要输入对应资产的显示名（在图库中展示的名字带后缀名）。 318<!--Del--> 319* mediatool list all可以获取到所有媒体库资产的uri列表，以及对应的资产的显示名。 320<!--DelEnd--> 321 322媒体库uri可以用于mediatool recv命令导出特定媒体库资产，也可以用于mediatool delete删除特定媒体库资产。 323 324uri样例：`file://media/Photo/1/IMG_1743078145_000/MyImage.jpg`。 325在mediatool操作中，需要使用以上uri时，无论使用`file://media/Photo/1/IMG_1743078145_000/MyImage.jpg`还是`file://media/Photo/1`都能够正确的定位到目标资产。
