# Installation with Ascend NPU (x86)

## Required Environment

CANN == 8.3.RC1

## Prepare CANN

Choose one of the following methods to use CANN:

1. Install CANN according to the [official documentation](https://www.hiascend.com/document/detail/zh/canncommercial/83RC1/softwareinst/instg/instg_quick.html?Mode=PmIns&InstallType=local&OS=openEuler&Software=cannToolKit)

2. Download and use [the CANN image](https://www.hiascend.com/developer/ascendhub/detail/17da20d1c2b6493cb38765adeba85884)

## Install with uv or pip

### UV

> Recommend to use [uv](https://docs.astral.sh/uv/) for faster and easier installation.

```bash
git clone https://github.com/ByteDance-Seed/VeOmni.git
cd VeOmni

# use the locked uv env
uv sync --locked  --extra npu
source .venv/bin/activate
```

You can use `--extra` to install other optional dependencies. Refer to [pyproject.toml](https://github.com/ByteDance-Seed/VeOmni/blob/main/pyproject.toml) for more details.

```bash
# eg. install with video/audio processing dependencies (torchcodec, PyAV, librosa, soundfile)
# Note: `video` and `audio` extras are equivalent - both include video and audio processing
uv sync --locked  --extra npu --extra video
# or equivalently:
uv sync --locked  --extra npu --extra audio
```

> **Note**: For video/audio processing with the `video` or `audio` extra, you also need to install ffmpeg separately:
> ```bash
> # Ubuntu/Debian/openEuler
> sudo apt-get install ffmpeg
> # or
> sudo yum install ffmpeg
> ```

### Pip

```bash
git clone https://github.com/ByteDance-Seed/VeOmni.git
cd VeOmni

# Choose one of the following installation options based on your needs:
# Option 1: Stable version (transformers < 5.0)
pip install -e .[npu,transformers-stable]

# Option 2: Experimental version for new models (transformers ≥ 5.0)
# Note: This uses the transformers5-exp extra which includes transformers 5.0+ support
# as specified in pyproject.toml (experimental and under development)
# pip install -e .[npu,transformers5-exp]
```

### Set up CANN environment before installing torchcodec
Make sure CANN_path is set to your CANN installation directory, e.g., export CANN_path=/usr/local/Ascend
```bash
source $CANN_path/ascend-toolkit/set_env.sh

# Add chunkloss feature
export VEOMNI_ENABLE_CHUNK_LOSS=1
```

### Video/Audio Processing Dependencies (Optional)

For video/audio processing capabilities, you need to install torchcodec separately. Follow these steps:

```bash
# Clone the torchcodec repository
cd ..
git clone https://github.com/meta-pytorch/torchcodec.git
cd torchcodec

# Checkout to a specific version for compatibility
git checkout v0.5.0

# Copy the installation script to the torchcodec source directory
cp ../VeOmni/docs/get_started/installation/install_torchcodec_Ascend.sh .

# Note: Ensure Python is installed as a shared library (required for compiling C++ extensions)
# The installation script will automatically verify this requirement

# Run the installation script (replace with your actual CANN path)
bash install_torchcodec_Ascend.sh $CANN_path/ascend-toolkit/set_env.sh

# Verify installation
pip show torchcodec

# Test torchcodec import
python -c "from torchcodec.decoders import VideoDecoder; print('Success')"
# If the terminal outputs'Success', it indicates that the torchcodec installation was successful. If an error message is output, it indicates that the installation was not successful
```