Package: djiutil
djiutil - manipulate files created by DJI dronesdjiutilis a command-line utility and Python package for working with files created byDJIdrones. The utility provides subcommands to assist with the following
tasks:cleaning upunwanted files (supports LRF, SRT, and video files)convertingDJI subtitle (SRT) files to GPX formatimportingDJI files (video and subtitle) from a mounted volumelistingDJI files on a mounted volumeplayingDJI video files by index numberInstallationThe easiest way to install the package is to download it fromPyPIusingpip.
Note thatdjiutildepends onPython3.11 or newer; please
ensure that you have a recent version of Python installed before proceeding.Run the following command in a shell (a UNIX-like environment is assumed):$ pip install djiutilThe package does depend on a few external Python packages available on PyPI. If you wish to
sandbox your installation inside a virtual environment, you may choose to usevirtualenvwrapperor a similar
utility to do so.When successfully installed, a program calleddjiutilwill be placed on yourPATH. See the
Usage section below for details about how to use this program.DependenciesThe utility expectsrsyncto be installed when importing
DJI video files. Modern distributions of Linux and macOS ship withrsyncpreinstalled, so you
likely do not need to install it separately. However, the version that is preinstalled on macOS
(as of macOS version 13.5) is an older version (2.x), and it is recommended to installrsyncversion 3 or newer (usingHomebrewor your preferred package manager) for the
best experience.UsageThedjiutilprogram is a command-line interface for working with files created by DJI drones.At any time, you can use the-hor--helpflags to see a summary of options that
the program accepts.$ djiutil -h
usage: djiutil [-h] {cleanup,convert,import,list,play} ...

manipulate files created by DJI drones

positional arguments:
  {cleanup,convert,import,list,play}
    cleanup             clean up unwanted DJI files (LRF, SRT, etc.)
    convert             convert DJI subtitle files to GPX format
    import              import DJI video and subtitle files
    list                list DJI files in a directory
    play                play a DJI video file by index number

options:
  -h, --help            show this help message and exitTo see more details about a specific subcommand and the options that it accepts, usedjiutil <subcommand> -h, for example:$ djiutil play -h
usage: djiutil play [-h] [dir_path] index

positional arguments:
  dir_path    path to the directory where DJI files are located
  index       index number of the video file to play (as returned by the list subcommand)

options:
  -h, --help  show this help message and exitPath ResolutionDJI drones create a directory structure like the following on their storage device (microSD or
internal SSD):/
├── DCIM
│   └── DJI_001
│       └── ...
└── MISCThe video (and subtitle) files created by the drone are stored under the/DCIM/DJI_001directory.
When mounted to a computer for viewing and transferring the files, these files might be located
at a path such as/Volumes/Mavic/DCIM/DJI_001. For convenience,djiutilwill resolve the path/Volumes/Mavicto the path/Volumes/Mavic/DCIM/DJI_001automatically. You only need to specify
the path to the mount point for the storage device, not the full path to the directory where the
files are stored.File FilteringSeveraldjiutilsubcommands support filtering DJI files by date, age, or index number. This can
be helpful when working with a subset of the files stored on a mounted volume instead of all files.Filtering by Date and AgeTo filter files by date, use the-d/--date-filteroption. In its simplest form, this filter
accepts a date in the formatYYYY-MM-DD, for example,2023-08-28. When used in this way, this
filter selects only files created on the specified date.The-doption also supports filtering files by age, using the syntax("<"|">")<value><unit>.
For example,<1dselects only files created within the past day, while>3mselects only files
created more than three months ago. Supported units are:h(hours),d(days),w(weeks),m(months), andy(years). Note that the argument passed to-dmust be quoted when using the
age syntax, since<and>have special meaning to the shell for input/output redirection.Filtering by File IndexDJI drones assign an incrementing index number to each set of files they create. This index number
is displayed by thedjiutil listsubcommand. The-i/--index/--index-numbersoption may be
used with other subcommands to select specific files by index.The argument passed to-imay be a single index (e.g.,12), a range of indices separated by a
hyphen (e.g.,5-8), or a sequence of indices or ranges separated by commas (e.g.,4,8,15,16or9,11-15,17-21,23). Ranges are inclusive on both ends, e.g.,5-8means indices 5, 6, 7, and 8.Cleaning Up Files$ djiutil cleanup -h
usage: djiutil cleanup [-h] [-d DATE_FILTER | -i INDEX] [-y] {lrf,srt,video,all} [dir_path]

