# Migrate from 9.x to 11.x

Dynamsoft Barcode Reader SDK has been refactored to integrate with the [`DynamsoftCaptureVision (DCV)`](https://www.dynamsoft.com/capture-vision/docs/core/architecture/index.md) architecture since version 10.0. This guide helps you upgrade from version 9.x by highlighting the key API changes and providing migration paths.

The actual migration effort depends on which APIs you currently use. In many cases, only the interfaces you actively use need to be updated - review the sections below to identify the changes that affect your integration.

> [!NOTE]
> If you are new to the DCV architecture and prefer to start fresh, refer to the [User Guide](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/user-guide.md) for a quick-start tutorial.

## Update the License Key

You may need to update your license key before upgrading to version 11.x.

- **30-Day Free Trial License**: Visit the [Request a Trial License](https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&utm_source=docs){:target="_blank"} page to obtain a free license for evaluation.
- **Annual Online Full License**: Your license will continue to work with the new SDK version. Go to <a href="https://www.dynamsoft.com/customer/license/fullLicense" target="_blank">Customer Portal</a> to get your license key.
- **Perpetual License**: Please contact our [sales team](https://www.dynamsoft.com/contact){:target="_blank"} to update your license.

## Migrate to New Package

As of version 10.0, the `dbr` package has been renamed to `dynamsoft-barcode-reader-bundle` to reflect changes in both architecture and API design. Run the following command to install the new package:

```bash
pip install dynamsoft-barcode-reader-bundle
```

## Migrate License Activation Code

Starting from 10.0, we have unified the API for setting licenses across different Dynamsoft products.

| Old APIs | New APIs |
| :----------- | :------- |
| `BarcodeReader.init_license` | [`LicenseManager.init_license`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/license/license-manager.md#init_license) |

## Migrate Decoding APIs

### Single Image Decoding

The APIs for decoding single image have been adjusted as follows:

| Old APIs | New APIs |
| :----------- | :------- |
| `BarcodeReader.decode_file` | [`CaptureVisionRouter.capture`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/single-file-processing.md#capture) |
| `BarcodeReader.decode_file_stream` | [`CaptureVisionRouter.capture`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/single-file-processing.md#capture) |
| `BarcodeReader.decode_buffer_manually` | [`CaptureVisionRouter.capture`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/single-file-processing.md#capture) |
| `BarcodeReader.decode_buffer` | [`CaptureVisionRouter.capture`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/single-file-processing.md#capture) |
| `class TextResult` | [`class BarcodeResultItem`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/barcode-result-item.md) |
| `BarcodeReader.decode_base64_string` | **Not available**. |

### Video Streaming Decoding

`ImageSourceAdapter` is added to replace the `FrameDecodingParameters` and the previous video methods. You should implement `ImageSourceAdapter` to transfer image data from camera or video file to buffer.

## Migrate Template APIs

The template-based APIs have been updated as follows:

| Old APIs | New APIs |
| :----------- | :------- |
| `BarcodeReader.init_runtime_settings_with_file` | [`CaptureVisionRouter.init_settings_from_file`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/settings.md#init_settings_from_file) |
| `BarcodeReader.init_runtime_settings_with_string` | [`CaptureVisionRouter.init_settings`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/settings.md#init_settings) |
| `BarcodeReader.output_settings_to_json_file` | [`CaptureVisionRouter.output_settings_to_file`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/settings.md#output_settings_to_file) |
| `BarcodeReader.output_settings_to_json_string` | [`CaptureVisionRouter.output_settings`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/settings.md#output_settings) |
| `BarcodeReader.reset_runtime_settings` | [`CaptureVisionRouter.reset_settings`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/settings.md#reset_settings) |
| `BarcodeReader.append_template_file_to_runtime_settings` | **Not available**. |
| `BarcodeReader.append_template_string_to_runtime_settings` | **Not available**. |
| `BarcodeReader.get_all_template_names` | **Not available**. |

## Upgrade Template Files

The template file format has changed in the new version. Templates created for version 9.x are not compatible with version 11.x. Use the <a href="https://www.dynamsoft.com/tools/template-upgrade/" target="_blank">Template Upgrade Tool</a> to automatically convert your existing templates to the new format.

## Migrate Runtime Settings

The class `PublicRuntimeSetting` has been refactored. It retains commonly used properties via `SimplifiedCaptureVisionSettings` while removing the previously complex property settings, which are now exclusively supported through templates.

The APIs for accessing and updating runtime settings have been adjusted as follows:

| Old APIs | New APIs |
| :----------- | :------- |
| `BarcodeReader.get_runtime_settings` | [`CaptureVisionRouter.get_simplified_settings`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/settings.md#get_simplified_settings) |
| `BarcodeReader.update_runtime_settings` | [`CaptureVisionRouter.update_settings`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/settings.md#update_settings) |

### Properties with Direct API Replacement

The following properties are replaced by similar properties under `SimplifiedCaptureVisionSettings` or `SimplifiedBarcodeReaderSettings`. They can also be set via a template file.

#### SimplifiedCaptureVisionSettings

| PublicRuntimeSetting Property | SimplifiedCaptureVisionSettings Parameter | Template File Parameter |
| ------------------------------- | ----------------------------------------- | ----------------------- |
| `region` | [`roi`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/auxiliary-classes/simplified-capture-vision-settings.md#roi) & [`roi_measured_in_percentage`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/auxiliary-classes/simplified-capture-vision-settings.md#roi_measured_in_percentage) | [`TargetROIDef.Location.Offset`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/target-roi-def/location.md) |
| `timeout` | [`timeout`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/capture-vision-router/auxiliary-classes/simplified-capture-vision-settings.md#timeout) | [`CaptureVisionTemplates.Timeout`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/capture-vision-template/timeout.md) |

#### SimplifiedBarcodeReaderSettings

| PublicRuntimeSetting Property | SimplifiedBarcodeReaderSettings Property | Template File Parameter |
| ------------------------------- | ----------------------------------------- | ----------------------- |
| `min_barcode_text_length` | [`min_barcode_text_length`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#min_barcode_text_length) | [`BarcodeFormatSpecification.BarcodeTextLengthRangeArray`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-text-length-range-array.md) |
| `min_result_confidence` | [`min_result_confidence`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#min_result_confidence) | [`BarcodeFormatSpecification.MinResultConfidence`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/min-result-confidence.md) |
| `localization_modes` | [`localization_modes`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#localization_modes) | [`BarcodeReaderTaskSetting.LocalizationModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/localization-modes.md) |
| `expected_barcodes_count` | [`expected_barcodes_count`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#expected_barcodes_count) | [`BarcodeReaderTaskSetting.ExpectedBarcodesCount`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/expected-barcodes-count.md) |
| `barcode_format_ids` | [`barcode_format_ids`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#barcode_format_ids) | [`BarcodeReaderTaskSetting.BarcodeFormatIds`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/barcode-format-ids.md) |
| `barcode_format_ids_2` | [`barcode_format_ids`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#barcode_format_ids) | [`BarcodeReaderTaskSetting.BarcodeFormatIds`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/barcode-format-ids.md) |
| `deblur_modes` | [`deblur_modes`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#deblur_modes) | [`BarcodeReaderTaskSetting.DeblurModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/deblur-modes.md) |
| `deblur_level` | [`deblur_modes`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#deblur_modes) | [`BarcodeReaderTaskSetting.DeblurModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/deblur-modes.md) |
| `max_algorithm_thread_count` | [`max_threads_in_one_task`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#max_threads_in_one_task) | [`BarcodeReaderTaskSetting.MaxThreadsInOneTask`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/max-threads-in-one-task.md) |
| `grayscale_transformation_modes` | [`grayscale_transformation_modes`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#grayscale_transformation_modes) | [`ImageParameter.GrayscaleTransformationModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/grayscale-transformation-modes.md) |
| `image_preprocessing_modes` | [`grayscale_enhancement_modes`](https://www.dynamsoft.com/barcode-reader/docs/server/programming/python/api-reference/simplified-barcode-reader-settings.md#grayscale_enhancement_modes) | [`ImageParameter.GrayscaleEnhancementModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/grayscale-enhancement-modes.md) |

> Remarks:
>
> * The 2 groups of barcode formats are merged.
> * `deblur_level` is deprecated. You can use `deblur_modes` instead.
> * The mode `IPM_MORPHOLOGY` of `image_preprocessing_modes` is migrated to `BinarizationModes`. The mode arguments `MorphOperation`, `MorphOperationKernelSizeX`, `MorphOperationKernelSizeY`, `MorphShape` are now available for all modes of `BinarizationModes`.

### Properties Requiring Template File

The following properties can only be set via a template file. Please call `BarcodeReader.output_settings_to_json_file` first with the old version to export the settings and then use the <a href="https://www.dynamsoft.com/tools/template-upgrade/" target="_blank">Template Upgrade Tool</a> to upgrade your template.

| PublicRuntimeSetting Property | Template File Parameter |
| ------------------------------- | ----------------------- |
| `scale_down_threshold` | [`ImageParameter.ImageScaleSettings`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/image-scale-settings.md) |
| `binarization_modes` | [`ImageParameter.BinarizationModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/binarization-modes.md) |
| `text_result_order_modes` | [`BarcodeReaderTaskSetting.TextResultOrderModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/text-result-order-modes.md) |
| `return_barcode_zone_clarity` | [`BarcodeReaderTaskSetting.ReturnBarcodeZoneClarity`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/return-barcode-zone-clarity.md) |
| `scale_up_modes` | [`BarcodeReaderTaskSetting.BarcodeScaleModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/barcode-scale-modes.md) |
| `barcode_zone_min_distance_to_image_borders` | [`BarcodeFormatSpecification.BarcodeZoneMinDistanceToImageBorders`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-format-specification/barcode-zone-min-distance-to-image-borders.md) |
| `colour_conversion_modes` | [`ImageParameter.ColourConversionModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/colour-conversion-modes.md) |
| `region_predetection_modes` | [`BarcodeReaderTaskSetting.RegionPredetectionModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/region-predetection-modes.md) |
| `texture_detection_modes` | [`ImageParameter.TextureDetectionModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/texture-detection-modes.md) |
| `text_filter_modes` | [`ImageParameter.TextDetectionMode`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/text-detection-mode.md) & [`ImageParameter.IfEraseTextZone`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/image-parameter/if-erase-text-zone.md) |
| `dpm_code_reading_modes` | [`BarcodeReaderTaskSetting.DPMCodeReadingModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/dpm-code-reading-modes.md) |
| `deformation_resisting_modes` | [`BarcodeReaderTaskSetting.DeformationResistingModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/deformation-resisting-modes.md) |
| `barcode_complement_modes` | [`BarcodeReaderTaskSetting.BarcodeComplementModes`](https://www.dynamsoft.com/capture-vision/docs/core/parameters/reference/barcode-reader-task-settings/barcode-complement-modes.md) |

### Properties Migrated to Other APIs

The PDF properties of `PublicRuntimeSetting` are moved to set via the `set_pdf_reading_parameter` method of [`DirectoryFetcher`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/utility/directory-fetcher.md) and [`FileFetcher`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/utility/file-fetcher.md) with a [`PDFReadingParameter`](https://www.dynamsoft.com/capture-vision/docs/server/programming/python/api-reference/core/basic-classes/pdf-reading-parameter.md) parameter.

| PublicRuntimeSetting Property |
| ----------------------------- |
| `pdf_reading_mode` |
| `pdf_raster_dpi` |

### Removed Properties (No Replacement)

The following properties are removed.

| PublicRuntimeSetting Property|
| --------------------- |
| `barcode_colour_modes` |
| `intermediate_result_types` |
| `intermediate_result_saving_mode` |
| `result_coordinate_type` |
| `terminate_phase` |

| FurtherModes Property|
| --------------------- |
| `colour_clustering_modes` |