Get Started with a Local Project
In this tutorial we will install the tools, set up the build environment, create your first PlayTorch project and see it running in an emulator or your phone.
If you're looking for a simpler way to get started try out PlayTorch using Expo Snacks — no dev environment required!
PlayTorch's command line tool torchlive-cli will automate most of the setup process.
The command line tool torchlive-cli is deprecated and will be removed in a future release. Instead, get started quickly with the PlayTorch app. An alternative to developing with the app is to manually set up a local environment or add PlayTorch to an existing app.
Here's a sneak peek of the PlayTorch app when the setup is complete:
Let's get started!
Prerequisites
- Our beta release only supports MacOS. Windows and Linux supports are coming soon. However, you can follow the manual installation instructions to get started on Windows and Linux.
- Node.js: If you don't have it already, you can download Node.js LTS from its website or install via Homebrew (ie,
brew install node).- Note that Node.js version 17 can cause issues, so it is recommended to use any of the LTS versions 12, 14, or 16.
- Xcode: If you want to run the app on an iOS simulator or a physical iOS device, you need to install Xcode from the Apple App Store on your macOS device. PlayTorch currently supports Xcode version 12.5 or later.
Installation
Setting up the build environment can be tedious and difficult. PlayTorch provides a setup routine to install the required dependencies automatically for you. It will try to install the following libraries and tools:
- Homebrew
- OpenJDK
- Yarn
- Watchman
- Android Command Line Tools
- Android SDK
- Android SDK Manager
- Android Virtual Device Manager
- Android Emulator
- CocoaPods
The PlayTorch CLI currently does not support the Apple M1 chipset. However, there are instructions by the community for how to install React Native on an Apple M1 without Rosetta.
Here's what you will see during the automatic setup process:
Check out the manual installation process if your operating system is Windows or Linux or if the PlayTorch command line tool torchlive-cli fails for you!
Now let's run this setup-dev command and get the build environment ready for development:
❯ npx torchlive-cli setup-dev
You will need administrator access (using sudo) to run this command. It may take 20 minutes to complete, depending on your laptop configurations.
You only need to run this once to install the dependencies. No need to run this again to start a new project.
Check installations
If everything goes well, the terminal will looks similar to the following output. If you run into any issues, please check the FAQ.
❯ npx torchlive-cli setup-dev
_ _ _ _
| |_ ___ _ __ ___| |__ | (_)_ _____
| __/ _ \| '__/ __| '_ \| | \ \ / / _ \
| || (_) | | | (__| | | | | |\ V / __/
\__\___/|_| \___|_| |_|_|_| \_/ \___|
torchlive version 0.0.2-alpha.5
Password:
↓ Homebrew (3.1.7) [SKIPPED]
✔ OpenJDK (1.8.0)
✔ Watchman (4.9.0)
↓ Node (16.1.0) [SKIPPED]
✔ Yarn (1.22.10)
✔ Android SDK
✔ Android SDK Manager
✔ Android Emulator
✔ Android Emulator Skin
Create a New Project
Now that we have set up the build environment, let's create a new PlayTorch project and see it running in an emulator or on your device. It's as simple as running two commands using the torchlive-cli tool.
Initialize Your Project
For PlayTorch beta, we provide a bootstrap React Native app, packed with AI demos and practical examples. Use the npx torchlive-cli init command to initialize your first PlayTorch project.
npx torchlive-cli init MyFirstProject
Behind the scene, the tool created a new React Native project and configured the build tools for mobile development. It also added a couple on-device AI models as well as examples to run them.
This is what you should see after the project is initialized:
❯ npx torchlive-cli init MyFirstProject
_ _ _ _
| |_ ___ _ __ ___| |__ | (_)_ _____
| __/ _ \| '__/ __| '_ \| | \ \ / / _ \
| || (_) | | | (__| | | | | |\ V / __/
\__\___/|_| \___|_| |_|_|_| \_/ \___|
torchlive version 0.0.2-alpha.5
✔ project MyFirstProject
Run Your Project
We are almost there. Now let's navigate to the newly created PlayTorch project folder:
cd MyFirstProject
And run the PlayTorch project on Android:
npx torchlive-cli run-android
By default, the PlayTorch app will run in an emulator. You can also run it on your own phone which may improve performance. To see it on your phone, plug it into your computer and enable Android's developer mode.
On Android 4.1 and lower, the Developer options screen is available by default. On Android 4.2 and higher, you must enable this screen. To enable developer options, go to Settings > Developer options and tap the Build Number option 7 times.
More details are on the Android configure on-device developer options.
Welcome to PlayTorch
Start by trying out the various Examples in the app. When you are ready to experiment, take a look at the Toolbox demos.
PlayTorch is in beta. Your feedback will help us improve tremendously. Please file issues and share ideas on GitHub.
Show us what you've made with PlayTorch by tagging #playtorch in your social media posts too.