From 303f4b7a861c7a6f0ccb3f9269a9ff1e34ab0721 Mon Sep 17 00:00:00 2001 From: Bentley Hensel Date: Fri, 23 May 2025 17:33:50 -0400 Subject: [PATCH 1/5] Sync docs to wiki Signed-off-by: Bentley Hensel --- .github/workflows/publish-wiki.yml | 24 +++++++ docs/Home.md | 6 ++ docs/Installing.md | 23 +++++++ docs/commands.md | 105 +++++++++++++++++++++++++++++ docs/configfile.md | 83 +++++++++++++++++++++++ 5 files changed, 241 insertions(+) create mode 100644 .github/workflows/publish-wiki.yml create mode 100644 docs/Home.md create mode 100644 docs/Installing.md create mode 100644 docs/commands.md create mode 100644 docs/configfile.md diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml new file mode 100644 index 0000000..ea6bc8f --- /dev/null +++ b/.github/workflows/publish-wiki.yml @@ -0,0 +1,24 @@ +name: Publish wiki +on: + push: + #branches: [main] + paths: + - docs/** + - .github/workflows/publish-wiki.yml + +concurrency: + group: publish-wiki + cancel-in-progress: true + +permissions: + contents: write + +jobs: + publish-wiki: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: Andrew-Chen-Wang/github-wiki-action@v4 + with: + path: docs/ + commit-message: Update wiki ${{ github.sha }} \ No newline at end of file diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 0000000..f610666 --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,6 @@ +# How To Use MMT + +- [Installing](installing) +- [Commands](commands) +- [Configuration file](configfile) +- [Example usecases](examples) \ No newline at end of file diff --git a/docs/Installing.md b/docs/Installing.md new file mode 100644 index 0000000..2a0d895 --- /dev/null +++ b/docs/Installing.md @@ -0,0 +1,23 @@ +## How to install MMT + +### Via binary: + +Right now, binaries will be provided via the GitHub Actions builder: https://github.com/KonradIT/mmt/actions/workflows/build-artifacts.yaml + +and also Releases tab: https://github.com/KonradIT/mmt/releases + +Download the binary for your OS and move it to an executable PATH (eg: `/usr/bin/`). + +### Build from source: + +```bash +git clone https://github.com/konradit/mmt.git +cd mmt +go install +``` + +To install system-wide. + +### Dependencies: + +The program will call FFmpeg for several tasks including transcoding/merging/extracting metadata. Make sure it's installed and in your PATH. \ No newline at end of file diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..b9e6814 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,105 @@ +## Commands: + +### import: import camera footage + +- `--input`: Either one of these: + - A directory pointing to your SD card, on Windows it would be a letter (eg: `E:\`) + - USB Ethernet IP (v4) bound to a GoPro Connect connection (GoPro HERO8, HERO9) / OpenGoPro (>HERO9) + - `10.5.5.9` if connected to a GoPro wirelessly +- `--output`: *MANDATORY* Destination folder, a hard drive, etc... +- `--name`: Project name, eg: `Paragliding Weekend Winter 2021` +- `--camera`: *MANDATORY* Type of device being imported. Values supported: `gopro, insta360, dji, android` +- `--buffersize`: Buffer size for copying files. Default is `1000 bytes` +- `--date`: Date format. Default is `dd-mm-yyyy` +- `--range`: Date range, for example: `12-03-2021,15-03-2021` +- `--skip_aux`: Skips `.THM`, `.LRV` files on GoPro cameras and .SRT files on DJI systems +- `--sort_by`: Sort by: `camera, location` (default: `camera, location` true) +- `--camera_name`: Camera name + +- Helper shortcuts: + - `--use_gopro`: Use the first GoPro available. Order: USB Ethernet > SD card. Errors out if no GoPro is found + - `--use_insta360`: Use the first Insta360 available. Errors out if no Insta360 is found + +- GoPro specific: + - `--connection`: `sd_card`/`connect` + - `--tag_names`: Tag names for number of HiLight tags in last 10s of video, each position being the amount, eg: 'marked 1,good stuff,important' => num of tags: 1,2,3" + +Examples: + +To import media from a GoPro HERO9/10/11 over USB Ethernet (GoPro Connect), while retaining LRV Proxy files and only the days 22-30 of December + +```bash +.\mmt.exe import --input "172.23.120.51" --output "C:\Users\konrad\Videos\Projects" --name "MadridXmas" --range "22-12-2022,30-12-2022" --camera gopro --connection connect --skip_aux "false" +``` + +To import media from a GoPro camera over WiFi to the current directory + +```bash +.\mmt.exe import --input "10.5.5.9" --output "." --camera gopro --connection connect +``` + +To import media from an Insta360 camera's SD card + +```bash +.\mmt.exe import --input "F:\" --output "C:\Users\konrad\Projects" --name "Skiing" --camera insta360 +``` + +To import media from a DJI drone's SD card + +```bash +.\mmt.exe import --input "F:\" --output "C:\Users\konrad\Projects" --name "Skiing" --camera dji +``` + +The cool part is, both Insta360 and DJI footage will be on the same project directory, and the files will be organized by day/location + +``` +C:\USERS\KONRA\VIDEOS\PROJECTS\ELESCORIALUAV +├───21-12-2022 +│ └───Air 2S +│ ├───El Escorial España +│ │ ├───photos +│ │ └───videos +│ └───San Lorenzo de El Escorial España +│ ├───photos +│ └───videos +``` + +### update: updates your camera + +- `--input`: A directory pointing to your SD card, MTP or GoPro Connect not supported +- `--camera`: Type of device being updated. Values supported: `gopro, insta360` + +### apply-lut: Applies LUT profile to photos + +- `--input`: path to one JPG file or directory of JPG files +- `--lut`: Path to .CUBE LUT +- `--intensity`: 0-100 +- `--resize`: Resize image. Use `0` to keep aspect ratio +- `--quality`: 0-100 + +```bash +./mmt.exe apply-lut --input "DJI_0468.JPG" --lut '..\GoPro LUTs Color Grading Pack by IWLTBAP\LUTs by IWLTBAP (CUBE)\IWLTBAP Kumate.cube' --intensity 75 --resize 2000x0 --quality 90 +``` + +### merge: merges videos together + +- `--input`: Files to merge. Specify multiple times + +```bash + .\mmt.exe merge --input "G:\Edits\Extremadura trip\13-03-2021\HERO9 Black\videos\GH1276-01.MP4" --input "G:\Edits\Extremadura trip\13-03-2021\HERO9 Black\videos\GH1276-02.MP4" +``` + +### list: list devices plugged in + +Will show you devices plugged in to make importing easier. + +``` +📷 Devices: + 🎥 0 - C: (C:) + 🎥 1 - F: (F:) + 🎥 2 - G: (G:) +🔌 GoPro cameras via Connect (USB Ethernet): + 📹 0 - 172.23.120.51 (HERO11 Black - H22.01.02.01.00) +``` + +### calendar: display an ascii calendar of days when media was captured \ No newline at end of file diff --git a/docs/configfile.md b/docs/configfile.md new file mode 100644 index 0000000..1d0f15f --- /dev/null +++ b/docs/configfile.md @@ -0,0 +1,83 @@ +## Config file: + +The location of the file is: `~/.mmt.yaml`. It is not created automatically. + +By default mmt will not use any config file, but you can change some aspects of the software only via this config file, as well put the values of the different CLI flags into the file to save time. + +You can check out some sample config files for different cameras and importing modes: [./config](https://github.com/KonradIT/mmt/tree/development/config) + +Example, if you only want to use the software to import media from GoPros wirelessly: + +```yaml +camera: gopro +output: /home/user/Videos +input: 10.5.5.9 +connection: connect +``` + +Supported keys for `import` command: + +- input +- output +- camera +- name +- date +- buffer +- range +- sort_by +- skip_aux +- connection +- tag_names + +### Location: + +Location.* keys will impact anything related to order of import that uses location info. + +Default values: + +- format: 1 +- fallback: `NoLocation` +- order: "date", "location", "camera" + +```yaml +location: + format: 1 # Different formats supported: 1 and 2 (default 1) + fallback: "NoLocation" # Leave empty to not make a folder for ungeolocated footage + order: # Default order is: + - date + - location + - camera +``` + +Location formats: + +- 1: + +```go +if len(address.City) < 9 && address.State != "" { + return fmt.Sprintf("%s %s %s", address.City, address.State, address.Country) +} +return fmt.Sprintf("%s %s", address.City, address.Country) +``` + +- 2: + +```go +return address.Country +``` + +### Camera: DJI + +Prefix: `dji` + +| Key | Description | Default | Example | +|-----|-------------|---------|---------| +| srt | Folder for SRT files | "" | ` srt: 'srt files'` | + +### Camera: GoPro + +Prefix: `gopro` +| Key | Description | Default | Example | +|-----|-------------|---------|---------| +| gps_fix | Only use the following GPS fix values | `2, 3 // ==> 3d lock, 2d lock` | ` 2` | +| gps_accuracy | Only GPS accuracy values equal or above to this setting will be used | 500 | 450 | From b7d5dd0538b59d186e69de4b90c9fb4f3dcdade8 Mon Sep 17 00:00:00 2001 From: Bentley Hensel Date: Fri, 20 Jun 2025 17:00:59 -0400 Subject: [PATCH 2/5] Revisiting code & tiny update Signed-off-by: Bentley Hensel --- .github/workflows/publish-wiki.yml | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml index ea6bc8f..6e73693 100644 --- a/.github/workflows/publish-wiki.yml +++ b/.github/workflows/publish-wiki.yml @@ -1,24 +1,36 @@ name: Publish wiki + on: push: - #branches: [main] + branches: + - development paths: - docs/** - .github/workflows/publish-wiki.yml - + + pull_request: + branches: + - development + types: + - closed + + workflow_dispatch: + + concurrency: group: publish-wiki cancel-in-progress: true - + permissions: contents: write - + jobs: publish-wiki: + if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.pull_request.merged == true) runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: Andrew-Chen-Wang/github-wiki-action@v4 with: - path: docs/ - commit-message: Update wiki ${{ github.sha }} \ No newline at end of file + path: docs/ + commit-message: Update wiki ${{ github.sha }} \ No newline at end of file From 2b97988019be074f31e44243e765165299aeecb0 Mon Sep 17 00:00:00 2001 From: Bentley Hensel Date: Fri, 20 Jun 2025 17:06:07 -0400 Subject: [PATCH 3/5] testing Signed-off-by: Bentley Hensel --- .github/workflows/publish-wiki.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml index 6e73693..0becefc 100644 --- a/.github/workflows/publish-wiki.yml +++ b/.github/workflows/publish-wiki.yml @@ -4,6 +4,7 @@ on: push: branches: - development + - docs paths: - docs/** - .github/workflows/publish-wiki.yml @@ -14,9 +15,6 @@ on: types: - closed - workflow_dispatch: - - concurrency: group: publish-wiki cancel-in-progress: true From 87e4bfa8fac69759e0701f27b97dcc4fce6e71f5 Mon Sep 17 00:00:00 2001 From: Bentley Hensel Date: Fri, 20 Jun 2025 17:19:33 -0400 Subject: [PATCH 4/5] Fixed examples link by adding examples.md to docs Signed-off-by: Bentley Hensel --- docs/Home.md | 2 +- docs/examples.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 125 insertions(+), 1 deletion(-) create mode 100644 docs/examples.md diff --git a/docs/Home.md b/docs/Home.md index f610666..77131c4 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -3,4 +3,4 @@ - [Installing](installing) - [Commands](commands) - [Configuration file](configfile) -- [Example usecases](examples) \ No newline at end of file +- [Example Use cases](examples) \ No newline at end of file diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 0000000..245f182 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,124 @@ +# Example Use Cases + +This page shows practical examples of how to use `mmt`, including sample config files. + + + +## 🧪 Importing media + +### GoPro over USB Ethernet (GoPro Connect) + +```bash +.\mmt.exe import --input "172.23.120.51" --output "C:\Users\konrad\Videos\Projects" --name "MadridXmas" --range "22-12-2022,30-12-2022" --camera gopro --connection connect --skip_aux false +``` + +### GoPro over WiFi + +```bash +.\mmt.exe import --input "10.5.5.9" --output "." --camera gopro --connection connect +``` + +### Insta360 SD card + +```bash +.\mmt.exe import --input "F:\" --output "C:\Users\konrad\Projects" --name "Skiing" --camera insta360 +``` + +### DJI drone SD card + +```bash +.\mmt.exe import --input "F:\" --output "C:\Users\konrad\Projects" --name "Skiing" --camera dji +``` + +Files will be imported into the same project folder, sorted by date and location. + + + +## ⚙️ Config file examples + +Rather than passing in flags every time, you can define them in a config file. + +> Location: `~/.mmt.yaml` + +Example use cases below — these live in the [`config/`](https://github.com/KonradIT/mmt/tree/development/config) folder of the repo. + + +### Wireless GoPro + +[`config/wireless_gopro.yaml`](https://github.com/KonradIT/mmt/blob/development/config/wireless_gopro.yaml): + +```yaml +input: 10.5.5.9 +camera: gopro +output: C:\Users\konrad\Videos\Projects +range: week +skip_aux: false +connection: connect +``` + + +### SD card GoPro + +[`config/sd_card_gopro.yaml`](https://github.com/KonradIT/mmt/blob/development/config/sd_card_gopro.yaml): + +```yaml +input: "F:\\" +camera: gopro +output: C:\Users\konrad\Videos\Projects +range: week +skip_aux: false +connection: sd_card +``` + + + +### HiLight tags + +[`config/gopro_hilights.yaml`](https://github.com/KonradIT/mmt/blob/development/config/gopro_hilights.yaml): + +```yaml +tag_names: + - "Marked 1" + - "Good Stuff" + - "Important" +``` + + + +### Custom location ordering + +[`config/location_tweaks.yaml`](https://github.com/KonradIT/mmt/blob/development/config/location_tweaks.yaml): + +```yaml +location: + format: 1 + fallback: '' + order: + - camera + - date + - location +``` + + +## 🧪 Test with a config + +```bash +.\mmt.exe import --config config/wireless_gopro.yaml +``` + + + +## 📁 Example output + +``` +C:\USERS\KONRAD\VIDEOS\PROJECTS\ELESCORIALUAV +├───21-12-2022 +│ └───Air 2S +│ ├───El Escorial España +│ │ ├───photos +│ │ └───videos +│ └───San Lorenzo de El Escorial España +│ ├───photos +│ └───videos +``` + From 142e5ddb5da2f88e873626f5d3b2a681bd0937f5 Mon Sep 17 00:00:00 2001 From: Bentley Hensel Date: Fri, 20 Jun 2025 17:23:27 -0400 Subject: [PATCH 5/5] Remove - docs branch trigger Signed-off-by: Bentley Hensel --- .github/workflows/publish-wiki.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml index 0becefc..70dcd0b 100644 --- a/.github/workflows/publish-wiki.yml +++ b/.github/workflows/publish-wiki.yml @@ -4,7 +4,6 @@ on: push: branches: - development - - docs paths: - docs/** - .github/workflows/publish-wiki.yml