View source for Mac Recording and Streaming/CocoaSplit

[[Category:Mac]]
[[Category:Recording]]
[[Category:Streaming]]
= Main Websites =
[http://cocoasplit.com cocoasplit.com]

[https://github.com/zakk4223/CocoaSplit github.com/zakk4223/CocoaSplit]

<u>Note</u>: There are currently two versions of CocoaSplit, the older "classic" one and the experimental CoreImage build.  This page will focus on the latter, as it is more capable and is better supported by its developer.


= Terminology =

This is not a comprehensive list, but just the basics one should know when learning how to stream with CocoaSplit.


== Video ==

*<u>Canvas</u>: The preview frame at the top where you can add and manage your input sources.
*<u>Layout</u>: A collection of input sources.  Layouts can be switched and allow you to group multiple elements in sets without having to constantly change them individually.  Think of these as Setups in CamTwist or Scenes in OBS.
*<u>FPS</u>: The ''frames per second'' that will be displayed for the stream.  This is separate from the frame rate of your sources.  For the smoothest motion you'll want 60 FPS, but keep in mind this will use substantially more CPU and requires a higher bit rate to maintain good quality than something like 30 FPS.  You'll also want to keep your source frame rate in mind.  60 FPS is pointless if your video source is 30 FPS.
*<u>Resolution</u>: The height & width (in pixels) of the canvas.  This is <u>''not''</u> the resolution the stream will be compressed to, but it still does affect quality based on your compression settings.  The closer these values are to your compression resolution, the higher quality you'll get.
*<u>Compress</u>: To make the audio/video size smaller so that you can reasonably upload live video as it happens.  Lossless video is far too big for most Internet connections to upload continuously.
*<u>Profile</u>: A set of compression settings that are saved and can be chosen from the dropdown menus.


== Audio ==

*<u>Source</u>: The audio device you want to use for the stream.
*<u>Bit Rate</u>: How much data (in kilobits) you want to upload per second.  Higher gives clearer audio.
*<u>Sample Rate</u>: Determines how high the frequency range can go.  44100 is ideal as it gives a maximum frequency of 20 kHz, which is the highest humans can generally hear.
*<u>Audio Shift</u>: How long the audio should be delayed for the stream.  Video and audio sources are often not properly synchronized.  You can use this setting to try and bridge the gap between them.


= Source Selection =

To add a source, first select the appropriate layout you want to use (create a new one with the + symbol and name it), then click "Add New" above the layout selection to add an empty source object in the canvas.  This will automatically bring up the source selection, where you can choose what to use from a dropdown menu.  These include images, text boxes, Syphon sources, window capture, etc.


<u>Note</u>: Window Capture is currently unoptimized and will result in very low frame rate.


Syphon will give the best results for your main video.  There are two approaches to use a Syphon source: you can manage all your video in CamTwist and select "Enable the Syphon Server" in its preferences, or you can make any OpenGL application temporary use Syphon by using [https://github.com/zakk4223/SyphonInject SyphonInject.] This will make it selectable in CocoaSplit as a Syphon source and share its frames with minimal CPU usage.


You can bring up these settings again by secondary clicking a source on the canvas and choosing "Settings."  Alternatively, you can secondary click outside the canvas, which will list all sources from that layout in a menu.


You can resize sources by clicking and dragging the blue borders around them.  For more control, go into the settings for that source and change its scale and cropping.  You can reposition a source by clicking and dragging anywhere within the blue border.


As for audio sources, I highly recommend using [https://github.com/RogueAmoeba/Soundflower Soundflower] in conjunction with [http://www.rogueamoeba.com/audiohijackpro/ Audio Hijack Pro.] This will enable you to stream multiple audio sources even though CocoaSplit only supports one.  It will also enable much more control over audio in the form of mixing, gain levels, various affects, input/output, etc.


(To do: explain Layout Previews once they're fixed.)


= Compression =

You'll need to find the ideal settings based on your computer hardware capabilities, video sources, Internet connection, etc.  There is no set format for this as it depends entirely on what your hardware can do and what you consider acceptable/good quality.


*<u>Resolution</u>: This is the resolution that you'll actually stream to.  For the best quality you'll want this as close to your canvas resolution as possible, but keep in mind that resolution significantly impacts performance.  You'll also want the correct values for the aspect ratio.  16:9 is the standard ratio used, and you can view a list of correct values [http://pacoup.com/2011/06/12/list-of-true-169-resolutions/ here.]
*<u>Type</u>: x264 will give the best results and highest compatibility with devices and stream services.
*<u>Name</u>: This is what you'll call your profile to distinguish it from other profiles.  For example, you may call it "Genesis" if you use the same settings for all Genesis games.
*<u>Preset</u>: Compression efficiency.  Slower results in higher quality but requires more CPU.  Faster is less efficient and lower quality, but better CPU usage.  Choose whichever you want other than placebo.
*<u>Tune</u>: This tailors some encoding options based on the type of content being streamed.  For most things just choose zerolatency.
*<u>Profile</u>: For compression, profile means the level of complexity for encoding/decoding.  This affects visual quality, CPU usage, and compatibility with devices.  Baseline and main are the standards.
*<u>VBV Max Rate</u>: The bit rate you want to limit your stream to.  Set this to something under your upload speed.  For instance, if you have 1 Mbps total upload, you may want to set this around 800 Kbps.
*<u>VBV Buffer</u>: If not using CBR, set this to the bit rate you want to target (usually the same as VBV Max Rate).  If using CBR, leave this at 0.
*<u>Keyframe</u>: Set this to 2 for best compatibility with stream services.
*<u>CRF</u>: If not using CBR, this will attempt to target a certain level of constant quality.  It ranges from 0 - 51, with lower values giving higher quality (using more CPU) and 23 being the default value.  Common values are 18, 23, and 28.  If using CBR, leave this at 0.
*<u>CBR</u>: Select this if you want to increase the stability of your stream at the possible expense of visual quality during frames with many changing pixels.  If your bit rate setting cannot handle high motion sequences, the quality will automatically degrade rather than skip, drop, or pile up pending frames.  Highly recommended to use this setting as VBR gets more unstable or causes buffering for viewers when your bit rate spikes.


= Stream Destinations =

Destinations have a checkbox and a dropdown menu.  Check whichever you want to currently stream to, and choose a compression profile on the right side before you start the stream.


== File Output ==

Click the dropdown menu under "Settings" in the main window and choose File.  Enter something like this: /Users/YourUserNameHere/Desktop/Test.mp4.  This will create a video called Test on your Desktop when you stream.  Keep in mind that streaming again will ''overwrite'' the previous file with no warning if you do not change the file name.


== Stream Output ==

Currently the only option in the dropdown menu is "TwitchTV," but you can use this for any RTMP-based stream service.  Select TwitchTV and click Add.  You'll be prompted to choose a server and enter your stream key.  Pick whatever server is closest to you (or gives the best connection) and find your stream key on whatever stream service website you use.  A couple examples:


*<u>Twitch</u>: Go to your Dashboard, click Stream Key, then Show Key.  It'll look something like this: live_somenumbers_morenumbersandletters.
*<u>Hitbox</u>: Go to Livestream -> Details and click Show Key.  It will look like this: hitboxusername?key=lettersandnumbers.  The destination URL will automatically be configured as if it was Twitch.  To change this, double click the destination in the output list and paste the Hitbox URL like this: rtmp://live.hitbox.tv/push/hitboxusername?key=lettersandnumbers.  This should work for any other RTMP-based service too as long as you use the correct URL for that service.


When you're done setting everything up, I recommend you quit CocoaSplit and then reopen it.  Should CocoaSplit crash, any changes you made will be erased.  Quitting will save all changes to a settings file.  Once you're ready, simply click "Stream!" and you will go live (and/or output to a file).  The window will automatically transition to the Status tab where you can see the live encoding details, such as your current frame rate and whether or not you're dropping or piling up frames.