StreamBeam

StreamBeam is a lightweight macOS menu bar app for mirroring and recording a wired iPhone or iPad screen on your Mac. Connect a device over USB, trust the Mac, and StreamBeam opens a clean preview window with an optional recording control.

Highlights

• Detects connected iPhone and iPad devices from the macOS USB device tree.
• Opens device-specific preview windows from the menu bar.
• Uses AVCaptureSession and AVCaptureVideoPreviewLayer for live screen preview.
• Records the active capture session to a .mov file selected with the native save panel.
• Runs as a menu bar utility with no persistent dock window.
• Reacts to device connection and disconnection events.

Demo

Video720StreamBeam.mp4

Requirements

• macOS 12.0 or later.
• Xcode with macOS development tools.
• Swift 5.
• A physical iPhone or iPad connected over USB.

StreamBeam depends on Apple system frameworks only. There are no package manager dependencies.

Getting Started

Clone the repository:

git clone https://github.com/jghg02/streambeam.git
cd streambeam

Open the Xcode project:

open StreamBeam.xcodeproj

Select the StreamBeam scheme, choose My Mac as the run destination, then build and run with Cmd + R.

You can also build from the command line:

xcodebuild -project StreamBeam.xcodeproj -scheme StreamBeam -configuration Debug build

If you do not have the repository owner's signing certificate, either select your own team in Xcode or use an unsigned local build:

xcodebuild -project StreamBeam.xcodeproj -scheme StreamBeam -configuration Debug CODE_SIGNING_ALLOWED=NO build

App Permissions

On first launch, macOS may ask for camera/video capture access because StreamBeam uses AVCaptureDevice to access connected device screen capture streams.

If permission was denied, update it in:

System Settings -> Privacy & Security -> Camera

Then quit and reopen StreamBeam.

How To Use

1. Launch StreamBeam.
2. Connect an iPhone or iPad with a USB cable.
3. Unlock the device and choose Trust This Computer if iOS or iPadOS asks.
4. Use the StreamBeam menu bar icon to select the connected device.
5. A preview window opens for that device.
6. Hover over the preview window to show the recording button.
7. Click the green button to choose a save location and start recording.
8. Click the red stop button to finish the recording.

Recordings are saved as .mov files using the filename pattern:

StreamBeam_yyyyMMdd_HHmmss.mov

Project Structure

StreamBeam/
├── AppDelegate/          # Menu bar lifecycle, menu items, and device windows
├── DeviceMonitor/        # IOKit USB connection and disconnection monitoring
├── Log/                  # Lightweight logging helper
├── Model/                # Device, capture session, and app metadata models
├── ScreenStream/         # AVFoundation capture sessions and preview layer bridge
├── Utils/                # Capture-device helper extensions
├── Views/                # SwiftUI views for preview, bezel, and About window
└── WindowsController/    # NSWindowController builder and window setup

StreamBeamTests/          # Unit test target
StreamBeamUITests/        # UI test target

Architecture

StreamBeam is a SwiftUI and AppKit hybrid:

• AppDelegate creates the menu bar item, manages menu actions, and opens preview windows.
• DeviceMonitor listens for USB device changes through IOKit and publishes device events with Combine.
• DeviceManager enables screen capture devices, requests capture authorization, creates AVCaptureSession instances, and starts or stops recordings.
• CapturePreviewRepresentable bridges AVCaptureVideoPreviewLayer into SwiftUI with NSViewRepresentable.
• WindowControllerBuilder keeps preview and About window creation consistent.

Running Tests

Run the test suite from Xcode with Cmd + U, or from the command line:

xcodebuild test -project StreamBeam.xcodeproj -scheme StreamBeam -destination 'platform=macOS'

Troubleshooting

The device does not appear

• Confirm the device is connected by USB.
• Unlock the device and accept the trust prompt.
• Try another USB cable or port.
• Quit and reopen StreamBeam after connecting the device.

The preview window opens but stays blank

• Confirm capture permission is enabled in macOS settings.
• Disconnect and reconnect the device.
• Close duplicate preview windows and select the device again from the menu bar.

Recording does not start

• Make sure a preview session is active before clicking record.
• Choose a writable destination in the save panel.
• Check whether macOS has blocked capture access for the app build you are running.

The app does not appear in the Dock

That is expected. StreamBeam runs as an accessory app and is controlled from the macOS menu bar.

Contributing

Issues and pull requests are welcome. For changes that affect capture behavior, please include:

• macOS version.
• Xcode version.
• Device model and iOS or iPadOS version.
• Steps used to verify preview and recording.

Before opening a pull request, build the app and run the tests when possible:

xcodebuild -project StreamBeam.xcodeproj -scheme StreamBeam -configuration Debug build
xcodebuild test -project StreamBeam.xcodeproj -scheme StreamBeam -destination 'platform=macOS'

For local verification without signing, add CODE_SIGNING_ALLOWED=NO to the build command.

Roadmap Ideas

• Release packaging and notarization.
• Better multi-device preview selection.
• Recording status and error feedback improvements.
• Configurable preview window sizes.
• Automated coverage for device-monitor behavior.

License

StreamBeam is available under the Apache License 2.0. See LICENSE for details.

Contact

• Website: streambeam.tech
• Email: info@streambeam.tech
• Issues: GitHub Issues