You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: add Dev Container support for standardized development environment (#1196)
* chore: add MLT 7 dev Dockerfile with Ubuntu 24.04 support
- Includes full multimedia stack, Qt6, and GPU headers
- Implements robust UID/GID 1000 conflict resolution
- Sets SDL_AUDIODRIVER=dummy for headless compatibility
* chore: add devcontainer.json for cross-IDE compatibility
- Configures DRI hardware device mapping
- Adds privileged/ipc=host placeholders for hardware access
- Sets up standard C++ extensions and CMake integration
* docs: unify official README with comprehensive Dev Container guide
- Adds modern CMake build instructions using a build directory
- Details hardware acceleration and audio setup (privileged mode)
- Clarifies testing procedures with setenv
MLT is a LGPL multimedia framework designed for video editing.
5
4
@@ -11,47 +10,140 @@ See the `docs/` directory for usage details.
11
10
See the [website](https://www.mltframework.org/docs/) for development details
12
11
and a [contributing](https://www.mltframework.org/docs/contributing/) guide.
13
12
13
+
---
14
14
15
-
Configuration
16
-
-------------
15
+
## Development Environment (Dev Container)
17
16
18
-
Configuration is triggered by running:
17
+
This repository provides a standardized development environment using the [Development Containers](https://containers.dev/) specification. It is compatible with **VS Code**, **CLion**, **DevPod**, and other IDEs supporting the `.devcontainer` standard.
19
18
20
-
cmake .
19
+
### Prerequisites
20
+
- Docker (or Podman)
21
+
- An IDE with Dev Container support.
21
22
22
-
More information on usage is found by viewing `CMakeLists.txt` and the [cmake man page](https://cmake.org/cmake/help/latest/manual/cmake.1.html).
23
+
### Hardware Acceleration and Audio Support
24
+
By default, the container runs in **Restricted Mode** (secure/headless). In this mode:
25
+
* Audio is routed to a `dummy` driver (no sound).
26
+
* GPU access might be limited to software rendering.
23
27
24
-
Compilation
25
-
-----------
28
+
#### Enabling Real Hardware Access
29
+
To enable **Full GPU Acceleration (DRI)** and **Physical Audio (ALSA/PulseAudio/PipeWire)**, follow these steps:
30
+
31
+
1.**Modify `devcontainer.json`**: Uncomment the following lines inside the `runArgs` array:
32
+
```json
33
+
"--ipc=host",
34
+
"--privileged"
35
+
```
36
+
* **What this does**: `--ipc=host` allows shared memory access for high-performance video frames, and `--privileged` grants the container direct access to host devices (GPU nodes and Sound Cards).
37
+
38
+
2. **Trigger a Rebuild**: Changes to `runArgs` require a container recreation.
39
+
* In VS Code: Run the command `Dev Containers: Rebuild Container`.
40
+
* In CLion: Select `Restart and Rebuild Container`.
41
+
42
+
3. **Switch the Audio Driver**: The `Dockerfile` defaults to `SDL_AUDIODRIVER=dummy`. Once in privileged mode, you must tell the MLT consumer to use a real driver:
43
+
* **Temporary (CLI)**:
44
+
```bash
45
+
SDL_AUDIODRIVER=alsa melt video.mp4
46
+
```
47
+
* **Permanent**: Edit the `ENV SDL_AUDIODRIVER` line in your `.devcontainer/Dockerfile` to `alsa` or `pulseaudio`.
48
+
49
+
> **Warning**: Using `--privileged` mode reduces the security isolation between the container and your host machine. Use it only when real-time hardware playback is required for development.
50
+
51
+
---
52
+
## Configuration
53
+
54
+
Configuration is triggered by running CMake **from inside a build directory**, not from the project root.
55
+
56
+
```bash
57
+
mkdir -p build
58
+
cd build
59
+
cmake ..
60
+
```
61
+
62
+
Alternatively, you can configure CMake with Ninja:
63
+
64
+
```bash
65
+
cmake -G Ninja ..
66
+
```
67
+
68
+
More information on usage is found by viewing `CMakeLists.txt` and the CMake manual page.
69
+
70
+
---
71
+
72
+
## Compilation
26
73
27
74
Once configured, it should be sufficient to run:
28
75
29
-
cmake --build .
76
+
```bash
77
+
cmake --build .
78
+
```
79
+
80
+
Alternatively, you can compile with Ninja:
81
+
82
+
```bash
83
+
ninja
84
+
```
85
+
86
+
Alternatively, you can compile using CMake or Ninja with one less CPU core (recommended only on systems with many CPU cores):
87
+
88
+
89
+
```bash
90
+
cmake --build . --parallel $(($(nproc) -1))
91
+
# or
92
+
ninja -j $(($(nproc) -1))
93
+
```
94
+
95
+
All generated files (Makefiles, Ninja files, cache, object files, binaries) will remain inside the `build/` directory.
96
+
97
+
---
98
+
99
+
## Testing
100
+
101
+
To execute the MLT tools without installation, or to test a new version on a system with an already installed MLT version, run:
102
+
103
+
```bash
104
+
source ../setenv
105
+
```
106
+
107
+
NB:
108
+
109
+
* This applies to the **current shell only**
110
+
* It assumes a **bash or Bourne-compatible shell** is in use
111
+
* The command must be executed from inside the `build/` directory
112
+
113
+
---
30
114
31
-
to compile the system. Alternatively, you can run `cmake` with `-G Ninja` and use ninja to compile.
115
+
## Installation
32
116
117
+
Installation is triggered by running:
33
118
34
-
Testing
35
-
-------
119
+
```bash
120
+
sudo cmake --install .
121
+
```
36
122
37
-
To execute the mlt tools without installation, or to test a new version
38
-
on a system with an already installed mlt version, you should run:
123
+
This installs the files generated in the `build/` directory, without affecting the project source tree.
39
124
40
-
source setenv
125
+
> **Note**: After installation, some Linux systems may require running `sudo ldconfig`
126
+
> to refresh the shared library cache, especially if the install prefix is not already
127
+
> part of the system linker configuration.
41
128
42
-
NB: This applies to your current shell only and it assumes a bash or
43
-
regular bourne shell is in use.
44
129
130
+
---
45
131
46
-
Installation
47
-
------------
132
+
## Summary
48
133
49
-
The install is triggered by running:
134
+
```bash
135
+
mkdir build
136
+
cd build
137
+
cmake ..
138
+
cmake --build .
139
+
source ../setenv
140
+
sudo cmake --install .
141
+
```
50
142
51
-
cmake --install .
143
+
This approach keeps the source tree clean and allows the entire build to be removed safely by deleting the `build/` directory.
52
144
145
+
---
53
146
54
-
More Information
55
-
----------------
147
+
# More Information
56
148
57
-
For more detailed information, please refer to https://mltframework.org/docs/install/.
149
+
For more detailed information, please refer to https://mltframework.org/docs/install/.
0 commit comments