diff --git a/.github/workflows/publish-wiki.yml b/.github/workflows/publish-wiki.yml new file mode 100644 index 0000000..70dcd0b --- /dev/null +++ b/.github/workflows/publish-wiki.yml @@ -0,0 +1,33 @@ +name: Publish wiki + +on: + push: + branches: + - development + paths: + - docs/** + - .github/workflows/publish-wiki.yml + + pull_request: + branches: + - development + types: + - closed + +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 diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 0000000..77131c4 --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,6 @@ +# How To Use MMT + +- [Installing](installing) +- [Commands](commands) +- [Configuration file](configfile) +- [Example Use cases](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 | 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 +``` +