positional arguments:
  {lrf,srt,video,all}   type of files to clean up (video includes .mov and .mp4 files)
  dir_path              path to the directory where DJI files are located

options:
  -h, --help            show this help message and exit
  -d DATE_FILTER, --date-filter DATE_FILTER
                        filter deleted files by date or age (examples: "<1d", ">1w", "2023-08-28"). Supported units are: h (hours), d (days), w (weeks),
                        m (months), and y (years).
  -i INDEX, --index INDEX, --index-numbers INDEX
                        index number(s) of the video file(s) to delete, as returned by the list subcommand (examples: "1-4", "5,7,8", "21-23,26-29,32")
  -y, --yes, --assume-yes
                        skip user confirmation before cleaning up files (default: false)DJI drones typically store their files on microSD cards (or a small internal SSD on some models).
A drone can quickly fill up even a fairly large microSD card, so it's common to need to clean up
files that are no longer wanted in order to free up space on the SD card or internal SSD.File TypesThedjiutil cleanup <type> <directory>command will delete DJI files of the specified type from
the specified directory. The following file types are supported:lrf- low-resolution video files created by the drone to preview on the remote controller's
built-in display (or a connected mobile device)srt- subtitle files containing information about the drone's location, altitude, and camera
settings during the recording of a video (see the section on converting SRT to GPX, below, for
more details)video- high-resolution video files recorded by the drone (includes.movand.mp4formats)all- all of the above: LRF, SRT, and video filesFile FilteringIn addition to checking the file type, the files to be cleaned up may be further filtered by
providing a date filter or index list; see the section on filtering, above, for more details.Bypassing ConfirmationBy default, when running in an interactive environment (e.g., a shell),djiutilwill prompt the
user for confirmation before cleaning up any files. To bypass this prompt, use the-y/--yes/--assume-yesflag.ExamplesUse the following command to clean up video files created more than two weeks ago
from the directory/Volumes/Mavic:$ djiutil cleanup video /Volumes/Mavic -d '>2w'Use the following command to clean up all files with index numbers 10-14 (inclusive)
from the directory/Volumes/Mavicwithout prompting for confirmation:$ djiutil cleanup all /Volumes/Mavic -i 10-14 -yConverting SRT to GPX$ djiutil convert -h
usage: djiutil convert [-h] srt_file_path [gpx_file_path]

positional arguments:
  srt_file_path  path to the subtitle (.srt) file to convert, or a directory where subtitle files are located
  gpx_file_path  output GPX file path (inferred from srt_file_path if not specified)

options:
  -h, --help     show this help message and exitSome DJI drones have the option to createSRT(subtitle)
files along with the video files they record. These files capture information about the drone's
location, altitude, and camera settings throughout the recording of a video. Using a media player
such asVLC, these SRT files can be paired with the corresponding
video files to display the flight data over the video as subtitles;this articledescribes how to do this (see the section called "Method 2").Useful though this feature is, the SRT format is limited in terms of its compatibility with other
software. The SRT files generated by DJI drones contain the drone's GPS location and altitude, but
this data is embedded in the text of the captions and is not easy to extract or interpret for use
in other applications besides viewing the flight data as a subtitle. In contrast,GPX,
or the GPS Exchange Format, is supported by a range of software and applications that work with
GPS and map data (for example,GPX Studio).Thedjiutil convert <srt_file> [<gpx_file>]command will convert the specified SRT file to the
GPX format. The resulting GPX file will either be given the specified GPX file name, or the file
name will be inferred from the SRT file if no GPX file name is provided.Converting All SRT Files in a DirectoryIf the SRT file path passed todjiutil convertis a directory, all SRT files in the provided
directory will be converted to GPX format. Note that no GPX file name may be provided when
converting an entire directory; the GPX file names will be inferred from the source SRT file names.ExamplesUse the following command to convert the file/Volumes/Mavic/0001.srtto the file/tmp/output.gpx:$ djiutil convert /Volumes/Mavic/0001.srt /tmp/output.gpxUse the following command to convert all SRT files in the directory/Volumes/Mavicto GPX format:$ djiutil convert /Volumes/MavicImporting Files$ djiutil import -h
usage: djiutil import [-h] [-d DATE_FILTER | -i INDEX] [-s] [-y] [dir_path] dest_path

