README.md 7.95 KB
Newer Older
Soomin Lee's avatar
Soomin Lee committed
1
2
3
4
5
<img src="https://www.videolan.org/images/vlckit/logo.svg" alt="VLCKit logo" height="140">

#

**VLCKit** is a generic multimedia library for any audio or video playback needs on macOS, iOS and tvOS.
6

Felix Paul Kühne's avatar
Felix Paul Kühne committed
7
8
9
10
11
|              | Platform                                                     | Cocoapods                                                    |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| VLCKit       | ![Platform](https://img.shields.io/cocoapods/p/VLCKit.svg?style=flat) | [![VLCKit is CocoaPods Compatible](https://img.shields.io/cocoapods/v/VLCKit.svg)](https://cocoapods.org/pods/VLCKit) |
| MobileVLCKit | ![Platform](https://img.shields.io/cocoapods/p/MobileVLCKit.svg?style=flat) | [![MobileVLCKit is CocoaPods Compatible](https://img.shields.io/cocoapods/v/MobileVLCKit.svg)](https://cocoapods.org/pods/MobileVLCKit) |
| TVVLCKit     | ![Platform](https://img.shields.io/cocoapods/p/TVVLCKit.svg?style=flat) | [![TVVLCKit is CocoaPods Compatible](https://img.shields.io/cocoapods/v/TVVLCKit.svg)](https://cocoapods.org/pods/TVVLCKit) |
12

Soomin Lee's avatar
Soomin Lee committed
13
14
## Table of content

15
16
17
18
19
- [Features](#features)
- [Use-case](#use-case)
- [Requirements](#requirements)
- [Installation](#installation)
    - [Cocoapods](#cocoapods)
Carola's avatar
Carola committed
20
    - [Carthage](#carthage)
Felix Paul Kühne's avatar
Felix Paul Kühne committed
21
- [Documentation](#documentation)
22
23
24
25
26
27
28
29
30
31
32
33
34
35
- [Build](#build)
    - [Default](#default)
    - [Build with your own VLC repository](#build-with-your-own-vlc-repository)
- [Contribute](#contribute)
    - [Pull Request](#pull-request)
    - [GitLab Issues](#gitlab-issues)
    - [Patches](#patches)
- [FAQ](#faq)
- [Communication](#communication)
    - [Forum](#forum)
    - [Issues](#issues)
    - [IRC](#irc)
- [License](#license)
- [Further reading](#further-reading)
Felix Paul Kühne's avatar
Felix Paul Kühne committed
36

37
## Features
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
38

Soomin Lee's avatar
Soomin Lee committed
39
40
- Wrapper of **libVLC**, the engine of the popular media player *VLC*.
- Supports playback, active streaming, and media to file conversations on the Mac.
41
- Open-source software licensed under [LGPLv2.1](http://opensource.org/licenses/LGPL-2.1/) or later, available in source code and binary form from [VideoLAN's website](http://www.videolan.org/).
Soomin Lee's avatar
Soomin Lee committed
42
- Easily integratable via [CocoaPods](http://cocoapods.org/).
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
43

44
## Use-case
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
45

Soomin Lee's avatar
Soomin Lee committed
46
47
48
When will you need VLCKit?

Frankly, you will need it whenever you need to play media not supported by QuickTime / AVFoundation or if you require more flexibility.
Felix Paul Kühne's avatar
Felix Paul Kühne committed
49

Soomin Lee's avatar
Soomin Lee committed
50
Here are some other common use-cases:
51

Soomin Lee's avatar
Soomin Lee committed
52
53
54
- Playing something else besides H264/AAC files or HLS streams.
- Need subtitles beyond QuickTime’s basic support for Closed Captions.
- Your media source is neither your mobile device nor a basic HTTP server, but a live stream hailing from some weird media server or even a raw DVB signal broadcasted on a local network.
55
56
57
58
- and more!

## Requirements

59
- iOS 8.4 + / macOS 10.9+ / tvOS 10.2+
60
61
- Xcode 9.0+
- Cocoapods 1.4+
Soomin Lee's avatar
Soomin Lee committed
62
- Python 3.7 (compile time only)
63
64
65
66
67

## Installation

### Cocoapods

Soomin Lee's avatar
Soomin Lee committed
68
[CocoaPods](http://cocoapods.org/) is a dependency manager for Cocoa projects. You can install it with the following command:
69
70

```bash
Soomin Lee's avatar
Soomin Lee committed
71
gem install cocoapods
72
73
```

Soomin Lee's avatar
Soomin Lee committed
74
To integrate the latest VLCKit into your project, specify it in your `Podfile`:
Felix Paul Kühne's avatar
Felix Paul Kühne committed
75

76
77
```ruby
source 'https://github.com/CocoaPods/Specs.git'
Felix Paul Kühne's avatar
Felix Paul Kühne committed
78

79
80
target '<macOS Target>' do
    platform :macos, '10.9'
81
    pod 'VLCKit', '~>3.3.0'
82
end
Felix Paul Kühne's avatar
Felix Paul Kühne committed
83

84
target '<iOS Target>' do
85
    platform :ios, '8.4'
86
    pod 'MobileVLCKit', '~>3.3.0'
87
end
Felix Paul Kühne's avatar
Felix Paul Kühne committed
88

89
target '<tvOS Target>' do
Soomin Lee's avatar
Soomin Lee committed
90
    platform :tvos, '10.2'
91
    pod 'TVVLCKit', '~>3.3.0'
92
93
end
```
Felix Paul Kühne's avatar
Felix Paul Kühne committed
94

Soomin Lee's avatar
Soomin Lee committed
95
Then, run the following command:
Felix Paul Kühne's avatar
Felix Paul Kühne committed
96

97
```bash
Soomin Lee's avatar
Soomin Lee committed
98
pod install
99
```
Carola's avatar
Carola committed
100
### Carthage
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
101

Soomin Lee's avatar
Soomin Lee committed
102
[Carthage](https://github.com/Carthage/Carthage) is a way to add frameworks to your Cocoa application. You can install it with the following command:
Carola's avatar
Carola committed
103
104
105
106
107

```bash
brew install carthage
```

108
To integrate VLCKit into your project, specify it in your `Cartfile`. The URL depends on your target OS.
Carola's avatar
Carola committed
109

110
iOS:
Carola's avatar
Carola committed
111
```
Soomin Lee's avatar
Soomin Lee committed
112
binary "https://code.videolan.org/videolan/VLCKit/raw/master/Packaging/MobileVLCKit.json" ~> 3.3.0
Carola's avatar
Carola committed
113
114
```

115
116
macOS:
```
Soomin Lee's avatar
Soomin Lee committed
117
binary "https://code.videolan.org/videolan/VLCKit/raw/master/Packaging/VLCKit.json" ~> 3.3.0
118
119
120
121
```

tvOS:
```
Soomin Lee's avatar
Soomin Lee committed
122
binary "https://code.videolan.org/videolan/VLCKit/raw/master/Packaging/TVVLCKit.json" ~> 3.3.0
123
124
```

Soomin Lee's avatar
Soomin Lee committed
125
Then, run the following command:
Carola's avatar
Carola committed
126
127
128
129

```bash
carthage update
```
Jonas Vautherin's avatar
Jonas Vautherin committed
130
131
132
133
134

Note that the following system dependencies are required and need to be linked into the project:

* AudioToolbox.framework
* AVFoundation.framework
135
136
137
* CFNetwork.framework
* CoreFoundation.framework
* CoreGraphics.framework
Jonas Vautherin's avatar
Jonas Vautherin committed
138
* CoreMedia.framework
139
140
141
* CoreText.framework
* CoreVideo.framework
* Foundation.framework
Jonas Vautherin's avatar
Jonas Vautherin committed
142
* libbz2.tbd
143
* libc++.tbd
144
* libiconv.tbd
145
* libxml2.tbd
146
147
148
149
* OpenGLES.framework
* QuartzCore.framework
* Security.framework
* VideoToolbox.framework
Jonas Vautherin's avatar
Jonas Vautherin committed
150

151
152
153
154
On iOS and tvOS, you also need to link:

* UIKit.framework

Felix Paul Kühne's avatar
Felix Paul Kühne committed
155
156
157
## Documentation
API documentation of VLCKit is available [online](https://videolan.videolan.me/VLCKit) and within both the source code as well as binary downloads. Except as indicated, all the APIs are the same on macOS, iOS and tvOS.

158
## Build
159

160
### Default
161

Soomin Lee's avatar
Soomin Lee committed
162
Make sure that Python 3.7 is installed. Get the package from https://www.python.org - do NOT use homebrew for installation as it will be ignored by VLC's build process.
163

164
165
Run `compileAndBuildVLCKit.sh` with the `-a ${ARCH}` option to specify the target architecture.

Soomin Lee's avatar
Soomin Lee committed
166
More information can be found under `./compileAndBuildVLCKit.sh -h`.
167
168

### Build with your own VLC repository
169

Soomin Lee's avatar
Soomin Lee committed
170
1. Put a VLC repository inside `libvlc/vlc`.
David's avatar
David committed
171

Soomin Lee's avatar
Soomin Lee committed
172
    `mkdir libvlc && cd libvlc && ln -s "PATH_TO_VLC"`
173

Soomin Lee's avatar
Soomin Lee committed
174
2. Apply VLC patches needed for VLCKit.
David's avatar
David committed
175

176
    `cd vlc`
David's avatar
David committed
177

178
    `git am ../libvlc/patches/*`
179

Soomin Lee's avatar
Soomin Lee committed
180
3. run `compileAndBuildVLCKit.sh` with the `-n` option.
Felix Paul Kühne's avatar
Felix Paul Kühne committed
181

182
## Contribute
Felix Paul Kühne's avatar
Felix Paul Kühne committed
183

184
As VLCKit is an open-source project hosted by VideoLAN, we happily welcome all kinds of contributions.
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
185

186
### Pull Request
Felix Paul Kühne's avatar
Felix Paul Kühne committed
187

188
189
190
191
192
193
194
195
Pull requests are more than welcome! If you do submit one, please make sure to use a descriptive title and description.

### GitLab Issues

You can look through the currently open [issues on GitLab](https://code.videolan.org/videolan/vlckit/issues/) and choose the one that interests you the most.

### Patches

196
If you like the more classic approach, you can submit patches!
197
198

For detailed explanation on how to do so, please read our wiki page on [how to send patches](https://wiki.videolan.org/Sending_Patches_VLC/).
Felix Paul Kühne's avatar
Felix Paul Kühne committed
199

200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
## FAQ

> Q. Since this isn't under the MIT license, is there something special I should know?

The [LGPLv2.1](http://opensource.org/licenses/LGPL-2.1/) allows our software to be included in proprietary apps, *as long as you follow the license.* Here are some key points you should be aware of.

- Make sure to publish any potential changes you do to our software
- Make sure that the end-user is aware that VLCKit is embedded within your greater work
- Make sure that the end-user is aware of the gained rights and is granted access to our code as well as to your additions to our work

For further details, please read the license and consult your lawyer with any questions you might have.

## Communication

### Forum

Soomin Lee's avatar
Soomin Lee committed
216
If you ever need help, feel free to reach out. The [forum](http://forum.videolan.org/) is always there for you.
217
218
219
220
221
222
223
224
225
226
227

### Issues

Did you find a bug and want to report it to us? You can create an issue on [GitLab](https://code.videolan.org/videolan/vlckit/issues/) or on our [bug tracker](https://trac.videolan.org/vlc/).

### IRC

Do you have a pressing question or just want to talk? Reach out to us via our IRC channel on the [freenode](http://www.freenode.net/) network's **#videolan** channel.

If you don't have an IRC client at hand, use the [freenode webchat](http://webchat.freenode.net/).

Martin Finkel's avatar
Martin Finkel committed
228
229
230
231
232
233
### Discord

For matters related to the VLCKit and LibVLC APIs, join our LibVLC bindings Community Discord Server!

[![Join the chat at https://discord.gg/3h3K3JF](https://img.shields.io/discord/716939396464508958?label=discord)](https://discord.gg/3h3K3JF)

234
235
236
237
238
239
240
## License

VLCKit is under the [LGPLv2.1](http://opensource.org/licenses/LGPL-2.1/) license.

See [COPYING](./COPYING) for more license info.

## Further reading
Felix Paul Kühne's avatar
Felix Paul Kühne committed
241

242
You can find more documentation on the [VideoLAN wiki](https://wiki.videolan.org/VLCKit/).