README
¶
Media Orientation (mediaorient)
mediaorient is a CLI tool and Go library to calculate the orientation of
images & videos based on their content, not EXIF data.
🖼️ Usage
You can use mediaorient in two ways: as a command-line interface (CLI) tool or a Go library.
The CLI tool is a standalone application that can be used to calculate and fix the orientation of media files, while the library can be integrated into your own Go projects.
The binaries are available for Windows, macOS, and Linux. Download the latest release that matches your computer architecture and operating system.
CLI
Calculate the orientation of one or more files
Run the command below in the terminal:
$ mediaorient files <media1> [<media2> ...]
Calculate the orientation of a directory
Run the command below in the terminal:
$ mediaorient dir <directory> [-r] [--mt <media-type>]
Where:
dir(mandatory): the path to the directory where the media files are located.-r(optional): recursively search for files in subdirectories to include in the calculation.--mt(optional): the file types to be included in the calculation. You can choose betweenimage,video, orall(default).
Other parameters you can use:
-o(optional): the output format; you can choosereport(default) or, if you prefer a raw output,jsonorcsv.--ie(optional): ignores errors and continues the calculation even if some files are not valid.
For the full list of parameters, type mediaorient --help in the terminal.
🎞️ Supported media types
In its default configuration, the mediaorient library supports media files with the following extensions:
- Images:
.bmp,.gif,.jpg(.jpeg),.png,.tiff,.webp - Videos:
.avi,.mp4(.m4v),.mkv,.mov,.webm
The CLI supports two additional image formats: .avif and .heic.
If you want to work with additional file extensions in the library, like those two above, you can use the functions AddImageType or AddVideoType before performing any orientation calculation. This allows mediaorient to include these file types during calculations.
When adding support for new media formats, it's essential to load a 3rd party library capable of decoding them. For example, to enable AVIF image calculation in mediaorient, you could use a library like avif-go to do this:
import _ "github.com/vegidio/avif-go"
mediaorient.AddImageType(".avif")
💣 Troubleshooting
Internet Connection Required On The First Run
This app uses a neural network trained with almost 1 million images, creating a model of nearly 100 MB. Unfortunately, it becomes impractical to embed this data in the executable, otherwise the file would become too big.
For this reason, the first time you run the app, it will download the model from the internet; this may take a few seconds, depending on your internet connection.
This approach not only prevents an excessive executable size but also allows the app to always use the most recent version of the model, which may contain improvements and bug fixes.
Miscalculation of Media Orientation
While the model has accuracy of about 99%, it isn’t perfect. It works very well with everyday media, such as photos of people, animals, documents and common scenes, but may perform less reliably with certain special cases.
For example, if you have a media depicting a medical procedure, the app may not detect the correct orientation because the model was not trained (or was only minimally trained), on this type of media. You can help improve the app by contributing to the training dataset. Upload your own media here, so that in future versions of the app this kind of media will be properly detected.
Any media you upload will not be shared with anyone else and will be used solely to train the neural network. I’m not here to judge anyone, so feel free to upload any legal content.
However, I cannot emphasize this enough: do NOT upload any illegal media. If you upload something illegal, I will not only block your access to this project, but I will also report you to the authorities using your IP address and any other information available.
Video Orientation Doesn't Work
If the orientation calculation of videos is not working, it may be because you don't have FFmpeg working in your computer, which is required to extract frames from the video files.
When FFmpeg is not found, mediaorient will try to automatically download and install it for you. Even though this will work in most cases, it may fail for unpredictable reasons.
The best option to have the video calculation working is to install FFmpeg yourself in your computer and make sure it is available in your PATH.
"App Is Damaged/Blocked..." (Windows & macOS only)
For a couple of years now, Microsoft and Apple have required developers to join their "Developer Program" to gain the pretentious status of an identified developer 😛.
Translating to non-BS language, this means that if you’re not registered with them (i.e., paying the fee), you can’t freely distribute Windows or macOS software. Apps from unidentified developers will display a message saying the app is damaged or blocked and can’t be opened.
To bypass this, open the Terminal and run one of the commands below (depending on your operating system), replacing <path-to-app> with the correct path to where you’ve installed the app:
- Windows:
Unblock-File -Path <path-to-app> - macOS:
xattr -d com.apple.quarantine <path-to-app>
🛠️ Build
Dependencies
To build this project, you will need the following dependencies installed in your computer:
Compiling
With all the dependencies installed, in the project's root folder run the command:
$ task cli os=<operating-system> arch=<architecture>
Where:
<operating-system>: can bewindows,darwin(macOS), orlinux.<architecture>: can beamd64orarm64.
For example, if I wanted to build the CLI for Windows, on architecture AMD64, I would run the command:
$ task cli os=windows arch=amd64
📝 License
mediaorient is released under the Apache 2.0 License. See LICENSE for details.
👨🏾💻 Author
Vinicius Egidio (vinicius.io)
Documentation
¶
Index ¶
- Constants
- func AddImageType(types ...string)
- func AddVideoType(types ...string)
- func CalculateDirectoryOrientation(directory string, mediaType string, recursive bool) (<-chan Result[Media], int)
- func CalculateFilesOrientation(filePaths []string) <-chan Result[Media]
- func Destroy()
- func Initialize(name string, onDownload func()) error
- type Media
- type Result
Constants ¶
const Version = "<version>"
Variables ¶
This section is empty.
Functions ¶
func AddImageType ¶
func AddImageType(types ...string)
AddImageType adds one or more image type extensions to the list of valid image types.
func AddVideoType ¶
func AddVideoType(types ...string)
AddVideoType adds one or more video type extensions to the list of valid video types.
func Destroy ¶
func Destroy()
Destroy cleans up resources used by the media orientation detection system.
This function performs cleanup operations to free memory and resources allocated during initialization. It should be called when the application is shutting down or when orientation detection functionality is no longer needed.
It's recommended to use this function with defer for proper cleanup:
Example: ¶
if err := mediaorient.Initialize("myapp", nil); err != nil {
log.Fatal("Initialization failed:", err)
}
defer mediaorient.Destroy() // Ensure cleanup on exit
func Initialize ¶
Initialize sets up the media orientation detection system by ensuring all required dependencies are available.
This function performs a three-step initialization process:
- Installs the ONNX runtime library if not already present in the user's config directory
- Downloads the latest image orientation model if needed or outdated
- Initializes the ONNX runtime session with the downloaded model
The name parameter specifies the application name used to create a dedicated config directory under the user's standard configuration path (e.g., ~/.config/name on Linux). It's important that you reuse the same name on later calls to Initialize() to ensure that the same config directory is used.
The onDownload callback function is called when the model needs to be downloaded, allowing the caller to notify users about the download process (e.g., show a progress indicator).
Returns an error if any step fails, including:
- Unable to create config directories or files
- Network errors during model download
- ONNX runtime initialization failures
Example: ¶
err := mediaorient.Initialize("myapp", func() {
fmt.Println("Downloading model, please wait...")
})
if err != nil {
log.Fatal("Failed to initialize:", err)
}
defer mediaorient.Destroy() // Clean up resources
Types ¶
type Media ¶
type Media struct {
// Name of the media.
Name string `json:"name"`
// Type of the media (e.g., image, video).
Type string `json:"type"`
// Rotation represents the rotation of the media.
Rotation int `json:"rotation"`
// Frames contain the image data of the media.
Frames []image.Image `json:"-"`
// Width represents the width of the media in pixels.
Width int `json:"width"`
// Height represents the height of the media in pixels.
Height int `json:"height"`
}
Media represents a media object.
Source Files