positional arguments:
  dir_path              path to the directory where DJI files are located
  dest_path             path to the directory to import the files to

options:
  -h, --help            show this help message and exit
  -d DATE_FILTER, --date-filter DATE_FILTER
                        filter imported files by date or age (examples: "<1d", ">1w", "2023-08-28"). Supported units are: h (hours), d (days), w (weeks),
                        m (months), and y (years).
  -i INDEX, --index INDEX, --index-numbers INDEX
                        index number(s) of the video file(s) to import, as returned by the list subcommand (examples: "1-4", "5,7,8", "21-23,26-29,32")
  -s, --srt, --include-srt
                        import SRT (subtitle) files in addition to video files (default: false)
  -y, --yes, --assume-yes
                        skip user confirmation before importing files (default: false)DJI drones typically store their files on microSD cards (or a small internal SSD on some models).
It's common to need to transfer the recorded video files from the microSD card or SSD to a more
permanent storage medium.Thedjiutil import <source_directory> <destination_directory>command will copy video files from
the specified source directory to the specified destination directory, creating the destination
directory if it does not exist.File FilteringThe files to be imported may be filtered by providing a date filter or index list; see the section
on filtering, above, for more details.Importing SRT FilesBy default,djiutil importimports only video (.movand.mp4) files. Use the-s/--srt/--include-srtflag to import SRT (subtitle) files as well as video files. See the
section on converting SRT to GPX, above, for more about these files.Bypassing ConfirmationBy default, when running in an interactive environment (e.g., a shell),djiutilwill prompt the
user for confirmation before importing any files. To bypass this prompt, use the-y/--yes/--assume-yesflag.ExamplesUse the following command to import all video files created within the past week
from the directory/Volumes/Mavicto the directory/var/video:$ djiutil import /Volumes/Mavic /var/video -d '<1w'Use the following command to import all video and SRT files with index numbers 22-26 (inclusive)
from the directory/Volumes/Mavicto the directory/var/videowithout prompting for
confirmation:$ djiutil import /Volumes/Mavic /var/video -i 22-26 -s -yListing Files$ djiutil list -h
usage: djiutil list [-h] [-d DATE_FILTER | -i INDEX] [-o {json,plain}] [-p] [dir_path]

positional arguments:
  dir_path              path to the directory where DJI files are located

options:
  -h, --help            show this help message and exit
  -d DATE_FILTER, --date-filter DATE_FILTER
                        filter results by date or age (examples: "<1d", ">1w", "2023-08-28"). Supported units are: h (hours), d (days), w (weeks), m
                        (months), and y (years).
  -i INDEX, --index INDEX, --index-numbers INDEX
                        index number(s) of the video file(s) to import, as returned by the list subcommand (examples: "1-4", "5,7,8", "21-23,26-29,32")
  -o {json,plain}, --output {json,plain}, --output-format {json,plain}
                        desired output format (plain format or JSON); default: pretty tabular format
  -p, --include-file-path
                        include video file paths in the listing (default: false)Thedjiutil list <directory>command will list all DJI video files in the specified directory.
