README.md 7.58 KB
Newer Older
Mike JS. Choi's avatar
Mike JS. Choi committed
1
<img src="https://www.videolan.org/images/vlckit/logo.svg" alt="VLCKit logo" height="70" >
2 3 4

|              | Platform                                                     | Master                                                       | Cocoapods                                                    |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
5 6 7
| 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) |
8 9 10 11 12 13

- [Features](#features)
- [Use-case](#use-case)
- [Requirements](#requirements)
- [Installation](#installation)
    - [Cocoapods](#cocoapods)
14
    - [Carthage](#carthage)
15 16 17 18 19 20 21 22 23 24 25 26 27 28
- [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
29

30
**VLCKit** is a generic multimedia library for any audio or video playback needs on macOS, iOS and tvOS.
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
31

32
## Features
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
33

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

39
## Use-case
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
40

41
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
42

43
Here are some other common use-cases
44

45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66
- 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
- and more!

## Requirements

- iOS 8.0 + / macOS 10.9+ / tvOS 10.2+
- Xcode 9.0+
- Cocoapods 1.4+

## Installation

### Cocoapods

[CocoaPods](http://cocoapods.org/) is a dependency manager for Cocoa projects. You can install it with the following command,

```bash
$ gem install cocoapods
```

To integrate VLCKit into your project, specify it in your `Podfile`,
Felix Paul Kühne's avatar
Felix Paul Kühne committed
67

68 69
```ruby
source 'https://github.com/CocoaPods/Specs.git'
Felix Paul Kühne's avatar
Felix Paul Kühne committed
70

71 72 73 74
target '<macOS Target>' do
    platform :macos, '10.9'
    pod 'VLCKit', '3.1.2'
end
Felix Paul Kühne's avatar
Felix Paul Kühne committed
75

76 77 78 79
target '<iOS Target>' do
    platform :ios, '8.0'
    pod 'MobileVLCKit', '3.1.2'
end
Felix Paul Kühne's avatar
Felix Paul Kühne committed
80

81 82 83 84 85
target '<tvOS Target>' do
    platform :tvos, '9.0'
    pod 'TVVLCKit', '3.1.2'
end
```
Felix Paul Kühne's avatar
Felix Paul Kühne committed
86

87
Then, run the following command,
Felix Paul Kühne's avatar
Felix Paul Kühne committed
88

89 90 91
```bash
$ pod install
```
92
### Carthage
Jean-Baptiste Kempf's avatar
Jean-Baptiste Kempf committed
93

94 95 96 97 98 99
[Carthage](https://github.com/Carthage/Carthage) is a way to add frameworks to your Cocoa application. You can install it with the following command,

```bash
brew install carthage
```

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

102
iOS:
103
```
Soomin Lee's avatar
Soomin Lee committed
104
binary "https://code.videolan.org/videolan/VLCKit/raw/master/Packaging/MobileVLCKit.json" ~> 3.1.4
105 106
```

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

tvOS:
```
Soomin Lee's avatar
Soomin Lee committed
114
binary "https://code.videolan.org/videolan/VLCKit/raw/master/Packaging/TVVLCKit.json" ~> 3.1.4
115 116
```

117 118 119 120 121
Then, run the following command,

```bash
carthage update
```
Jonas Vautherin's avatar
Jonas Vautherin committed
122 123 124 125 126

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

* AudioToolbox.framework
* AVFoundation.framework
127 128 129
* CFNetwork.framework
* CoreFoundation.framework
* CoreGraphics.framework
Jonas Vautherin's avatar
Jonas Vautherin committed
130
* CoreMedia.framework
131 132 133
* CoreText.framework
* CoreVideo.framework
* Foundation.framework
Jonas Vautherin's avatar
Jonas Vautherin committed
134
* libbz2.tbd
135 136 137 138 139
* libiconv.tbd
* OpenGLES.framework
* QuartzCore.framework
* Security.framework
* VideoToolbox.framework
Jonas Vautherin's avatar
Jonas Vautherin committed
140

141 142 143 144
On iOS and tvOS, you also need to link:

* UIKit.framework

145
## Build
146

147
### Default
148

149 150 151
Run `compileAndBuildVLCKit.sh` with the `-a ${ARCH}` option to specify the target architecture.

More information can be found under `./compileAndBuildVLCKit.sh -h`
152 153

### Build with your own VLC repository
154

155
1. Put a vlc repository inside libvlc/vlc
156

157 158 159
    `mkdir libvlc && cd libvlc && ln -s ${MYVLCGIT}`

2. Apply VLC patches needed for VLCKit
160

161
    `cd vlc`
162

163
    `git am ../../Resources/MobileVLCKit/patches/*`
164

165
3. run `compileAndBuildVLCKit.sh` with the `-n` and the `-a ${ARCH}` option
Felix Paul Kühne's avatar
Felix Paul Kühne committed
166

167
## Contribute
Felix Paul Kühne's avatar
Felix Paul Kühne committed
168

169
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
170

171
### Pull Request
Felix Paul Kühne's avatar
Felix Paul Kühne committed
172

173 174 175 176 177 178 179 180 181 182 183
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
184

185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219
## 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

If you ever need help, feel free to reach out. The [web forum](http://forum.videolan.org/) is always there for you.

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

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