README.md 7.81 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 7 8

|              | Platform                                                     | Master                                                       | Cocoapods                                                    |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
9 10 11
| VLCKit       | ![Platform](https://img.shields.io/cocoapods/p/VLCKit.svg?style=flat) | ![CircleCI](https://img.shields.io/circleci/project/github/videolan/vlckit/master.svg) | [![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) | ![CircleCI](https://img.shields.io/circleci/project/github/videolan/vlckit/master.svg) | [![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) | ![CircleCI](https://img.shields.io/circleci/project/github/videolan/vlckit/master.svg) | [![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)
20
    - [Carthage](#carthage)
21 22 23 24 25 26 27 28 29 30 31 32 33 34
- [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
35

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

Soomin Lee's avatar
Soomin Lee committed
38 39
- Wrapper of **libVLC**, the engine of the popular media player *VLC*.
- Supports playback, active streaming, and media to file conversations on the Mac.
40
- 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
41
- Easily integratable via [CocoaPods](http://cocoapods.org/).
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
42

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

Soomin Lee's avatar
Soomin Lee committed
45 46 47
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
48

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

Soomin Lee's avatar
Soomin Lee committed
51 52 53
- 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.
54 55 56 57
- and more!

## Requirements

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

## Installation

### Cocoapods

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

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

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

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

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

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

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

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

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

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

```bash
brew install carthage
```

107
To integrate VLCKit into your project, specify it in your `Cartfile`. The URL depends on your target OS.
108

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

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

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

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

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

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

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

148 149 150 151
On iOS and tvOS, you also need to link:

* UIKit.framework

152
## Build
153

154
### Default
155

Soomin Lee's avatar
Soomin Lee committed
156
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.
157

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

Soomin Lee's avatar
Soomin Lee committed
160
More information can be found under `./compileAndBuildVLCKit.sh -h`.
161 162

### Build with your own VLC repository
163

Soomin Lee's avatar
Soomin Lee committed
164
1. Put a VLC repository inside `libvlc/vlc`.
165

Soomin Lee's avatar
Soomin Lee committed
166
    `mkdir libvlc && cd libvlc && ln -s "PATH_TO_VLC"`
167

Soomin Lee's avatar
Soomin Lee committed
168
2. Apply VLC patches needed for VLCKit.
169

170
    `cd vlc`
171

172
    `git am ../../Resources/MobileVLCKit/patches/*`
173

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

176
## Contribute
Felix Paul Kühne's avatar
Felix Paul Kühne committed
177

178
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
179

180
### Pull Request
Felix Paul Kühne's avatar
Felix Paul Kühne committed
181

182 183 184 185 186 187 188 189 190 191 192
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

If you like the more classic apporach, you can submit patches!

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
193

194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209
## 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
210
If you ever need help, feel free to reach out. The [forum](http://forum.videolan.org/) is always there for you.
211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228

### 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/).

## 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
229

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