The listing also indicates whether corresponding LRF (low-resolution video) and/or SRT (subtitle)
files exist for each of the video files.File FilteringThe files listed may be filtered by providing a date filter or index list; see the section on
filtering, above, for more details.Including File PathsUse the-p/--include-file-pathflag to include the full path to each video file in the listing.
The path is hidden by default.Output FormatsThe default output format is a pretty-printed tabular format that looks like the following:╭─────┬───────┬───────┬─────────────────────┬────────╮
│   # │  LRF  │  SRT  │       Created       │  Size  │
├─────┼───────┼───────┼─────────────────────┼────────┤
│  31 │       │       │ 2023-09-02 17:24:03 │  3.5G  │
│  32 │       │   ✓   │ 2023-09-02 17:27:00 │  2.6G  │
│  33 │   ✓   │   ✓   │ 2023-09-02 17:29:43 │  2.3G  │
╰─────┴───────┴───────┴─────────────────────┴────────╯In the default mode, consecutive files that were created more than 10 minutes apart are separated
by a horizontal dividing line in the table. This is intended to serve as a quick visual reference
for which files were recorded during the same flight or session.The default output format is intended for human consumption, but it is not ideal for being passed
to or parsed by other utilities. If you are processing the output ofdjiutil listprogrammatically, you may wish to use the-o/--output/--output-formatoption to control the
output format.Use theplainoutput format for a simpler tabular format that looks like the following:#   LRF    SRT         Created         Size
---  -----  -----  -------------------  ------
 31                2023-09-02 17:24:03   3.5G
 32           ✓    2023-09-02 17:27:00   2.6G
 33    ✓      ✓    2023-09-02 17:29:43   2.3GThis format is well suited to processing by utilities such asawkorsed.Use thejsonoutput format for JSON formatted data that looks like the following:[
  {
    "index": 31,
    "has_lrf": false,
    "has_srt": false,
    "created": "2023-09-02T17:24:03.900000",
    "size": "3.5G",
    "size_in_bytes": 3760740181
  },
  {
    "index": 32,
    "has_lrf": false,
    "has_srt": true,
    "created": "2023-09-02T17:27:00.350000",
    "size": "2.6G",
    "size_in_bytes": 2760949500
  },
  {
    "index": 33,
    "has_lrf": true,
    "has_srt": true,
    "created": "2023-09-02T17:29:43.270000",
    "size": "2.3G",
    "size_in_bytes": 2433459466
  }
]The JSON format gives the most flexibility in terms of processing by other software, but it
is also the most verbose and may be overkill for most situations.ExamplesUse the following command to list all DJI files in the directory/Volumes/Mavicthat were created
less than a month ago:$ djiutil list /Volumes/Mavic -d '<1m'Use the following command to list all DJI files in the directory/Volumes/Mavicwith index
numbers in the range 33-37 (inclusive) and to include the full path to each file in the output:$ djiutil list /Volumes/Mavic -i 33-37 -pUse the following command to list all DJI files in the directory/Volumes/Mavicin JSON format:$ djiutil list /Volumes/Mavic -o jsonPlaying Video Files$ djiutil play -h
usage: djiutil play [-h] [dir_path] index

positional arguments:
  dir_path    path to the directory where DJI files are located
  index       index number of the video file to play (as returned by the list subcommand)

options:
  -h, --help  show this help message and exitThedjiutil play <directory> <index>command is a simple shortcut to play the video file in the
specified directory with the specified index. The index number is the same one returned by thelistsubcommand (see above).ExampleUse the following command to play the video file with index 42 from the directory/Volumes/Mavic:$ djiutil play /Volumes/Mavic 42Configuring a Default Directory PathAlldjiutilsubcommands exceptdjiutil convertrequire specifying the path to a directory where
DJI files are located. The sections above describe how to specify this directory path on the
command line when invokingdjiutil. However, the directory path does not change frequently (if
ever) when working with the files created by a single drone, and typing the path repeatedly for
everydjiutilcommand can become tiresome.To alleviate the amount of repetitive typing required,djiutilsupports configuring a default
directory path via environment variable and/or config file. If no directory path is specified on
the command line,djiutilwill attempt to find the path to use in an environment variable calledDJIUTIL_DIR_PATH. If this environment variable is not defined (or empty), the value will be taken
from thedji_dir_pathfound in the file~/.djiutil.json, if it exists (see below).Example Config FileAs described above, you may optionally choose to create a config file to store the default
directory path fordjiutilto use. The following is an example config file, which should be
located at~/.djiutil.json:{"dji_dir_path":"/Volumes/Mavic"}